@spree/docs 0.1.88 → 0.1.90

package/dist/developer/contributing/developing-spree.md

@@ -337,7 +337,9 @@ cd packages/sdk    # or packages/admin-sdk, packages/cli, packages/create-spree-
 pnpm changeset
 ```
 
-This creates a changeset file describing your changes. Commit it with your PR. When merged to `main`, a GitHub Action creates a "Version Packages" PR that bumps the version and publishes to npm.
+This creates a changeset file describing your changes. Commit it with your PR.
+
+Releasing is a two-step flow: a maintainer consumes the pending changesets (`changeset version` — writes the CHANGELOG and bumps `package.json`) and merges that bump to `main`; the release jobs in `.github/workflows/packages.yml` then detect the unpublished version and publish with npm provenance via Trusted Publishing. `@spree/admin-sdk` publishes under the `next` dist-tag while on the 0.x Developer Preview line; the others ship as `latest` (prereleases go to `beta`).
 
 Private packages (`@spree/dashboard`, `@spree/dashboard-core`, `@spree/dashboard-ui`, `@spree/sdk-core`) don't need changesets.
 

package/dist/developer/sdk/admin/authentication.md

@@ -0,0 +1,109 @@
+---
+title: "Admin SDK authentication with API keys and JWT cookies"
+sidebarTitle: "Authentication"
+description: "Authenticate @spree/admin-sdk with a secret API key for server-to-server, scope-based access or JWT cookie auth for role-based browser admin apps."
+---
+
+The Admin API supports two authentication methods. Both reach the same endpoints — they differ in **where the credential lives** and **how authorization is decided**:
+
+| | Secret API key | JWT + cookie |
+|---|---|---|
+| **For** | Backend integrations, automations, cron jobs | Browser-based admin apps where a human signs in |
+| **Credential** | `sk_…` key, created in the admin | Short-lived access token + httpOnly refresh cookie |
+| **Authorization** | [Scopes](../../../api-reference/admin-api/authentication.md) attached to the key (`read_products`, `write_orders`, …) | The admin user's roles and permissions |
+| **Where it runs** | Server-side only — never in a browser | Browser (the refresh token never touches your JS) |
+
+## Secret API key (server-to-server)
+
+Create a secret key in the admin under **Settings → API Keys**, grant it the scopes your integration needs, and pass it to the client:
+
+```typescript
+import { createAdminClient } from '@spree/admin-sdk'
+
+const client = createAdminClient({
+  baseUrl: 'https://your-store.com',
+  secretKey: process.env.SPREE_SECRET_KEY, // sk_xxx
+})
+```
+
+Each key carries the list of scopes granted at creation time. A request to an endpoint the key isn't scoped for fails with `code: 'access_denied'` — the error's `details.required_scope` names the missing scope (see [Querying & Errors](querying-and-errors.md#scope-errors)).
+
+> **WARNING:** Secret keys grant back-office access to your store. Never embed them in client-side code, mobile apps, or public repositories — keep them in server-side environment variables or a secrets manager.
+
+## JWT + cookie authentication (browser apps)
+
+For browser-based admin tooling, authenticate as an admin user. The flow is designed so that **no long-lived credential is ever exposed to JavaScript**:
+
+- `auth.login()` returns `{ token, user }` — a short-lived access token you hold in memory.
+- The **refresh token never appears in JSON.** The server sets it as an `HttpOnly` cookie scoped to `/api/v3/admin/auth`, and the SDK sends requests with `credentials: 'include'` by default, so the cookie flows automatically.
+- `auth.refresh()` takes **no arguments** — it's driven entirely by the cookie, and rotates it on every call.
+- `auth.logout()` revokes the refresh token server-side and clears the cookie.
+
+```typescript
+import { createAdminClient } from '@spree/admin-sdk'
+
+// A cookie-auth app can start with no credentials at all
+const client = createAdminClient({ baseUrl: 'https://your-store.com' })
+
+// Sign in — the refresh token lands in the httpOnly cookie
+const { token, user } = await client.auth.login({
+  email: 'admin@example.com',
+  password: 'password123',
+})
+client.setToken(token)
+
+// Auto-recover from expired access tokens
+client.onUnauthorized(async () => {
+  const { token: fresh } = await client.auth.refresh()
+  client.setToken(fresh)
+  return true // retry the failed request
+})
+
+// Sign out — revokes the refresh token server-side
+await client.auth.logout()
+```
+
+### Bootstrapping a returning session
+
+Because the refresh cookie outlives the in-memory access token, a returning user can be signed back in without re-entering credentials — call `refresh()` on app load and treat failure as "not signed in":
+
+```typescript
+try {
+  const { token } = await client.auth.refresh()
+  client.setToken(token)
+} catch {
+  // No valid session — show the login form
+}
+```
+
+### Identity providers
+
+`auth.login()` also accepts third-party identity-provider payloads when the server has a matching strategy registered in `Spree.store_authentication_strategies`:
+
+```typescript
+const { token } = await client.auth.login({ provider: 'auth0', token: idpJwt })
+```
+
+### Current user and permissions
+
+After signing in, `client.me.get()` returns the admin user's profile together with their serialized permissions — use it to drive what your UI shows:
+
+```typescript
+const { user, permissions } = await client.me.get()
+```
+
+## Staff invitations
+
+The `auth` resource also exposes the unauthenticated invitation-acceptance flow used when onboarding new staff: `auth.lookupInvitation(id, token)` returns the safe-to-render invitation context (store, role, inviter), and `auth.acceptInvitation(id, token, params)` accepts it — issuing a JWT and refresh cookie identical to `login`. Sending invitations is an authenticated operation on [`client.invitations`](resources.md).
+
+## Custom fetch
+
+Pass a custom `fetch` implementation when you need request interception, proxying, or a non-standard runtime:
+
+```typescript
+const client = createAdminClient({
+  baseUrl: 'https://your-store.com',
+  secretKey: process.env.SPREE_SECRET_KEY,
+  fetch: customFetchImplementation,
+})
+```

package/dist/developer/sdk/admin/querying-and-errors.md

@@ -0,0 +1,130 @@
+---
+title: "Filtering, pagination, and error handling in the Admin SDK"
+sidebarTitle: "Querying & Errors"
+description: "Filter, sort, paginate, and expand Admin API collections with flat Ransack parameters and handle structured SpreeError responses from @spree/admin-sdk."
+---
+
+## Filtering
+
+Collection endpoints support [Ransack](https://activerecord-hackery.github.io/ransack/) filters passed as **flat parameters** — append a predicate suffix to any filterable attribute. The SDK wraps filter keys in `q[…]` automatically:
+
+```typescript
+const { data: orders } = await client.orders.list({
+  status_eq: 'complete',          // exact match
+  total_gteq: 100,                // greater than or equal
+  email_cont: '@example.com',     // substring match
+  user_id_eq: 'cus_xxx',          // prefixed IDs work directly
+  sort: '-completed_at',
+  page: 2,
+  limit: 50,
+})
+```
+
+Common predicates: `_eq`, `_not_eq`, `_cont` (contains), `_start`, `_end`, `_gteq` / `_lteq`, `_gt` / `_lt`, `_in` (array), `_null`. The filterable attributes per resource are listed in the [Admin API reference](../../../api-reference/admin-api/introduction.md); each model declares an explicit allowlist, so unknown filter keys are ignored rather than executed.
+
+> **NOTE:** Foreign-key predicates accept **prefixed IDs** (`user_id_eq: 'cus_xxx'`, `variant_id_in: ['variant_a', 'variant_b']`) — the API translates them; you never handle raw database IDs.
+
+## Sorting
+
+Pass `sort` with an attribute name; prefix with `-` for descending. Comma-separate multiple fields:
+
+```typescript
+await client.products.list({ sort: '-updated_at,name' })
+```
+
+## Pagination
+
+List responses return `{ data, meta }`. Drive pagination with `page` and `limit`:
+
+```typescript
+const { data, meta } = await client.products.list({ page: 1, limit: 50 })
+
+meta.count    // total records
+meta.pages    // total pages
+meta.next     // next page number, or null on the last page
+meta.previous // previous page number, or null on the first
+```
+
+A simple fetch-all loop:
+
+```typescript
+let page: number | null = 1
+while (page) {
+  const { data, meta } = await client.products.list({ page, limit: 100 })
+  process(data)
+  page = meta.next
+}
+```
+
+## Expanding associations
+
+Pass `expand` to embed related records in the response, instead of making follow-up requests. Dot notation reaches nested associations (up to 4 levels):
+
+```typescript
+const order = await client.orders.get('order_xxx', {
+  expand: ['items', 'customer', 'fulfillments.items'],
+})
+
+const products = await client.products.list({
+  expand: ['variants', 'variants.media'],
+})
+```
+
+`fields` does the opposite — trims the response to just the attributes you name (`id` is always included):
+
+```typescript
+await client.products.list({ fields: ['name', 'slug', 'status'] })
+```
+
+## Error handling
+
+Every non-2xx response throws a `SpreeError` with a stable machine-readable `code`, the HTTP `status`, and optional structured `details`:
+
+```typescript
+import { SpreeError } from '@spree/admin-sdk'
+
+try {
+  await client.orders.update(orderId, { email })
+} catch (err) {
+  if (err instanceof SpreeError) {
+    err.code     // e.g. 'validation_error', 'record_not_found', 'access_denied'
+    err.status   // e.g. 422
+    err.message  // human-readable summary
+    err.details  // optional structured context
+  }
+}
+```
+
+### Validation errors
+
+On `422` responses, `details` maps attribute names to arrays of messages — ready to project onto form fields:
+
+```typescript
+try {
+  await client.products.create({ name: '' })
+} catch (err) {
+  if (err instanceof SpreeError && err.status === 422) {
+    err.details // { name: ["can't be blank"] }
+  }
+}
+```
+
+### Scope errors
+
+When a request fails because the secret API key lacks the required [scope](authentication.md), the error has `code: 'access_denied'` and `details.required_scope` names the missing scope:
+
+```typescript
+catch (err) {
+  if (err instanceof SpreeError && err.code === 'access_denied') {
+    console.error(`API key is missing scope: ${err.details?.required_scope}`)
+  }
+}
+```
+
+### Expired JWT sessions
+
+For cookie-authenticated apps, register an `onUnauthorized` handler to transparently refresh and retry on `401` — see [Authentication](authentication.md#jwt--cookie-authentication-browser-apps).
+
+## Retries
+
+The SDK retries failed idempotent requests (GET/HEAD, plus requests carrying an idempotency key) with exponential backoff and jitter — transient network errors and retryable statuses recover without any code on your side.

package/dist/developer/sdk/admin/quickstart.md

@@ -1,22 +1,69 @@
 ---
-title: Admin API
-description: Manage your store programmatically with the Spree Admin SDK
+title: "Admin SDK quickstart for @spree/admin-sdk"
+sidebarTitle: Quickstart
+description: "Install and configure @spree/admin-sdk, the official TypeScript client for the Spree Admin API v3, to manage products, orders, customers, and stock."
 ---
 
-> **INFO:** The Admin API SDK is coming soon. The `client.admin` namespace is ready and will provide full access to administrative endpoints for managing products, orders, customers, and store settings.
+[`@spree/admin-sdk`](https://www.npmjs.com/package/@spree/admin-sdk) is the official TypeScript SDK for the [Admin API v3](../../../api-reference/admin-api/introduction.md) — the back-office counterpart to [`@spree/sdk`](../quickstart.md). Use it to build integrations, automations, internal tools, and custom admin UIs: manage products, orders, customers, stock, promotions, webhooks, and more.
 
-## Preview
+> **WARNING:** The Admin SDK is in **Developer Preview** on the `0.x` line and published under the `next` dist-tag. The API surface may change between minor versions — check the [changelog](https://github.com/spree/spree/blob/main/packages/admin-sdk/CHANGELOG.md) when updating. It requires Spree 5.5 or newer.
+
+## Installation
+
+```bash
+npm install @spree/admin-sdk@next
+```
+
+## Quick start
+
+Create a client with a [secret API key](authentication.md) (server-to-server) and start calling resources:
 
 ```typescript
