@spree/docs 0.1.0

package/README.md

@@ -0,0 +1,54 @@
+# @spree/docs
+
+Spree Commerce developer documentation packaged for local access by AI agents and development tools.
+
+## Installation
+
+```bash
+npm install @spree/docs
+# or
+pnpm add @spree/docs
+```
+
+## Usage
+
+Documentation files are plain Markdown, accessible at:
+
+```
+node_modules/@spree/docs/dist/
+├── developer/
+│   ├── core-concepts/     # Products, orders, payments, inventory, etc.
+│   ├── customization/     # Decorators, extensions, configuration
+│   ├── admin/             # Admin panel customization
+│   ├── storefront/        # Storefront building guides
+│   ├── sdk/               # TypeScript SDK documentation
+│   ├── deployment/        # Deployment guides
+│   └── tutorial/          # Step-by-step tutorials
+├── api-reference/
+│   └── store-api/         # Store API reference
+└── integrations/          # Third-party integration guides
+```
+
+### For AI Agents
+
+Point your `CLAUDE.md` or agent configuration to the docs:
+
+```markdown
+## Spree Documentation
+Full developer docs: `node_modules/@spree/docs/dist/`
+```
+
+### Programmatic Access (Node.js)
+
+```javascript
+import { readFileSync } from 'fs'
+import { createRequire } from 'module'
+
+const require = createRequire(import.meta.url)
+const docsPath = require.resolve('@spree/docs/dist/developer/core-concepts/products.md')
+const content = readFileSync(docsPath, 'utf-8')
+```
+
+## License
+
+CC-BY-4.0 — same as the Spree Commerce documentation.

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

@@ -0,0 +1,38 @@
+Platform API is meant to be used by external applications to perform operations within Spree. Because of that, it uses a different authentication schema than the Storefront API.
+
+### Creating an application inside Spree
+
+To generate a valid token for the Platform API, you'll first need to create an application inside Spree.
+
+1. Go to Spree's admin panel and open `Apps` -> `oAuth Applications` in the menu
+
+    <img src="/images/Platform API 1.png"/>
+
+2. Click on `New oAuth Application`
+
+    <img src="/images/Platform API 2.png"/>
+
+3. Give your application a name and click `Create`
+
+    <img src="/images/Platform API 3.png"/>
+
+4. Save your Client ID and Secret - you'll later use it to generate a OAuth token to access the platform API
+
+    <img src="/images/Platform API 4.png"/>
+
+### Generating OAuth token
+
+Once the application is configured inside Spree, you can use its credentials to generate an OAuth token that will give you access to the APIs.
+
+To obtain the token, send the following `POST` request to `/spree_oauth/token`
+
+```json
+{
+  "grant_type": "client_credentials",
+  "client_id": "xxx",
+  "client_secret": "xxx",
+  "scope": "admin"
+}
+```
+
+In the response, you'll receive a token to pass in `Authorization: Bearer {token}` header when making requests to the Platform API.

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

