@spree/docs 0.1.8 → 0.1.9

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

@@ -80,9 +80,14 @@ You can filter by associated model attributes using underscore notation:
 
 
 ```typescript SDK
-// Products in a specific category
+// Products in a specific category (includes descendants)
 const products = await client.products.list({
-  categories_id_eq: 'ctg_abc123',
+  in_category: 'ctg_abc123',
+})
+
+// Multiple categories (OR logic, checkbox filters)
+const products = await client.products.list({
+  in_categories: ['ctg_abc123', 'ctg_def456'],
 })
 
 // Categories at a specific depth
@@ -92,10 +97,10 @@ const categories = await client.categories.list({
 ```
 
 ```bash cURL
-# Products in a specific category
+# Products in a specific category (includes descendants)
 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'
+  --data-urlencode 'q[in_category]=ctg_abc123'
 
 # Top-level categories only
 curl -G 'http://localhost:3000/api/v3/store/categories' \

package/dist/api-reference/store.yaml

@@ -7943,12 +7943,20 @@ paths:
         description: Filter by name containing string
         schema:
           type: string
-      - name: q[categories_id_eq]
+      - name: q[in_category]
         in: query
         required: false
-        description: Filter by category ID
+        description: Filter by category prefixed ID (includes descendants)
         schema:
           type: string
+      - name: q[in_categories][]
+        in: query
+        required: false
+        description: Filter by multiple category prefixed IDs (OR logic, includes descendants)
+        schema:
+          type: array
+          items:
+            type: string
       - name: q[price_gte]
         in: query
         required: false

package/dist/developer/core-concepts/search-filtering.md

@@ -73,9 +73,14 @@ const { data: products } = await client.categories.products.list('clothing/shirt
   limit: 12,
 })
 
-// Or filter by category ID
+// Or filter by category ID (includes descendants)
 const { data: products } = await client.products.list({
-  categories_id_eq: 'ctg_xxx',
+  in_category: 'ctg_xxx',
+})
+
+// Multiple categories (OR logic, checkbox filters)
+const { data: products } = await client.products.list({
+  in_categories: ['ctg_shirts', 'ctg_pants'],
 })
 ```
 