-import { createClient } from '@spree/sdk';
+import { createAdminClient } from '@spree/admin-sdk'
 
-const client = createClient({
-  baseUrl: 'https://api.mystore.com',
-  secretKey: 'sk_xxx', // Admin API requires a secret key
-});
+const client = createAdminClient({
+  baseUrl: 'https://your-store.com',
+  secretKey: process.env.SPREE_SECRET_KEY, // sk_xxx — server-side only
+})
 
-// Admin endpoints will be available under client.admin.*
-// client.admin.products.list()
-// client.admin.orders.list()
-// client.admin.customers.list()
+// List recent completed orders
+const { data: orders, meta } = await client.orders.list({
+  status_eq: 'complete',
+  sort: '-completed_at',
+  limit: 25,
+})
+
+// Create a purchasable product — pricing lives on variants
+const product = await client.products.create({
+  name: 'Aero Hoodie',
+  status: 'active',
+  tags: ['new-arrivals'],
+  variants: [
+    {
+      sku: 'AERO-HOODIE',
+      prices: [{ currency: 'USD', amount: '59.00' }],
+    },
+  ],
+})
 ```
+
+Every method is fully typed — responses use `Admin`-prefixed types generated from the API serializers:
+
+```typescript
+import type { AdminOrder, PaginatedResponse } from '@spree/admin-sdk'
+
+const page: PaginatedResponse<AdminOrder> = await client.orders.list()
+```
+
+> **NOTE:** Secret keys grant back-office access — never ship them in browser code. For browser-based admin apps, use [JWT cookie authentication](authentication.md#jwt--cookie-authentication-browser-apps) instead.
+
+## Learn more
+
+
+  - [Authentication](authentication.md) — Secret keys with scopes for servers, JWT + httpOnly refresh cookie for browser apps.
+  - [Resources](resources.md) — The full resource map — products, orders, customers, stock, promotions, webhooks, and more.
+  - [Querying & Errors](querying-and-errors.md) — Filtering, sorting, pagination, prefixed IDs, and structured error handling.
+  - [Admin API Reference](../../../api-reference/admin-api/introduction.md) — The underlying REST API the SDK wraps — every endpoint, parameter, and response shape.
+
+
+> **TIP:** Adding your own resources? The [`spree generate api_resource`](../../tutorial/api.md) generator scaffolds Admin API endpoints (model, serializers, controllers, specs) in one command, and the [extending guide](../extending.md) shows how to call custom endpoints from the SDK.

package/dist/developer/sdk/admin/resources.md

@@ -0,0 +1,127 @@
+---
+title: "Admin SDK resources and CRUD client methods"
+sidebarTitle: "Resources"
+description: "Reference for every @spree/admin-sdk resource — products, orders, customers, inventory, pricing, promotions, store configuration, and platform clients."
+---
+
+Every Admin API resource is exposed as a property on the client (`client.orders`, `client.products`, …). Collection resources follow a consistent CRUD shape — `list`, `get`, `create`, `update`, `delete` — plus resource-specific actions. Nested resources take the **parent ID as the first argument**:
+
+```typescript
+// Top-level
+const order = await client.orders.get('order_xxx')
+
+// Nested — parent ID first
+const payments = await client.orders.payments.list('order_xxx')
+await client.orders.payments.capture('order_xxx', 'payment_xxx')
+
+// Nested create
+await client.customers.addresses.create('cus_xxx', {
+  first_name: 'Jane',
+  last_name: 'Doe',
+  address1: '350 Fifth Avenue',
+  city: 'New York',
+  postal_code: '10118',
+  country_iso: 'US',
+  state_abbr: 'NY',
+  is_default_shipping: true,
+})
+```
+
+## Catalog
+
+| Client | Endpoints |
+|---|---|
+| `client.products` | CRUD, `clone`, and bulk operations (`bulkStatusUpdate`, `bulkAddToCategories` / `bulkRemoveFromCategories`, `bulkAddToChannels` / `bulkRemoveFromChannels`, `bulkAddTags` / `bulkRemoveTags`, `bulkDestroy`). Nested: `media`, `variants` (with their own `media`). |
+| `client.variants` | Top-level variant search across products (`list`, `get`). |
+| `client.optionTypes` | CRUD on option types and their values. |
+| `client.categories` | List categories. |
+| `client.tags` | Autocomplete tag names per taggable type. |
+| `client.taxCategories` | CRUD on tax categories. |
+
+## Orders & fulfillment
+
+| Client | Endpoints |
+|---|---|
+| `client.orders` | List, get, create, update, delete, `complete`, `cancel`, `approve`, `resume`, `resendConfirmation`. Nested: `items`, `payments` (incl. `capture` / `void`), `fulfillments` (incl. `fulfill` / `cancel` / `resume` / `split`), `refunds`, `giftCards`, `storeCredits`, `adjustments`. |
+
+## Customers
+
+| Client | Endpoints |
+|---|---|
+| `client.customers` | CRUD plus bulk group operations (`bulkAddToGroups` / `bulkRemoveFromGroups`) and bulk tags. Nested: `addresses`, `creditCards`, `storeCredits`. |
+| `client.customerGroups` | CRUD on customer groups. |
+
+## Pricing & promotions
+
+| Client | Endpoints |
+|---|---|
+| `client.prices` | CRUD plus `bulkUpsert` / `bulkDestroy` for variant prices. |
+| `client.priceLists` | CRUD, `activate` / `deactivate`, and price-list rule types. |
+| `client.promotions` | CRUD. Nested: `actions`, `rules`, `couponCodes`. |
+| `client.promotionActions` | Lookup of available action `types` and `calculators`. |
+| `client.promotionRules` | Lookup of available rule `types`. |
+| `client.giftCards` | CRUD on gift cards. |
+| `client.giftCardBatches` | List, get, and create gift card batches. |
+| `client.storeCreditCategories` | List and read store credit categories. |
+
+## Inventory
+
+| Client | Endpoints |
+|---|---|
+| `client.stockLocations` | CRUD on stock locations. |
+| `client.stockItems` | List, get, update, delete stock items. |
+| `client.stockTransfers` | List, get, create, delete stock transfers. |
+
+## Sales channels
+
+| Client | Endpoints |
+|---|---|
+| `client.channels` | CRUD plus `addProducts` / `removeProducts`. |
+| `client.markets` | CRUD on markets. |
+
+## Store configuration
+
+| Client | Endpoints |
+|---|---|
+| `client.store` | Store profile (`get`, `update`). |
+| `client.paymentMethods` | CRUD plus `types` (available gateway types). |
+| `client.countries` | List and read countries (for address dropdowns). |
+| `client.customFieldDefinitions` | CRUD on [custom field](../../core-concepts/metafields.md) definitions. |
+| `client.exports` | Create and track CSV exports (products, orders, customers, …). |
+| `client.directUploads` | Pre-signed Active Storage uploads (used by media flows). |
+
+## Platform & access
+
+| Client | Endpoints |
+|---|---|
+| `client.auth` | Login (email/password or identity provider), cookie-driven refresh, logout, invitation lookup/acceptance — see [Authentication](authentication.md). |
+| `client.me` | Current admin user + permissions. |
+| `client.adminUsers` | List, get, update, delete admin users. |
+| `client.invitations` | Staff invitations — list, get, create, delete, `resend`. |
+| `client.roles` | List and read roles. |
+| `client.apiKeys` | CRUD plus `revoke` for API keys. |
+| `client.allowedOrigins` | CRUD on CORS allowed origins. |
+| `client.webhookEndpoints` | CRUD, `sendTest`, `enable` / `disable`. Nested: `deliveries` (list, get, `redeliver`). |
+| `client.dashboard` | Sales analytics. |
+
+## Custom fields
+
+Resources that support [custom fields](../../core-concepts/metafields.md) (products, variants, orders, customers, categories, option types) expose a `customFields` accessor taking the parent ID first:
+
+```typescript
+await client.products.customFields.list('prod_xxx')
+await client.products.customFields.create('prod_xxx', {
+  custom_field_definition_id: 'cfd_xxx',
+  value: 'limited-edition',
+})
+```
+
+The generic escape hatch covers any owner type:
+
+```typescript
+await client.customFields('Spree::Product', 'prod_xxx').list()
+```
+
+## Adding your own resources
+
+The resource map grows with your store. The [`spree generate api_resource`](../../tutorial/api.md) generator scaffolds new Admin API endpoints (model, serializers, controllers, routes, specs) in one command — then call them from the SDK with a [custom fetch or raw request](../extending.md), or generate a typed client for them.

package/dist/developer/sdk/quickstart.md

@@ -1,8 +1,11 @@
 ---
-title: Quickstart
-description: Install the Spree TypeScript SDK, configure your Store API client, and make your first calls to products, carts, checkout, and customer endpoints.
+title: Spree TypeScript SDK quickstart for the Store API
+sidebarTitle: Quickstart
+description: Install @spree/sdk, configure the Store API client, and make your first calls to products, carts, checkout, and customer account endpoints from TypeScript.
 ---
 
+`@spree/sdk` is the customer-facing SDK — products, carts, checkout, and account flows against the Store API. For back-office integrations (managing products, orders, customers, stock), use the [Admin SDK](admin/quickstart.md).
+
 ## Installation
 
 ```bash