@@ -0,0 +1,188 @@
+---
+title: "Authentication"
+sidebarTitle: "Authentication"
+description: "How to authenticate requests to the Store API"
+---
+
+The Store API uses three authentication mechanisms depending on the use case: **API keys** for all requests, **JWT tokens** for authenticated customers, and **order tokens** for guest checkout.
+
+## API Key (Required)
+
+Every request to the Store API requires a **publishable API key**. This key identifies your storefront and is safe to use in client-side code.
+
+Pass the key via the `X-Spree-Api-Key` header:
+
+
+```typescript SDK
+import { createClient } from '@spree/sdk'
+
+const client = createClient({
+  baseUrl: 'http://localhost:3000',
+  publishableKey: 'spree_pk_xxx',
+})
+
+// The SDK automatically sends the publishable key with every request
+const products = await client.products.list()
+```
+
+```bash cURL
+curl -X GET 'http://localhost:3000/api/v3/store/products' \
+  -H 'X-Spree-Api-Key: spree_pk_xxx'
+```
+
+
+Publishable API keys are prefixed with `spree_pk_`. You can create them in the Spree Admin under **Settings > API Keys** or via the Spree CLI:
+
+```bash
+spree api-key create       # Create a new API key
+spree api-key list         # List existing API keys
+```
+
+> **WARNING:** If you omit the API key, the API returns a `401 Unauthorized` error:
+> 
+> ```json
+{
+  "error": {
+    "code": "invalid_token",
+    "message": "Valid API key required"
+  }
+}
+```
+
+## JWT Token (Authenticated Customer)
+
+For actions that require a logged-in customer (viewing orders, managing addresses, saved payment methods), use a **JWT bearer token** in addition to the API key.
+
+### Login
+
+
+```typescript SDK
+// Login to get a JWT token
+const { token, user } = await client.auth.login({
+  email: 'customer@example.com',
+  password: 'password123',
+})
+
+// Use the token for authenticated requests
+const orders = await client.customer.orders.list({}, { token })
+```
+
+```bash cURL
+# Login
+curl -X POST 'http://localhost:3000/api/v3/store/auth/login' \
+  -H 'X-Spree-Api-Key: spree_pk_xxx' \
+  -H 'Content-Type: application/json' \
+  -d '{"email": "customer@example.com", "password": "password123"}'
+
+# Use the returned token for authenticated requests
+curl -X GET 'http://localhost:3000/api/v3/store/orders' \
+  -H 'X-Spree-Api-Key: spree_pk_xxx' \
+  -H 'Authorization: Bearer <jwt_token>'
+```
+
+
+### Register
+
+
+```typescript SDK
+const { token, user } = await client.customers.create({
+  email: 'new@example.com',
+  password: 'password123',
+  password_confirmation: 'password123',
+  first_name: 'John',
+  last_name: 'Doe',
+})
+```
+
+```bash cURL
+curl -X POST 'http://localhost:3000/api/v3/store/customers' \
+  -H 'X-Spree-Api-Key: spree_pk_xxx' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "email": "new@example.com",
+    "password": "password123",
+    "password_confirmation": "password123",
+    "first_name": "John",
+    "last_name": "Doe"
+  }'
+```
+
+
+### Token Refresh
+
+JWT tokens expire after 1 hour by default. Use the refresh endpoint to get a new token:
+
+
+```typescript SDK
+const { token } = await client.auth.refresh({ token: currentToken })
+```
+
+```bash cURL
+curl -X POST 'http://localhost:3000/api/v3/store/auth/refresh' \
+  -H 'X-Spree-Api-Key: spree_pk_xxx' \
+  -H 'Authorization: Bearer <current_jwt_token>'
+```
+
+
+## Order Token (Guest Checkout)
+
+For guest checkout flows, use the **order token** returned when creating a cart. This allows unauthenticated users to manage their cart and complete checkout.
+
+Pass the token via the `x-spree-token` header:
+
+
+```typescript SDK
+// Create a cart (guest)
+const cart = await client.carts.create()
+
+// Use spreeToken for all guest cart operations
+const options = { spreeToken: cart.token }
+
+// Add items
+await client.carts.items.create(cart.id, {
+  variant_id: 'variant_abc123',
+  quantity: 1,
+}, options)
+```
+
+```bash cURL
+# Create a cart
+curl -X POST 'http://localhost:3000/api/v3/store/carts' \
+  -H 'X-Spree-Api-Key: spree_pk_xxx'
+
+# Use the returned token for cart operations
+curl -X POST 'http://localhost:3000/api/v3/store/carts/cart_xxx/items' \
+  -H 'X-Spree-Api-Key: spree_pk_xxx' \
+  -H 'X-Spree-Token: <order_token>' \
+  -H 'Content-Type: application/json' \
+  -d '{"variant_id": "variant_abc123", "quantity": 1}'
+```
+
+
+### Associating a Guest Cart
+
+After a guest user logs in, you can associate their guest cart with their account:
+
+
+```typescript SDK
+await client.carts.associate(cart.id, {
+  token: jwtToken,
+  spreeToken: cart.token,
+})
+```
+
+```bash cURL
+curl -X PATCH 'http://localhost:3000/api/v3/store/carts/cart_xxx/associate' \
+  -H 'X-Spree-Api-Key: spree_pk_xxx' \
+  -H 'Authorization: Bearer <jwt_token>' \
+  -H 'X-Spree-Token: <order_token>'
+```
+
+
+## Authentication Summary
+
+| Method | Header | Use Case |
+|--------|--------|----------|
+| API Key | `X-Spree-Api-Key: spree_pk_xxx` | All requests (required) |
+| JWT Token | `Authorization: Bearer <token>` | Authenticated customer actions |
+| Order Token | `X-Spree-Token: <token>` | Guest cart and checkout |

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

