@spree/docs 0.1.0

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

@@ -0,0 +1,399 @@
+---
+title: "Querying"
+sidebarTitle: "Querying"
+description: "How to filter, sort, and paginate Store API results using Ransack"
+---
+
+The Store API uses [Ransack](https://activerecord-hackery.github.io/ransack/) for filtering and sorting collection endpoints. All query parameters are passed via the `q` parameter.
+
+## Filtering
+
+Pass filter conditions using the `q` parameter with Ransack predicates:
+
+
+```typescript SDK
+const products = await client.products.list({
+  name_cont: 'shirt',
+  price_gte: 20,
+  price_lte: 100,
+})
+```
+
+```bash cURL
+curl -G 'http://localhost:3000/api/v3/store/products' \
+  -H 'X-Spree-Api-Key: spree_pk_xxx' \
+  --data-urlencode 'q[name_cont]=shirt' \
+  --data-urlencode 'q[price_gte]=20' \
+  --data-urlencode 'q[price_lte]=100'
+```
+
+
+### Common Predicates
+
+| Predicate | Description | SDK | cURL |
+|-----------|-------------|-----|------|
+| `eq` | Equals | `status_eq: 'active'` | `q[status_eq]=active` |
+| `not_eq` | Not equals | `status_not_eq: 'draft'` | `q[status_not_eq]=draft` |
+| `cont` | Contains (case-insensitive) | `name_cont: 'shirt'` | `q[name_cont]=shirt` |
+| `start` | Starts with | `name_start: 'Spree'` | `q[name_start]=Spree` |
+| `end` | Ends with | `slug_end: 'tote'` | `q[slug_end]=tote` |
+| `lt` | Less than | `price_lt: 50` | `q[price_lt]=50` |
+| `lteq` | Less than or equal | `price_lteq: 50` | `q[price_lteq]=50` |
+| `gt` | Greater than | `price_gt: 10` | `q[price_gt]=10` |
+| `gteq` | Greater than or equal | `price_gteq: 10` | `q[price_gteq]=10` |
+| `in` | In a list | `status_in: ['active', 'draft']` | `q[status_in][]=active&q[status_in][]=draft` |
+| `null` | Is null | `deleted_at_null: true` | `q[deleted_at_null]=true` |
+| `not_null` | Is not null | `completed_at_not_null: true` | `q[completed_at_not_null]=true` |
+| `present` | Is present (not empty) | `description_present: true` | `q[description_present]=true` |
+| `blank` | Is blank (null or empty) | `description_blank: true` | `q[description_blank]=true` |
+| `true` | Is true (boolean) | `purchasable_true: 1` | `q[purchasable_true]=1` |
+| `false` | Is false (boolean) | `purchasable_false: 1` | `q[purchasable_false]=1` |
+
+> **NOTE:** The SDK automatically wraps filter keys in `q[...]` and appends `[]` for array values — just pass flat params.
+
+### Combining Filters
+
+Multiple filters are combined with AND logic:
+
+
+```typescript SDK
+// Products that contain "shirt" AND cost between $20-$100
+const products = await client.products.list({
+  name_cont: 'shirt',
+  price_gteq: 20,
+  price_lteq: 100,
+})
+```
+
+```bash cURL
+curl -G 'http://localhost:3000/api/v3/store/products' \
+  -H 'X-Spree-Api-Key: spree_pk_xxx' \
+  --data-urlencode 'q[name_cont]=shirt' \
+  --data-urlencode 'q[price_gteq]=20' \
+  --data-urlencode 'q[price_lteq]=100'
+```
+
+
+### Filtering by Association
+
+You can filter by associated model attributes using underscore notation:
+
+
+```typescript SDK
+// Products in a specific category
+const products = await client.products.list({
+  categories_id_eq: 'ctg_abc123',
+})
+
+// Categories at a specific depth
+const categories = await client.categories.list({
+  depth_eq: 1,
+})
+```
+
+```bash cURL
+# Products in a specific category
+curl -G 'http://localhost:3000/api/v3/store/products' \
+  -H 'X-Spree-Api-Key: spree_pk_xxx' \
+  --data-urlencode 'q[categories_id_eq]=ctg_abc123'
+
+# Top-level categories only
+curl -G 'http://localhost:3000/api/v3/store/categories' \
+  -H 'X-Spree-Api-Key: spree_pk_xxx' \
+  --data-urlencode 'q[depth_eq]=1'
+```
+
+
+## Product Scopes
+
+Products support additional filter scopes beyond standard Ransack predicates:
+
+
+```typescript SDK
+const products = await client.products.list({
+  price_gte: 20,                                        // Minimum price
+  price_lte: 100,                                       // Maximum price
+  with_option_value_ids: ['optval_abc', 'optval_def'], // Filter by option values
+  in_stock: true,                                       // Only in-stock products
+})
+```
+
+```bash cURL
+curl -G 'http://localhost:3000/api/v3/store/products' \
+  -H 'X-Spree-Api-Key: spree_pk_xxx' \
+  --data-urlencode 'q[price_gte]=20' \
+  --data-urlencode 'q[price_lte]=100' \
+  --data-urlencode 'q[with_option_value_ids][]=optval_abc' \
+  --data-urlencode 'q[with_option_value_ids][]=optval_def' \
+  --data-urlencode 'q[in_stock]=true'
+```
+
+
+| Scope | Description | SDK | cURL |
+|-------|-------------|-----|------|
+| `price_gte` | Minimum price | `price_gte: 20` | `q[price_gte]=20` |
+| `price_lte` | Maximum price | `price_lte: 100` | `q[price_lte]=100` |
+| `with_option_value_ids` | Filter by option value IDs | `with_option_value_ids: ['optval_abc']` | `q[with_option_value_ids][]=optval_abc` |
+| `in_stock` | Only in-stock products | `in_stock: true` | `q[in_stock]=true` |
+| `out_of_stock` | Only out-of-stock products | `out_of_stock: true` | `q[out_of_stock]=true` |
+| `search` | Full-text search | `search: 'shirt'` | `q[search]=shirt` |
+
+## Sorting
+
+Use the `sort` parameter on any list endpoint. Prefix a field with `-` for descending order (ascending is the default). This follows the [JSON:API sorting convention](https://jsonapi.org/format/#fetching-sorting).
+
+
+```typescript SDK
+// Sort by price (low to high)
+const products = await client.products.list({
+  sort: 'price',
+})
+
+// Sort by price (high to low)
+const products = await client.products.list({
+  sort: '-price',
+})
+
+// Sort by best selling
+const products = await client.products.list({
+  sort: 'best_selling',
+})
+```
+
+```bash cURL
+# Sort by price low to high
+curl -G 'http://localhost:3000/api/v3/store/products' \
+  -H 'X-Spree-Api-Key: spree_pk_xxx' \
+  -d 'sort=price'
+
+# Sort by price high to low
+curl -G 'http://localhost:3000/api/v3/store/products' \
+  -H 'X-Spree-Api-Key: spree_pk_xxx' \
+  -d 'sort=-price'
+```
+
+
+### Product Sort Options
+
+| Value | Description |
+|-------|-------------|
+| `manual` | Manual sort order (default, uses taxon position) |
+| `best_selling` | Best selling products first |
+| `price` | Price low to high |
+| `-price` | Price high to low |
+| `name` | Name A-Z |
+| `-name` | Name Z-A |
+| `-available_on` | Newest first |
+| `available_on` | Oldest first |
+
+### Sorting Other Resources
+
+The `sort` parameter works on all list endpoints. Use any sortable column name:
+
+
+```typescript SDK
+// Categories sorted by name
+const categories = await client.categories.list({
+  sort: 'name',
+})
+
+// Customer orders sorted by most recent
+const orders = await client.customer.orders.list({
+  sort: '-completed_at',
+})
+```
+
+```bash cURL
+# Categories sorted by name
+curl -G 'http://localhost:3000/api/v3/store/categories' \
+  -H 'X-Spree-Api-Key: spree_pk_xxx' \
+  -d 'sort=name'
+
+# Customer orders by most recent
+curl -G 'http://localhost:3000/api/v3/store/customer/orders' \
+  -H 'X-Spree-Api-Key: spree_pk_xxx' \
+  -H 'Authorization: Bearer <token>' \
+  -d 'sort=-completed_at'
+```
+
+
+## Expanding Associations
+
+Use the `expand` parameter to include associated resources in the response. Pass a comma-separated list of association names:
+
+
+```typescript SDK
+const product = await client.products.get('spree-tote', {
+  expand: ['variants', 'images'],
+})
+```
+
+```bash cURL
+curl -G 'http://localhost:3000/api/v3/store/products/spree-tote' \
+  -H 'X-Spree-Api-Key: spree_pk_xxx' \
+  -d 'expand=variants,images'
+```
+
+
+### Nested Expand
+
+Use dot notation to expand nested associations (up to 4 levels deep):
+
+
+```typescript SDK
+// Expand variants and their images in one request
+const product = await client.products.get('spree-tote', {
+  expand: ['variants.images'],
+})
+
+// Multiple nested expands
+const product = await client.products.get('spree-tote', {
+  expand: ['variants.images', 'variants.metafields', 'option_types'],
+})
+
+// Category with nested children
+const category = await client.categories.get('clothing/shirts', {
+  expand: ['children.children'],  // Two levels of subcategories
+})
+```
+
+```bash cURL
+# Expand variants with their images
+curl -G 'http://localhost:3000/api/v3/store/products/spree-tote' \
+  -H 'X-Spree-Api-Key: spree_pk_xxx' \
+  -d 'expand=variants.images'
+
+# Multiple nested expands
+curl -G 'http://localhost:3000/api/v3/store/products/spree-tote' \
+  -H 'X-Spree-Api-Key: spree_pk_xxx' \
+  -d 'expand=variants.images,variants.metafields,option_types'
+```
+
+
+### Rules
+
+- Maximum depth is **4 levels** (e.g., `a.b.c.d`)
+- A nested expand automatically includes its parent — `expand=variants.images` expands both `variants` and their `images`
+- Nested expand only applies to conditional associations (those controlled by `expand`)
+
+## Field Selection
+
+Use the `fields` parameter to request only specific fields in the response. This reduces payload size for bandwidth-sensitive clients like mobile apps or server-side rendering.
+
+
+```typescript SDK
+// Only return name, slug, and price
+const products = await client.products.list({
+  fields: ['name', 'slug', 'price', 'display_price'],
+})
+
+// Works on single resources too
+const product = await client.products.get('spree-tote', {
+  fields: ['name', 'slug', 'price'],
+})
+```
+
+```bash cURL
+curl -G 'http://localhost:3000/api/v3/store/products' \
+  -H 'X-Spree-Api-Key: spree_pk_xxx' \
+  -d 'fields=name,slug,price,display_price'
+```
+
+
+```json
+{
+  "data": [
+    {
+      "id": "prod_86Rf07xd4z",
+      "name": "Spree Tote",
+      "slug": "spree-tote",
+      "price": "15.99",
+      "display_price": "$15.99"
+    }
+  ],
+  "meta": { ... }
+}
+```
+
+### Rules
+
+- The `id` field is **always included**, even if not listed in `fields`
+- Omitting `fields` returns all fields (default behavior)
+- Field selection applies to the top-level resource only — expanded associations always return their full set of fields
+- Expanded associations are **always included** in the response regardless of `fields` — `?fields=name&expand=variants` returns `id`, `name`, and `variants`
+
+> **NOTE:** The SDK TypeScript types remain fully typed regardless of field selection. When using `fields`, be aware that only the requested fields will be present at runtime.
+
+## Pagination
+
+All collection endpoints return paginated results. Control pagination with `page` and `limit` parameters:
+
+
+```typescript SDK
+const { data: products, meta } = await client.products.list({
+  page: 2,
+  limit: 10,
+})
+
+// meta contains pagination info
+console.log(meta)
+// {
+//   page: 2,
+//   limit: 10,
+//   count: 85,
+//   pages: 9,
+//   from: 11,
+//   to: 20,
+//   in: 10,
+//   previous: 1,
+//   next: 3
+// }
+```
+
+```bash cURL
+curl -G 'http://localhost:3000/api/v3/store/products' \
+  -H 'X-Spree-Api-Key: spree_pk_xxx' \
+  -d 'page=2' \
+  -d 'limit=10'
+```
+
+
+### Pagination Parameters
+
+| Parameter | Default | Max | Description |
+|-----------|---------|-----|-------------|
+| `page` | `1` | - | Page number |
+| `limit` | `25` | `100` | Number of records per page |
+
+### Pagination Metadata
+
+Collection responses include a `meta` object with pagination info:
+
+```json
+{
+  "data": [...],
+  "meta": {
+    "page": 1,
+    "limit": 25,
+    "count": 85,
+    "pages": 4,
+    "from": 1,
+    "to": 25,
+    "in": 25,
+    "previous": null,
+    "next": 2
+  }
+}
+```
+
+| Field | Description |
+|-------|-------------|
+| `page` | Current page number |
+| `limit` | Records per page |
+| `count` | Total number of records |
+| `pages` | Total number of pages |
+| `from` | Starting record number on this page |
+| `to` | Ending record number on this page |
+| `in` | Number of records returned on this page |
+| `previous` | Previous page number (null if first page) |
+| `next` | Next page number (null if last page) |

package/dist/api-reference/store-api/rate-limitting.md

@@ -0,0 +1,103 @@
+---
+title: "Rate Limiting"
+sidebarTitle: "Rate Limiting"
+description: "Rate limits and throttling for the Store API"
+---
+
+The Store API enforces rate limits to protect against abuse and ensure fair usage. Rate limits are applied per API key or per IP address depending on the endpoint.
+
+## Default Limits
+
+| Endpoint | Limit | Scope | Window |
+|----------|-------|-------|--------|
+| All endpoints | 300 requests | Per API key | 1 minute |
+| `POST /auth/login` | 5 requests | Per IP | 1 minute |
+| `POST /customers` | 3 requests | Per IP | 1 minute |
+| `POST /auth/refresh` | 10 requests | Per IP | 1 minute |
+| `POST /auth/oauth/callback` | 5 requests | Per IP | 1 minute |
+
+The global rate limit is tracked by your publishable API key (`X-Spree-Api-Key`). If the key is not provided, the limit falls back to the client's IP address.
+
+Authentication endpoints have stricter per-IP limits to prevent brute-force attacks.
+
+## Rate Limit Headers
+
+Every Store API response includes headers that show your current rate limit usage:
+
+| Header | Description |
+|--------|-------------|
+| `X-RateLimit-Limit` | Maximum number of requests allowed per window |
+| `X-RateLimit-Remaining` | Number of requests remaining in the current window |
+| `Retry-After` | Seconds to wait before retrying (only present when limit is reached) |
+
+Example response headers:
+
+```
+HTTP/1.1 200 OK
+X-RateLimit-Limit: 300
+X-RateLimit-Remaining: 295
+```
+
+## Rate Limit Response
+
+When you exceed the rate limit, the API returns a `429 Too Many Requests` response:
+
+```json
+{
+  "error": {
+    "code": "rate_limit_exceeded",
+    "message": "Too many requests. Please retry later."
+  }
+}
+```
+
+The response includes rate limit headers and a `Retry-After` header indicating how many seconds to wait before retrying:
+
+```
+HTTP/1.1 429 Too Many Requests
+Content-Type: application/json
+X-RateLimit-Limit: 300
+X-RateLimit-Remaining: 0
+Retry-After: 60
+```
+
+## SDK Retry Handling
+
+The Spree SDK automatically handles rate-limited responses with built-in retry logic and exponential backoff:
+
+```typescript
+import { createClient } from '@spree/sdk'
+
+const client = createClient({
+  baseUrl: 'http://localhost:3000',
+  publishableKey: 'spree_pk_xxx',
+  retry: {
+    maxRetries: 2,         // Number of retry attempts (default: 2)
+    baseDelay: 300,        // Initial delay in ms (default: 300)
+    maxDelay: 10000,       // Maximum delay in ms (default: 10000)
+  },
+})
+```
+
+The SDK respects the `Retry-After` header and only retries on `429` status codes for non-GET requests. For GET/HEAD requests, it also retries on `500`, `502`, `503`, and `504` errors.
+
+## Configuring Rate Limits
+
+If you're self-hosting Spree, you can adjust rate limits in your initializer:
+
+```ruby
+# config/initializers/spree.rb
+Spree::Api::Config[:rate_limit_per_key] = 300  # Global limit per API key
+Spree::Api::Config[:rate_limit_window] = 60    # Window in seconds
+Spree::Api::Config[:rate_limit_login] = 5      # Login attempts per IP
+Spree::Api::Config[:rate_limit_register] = 3   # Registration attempts per IP
+Spree::Api::Config[:rate_limit_refresh] = 10   # Token refresh per IP
+Spree::Api::Config[:rate_limit_oauth] = 5      # OAuth callbacks per IP
+```
+
+Rate limiting uses `Rails.cache` as the backing store. For production environments with multiple application servers, ensure you're using a shared cache store like Redis:
+
+```ruby
+# config/environments/production.rb
+config.cache_store = :redis_cache_store, { url: ENV['REDIS_URL'] }
+```

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

@@ -0,0 +1,185 @@
+---
+title: "Relations"
+sidebarTitle: "Relations"
+description: "How to include related resources in API responses"
+---
+
+By default, the Store API returns only the primary resource attributes to keep responses fast and lightweight. Use the `expand` parameter to expand related resources inline.
+
+## Including Relations
+
+Pass a comma-separated list of relation names via the `expand` query parameter:
+
+
+```typescript SDK
+// Product with variants and images
+const product = await client.products.get('spree-tote', {
+  expand: ['variants', 'images'],
+})
+
+// Access included relations directly
+console.log(product.variants)  // Array of variant objects
+console.log(product.images)    // Array of image objects
+```
+
+```bash cURL
+curl -G 'http://localhost:3000/api/v3/store/products/spree-tote' \
+  -H 'X-Spree-Api-Key: spree_pk_xxx' \
+  -d 'expand=variants,images'
+```
+
+
+## Response Format
+
+Without `expand`, relation fields are omitted from the response:
+
+```json
+{
+  "id": "prod_86Rf07xd4z",
+  "name": "Spree Tote",
+  "slug": "spree-tote",
+  "price": { "amount": "15.99", "currency": "USD" },
+  "created_at": "2025-01-15T10:30:00Z"
+}
+```
+
+With `?expand=variants,images`, the related resources are embedded:
+
+```json
+{
+  "id": "prod_86Rf07xd4z",
+  "name": "Spree Tote",
+  "slug": "spree-tote",
+  "price": { "amount": "15.99", "currency": "USD" },
+  "created_at": "2025-01-15T10:30:00Z",
+  "variants": [
+    {
+      "id": "variant_k5nR8xLq",
+      "sku": "SPR-TOTE-RED",
+      "price": { "amount": "15.99", "currency": "USD" },
+      "in_stock": true,
+      "option_values": [{ "name": "Red", "option_type_name": "Color" }]
+    }
+  ],
+  "images": [
+    {
+      "id": "img_9xPq2wLm",
+      "url": "https://cdn.example.com/spree-tote.jpg",
+      "alt": "Spree Tote"
+    }
+  ]
+}
+```
+
+## Available Relations by Resource
+
+### Products
+
+| Relation | Description |
+|----------|-------------|
+| `variants` | All purchasable variants |
+| `default_variant` | The default variant |
+| `master_variant` | The master variant |
+| `images` | All product images (across all variants) |
+| `option_types` | Option types (e.g., Size, Color) |
+| `categories` | Categories this product belongs to |
+| `metafields` | Public metafields (custom structured data) |
+
+
+```typescript SDK
+const product = await client.products.get('spree-tote', {
+  expand: ['variants', 'images', 'option_types', 'metafields'],
+})
+```
+
+```bash cURL
+curl -G 'http://localhost:3000/api/v3/store/products/spree-tote' \
+  -H 'X-Spree-Api-Key: spree_pk_xxx' \
+  -d 'expand=variants,images,option_types,metafields'
+```
+
+
+### Categories
+
+| Relation | Description |
+|----------|-------------|
+| `ancestors` | Parent categories (for breadcrumbs) |
+| `children` | Direct child categories |
+| `products` | Products in this category |
+
+
+```typescript SDK
+const category = await client.categories.get('clothing/shirts', {
+  expand: ['ancestors', 'children'],
+})
+```
+
+```bash cURL
+curl -G 'http://localhost:3000/api/v3/store/categories/clothing/shirts' \
+  -H 'X-Spree-Api-Key: spree_pk_xxx' \
+  -d 'expand=ancestors,children'
+```
+
+
+### Countries
+
+| Relation | Description |
+|----------|-------------|
+| `states` | States/provinces within the country |
+
+
+```typescript SDK
+const usa = await client.countries.get('US', {
+  expand: ['states'],
+})
+console.log(usa.states) // Array of state objects
+```
+
+```bash cURL
+curl -G 'http://localhost:3000/api/v3/store/countries/US' \
+  -H 'X-Spree-Api-Key: spree_pk_xxx' \
+  -d 'expand=states'
+```
+
+
+## Collections with Includes
+
+The `expand` parameter also works on collection endpoints:
+
+
+```typescript SDK
+// List products with their images and default variant
+const { data: products } = await client.products.list({
+  expand: ['images', 'default_variant'],
+  limit: 12,
+})
+```
+
+```bash cURL
+curl -G 'http://localhost:3000/api/v3/store/products' \
+  -H 'X-Spree-Api-Key: spree_pk_xxx' \
+  -d 'expand=images,default_variant' \
+  -d 'limit=12'
+```
+
+
+## Nested Includes
+
+Use dot notation to include nested relations:
+
+
+```typescript SDK
+// Include variants and their nested option values
+const product = await client.products.get('spree-tote', {
+  expand: ['variants.option_values'],
+})
+```
+
+```bash cURL
+curl -G 'http://localhost:3000/api/v3/store/products/spree-tote' \
+  -H 'X-Spree-Api-Key: spree_pk_xxx' \
+  -d 'expand=variants.option_values'
+```
+
+
+> **NOTE:** Only include relations you actually need. Each included relation requires additional database queries, so requesting unnecessary relations will slow down the response.