@@ -70,7 +73,6 @@ The SDK uses a resource builder pattern for nested resources:
 | `customer` | `orders` | `list` |
 | `customer` | `paymentSetupSessions` | `create`, `get`, `complete` |
 | `policies` | — | `list`, `get` |
-| `categories` | `products` | `list` |
 | `wishlists` | `items` | `create`, `update`, `delete` |
 
 ```typescript
@@ -79,7 +81,6 @@ await client.carts.items.create(cartId, params, options);
 await client.carts.payments.list(cartId, options);
 await client.carts.fulfillments.update(cartId, fulfillmentId, params, options);
 await client.customer.addresses.list({}, options);
-await client.categories.products.list(categoryId, params, options);
 await client.wishlists.items.create(wishlistId, params, options);
 ```
 

package/dist/developer/tutorial/api.md

@@ -1,5 +1,6 @@
 ---
-title: API
+title: Expose a custom model through the Store and Admin APIs
+sidebarTitle: API
 description: Expose your custom Brand model through the Spree Store and Admin REST APIs with serializers, controllers, routes, and the spree:api_resource generator.
 ---
 
@@ -362,7 +363,7 @@ curl -X POST -H "X-Spree-API-Key: sk_YOUR_KEY" \
      http://localhost:3000/api/v3/admin/brands
 ```
 
-> **INFO:** Secret keys carry scopes (`read_brands`, `write_brands` style) and JWT admin users go through CanCanCan abilities — see [API authentication](../customization/api.md) for the full model.
+> **INFO:** Secret keys carry scopes (`read_brands`, `write_brands` style) and JWT admin users go through CanCanCan abilities — see [API authentication](../customization/api.md) for the full model. From TypeScript, the [Admin SDK](../sdk/admin/quickstart.md) wraps the Admin API with typed clients for all built-in resources.
 
 ## Step 6: Add Brand to Product Responses
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spree/docs",
-  "version": "0.1.88",
+  "version": "0.1.90",
   "description": "Spree Commerce developer documentation for AI agents and local reference",
   "type": "module",
   "license": "CC-BY-4.0",