@@ -84,8 +89,12 @@ const { data: products } = await client.products.list({
 curl 'https://api.mystore.com/api/v3/store/categories/clothing/shirts/products?limit=12' \
   -H 'Authorization: Bearer spree_pk_xxx'
 
-# Filter by category ID
-curl 'https://api.mystore.com/api/v3/store/products?q[categories_id_eq]=ctg_xxx' \
+# Filter by category ID (includes descendants)
+curl 'https://api.mystore.com/api/v3/store/products?q[in_category]=ctg_xxx' \
+  -H 'Authorization: Bearer spree_pk_xxx'
+
+# Multiple categories (OR logic)
+curl 'https://api.mystore.com/api/v3/store/products?q[in_categories][]=ctg_shirts&q[in_categories][]=ctg_pants' \
   -H 'Authorization: Bearer spree_pk_xxx'
 ```
 

package/dist/developer/core-concepts/webhooks.md

@@ -163,22 +163,56 @@ Each webhook request includes these headers:
 
 ### Verifying Webhook Signatures
 
-To ensure webhooks are genuinely from your Spree store, verify the signature:
+To ensure webhooks are genuinely from your Spree store, verify the signature.
+
+#### Next.js (recommended)
+
+Use `@spree/next/webhooks` for a ready-made Route Handler:
+
+```typescript
+// src/app/api/webhooks/spree/route.ts
+import { createWebhookHandler } from '@spree/next/webhooks'
+
+export const POST = createWebhookHandler({
+  secret: process.env.SPREE_WEBHOOK_SECRET!,
+  handlers: {
+    'order.completed': async (event) => {
+      // event.data is the order payload (same shape as Store API)
+      await sendOrderConfirmationEmail(event.data)
+    },
+    'order.canceled': async (event) => {
+      await sendCancellationEmail(event.data)
+    },
+  },
+})
+```
 
-```ruby
-# In your webhook receiver
-def verify_webhook(request)
-  payload = request.body.read
-  signature = request.headers['X-Spree-Webhook-Signature']
-  secret_key = ENV['SPREE_WEBHOOK_SECRET'] # Your endpoint's secret_key
+#### Any JavaScript/TypeScript framework
 
-  expected = OpenSSL::HMAC.hexdigest('SHA256', secret_key, payload)
+Use `@spree/sdk/webhooks` for framework-agnostic verification:
 
-  ActiveSupport::SecurityUtils.secure_compare(signature, expected)
-end
+```typescript
+import { verifyWebhookSignature } from '@spree/sdk/webhooks'
+import type { WebhookEvent } from '@spree/sdk/webhooks'
+import type { Order } from '@spree/sdk'
+
+// Hono, Cloudflare Workers, or any Web Fetch API-based framework
+app.post('/webhooks/spree', async (req, res) => {
+  const body = await req.text()
+  const signature = req.headers['x-spree-webhook-signature']
+  const timestamp = req.headers['x-spree-webhook-timestamp']
+
+  if (!verifyWebhookSignature(body, signature, timestamp, process.env.SPREE_WEBHOOK_SECRET!)) {
+    return res.status(401).json({ error: 'Invalid signature' })
+  }
+
+  const event: WebhookEvent<Order> = JSON.parse(body)
+  // handle event...
+  res.json({ received: true })
+})
 ```
 
-Example in a Rails controller:
+#### Ruby
 
 ```ruby
 class WebhooksController < ApplicationController
@@ -209,7 +243,8 @@ class WebhooksController < ApplicationController
     request.body.rewind
 
     signature = request.headers['X-Spree-Webhook-Signature']
-    expected = OpenSSL::HMAC.hexdigest('SHA256', ENV['SPREE_WEBHOOK_SECRET'], payload)
+    timestamp = request.headers['X-Spree-Webhook-Timestamp']
+    expected = OpenSSL::HMAC.hexdigest('SHA256', ENV['SPREE_WEBHOOK_SECRET'], "#{timestamp}.#{payload}")
 
     ActiveSupport::SecurityUtils.secure_compare(signature.to_s, expected)
   end

package/dist/developer/storefront/nextjs/spree-next-package.md

@@ -20,6 +20,9 @@ Set environment variables and the client initializes automatically:
 ```env
 SPREE_API_URL=https://api.mystore.com
 SPREE_PUBLISHABLE_KEY=spree_pk_xxx
+
+# Required for webhook-based emails (see Webhooks section below)
+SPREE_WEBHOOK_SECRET=your_webhook_endpoint_secret_key
 ```
 
 ### Explicit initialization
@@ -284,6 +287,48 @@ const products = await listProducts({ limit: 10 }, { locale: 'fr', country: 'FR'
 const category = await getCategory('clothing/shirts', {}, { locale: 'de', country: 'DE' });
 ```
 
+## Webhooks
+
+Handle Spree webhook events in your Next.js app with `@spree/next/webhooks`:
+
+```typescript
+// src/app/api/webhooks/spree/route.ts
+import { createWebhookHandler } from '@spree/next/webhooks'
+
+export const POST = createWebhookHandler({
+  secret: process.env.SPREE_WEBHOOK_SECRET!,
+  handlers: {
+    'order.completed': async (event) => {
+      await sendOrderConfirmationEmail(event.data)
+    },
+    'order.canceled': async (event) => {
+      await sendCancellationEmail(event.data)
+    },
+    'order.shipped': async (event) => {
+      await sendShippingNotification(event.data)
+    },
+    'customer.password_reset_requested': async (event) => {
+      await sendPasswordResetEmail(event.data)
+    },
+  },
+})
+```
+
+The handler verifies HMAC-SHA256 signatures, rejects replayed requests, routes events to your handlers, and returns 200 immediately (handlers run async).
+
+### Local development
+
+Webhooks require a publicly accessible URL. Use [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/install-and-setup/) for local development:
+
+```bash
+brew install cloudflared
+cloudflared tunnel --url http://localhost:3001
+```
+
+Then create a webhook endpoint in **Spree Admin → Settings → Developers → Webhooks** pointing to your tunnel URL + `/api/webhooks/spree`.
+
+For more details, see [Webhooks](../../core-concepts/webhooks.md).
+
 ## TypeScript
 
 All types are re-exported from `@spree/sdk`:

package/package.json

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