npm install @spree/admin-sdk
# or
yarn add @spree/admin-sdk
# or
pnpm add @spree/admin-sdk

import { createAdminClient } from '@spree/admin-sdk'

const client = createAdminClient({
  baseUrl: 'https://store.example.com',
  secretKey: 'sk_xxx',
})

// List orders
const { data: orders, meta } = await client.orders.list({
  status_eq: 'complete',
  sort: '-completed_at',
  limit: 25,
})

// Create an order in one shot
const order = await client.orders.create({
  email: '[email protected]',
  currency: 'USD',
  items: [{ variant_id: 'variant_xxx', quantity: 1 }],
  shipping_address: {
    first_name: 'Jane',
    last_name: 'Doe',
    address1: '350 Fifth Avenue',
    city: 'New York',
    postal_code: '10118',
    country_iso: 'US',
    state_abbr: 'NY',
    phone: '+1 212 555 1234',
  },
})

// Manage a customer
const customer = await client.customers.create({
  email: '[email protected]',
  first_name: 'Jane',
  last_name: 'Doe',
  tags: ['wholesale'],
})

await client.customers.addresses.create(customer.id, {
  first_name: 'Jane',
  last_name: 'Doe',
  address1: '350 Fifth Avenue',
  city: 'New York',
  postal_code: '10118',
  country_iso: 'US',
  state_abbr: 'NY',
  phone: '+1 212 555 1234',
  is_default_shipping: true,
})

const client = createAdminClient({
  baseUrl: 'https://store.example.com',
  secretKey: 'sk_xxx',
})

// A cookie-auth SPA can start with no credentials at all and bootstrap
// from the refresh cookie:
const client = createAdminClient({ baseUrl: 'https://store.example.com' })

// Login returns { token, user } — the refresh token lands in the cookie
const { token, user } = await client.auth.login({
  email: '[email protected]',
  password: 'password123',
})
client.setToken(token)

// Refresh takes no arguments — it's driven entirely by the cookie
client.onUnauthorized(async () => {
  const { token: fresh } = await client.auth.refresh()
  client.setToken(fresh)
  return true
})

// Logout destroys the refresh token server-side and clears the cookie
await client.auth.logout()

await client.customFields('Spree::Product', 'prod_xxx').list()

const orders = await client.orders.list({
  status_eq: 'complete',
  total_gteq: 100,
  email_cont: '@example.com',
  user_id_eq: 'cus_xxx',           // resource IDs work directly
  sort: '-completed_at',
  page: 2,
  limit: 50,
  expand: ['items', 'customer'],
})

import { SpreeError } from '@spree/admin-sdk'

try {
  await client.orders.update(orderId, { email })
} catch (err) {
  if (err instanceof SpreeError) {
    console.log(err.code)    // e.g. 'cart_already_updated'
    console.log(err.status)  // e.g. 409
    console.log(err.details) // optional structured context
  }
}

import type {
  AdminOrder,
  AdminProduct,
  AdminCustomer,
  AdminFulfillment,
  AdminPayment,
  PaginatedResponse,
} from '@spree/admin-sdk'

const orders: PaginatedResponse<AdminOrder> = await client.orders.list()
const product: AdminProduct = await client.products.get('prod_xxx')

const client = createAdminClient({
  baseUrl: 'https://store.example.com',
  secretKey: 'sk_xxx',
  fetch: customFetchImplementation,
})

cd packages/admin-sdk
pnpm install

# 1. Regenerate TypeScript types from Alba serializers
cd spree/api && bundle exec rake typelizer:generate

# 2. Rebuild the SDK (consumes the generated types)
cd packages/admin-sdk && pnpm build

# 3. Run tests to confirm nothing broke
pnpm test

pnpm changeset

pnpm version   # Apply changesets and bump version
pnpm release   # Build and publish to npm