@spree/docs 0.1.15 → 0.1.17

package/dist/api-reference/webhooks-events.md

@@ -348,7 +348,7 @@ Variant event payloads include pricing, stock status, and always-included `optio
   "is_master": false,
   "options_text": "Size: M, Color: Black",
   "track_inventory": true,
-  "image_count": 2,
+  "media_count": 2,
   "thumbnail": "https://cdn.example.com/images/tote-bag-black.jpg",
   "purchasable": true,
   "in_stock": true,

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

@@ -183,7 +183,6 @@ pnpm dev
 | Package | Path | Description |
 |---|---|---|
 | `@spree/sdk` | `packages/sdk` | TypeScript SDK for the Spree Storefront API |
-| `@spree/next` | `packages/next` | Next.js integration (server actions, caching, cookie-based auth) |
 
 ### Common commands
 
@@ -317,7 +316,7 @@ To help us review your PR quickly:
 - **Describe your changes.** Explain what you changed and why. Include screenshots for UI changes.
 - **Add tests.** All new features and bug fixes should include appropriate test coverage.
 - **Update documentation.** If your change affects user-facing behavior, update the relevant docs.
-- **Include a changeset** (TypeScript packages only). Run `pnpm changeset` if your change affects `@spree/sdk` or `@spree/next`.
+- **Include a changeset** (TypeScript packages only). Run `pnpm changeset` if your change affects `@spree/sdk`.
 - **Ensure CI passes.** PRs with failing CI will not be reviewed.
 
 ## Reporting Bugs

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

@@ -164,7 +164,6 @@ Spree is distributed as a set of packages:
 | Package | Purpose |
 |---------|---------|
 | [`@spree/sdk`](../sdk/quickstart.md) | TypeScript SDK for Store API and Admin API |
-| [`@spree/next`](../storefront/nextjs/spree-next-package.md) | Next.js integration — server actions, caching, cookie-based auth |
 
 > **INFO:** For headless commerce, you only need the `spree` package. Build your customer-facing frontend with any technology (Next.js, Nuxt, mobile apps) using the Store API and SDK.
 

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

@@ -165,27 +165,9 @@ Each webhook request includes these headers:
 
 To ensure webhooks are genuinely from your Spree store, verify the signature.
 
-#### Next.js (recommended)
+#### Next.js
 
-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)
-    },
-  },
-})
-```
+The [Spree Storefront](https://github.com/spree/storefront) includes a ready-made webhook route handler with signature verification and event routing. See the [storefront email docs](../storefront/nextjs/customization.md#transactional-emails) for details.
 
 #### Any JavaScript/TypeScript framework
 

package/dist/developer/customization/metadata.md

@@ -36,8 +36,6 @@ const cart = await client.carts.create({
   metadata: { source: 'mobile_app', campaign: 'summer_sale' }
 })
 
-// @spree/next
-const cart = await getOrCreateCart({ source: 'mobile_app' })
 ```
 
 ### Adding items

package/dist/developer/deployment/emails.md

@@ -35,7 +35,7 @@ RESEND_API_KEY=re_your_resend_api_key
 EMAIL_FROM=Your Store <orders@your-domain.com>
 ```
 
-3. **The storefront handles everything else** — signature verification, event routing, email rendering, and delivery are built into `@spree/next/webhooks`. See the [Next.js storefront email docs](../storefront/nextjs/customization.md#transactional-emails) for template customization.
+3. **The storefront handles everything else** — signature verification, event routing, email rendering, and delivery are built in. See the [Next.js storefront email docs](../storefront/nextjs/customization.md#transactional-emails) for template customization.
 
 ### Supported Events
 

package/dist/developer/storefront/nextjs/architecture.md

@@ -9,10 +9,10 @@ The storefront follows a **server-first architecture** where all API calls are m
 
 ```
 Browser → Server Action → @spree/sdk → Spree API
-         (with httpOnly cookies via @spree/next helpers)
+         (with httpOnly cookies via src/lib/spree helpers)
 ```
 
-- **Server Actions** (`src/lib/data/`) — call `@spree/sdk` directly with auth/cookie helpers from `@spree/next`
+- **Server Actions** (`src/lib/data/`) — call `@spree/sdk` directly with auth/cookie helpers from `src/lib/spree`
 - **httpOnly Cookies** — auth tokens, cart tokens, and locale are stored securely
 - **No Client-Side API Calls** — the Spree API key stays on the server
 - **Auto-Localization** — locale and country are read from cookies via `getLocaleOptions()`
@@ -85,13 +85,13 @@ src/
 
 1. User submits login form
 2. Server action calls `@spree/sdk` to authenticate
-3. JWT token is stored in an httpOnly cookie via `@spree/next` cookie helpers
+3. JWT token is stored in an httpOnly cookie via `src/lib/spree` cookie helpers
 4. Subsequent requests use `withAuthRefresh()` which reads the token from cookies automatically
 5. Token is never accessible to client-side JavaScript
 
 ```typescript
 // src/lib/data/customer.ts
-import { getClient, withAuthRefresh, setAccessToken, setRefreshToken } from '@spree/next'
+import { getClient, withAuthRefresh, setAccessToken, setRefreshToken } from '@/lib/spree'
 
 export async function login(email: string, password: string) {
   const result = await getClient().auth.login({ email, password })
@@ -117,11 +117,11 @@ The storefront supports multiple countries and currencies via URL segments:
 /uk/en/products          # UK store, English
 ```
 
-A middleware (`src/proxy.ts`) uses `createSpreeMiddleware` from `@spree/next` to detect the visitor's country and locale, then redirects to the correct URL prefix. The `CountrySwitcher` component lets users change regions manually.
+A middleware (`src/proxy.ts`) uses `createSpreeMiddleware` from `src/lib/spree` to detect the visitor's country and locale, then redirects to the correct URL prefix. The `CountrySwitcher` component lets users change regions manually.
 
 ## Server Actions
 
-All data fetching is done through server actions in `src/lib/data/`. These call `@spree/sdk` directly, using `@spree/next` helpers for auth and locale:
+All data fetching is done through server actions in `src/lib/data/`. These call `@spree/sdk` directly, using `src/lib/spree` helpers for auth and locale:
 
 ```typescript
 // Products — use getLocaleOptions() for locale-aware reads

package/dist/developer/storefront/nextjs/customization.md

@@ -111,7 +111,7 @@ To customize API behavior, modify the server actions in `src/lib/data/`. Each fi
 | `gift-cards.ts` | Gift card management |
 | `utils.ts` | Shared helpers (error handling, fallbacks) |
 
-These server actions call `@spree/sdk` directly, using `@spree/next` helpers for auth cookies and locale resolution. You can add custom logic, caching strategies, or additional transformations as needed.
+These server actions call `@spree/sdk` directly, using helpers in `src/lib/spree/` for auth cookies and locale resolution. You can add custom logic, caching strategies, or additional transformations as needed.
 
 ## Adding New Pages
 
@@ -163,10 +163,10 @@ Opens the react-email dev server with mock data for all templates at `http://loc
 
 ### Webhook Handler
 
-The webhook route (`src/app/api/webhooks/spree/route.ts`) uses `createWebhookHandler` from `@spree/next/webhooks`:
+The webhook route (`src/app/api/webhooks/spree/route.ts`) uses `createWebhookHandler` from `src/lib/spree/webhooks`:
 
 ```typescript
-import { createWebhookHandler } from '@spree/next/webhooks'
+import { createWebhookHandler } from '@/lib/spree/webhooks'
 
 export const POST = createWebhookHandler({
   secret: process.env.SPREE_WEBHOOK_SECRET!,
@@ -198,4 +198,4 @@ For full setup details, see [Sending out Emails](../../deployment/emails.md).
 
 ## Building a Custom Storefront
 
-If you prefer to build from scratch instead of forking the starter, you can use the `@spree/next` and `@spree/sdk` packages directly in any Next.js application. See the [@spree/next Package](spree-next-package.md) documentation for the complete API reference.
+If you prefer to build from scratch instead of forking the starter, you can use the `@spree/sdk` package directly in any Next.js application. The storefront's `src/lib/spree/` directory contains reusable helpers for cookie-based auth, locale resolution, middleware, and webhook verification that you can copy into your own project.

package/dist/developer/storefront/nextjs/quickstart.md

@@ -12,7 +12,6 @@ The [Spree Storefront](https://github.com/spree/storefront) is a production-read
 - **Tailwind CSS 4** - Utility-first styling
 - **TypeScript 5** - Full type safety
 - **[@spree/sdk](https://github.com/spree/spree/tree/main/packages/sdk)** - Official Spree Commerce SDK
-- **[@spree/next](https://github.com/spree/spree/tree/main/packages/next)** - Cookie-based auth, middleware, and webhook helpers
 - **Sentry** - Error tracking and performance monitoring
 
 ## Features

package/package.json

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

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

@@ -1,247 +0,0 @@
----
-title: "@spree/next Package"
-description: Next.js integration library — cookie-based auth, middleware, and webhook helpers
----
-
-The `@spree/next` package provides the server-side plumbing for building a Next.js storefront with `@spree/sdk`: JWT token lifecycle, httpOnly cookie management, locale/country middleware, and webhook verification.
-
-Your storefront calls `@spree/sdk` directly for all API operations. `@spree/next` handles the Next.js-specific concerns — cookies, auth refresh, and middleware — so you don't have to.
-
-## Installation
-
-```bash
-npm install @spree/next @spree/sdk
-```
-
-## Configuration
-
-### Auto-initialization
-
-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
-
-```typescript
-// lib/storefront.ts
-import { initSpreeNext } from '@spree/next';
-
-initSpreeNext({
-  baseUrl: process.env.SPREE_API_URL!,
-  publishableKey: process.env.SPREE_PUBLISHABLE_KEY!,
-  cartCookieName: '_spree_cart_token',     // default
-  accessTokenCookieName: '_spree_jwt',     // default
-  defaultLocale: 'en',
-  defaultCurrency: 'USD',
-  defaultCountry: 'US',
-});
-```
-
-## Architecture
-
-`@spree/next` provides four things:
-
-1. **`getClient()`** — singleton `@spree/sdk` Client instance (auto-inits from env vars)
-2. **Auth helpers** — `withAuthRefresh()` for JWT lifecycle, cookie read/write for tokens
-3. **Locale resolution** — `getLocaleOptions()` reads country/locale from cookies
-4. **Framework helpers** — `createSpreeMiddleware()` for URL routing, `createWebhookHandler()` for webhooks
-
-Your storefront's server actions call `@spree/sdk` directly, using these helpers for auth and cookies:
-
-```
-Server Action → getClient().products.list(params, localeOptions)
-Server Action → withAuthRefresh(fn) → getClient().customer.get(options)
-Server Action → getCartOptions() → getClient().carts.items.create(...)
-```
-
-## Auth Helpers
-
-### `withAuthRefresh(fn)`
-
-Wraps an authenticated SDK call with automatic token management:
-
-1. Reads JWT from cookie
-2. Proactively refreshes if expiring within 5 minutes
-3. Executes your function with `{ token }` options
-4. On 401: refreshes token and retries once
-5. On refresh failure: clears cookies and throws
-
-```typescript
-'use server';
-
-import { getClient, withAuthRefresh } from '@spree/next';
-
-export async function getCustomer() {
-  return withAuthRefresh(async (options) => {
-    return getClient().customer.get(options);
-  });
-}
-
-export async function listAddresses() {
-  return withAuthRefresh(async (options) => {
-    return getClient().customer.addresses.list(undefined, options);
-  });
-}
-```
-
-### `getAuthOptions()`
-
-Lower-level helper that returns `{ token }` or `{}` with proactive refresh. Use when you need the token but want to handle errors yourself.
-
-## Cookie Management
-
-All cookie helpers are async (they use Next.js `cookies()` API):
-
-```typescript
-import {
-  // Cart
-  getCartToken, getCartId, setCartCookies, clearCartCookies,
-  getCartOptions,   // { spreeToken, token } for cart SDK calls
-  requireCartId,    // throws if no cart
-
-  // Auth
-  getAccessToken, setAccessToken, clearAccessToken,
-  getRefreshToken, setRefreshToken, clearRefreshToken,
-} from '@spree/next';
-```
-
-### Cart operations pattern
-
-```typescript
-'use server';
-
-import { getClient, getCartOptions, requireCartId } from '@spree/next';
-
-export async function updateCartItem(lineItemId: string, quantity: number) {
-  const options = await getCartOptions();
-  const cartId = await requireCartId();
-  return getClient().carts.items.update(cartId, lineItemId, { quantity }, options);
-}
-```
-
-### Auth operations pattern
-
-```typescript
-'use server';
-
-import { getClient, setAccessToken, setRefreshToken, getCartToken, getCartId } from '@spree/next';
-
-export async function login(email: string, password: string) {
-  const result = await getClient().auth.login({ email, password });
-  await setAccessToken(result.token);
-  await setRefreshToken(result.refresh_token);
-
-  // Associate guest cart if one exists
-  const cartToken = await getCartToken();
-  const cartId = await getCartId();
-  if (cartToken && cartId) {
-    await getClient().carts.associate(cartId, {
-      token: result.token,
-      spreeToken: cartToken,
-    }).catch(() => {}); // non-fatal
-  }
-
-  return { success: true, user: result.user };
-}
-```
-
-## Locale Resolution
-
-`getLocaleOptions()` reads country and locale from cookies (set by middleware or explicitly). All data-fetching server actions should use this:
-
-```typescript
-'use server';
-
-import { getClient, getLocaleOptions } from '@spree/next';
-
-export async function getProducts(params?: { limit?: number }) {
-  const options = await getLocaleOptions();
-  return getClient().products.list(params, options);
-}
-
-export async function getCategory(idOrPermalink: string) {
-  const options = await getLocaleOptions();
-  return getClient().categories.get(idOrPermalink, undefined, options);
-}
-```
-
-## Middleware
-
-Handles URL-based country/locale routing. Detects country from cookies, geo headers (Vercel/Cloudflare), or defaults, then redirects to `/{country}/{locale}/...`:
-
-```typescript
-// middleware.ts
-import { createSpreeMiddleware } from '@spree/next/middleware';
-
-export default createSpreeMiddleware({
-  defaultCountry: 'us',
-  defaultLocale: 'en',
-});
-
-export const config = {
-  matcher: ['/((?!_next/static|_next/image|favicon.ico|.*\\..*$).*)'],
-};
-```
-
-## 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
-
-Import types directly from `@spree/sdk`:
-
-```typescript
-import type {
-  Product, Order, Cart, LineItem, Variant,
-  Category, Country, Currency, Address, Customer,
-  CreditCard, GiftCard, Fulfillment, DeliveryRate,
-  Payment, PaymentSession, PaginatedResponse,
-  AddressParams, SpreeError,
-} from '@spree/sdk';
-```