@@ -0,0 +1,277 @@
+---
+title: Errors
+description: Error response format, error codes, and handling strategies
+---
+
+The Store API uses a consistent, Stripe-style error format across all endpoints. Every error response includes a machine-readable `code` and a human-readable `message`.
+
+## Error Response Format
+
+All errors return a JSON object with a single `error` key:
+
+```json
+{
+  "error": {
+    "code": "record_not_found",
+    "message": "Product not found"
+  }
+}
+```
+
+Validation errors include an additional `details` field with per-field error messages:
+
+```json
+{
+  "error": {
+    "code": "validation_error",
+    "message": "Name can't be blank and Email is invalid",
+    "details": {
+      "name": ["can't be blank"],
+      "email": ["is invalid"]
+    }
+  }
+}
+```
+
+### Schema
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `error.code` | `string` | Machine-readable error code (see table below) |
+| `error.message` | `string` | Human-readable description of the error |
+| `error.details` | `object` | Field-specific validation errors. Each key is a field name, each value is an array of error strings. Only present for validation errors. |
+
+## HTTP Status Codes
+
+| Status | Meaning | When |
+|--------|---------|------|
+| `400` | Bad Request | Missing required parameters, malformed JSON, invalid arguments |
+| `401` | Unauthorized | Missing or invalid API key, expired JWT token |
+| `403` | Forbidden | Authenticated but not authorized for this resource |
+| `404` | Not Found | Resource doesn't exist or isn't accessible |
+| `409` | Conflict | Resource was modified by another request (concurrent update) |
+| `422` | Unprocessable Content | Validation failed, invalid state transition, payment error |
+| `429` | Too Many Requests | Rate limit exceeded (see [Rate Limiting](/api-reference/store-api/rate-limitting)) |
+
+## Error Codes
+
+### Authentication & Authorization
+
+| Code | Status | Description |
+|------|--------|-------------|
+| `authentication_required` | 401 | Request requires a valid JWT token |
+| `authentication_failed` | 401 | Email or password is incorrect |
+| `invalid_token` | 401 | API key or JWT token is invalid or expired |
+| `invalid_provider` | 400 | OAuth provider not recognized |
+| `access_denied` | 403 | User doesn't have permission for this action |
+
+### Resource Errors
+
+| Code | Status | Description |
+|------|--------|-------------|
+| `record_not_found` | 404 | Resource doesn't exist or isn't accessible in the current store |
+| `resource_invalid` | 422 | Resource couldn't be saved |
+
+### Validation Errors
+
+| Code | Status | Description |
+|------|--------|-------------|
+| `validation_error` | 422 | Model validation failed. Check `details` for field-specific messages. |
+| `parameter_missing` | 400 | A required parameter is missing |
+| `parameter_invalid` | 400 | A parameter has an invalid value |
+
+### Cart Errors
+
+| Code | Status | Description |
+|------|--------|-------------|
+| `cart_not_found` | 404 | Cart doesn't exist or doesn't belong to the current user/guest |
+| `cart_cannot_complete` | 422 | Cart cannot be completed (e.g., missing payment or address) |
+| `cart_cannot_transition` | 422 | Internal state machine transition failed (e.g., completing a cart that isn't ready) |
+| `cart_empty` | 422 | Cart has no line items |
+| `cart_invalid_state` | 422 | Cart is in an invalid state for this operation |
+| `cart_already_updated` | 409 | Cart was modified by another request (optimistic locking conflict) |
+
+### Order Errors
+
+| Code | Status | Description |
+|------|--------|-------------|
+| `order_not_found` | 404 | Completed order doesn't exist or doesn't belong to the current user/guest |
+
+### Line Item & Stock Errors
+
+| Code | Status | Description |
+|------|--------|-------------|
+| `line_item_not_found` | 404 | Line item doesn't exist in this order |
+| `variant_not_found` | 404 | Variant doesn't exist or isn't available |
+| `insufficient_stock` | 422 | Not enough stock to fulfill the requested quantity |
+| `invalid_quantity` | 422 | Quantity must be a positive integer |
+
+### Payment Errors
+
+| Code | Status | Description |
+|------|--------|-------------|
+| `payment_failed` | 422 | Payment was declined or couldn't be processed |
+| `payment_processing_error` | 422 | Error communicating with the payment gateway |
+| `gateway_error` | 422 | Payment gateway returned an error |
+
+### Digital Download Errors
+
+| Code | Status | Description |
+|------|--------|-------------|
+| `attachment_missing` | 403 | File attachment not found for this digital product |
+| `download_unauthorized` | 403 | User is not authorized to download this file |
+| `digital_link_expired` | 403 | Download link has expired |
+| `download_limit_exceeded` | 403 | Maximum number of downloads reached |
+
+### Concurrency & Idempotency Errors
+
+| Code | Status | Description |
+|------|--------|-------------|
+| `order_already_updated` | 409 | Order was modified by another concurrent request. Retry with fresh data. |
+| `idempotency_key_reused` | 422 | Idempotency key was already used with different request parameters. See [Idempotency](/api-reference/store-api/idempotency). |
+
+### Other Errors
+
+| Code | Status | Description |
+|------|--------|-------------|
+| `rate_limit_exceeded` | 429 | Too many requests. Retry after the `Retry-After` header value. |
+| `request_too_large` | 413 | Request body exceeds the size limit |
+| `processing_error` | 422 | Generic server-side processing error |
+| `invalid_request` | 400 | Request is malformed (e.g., invalid JSON body) |
+
+## Examples
+
+### Not Found
+
+```bash
+curl https://api.mystore.com/api/v3/store/products/prod_nonexistent \
+  -H "Authorization: Bearer spree_pk_xxx"
+```
+
+```json 404
+{
+  "error": {
+    "code": "record_not_found",
+    "message": "Product not found"
+  }
+}
+```
+
+### Validation Error
+
+```bash
+curl -X POST https://api.mystore.com/api/v3/store/account/addresses \
+  -H "Authorization: Bearer <jwt_token>" \
+  -H "Content-Type: application/json" \
+  -d '{}'
+```
+
+```json 422
+{
+  "error": {
+    "code": "validation_error",
+    "message": "First name can't be blank, Address can't be blank, City can't be blank, and Country can't be blank",
+    "details": {
+      "firstname": ["can't be blank"],
+      "address1": ["can't be blank"],
+      "city": ["can't be blank"],
+      "country": ["can't be blank"]
+    }
+  }
+}
+```
+
+### Insufficient Stock
+
+```bash
+curl -X POST https://api.mystore.com/api/v3/store/carts/cart_xxx/items \
+  -H "Authorization: Bearer spree_pk_xxx" \
+  -H "X-Spree-Token: abc123" \
+  -H "Content-Type: application/json" \
+  -d '{"variant_id": "var_xxx", "quantity": 999}'
+```
+
+```json 422
+{
+  "error": {
+    "code": "insufficient_stock",
+    "message": "Quantity selected exceeds available stock"
+  }
+}
+```
+
+### Invalid State Transition
+
+```bash
+curl -X POST https://api.mystore.com/api/v3/store/carts/cart_xxx/complete \
+  -H "Authorization: Bearer spree_pk_xxx"
+```
+
+```json 422
+{
+  "error": {
+    "code": "cart_cannot_transition",
+    "message": "Cannot transition cart to complete — ensure address, shipping, and payment are set"
+  }
+}
+```
+
+## Handling Errors in the SDK
+
+The `@spree/sdk` package throws a `SpreeError` for all non-2xx responses:
+
+```typescript
+import { SpreeError } from '@spree/sdk';
+
+try {
+  const product = await client.products.get('nonexistent');
+} catch (error) {
+  if (error instanceof SpreeError) {
+    console.log(error.code);    // 'record_not_found'
+    console.log(error.message); // 'Product not found'
+    console.log(error.status);  // 404
+    console.log(error.details); // undefined (or field errors for validation)
+  }
+}
+```
+
+### Common Patterns
+
+Handle specific error codes:
+
+```typescript
+try {
+  await client.carts.items.create(cartId, {
+    variant_id: variantId,
+    quantity: 1,
+  });
+} catch (error) {
+  if (error instanceof SpreeError) {
+    switch (error.code) {
+      case 'insufficient_stock':
+        showNotification('This item is out of stock');
+        break;
+      case 'variant_not_found':
+        showNotification('This product is no longer available');
+        break;
+      default:
+        showNotification(error.message);
+    }
+  }
+}
+```
+
+Display validation errors per field:
+
+```typescript
+try {
+  await client.customer.addresses.create(addressData);
+} catch (error) {
+  if (error instanceof SpreeError && error.details) {
+    // error.details = { city: ["can't be blank"], zipcode: ["is invalid"] }
+    for (const [field, messages] of Object.entries(error.details)) {
+      setFieldError(field, messages.join(', '));
+    }
+  }
+}
+```

package/dist/api-reference/store-api/idempotency.md

@@ -0,0 +1,129 @@
+---
+title: "Idempotency"
+sidebarTitle: "Idempotency"
+description: "Prevent duplicate operations with idempotency keys"
+---
+
+The Store API supports idempotency keys on mutating endpoints. This lets you safely retry requests without risking duplicate side effects — for example, adding an item to cart twice or creating duplicate payments due to network timeouts.
+
+## How It Works
+
+Include an `Idempotency-Key` header with a unique value (e.g., a UUID) on any supported request. The API will:
+
+1. **First request** — process normally and cache the response for 24 hours
+2. **Duplicate request** (same key, same parameters) — return the cached response without re-executing the operation
+3. **Key reuse with different parameters** — return a `422` error to prevent misuse
+
+```bash
+curl -X POST https://api.mystore.com/api/v3/store/carts/cart_xxx/items \
+  -H "Authorization: Bearer spree_pk_xxx" \
+  -H "X-Spree-Token: abc123" \
+  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
+  -H "Content-Type: application/json" \
+  -d '{"variant_id": "variant_xxx", "quantity": 1}'
+```
+
+If the client retries this exact request with the same idempotency key, the API returns the original response with an `Idempotent-Replayed: true` header — without adding the item again.
+
+## Supported Endpoints
+
+| Endpoint | Actions |
+|----------|---------|
+| `POST /carts` | Cart creation |
+| `PATCH /carts/:id` | Cart updates |
+| `POST /carts/:id/complete` | Order completion |
+| `POST /carts/:id/items` | Adding items to cart |
+| `POST /carts/:id/payment_sessions` | Payment session creation |
+| `PATCH /carts/:id/payment_sessions/:id/complete` | Payment completion |
+| `POST /carts/:id/coupon_codes` | Applying coupon codes |
+| `POST /carts/:id/store_credits` | Applying store credits |
+
+Idempotency keys are ignored on `GET`, `DELETE`, and other non-supported actions.
+
+## Key Requirements
+
+- Must be a string of **255 characters or less**
+- Should be unique per distinct operation (UUIDs are recommended)
+- Keys are scoped per API key — different API keys can use the same idempotency key without conflict
+- Cached responses expire after **24 hours**
+
+## Response Headers
+
+When a cached response is replayed, the API sets:
+
+```
+Idempotent-Replayed: true
+```
+
+You can use this header to detect replayed responses in your application or logging.
+
+## Error Handling
+
+### Key Reuse with Different Parameters
+
+If you send a request with an idempotency key that was previously used with different request parameters (different body, different path), the API returns a `422` error:
+
+```json
+{
+  "error": {
+    "code": "idempotency_key_reused",
+    "message": "This Idempotency-Key has already been used with different request parameters."
+  }
+}
+```
+
+### Key Too Long
+
+Keys longer than 255 characters return a `400` error:
+
+```json
+{
+  "error": {
+    "code": "invalid_request",
+    "message": "Idempotency-Key must be 255 characters or less."
+  }
+}
+```
+
+### Server Errors
+
+`5xx` responses are **not cached**. If the server fails to process your request, you can safely retry with the same idempotency key and the request will be re-executed.
+
+## SDK Usage
+
+The Spree SDK supports idempotency keys via the `idempotencyKey` option:
+
+```typescript
+import { createClient } from '@spree/sdk'
+
+const client = createClient({
+  baseUrl: 'http://localhost:3000',
+  publishableKey: 'spree_pk_xxx',
+})
+
+// Add item to cart with idempotency key
+await client.carts.items.create(cartId, {
+  variant_id: 'variant_xxx',
+  quantity: 1,
+}, {
+  idempotencyKey: '550e8400-e29b-41d4-a716-446655440000',
+})
+```
+
+## Best Practices
+
+- **Generate a new key for each distinct operation.** Use a UUID (v4) or another random identifier. Never reuse keys across different operations.
+- **Store the key before sending the request.** If the request fails due to a network error, retry with the same key to ensure the operation is only performed once.
+- **Don't use idempotency keys for GET requests.** GET requests are naturally idempotent and the API ignores the header on read-only endpoints.
+- **Let keys expire naturally.** Cached responses expire after 24 hours. Don't rely on idempotency keys for longer-term deduplication.
+
+## Relationship with Optimistic Locking
+
+The Store API also uses [optimistic locking](/api-reference/store-api/introduction) via the `state_lock_version` field on orders. These mechanisms complement each other:
+
+| Mechanism | Prevents | Scope |
+|-----------|----------|-------|
+| **Idempotency keys** | Duplicate operations from retries | Per-request deduplication |
+| **Optimistic locking** (`state_lock_version`) | Concurrent modifications | Conflict detection between clients |
+
+Use both together for robust checkout flows: idempotency keys protect against network retries, while `state_lock_version` detects when another client has modified the order.