@spree/docs 0.1.32 → 0.1.34

package/dist/api-reference/admin-api/authentication.md

@@ -0,0 +1,161 @@
+---
+title: "Authentication"
+sidebarTitle: "Authentication"
+description: "How to authenticate requests to the Admin API"
+---
+
+The Admin API supports two authentication methods: **secret API keys** for server-to-server integrations, and **JWT bearer tokens** for admin SPA / interactive sessions. Every request must include credentials — there is no public surface.
+
+> **WARNING:** Secret API keys grant full administrative access to your store. **Never embed them in client-side code, mobile apps, or public repositories.** Use them only from secure server environments.
+
+## Secret API key
+
+Pass the key via the `X-Spree-Api-Key` header:
+
+
+```typescript SDK
+import { createAdminClient } from '@spree/admin-sdk'
+
+const client = createAdminClient({
+  baseUrl: 'https://store.example.com',
+  secretKey: 'sk_xxx',
+})
+
+// The SDK automatically sends the secret key with every request
+const { data: products } = await client.products.list()
+```
+
+```bash cURL
+curl -X GET 'https://store.example.com/api/v3/admin/orders' \
+  -H 'X-Spree-Api-Key: sk_xxx'
+```
+
+
+Secret API keys are prefixed with `sk_`. Create them in the Spree admin under **Settings → API Keys** or via the Spree CLI:
+
+```bash
+spree api-key create --type secret    # Create a new secret key
+spree api-key list                     # List existing keys
+spree api-key revoke <key_id>          # Revoke a key
+```
+
+> **WARNING:** If you omit the API key, the API returns `401 Unauthorized`:
+> 
+> ```json
+{
+  "error": {
+    "code": "authentication_required",
+    "message": "Authentication required"
+  }
+}
+```
+
+## JWT bearer token (admin user)
+
+For interactive admin sessions (the Spree admin SPA, custom dashboards, etc.) authenticate as an admin user and use the returned JWT token for subsequent requests.
+
+### Login
+
+
+```typescript SDK
+const { token, user } = await client.auth.login({
+  email: 'admin@example.com',
+  password: 'secret123',
+})
+
+// Use the token for authenticated requests
+const orders = await client.orders.list({}, { bearerToken: token })
+```
+
+```bash cURL
+curl -X POST 'https://store.example.com/api/v3/admin/auth/login' \
+  -H 'X-Spree-Api-Key: sk_xxx' \
+  -H 'Content-Type: application/json' \
+  -d '{"email": "admin@example.com", "password": "secret123"}'
+```
+
+
+### Token refresh
+
+JWT tokens expire after 1 hour by default. Refresh them with the current token:
+
+
+```typescript SDK
+const { token } = await client.auth.refresh({ token: currentToken })
+```
+
+```bash cURL
+curl -X POST 'https://store.example.com/api/v3/admin/auth/refresh' \
+  -H 'X-Spree-Api-Key: sk_xxx' \
+  -H 'Authorization: Bearer <current_jwt_token>'
+```
+
+
+## Permissions
+
+Authorization works differently depending on which credentials you use.
+
+### Secret API keys: scopes
+
+Each secret API key carries a list of **scopes** that grant access to specific resources. Scopes follow a `read_<resource>` / `write_<resource>` convention; `write_<resource>` implies `read_<resource>`.
+
+| Scope | Endpoints |
+|---|---|
+| `read_orders` / `write_orders` | `/orders/*`, `/orders/:id/items` |
+| `read_products` / `write_products` | `/products/*`, `/variants/*`, `/option_types/*`, `/media/*` |
+| `read_customers` / `write_customers` | `/customers/*`, `/customers/:id/addresses`, `/customers/:id/credit_cards` |
+| `read_payments` / `write_payments` | `/orders/:id/payments` |
+| `read_fulfillments` / `write_fulfillments` | `/orders/:id/fulfillments` |
+| `read_refunds` / `write_refunds` | `/orders/:id/refunds` |
+| `read_gift_cards` / `write_gift_cards` | `/orders/:id/gift_cards` |
+| `read_store_credits` / `write_store_credits` | `/customers/:id/store_credits`, `/orders/:id/store_credits` |
+| `read_categories` / `write_categories` | `/categories/*` |
+| `read_settings` / `write_settings` | `/payment_methods`, `/markets`, `/countries`, `/tax_categories`, `/store` |
+| `read_dashboard` | `/dashboard/*` (analytics) |
+
+Two convenience aliases:
+
+- **`read_all`** — every `read_*` scope
+- **`write_all`** — every `read_*` and `write_*` scope (full admin)
+
+If the key lacks the required scope, the API returns `403 Forbidden`:
+
+```json
+{
+  "error": {
+    "code": "access_denied",
+    "message": "API key lacks scope: write_orders",
+    "details": {
+      "required_scope": "write_orders"
+    }
+  }
+}
+```
+
+The `details.required_scope` field tells you exactly which scope to add.
+
+Pick scopes when creating the key in **Settings → API Keys**. Choose the narrowest set that covers your integration's needs.
+
+### JWT bearer tokens: CanCanCan abilities
+
+JWT-authenticated admin users are authorized via [CanCanCan](https://github.com/CanCanCommunity/cancancan) abilities derived from their `Spree::Role`s. The SPA uses this fine-grained model to render UI conditionally; partial-permission staff users see only the resources their role grants.
+
+If the caller lacks permission for a specific action, the API returns `403 Forbidden`:
+
+```json
+{
+  "error": {
+    "code": "access_denied",
+    "message": "You are not authorized to perform this action"
+  }
+}
+```
+
+## Authentication summary
+
+| Method | Header | Use case | Authorization |
+|---|---|---|---|
+| Secret API key | `X-Spree-Api-Key: sk_xxx` | Server-to-server integrations | Scopes |
+| JWT token | `Authorization: Bearer <token>` | Interactive admin sessions; SPA | CanCanCan abilities |
+
+> **NOTE:** If both headers are present, the JWT token wins: CanCanCan applies and scopes are ignored. This lets you use `sk_xxx` to bootstrap a session and then issue per-user JWTs for individual admin actions.

package/dist/api-reference/admin-api/errors.md

@@ -0,0 +1,277 @@
+---
+title: Errors
+description: Error response format and admin-specific error codes
+---
+
+The Admin API uses the same Stripe-style error format as the rest of the Spree v3 API. Every error response carries a machine-readable `code` and a human-readable `message`.
+
+## Error response format
+
+```json
+{
+  "error": {
+    "code": "record_not_found",
+    "message": "Order not found"
+  }
+}
+```
+
+Validation errors include a `details` field with per-field error messages:
+
+```json
+{
+  "error": {
+    "code": "validation_error",
+    "message": "Email is invalid and Phone can't be blank",
+    "details": {
+      "email": ["is invalid"],
+      "phone": ["can't be blank"]
+    }
+  }
+}
+```
+
+Some specialized errors carry structured `details` (for example, scope errors include the `required_scope`):
+
+```json
+{
+  "error": {
+    "code": "access_denied",
+    "message": "API key lacks scope: write_orders",
+    "details": {
+      "required_scope": "write_orders"
+    }
+  }
+}
+```
+
+### Schema
+
+| Field | Type | Description |
+|---|---|---|
+| `error.code` | `string` | Machine-readable error code (see tables below) |
+| `error.message` | `string` | Human-readable description of the error |
+| `error.details` | `object` | Optional. Field-specific validation errors or structured context (varies by `code`). |
+
+## HTTP status codes
+
+| Status | Meaning | When |
+|---|---|---|
+| `400` | Bad Request | Missing required parameters, malformed JSON |
+| `401` | Unauthorized | Missing or invalid API key, expired or invalid JWT token |
+| `403` | Forbidden | Authenticated but lacks permission (CanCanCan ability) or scope |
+| `404` | Not Found | Resource doesn't exist, isn't accessible to the calling key, or belongs to a different store |
+| `409` | Conflict | Resource was modified by a concurrent request (optimistic locking) |
+| `422` | Unprocessable Content | Validation failed, invalid state transition, business rule violation |
+| `429` | Too Many Requests | Login/refresh rate limit exceeded |
+
+## Authentication & authorization
+
+| Code | Status | Description |
+|---|---|---|
+| `authentication_required` | 401 | Request reached a protected endpoint with no credentials |
+| `authentication_failed` | 401 | Login email/password was wrong |
+| `invalid_token` | 401 | API key or JWT token is invalid or expired |
+| `invalid_refresh_token` | 401 | Refresh token is invalid or expired |
+| `access_denied` | 403 | Caller lacks permission. For API-key callers, `details.required_scope` indicates the missing scope (see [Authentication](authentication.md#permissions)). For JWT callers, the user's role lacks the CanCanCan ability for this action. |
+| `current_password_invalid` | 422 | Current password is wrong (when changing password) |
+
+## Resources
+
+| Code | Status | Description |
+|---|---|---|
+| `record_not_found` | 404 | Resource doesn't exist or isn't accessible in the calling key's store |
+| `resource_invalid` | 422 | Resource couldn't be saved |
+
+## Validation
+
+| Code | Status | Description |
+|---|---|---|
+| `validation_error` | 422 | Model validation failed. Inspect `details` for field-specific messages. |
+| `parameter_missing` | 400 | A required parameter is missing |
+| `parameter_invalid` | 400 | A parameter has an invalid value |
+
+## Orders
+
+| Code | Status | Description |
+|---|---|---|
+| `cart_cannot_transition` | 422 | Order state machine refused the transition (e.g., completing an order without an address or payment) |
+| `cart_already_updated` | 409 | Order was modified by a concurrent request. Refetch and retry. See [optimistic locking](#optimistic-locking) below. |
+| `cart_invalid_state` | 422 | Order is in a state that doesn't allow this operation |
+| `cart_empty` | 422 | Cannot complete an order with no line items |
+
+## Customers
+
+| Code | Status | Description |
+|---|---|---|
+| `customer_has_orders` | 422 | Cannot delete a customer with completed orders. Anonymize instead. |
+
+## Store credits
+
+| Code | Status | Description |
+|---|---|---|
+| `store_credit_in_use` | 422 | Cannot edit `amount` on or delete a store credit that has been partially or fully used. |
+
+## Tags
+
+| Code | Status | Description |
+|---|---|---|
+| `invalid_taggable_type` | 422 | The `taggable_type` query param isn't one of the allowed values (`Spree::Product`, `Spree::Order`, `Spree::User`). |
+
+## Payments
+
+| Code | Status | Description |
+|---|---|---|
+| `payment_failed` | 422 | Payment was declined by the gateway |
+| `payment_processing_error` | 422 | Spree couldn't process the payment due to an internal error |
+| `gateway_error` | 422 | Payment gateway returned an error |
+
+## Examples
+
+### Insufficient scope (API key)
+
+```bash
+curl -X POST 'https://store.example.com/api/v3/admin/orders' \
+  -H 'X-Spree-Api-Key: sk_xxx' \
+  -H 'Content-Type: application/json' \
+  -d '{"email": "test@example.com"}'
+```
+
+```json 403
+{
+  "error": {
+    "code": "access_denied",
+    "message": "API key lacks scope: write_orders",
+    "details": {
+      "required_scope": "write_orders"
+    }
+  }
+}
+```
+
+### Validation error (customer create)
+
+```bash
+curl -X POST 'https://store.example.com/api/v3/admin/customers' \
+  -H 'X-Spree-Api-Key: sk_xxx' \
+  -H 'Content-Type: application/json' \
+  -d '{}'
+```
+
+```json 422
+{
+  "error": {
+    "code": "validation_error",
+    "message": "Email can't be blank",
+    "details": {
+      "email": ["can't be blank"]
+    }
+  }
+}
+```
+
+### Customer with completed orders
+
+```bash
+curl -X DELETE 'https://store.example.com/api/v3/admin/customers/cus_xxx' \
+  -H 'X-Spree-Api-Key: sk_xxx'
+```
+
+```json 422
+{
+  "error": {
+    "code": "customer_has_orders",
+    "message": "Cannot delete customer with completed orders"
+  }
+}
+```
+
+### Concurrent order update
+
+```bash
+curl -X PATCH 'https://store.example.com/api/v3/admin/orders/or_xxx' \
+  -H 'X-Spree-Api-Key: sk_xxx' \
+  -H 'Content-Type: application/json' \
+  -d '{"email": "new@example.com"}'
+```
+
+```json 409
+{
+  "error": {
+    "code": "cart_already_updated",
+    "message": "Order was modified by another request. Refetch and retry."
+  }
+}
+```
+
+## Handling errors with the SDK
+
+`@spree/admin-sdk` throws a `SpreeError` for every non-2xx response:
+
+```typescript
+import { SpreeError } from '@spree/admin-sdk'
+
+try {
+  await client.orders.update(orderId, { email: 'new@example.com' })
+} catch (error) {
+  if (error instanceof SpreeError) {
+    console.log(error.code)    // 'cart_already_updated'
+    console.log(error.message) // 'Order was modified by another request...'
+    console.log(error.status)  // 409
+    console.log(error.details) // undefined or { ... }
+  }
+}
+```
+
+### Common patterns
+
+**Branch on error code**:
+
+```typescript
+try {
+  await client.customers.delete(customerId)
+} catch (error) {
+  if (error instanceof SpreeError && error.code === 'customer_has_orders') {
+    // Anonymize instead of deleting
+    return anonymizeCustomer(customerId)
+  }
+  throw error
+}
+```
+
+**Retry on optimistic-lock conflicts**:
+
+```typescript
+async function updateOrderWithRetry(id, params, attempts = 3) {
+  for (let i = 0; i < attempts; i++) {
+    try {
+      return await client.orders.update(id, params)
+    } catch (error) {
+      if (error instanceof SpreeError && error.code === 'cart_already_updated' && i < attempts - 1) {
+        continue
+      }
+      throw error
+    }
+  }
+}
+```
+
+**Show field-level validation errors**:
+
+```typescript
+try {
+  await client.customers.create(customerData)
+} catch (error) {
+  if (error instanceof SpreeError && error.details) {
+    for (const [field, messages] of Object.entries(error.details)) {
+      setFieldError(field, (messages as string[]).join(', '))
+    }
+  }
+}
+```
+
+## Optimistic locking
+
+Orders use a `state_lock_version` column to detect concurrent modifications. Every state-changing operation increments it; if two callers update the same order simultaneously, the second write fails with `cart_already_updated` (409) — refetch and retry.
+
+This protects against race conditions when multiple clients (or the same client, retried) try to mutate the same order. Combined with idempotency at the integration level (e.g., dedupe webhook deliveries by event ID), it makes admin order management safe under concurrency.

package/dist/api-reference/admin-api/introduction.md

@@ -0,0 +1,68 @@
+---
+title: "Admin API"
+sidebarTitle: "Introduction"
+---
+
+> **WARNING:** **Developer Preview.** The Admin API is in active development and may change between major versions.
+
+The Admin API is a REST API for managing a Spree stores programmatically — products, orders, customers, fulfillments, payments, and more. It is intended for backend integrations, custom admin tooling, and automation.
+
+All routes are prefixed with `/api/v3/admin`. During development the API is available under `http://localhost:3000/api/v3/admin`. For production, replace `http://localhost:3000` with your Spree application URL.
+
+## Admin API vs Store API
+
+| | Admin API | Store API |
+|---|---|---|
+| **Purpose** | Manage store data | Power storefronts |
+| **Audience** | Staff users, backend integrations | Customers, storefronts |
+| **Authentication** | Secret API key (`sk_…`) or admin JWT | Publishable API key (`pk_…`), customer JWT, order token |
+| **Permissions** | API key scopes (API key authentication) or Admin Staff permission sets | Customer can only read/modify their own data |
+| **Write operations** | Full CRUD on most resources | Limited to the current customer's cart, addresses, profile |
+
+If you're building a storefront, use the [Store API](../store-api/introduction.md). The Admin API exposes administrative operations that should never be invoked from a browser.
+
+## Using the SDK
+
+We recommend using `@spree/admin-sdk` to interact with the Admin API. It provides typed clients, automatic retries, and idempotency support.
+
+### Installation
+
+```bash
+npm install @spree/admin-sdk
+# or
+yarn add @spree/admin-sdk
+# or
+pnpm add @spree/admin-sdk
+```
+
+### Quick start
+
+```typescript
+import { createAdminClient } from '@spree/admin-sdk'
+
+const client = createAdminClient({
+  baseUrl: 'http://localhost:3000',
+  secretKey: 'sk_xxx',
+})
+
+const { data: orders } = await client.orders.list({
+  status_eq: 'complete',
+  limit: 25,
+})
+```
+
+## What's covered
+
+The Admin API today (in Spree 5.5) covers:
+
+- **Catalog** — products, variants, prices
+- **Orders** — list, create, update, items, complete, cancel, approve, resume; nested fulfillments, payments, refunds, gift cards, store credits
+- **Customers** — full CRUD, addresses, store credits, credit cards
+
+See the **Endpoints** section in the sidebar for the complete reference, generated from the OpenAPI spec.
+
+Before integrating, read:
+
+- [Authentication](authentication.md) — secret API keys, scopes, and JWT tokens
+- [Errors](errors.md) — error format and admin-specific codes
+- [Querying](querying.md) — filtering, sorting, pagination, and `expand`