@spree/docs 0.1.12 → 0.1.13

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

@@ -165,18 +165,22 @@ When editing a resource (e.g., a product), metafields appear in a dedicated sect
 
 ## Metafields vs Metadata
 
-| Feature | Metafields | Metadata |
+Spree has two permanent, complementary systems for custom data — **metadata for machines, metafields for humans**. They serve different purposes and are not interchangeable. Neither is going away.
+
+| Feature | Metafields | [Metadata](../customization/metadata.md) |
 |---------|-----------|----------|
-| Structure | Strongly typed, schema-defined | Flat key-value JSON |
-| Validation | Type-specific validation | None |
-| Visibility | Configurable (front/back/both) | Write-only in Store API |
-| Admin UI | Dedicated management forms | JSON preview |
-| Data Types | 6 specific types | Any JSON-serializable data |
-| Organization | Namespaced (`namespace.key`) | Flat structure |
+| **Purpose** | Merchant-defined structured attributes | Developer escape hatch — integration IDs, sync state |
+| **Schema** | Defined via MetafieldDefinitions | Schemaless JSON — no definition required |
+| **Validation** | Type-specific (text, number, boolean, etc.) | None — accepts any JSON-serializable data |
+| **Visibility** | Configurable (admin-only or public) | Write-only in Store API, readable in Admin API |
+| **Admin UI** | Dedicated management forms | JSON preview |
+| **Data Types** | 6 specific types | Any JSON value |
+| **Organization** | Namespaced (`namespace.key`) | Flat key-value structure |
+| **Queryable** | Via SQL joins, Ransack scopes, search providers | Via JSONB operators (PostgreSQL) |
 
 **Use Metafields** when you need type validation, visibility control, admin UI forms, or organized namespacing.
 
-**Use Metadata** for external system IDs, tracking attribution, or simple write-and-forget data.
+**Use [Metadata](../customization/metadata.md)** for external system IDs, tracking attribution, syncing with integrations, or simple write-and-forget data that only backend systems need to read.
 
 > **WARNING:** Product Properties are deprecated and will be removed in Spree 6.0. For new projects, always use Metafields. For existing projects, plan to migrate using the [migration guide](../upgrades/5.1-to-5.2.md#3-migrate-to-metafields-or-keep-using-properties).
 

package/dist/developer/customization/dependencies.md

@@ -35,7 +35,7 @@ And add the following code to it:
 
 ```ruby
 class MyAddToCartService < Spree::Cart::AddItem
-  def call(order:, variant:, quantity: nil, public_metadata: {}, private_metadata: {}, options: {})
+  def call(order:, variant:, quantity: nil, metadata: {}, options: {})
     ApplicationRecord.transaction do
       run :add_to_line_item
       run Spree.cart_recalculate_service

package/dist/developer/customization/metadata.md

@@ -6,6 +6,8 @@ title: Metadata
 
 Metadata provides simple, unstructured key-value storage on Spree resources — similar to [Stripe's metadata](https://docs.stripe.com/api/metadata). It's ideal for storing integration IDs, tracking data, or any arbitrary information that doesn't need validation or admin UI.
 
+Metadata is a **permanent, first-class system** in Spree. It is designed to coexist alongside [Metafields](../core-concepts/metafields.md) (structured, typed, admin-managed). The two systems serve different purposes and are not interchangeable — think of it as **metadata for machines, metafields for humans**.
+
 Metadata is **write-only** in the Store API — you can set it when creating or updating resources, but it is never returned in Store API responses. It is visible in Admin API responses for administrative use.
 
 > **INFO:** For structured, type-safe custom attributes with admin UI support, use [Metafields](../core-concepts/metafields.md) instead.
@@ -144,7 +146,7 @@ When there is no metadata, the field is `null`.
 
 ### Reading and writing
 
-Every model that includes `Spree::Metadata` has a `metadata` accessor (alias for `private_metadata`):
+Every model that includes `Spree::Metadata` has a `metadata` accessor. Always use `metadata` in Ruby code — do not call `public_metadata=` or `private_metadata=` directly. (SQL queries still reference the underlying `private_metadata` column name — see querying examples below.)
 
 ```ruby
 order = Spree::Order.find_by!(number: 'R123456')
@@ -188,14 +190,17 @@ Metadata updates use **merge semantics** — existing keys are preserved, new ke
 
 ## Metadata vs Metafields
 
+Spree has two permanent, complementary systems for custom data. They are not interchangeable and neither is going away.
+
 | | Metadata | [Metafields](../core-concepts/metafields.md) |
 |---|---|---|
-| **Use case** | Integration data, tracking, simple key-value | Structured custom attributes with admin UI |
-| **Validation** | None | Type-specific (text, number, boolean, JSON) |
+| **Purpose** | Developer escape hatch — integration data, sync state, ad-hoc flags | Merchant-defined structured attributes with admin UI |
+| **Schema** | Schemaless JSON — no definition required | Defined via MetafieldDefinitions (typed, validated) |
+| **Validation** | None — accepts any JSON-serializable data | Type-specific (text, number, boolean, rich text, JSON) |
 | **Visibility** | Write-only in Store API, readable in Admin API | Configurable (front-end, back-end, both) |
-| **Admin UI** | Viewable in JSON preview | Full admin management |
-| **Schema** | Schemaless JSON | Defined via MetafieldDefinitions |
-| **API pattern** | Stripe-style flat key-value | Shopify-style typed resources |
+| **Admin UI** | JSON preview only | Dedicated management forms |
+| **API pattern** | Stripe-style: `metadata: { key: value }` | Expand-based: `?expand=metafields` |
+| **Queryable** | Via JSONB operators (PostgreSQL) | Via SQL joins, Ransack scopes, search providers |
 
 ### When to use metadata
 
@@ -203,13 +208,15 @@ Metadata updates use **merge semantics** — existing keys are preserved, new ke
 - Tracking attribution data (UTM parameters, referral source)
 - Passing context from the storefront that doesn't need validation
 - Any write-and-forget data that only needs to be read by backend systems
+- Syncing state with external integrations (webhooks, ETL pipelines)
 
 ### When to use metafields
 
-- Custom product specifications shown to customers
-- Admin-managed fields with validation
-- Data that needs to appear in the admin UI
-- Querying/filtering by custom attributes
+- Custom product specifications shown to customers (material, dimensions, certifications)
+- Admin-managed fields with validation and type safety
+- Data that needs to appear in the admin UI with dedicated form inputs
+- Querying/filtering by custom attributes (search facets, product filtering)
+- CSV import/export of structured product data
 
 ## Supported resources
 
@@ -220,17 +227,21 @@ The Store API currently supports writing metadata on:
 - **Carts** — on creation and update (`POST /api/v3/store/carts`, `PATCH /api/v3/store/carts/:id`)
 - **Items** — on create and update (`POST/PATCH /api/v3/store/carts/:id/items`)
 
-## Migration from public_metadata
+## Deprecation: public_metadata
+
+> **WARNING:** `public_metadata` is deprecated and will be removed in Spree 6.0. Use `metadata` instead.
+
+The `public_metadata` column was never exposed in Store API responses and in practice served the same purpose as `private_metadata`. It will be removed in Spree 6.0 and calling `public_metadata=` will emit a deprecation warning.
 
-The `public_metadata` column is deprecated. Metadata is no longer returned in Store API responses. If you were using `public_metadata` for data that needs to be visible to customers, migrate to [Metafields](../core-concepts/metafields.md) with `display_on: 'both'`.
+Always use the single `metadata` accessor for all schemaless key-value storage. If you need data visible to customers on the storefront, use [Metafields](../core-concepts/metafields.md) instead.
 
 ```ruby
-# Before (deprecated)
+# Deprecated — will be removed in 6.0
 order.public_metadata = { 'gift_message' => 'Happy Birthday!' }
 
-# After — use metadata for write-only storage
+# Use metadata for internal storage
 order.metadata = { 'gift_message' => 'Happy Birthday!' }
 
-# After — use metafields for customer-visible structured data
+# Use metafields for customer-visible structured data
 order.set_metafield('custom.gift_message', 'Happy Birthday!')
 ```

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

@@ -8,14 +8,14 @@ description: Server-first architecture, project structure, and auth flow
 The storefront follows a **server-first architecture** where all API calls are made server-side. The Spree API key is never exposed to the browser.
 
 ```
-Browser → Server Action → @spree/next → Spree API
-         (with httpOnly cookies)
+Browser → Server Action → @spree/sdk → Spree API
+         (with httpOnly cookies via @spree/next helpers)
 ```
 
-- **Server Actions** (`src/lib/data/`) — thin wrappers around `@spree/next` data functions
+- **Server Actions** (`src/lib/data/`) — call `@spree/sdk` directly with auth/cookie helpers from `@spree/next`
 - **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 automatically by `@spree/next`
+- **Auto-Localization** — locale and country are read from cookies via `getLocaleOptions()`
 
 ## Project Structure
 
@@ -59,7 +59,7 @@ src/
 └── lib/
     ├── analytics/                   # GTM integration
     ├── constants.ts                 # App constants
-    ├── data/                        # Server Actions
+    ├── data/                        # Server Actions (call @spree/sdk directly)
     │   ├── addresses.ts             # Address CRUD
     │   ├── cart.ts                  # Cart operations
     │   ├── checkout.ts              # Checkout flow
@@ -71,8 +71,7 @@ src/
     │   ├── orders.ts                # Order history
     │   ├── payment.ts               # Payment processing
     │   ├── products.ts              # Product queries
-    │   ├── store.ts                 # Store configuration
-    │   ├── categories.ts             # Categories
+    │   ├── categories.ts            # Categories
     │   └── utils.ts                 # Shared helpers (actionResult, withFallback)
     └── utils/                       # Client utilities
         ├── address.ts               # Address formatting
@@ -85,21 +84,26 @@ src/
 ## Authentication Flow
 
 1. User submits login form
-2. Server action calls `@spree/next` which authenticates with the Spree API
-3. JWT token is stored in an httpOnly cookie by `@spree/next`
-4. Subsequent requests include the token automatically
+2. Server action calls `@spree/sdk` to authenticate
+3. JWT token is stored in an httpOnly cookie via `@spree/next` 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 { login as _login, getCustomer as _getCustomer } from '@spree/next'
+import { getClient, withAuthRefresh, setAccessToken, setRefreshToken } from '@spree/next'
 
 export async function login(email: string, password: string) {
-  return _login(email, password) // token stored in httpOnly cookie automatically
+  const result = await getClient().auth.login({ email, password })
+  await setAccessToken(result.token)
+  await setRefreshToken(result.refresh_token)
+  return { success: true, user: result.user }
 }
 
 export async function getCustomer() {
-  return _getCustomer() // reads token from cookie automatically
+  return withAuthRefresh(async (options) => {
+    return getClient().customer.get(options) // reads token from cookie
+  })
 }
 ```
 
@@ -117,17 +121,17 @@ A middleware (`src/proxy.ts`) uses `createSpreeMiddleware` from `@spree/next` to
 
 ## Server Actions
 
-All data fetching is done through server actions in `src/lib/data/`. These are thin wrappers around `@spree/next` functions — locale and currency are resolved automatically from cookies:
+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:
 
 ```typescript
-// Products
+// Products — use getLocaleOptions() for locale-aware reads
 import { getProducts, getProduct, getProductFilters } from '@/lib/data/products'
 
 const products = await getProducts({ limit: 12 })
 const product = await getProduct('product-slug')
 const filters = await getProductFilters()
 
-// Cart
+// Cart — use getCartOptions()/requireCartId() for cart operations
 import { getCart, addToCart, updateCartItem, removeCartItem } from '@/lib/data/cart'
 
 const cart = await getCart()
@@ -135,14 +139,14 @@ await addToCart('var_xxx', 1)
 await updateCartItem('li_xxx', 2)
 await removeCartItem('li_xxx')
 
-// Authentication
+// Authentication — use withAuthRefresh() for authenticated endpoints
 import { login, register, logout, getCustomer } from '@/lib/data/customer'
 
 await login('user@example.com', 'password')
 const customer = await getCustomer()
 await logout()
 
-// Addresses
+// Addresses — use withAuthRefresh() for customer data
 import { getAddresses, createAddress, updateAddress, deleteAddress } from '@/lib/data/addresses'
 
 const addresses = await getAddresses()

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 wrap the `@spree/next` package functions. You can add custom logic, caching strategies, or additional transformations as needed.
+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.
 
 ## Adding New Pages
 
@@ -122,10 +122,10 @@ src/app/[country]/[locale]/(storefront)/your-new-page/page.tsx
 ```
 
 ```typescript
-import { listProducts } from '@spree/next';
+import { getProducts } from '@/lib/data/products';
 
 export default async function YourNewPage() {
-  const products = await listProducts({ limit: 6 });
+  const products = await getProducts({ limit: 6 });
 
   return (
     <div>

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

@@ -12,7 +12,7 @@ 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)** - Server actions, caching, and cookie-based auth
+- **[@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/dist/developer/storefront/nextjs/spree-next-package.md

@@ -1,9 +1,11 @@
 ---
 title: "@spree/next Package"
-description: Next.js integration library — server actions, caching, and cookie-based auth
+description: Next.js integration library — cookie-based auth, middleware, and webhook helpers
 ---
 
-The `@spree/next` package provides a complete Next.js integration for Spree Commerce with server actions, automatic cookie management, and full TypeScript support.
+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
 
@@ -42,211 +44,137 @@ initSpreeNext({
 });
 ```
 
-## Data Functions
+## Architecture
 
-Plain async functions for reading data in Server Components. Wrap with `"use cache"` in your app for caching.
+`@spree/next` provides four things:
 
-### Products
+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
 
-```typescript
-import { listProducts, getProduct, getProductFilters } from '@spree/next';
+Your storefront's server actions call `@spree/sdk` directly, using these helpers for auth and cookies:
 
-const products = await listProducts({ limit: 25 });
-const product = await getProduct('spree-tote', { expand: ['variants', 'media'] });
-const filters = await getProductFilters({ category_id: 'ctg_123' });
+```
+Server Action → getClient().products.list(params, localeOptions)
+Server Action → withAuthRefresh(fn) → getClient().customer.get(options)
+Server Action → getCartOptions() → getClient().carts.items.create(...)
 ```
 
-### Categories
+## Auth Helpers
 
-```typescript
-import { listCategories, getCategory, listCategoryProducts } from '@spree/next';
+### `withAuthRefresh(fn)`
 
-const categories = await listCategories({ depth_eq: 1 });
-const category = await getCategory('clothing/shirts');
-const products = await listCategoryProducts('clothing/shirts', { limit: 12 });
-```
+Wraps an authenticated SDK call with automatic token management:
 
-### Store & Geography
+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
-import { getStore, listCountries, getCountry, listCurrencies, listLocales } from '@spree/next';
+'use server';
 
-const store = await getStore();
-const countries = await listCountries();
-const usa = await getCountry('US');
-const currencies = await listCurrencies();
-const locales = await listLocales();
-```
+import { getClient, withAuthRefresh } from '@spree/next';
 
-### Using in Server Components
+export async function getCustomer() {
+  return withAuthRefresh(async (options) => {
+    return getClient().customer.get(options);
+  });
+}
 
-```typescript
-import { listProducts, listCategories } from '@spree/next';
-
-export default async function ProductsPage() {
-  const products = await listProducts({ limit: 12 });
-  const categories = await listCategories({ depth_eq: 1 });
-
-  return (
-    <div>
-      {products.data.map((product) => (
-        <div key={product.id}>{product.name}</div>
-      ))}
-    </div>
-  );
+export async function listAddresses() {
+  return withAuthRefresh(async (options) => {
+    return getClient().customer.addresses.list(undefined, options);
+  });
 }
 ```
 
-## Server Actions
+### `getAuthOptions()`
 
-Server actions handle mutations and auth-dependent reads. They automatically manage cookies for cart tokens and JWT authentication.
+Lower-level helper that returns `{ token }` or `{}` with proactive refresh. Use when you need the token but want to handle errors yourself.
 
-### Cart
+## Cookie Management
 
-```typescript
-import { getCart, getOrCreateCart, addItem, updateItem, removeItem, clearCart, associateCart } from '@spree/next';
-
-const cart = await getCart();              // null if no cart
-const cart = await getOrCreateCart();       // creates if needed
-await addItem(variantId, quantity);
-await updateItem(lineItemId, { quantity: 2 });
-await removeItem(lineItemId);
-await clearCart();
-await associateCart();                     // link guest cart to logged-in user
-```
-
-### Checkout
-
-Checkout functions use the implicit cart resolved from cookies. No `orderId` is needed.
+All cookie helpers are async (they use Next.js `cookies()` API):
 
 ```typescript
 import {
-  getCheckout,
-  updateCheckout,
-  selectDeliveryRate,
-  applyDiscountCode,
-  removeDiscountCode,
-  applyGiftCard,
-  removeGiftCard,
-  complete,
+  // 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';
-
-const checkout = await getCheckout();
-await updateCheckout({ shipping_address: { ... }, billing_address: { ... } });
-await selectDeliveryRate(fulfillmentId, deliveryRateId);
-await applyDiscountCode('SAVE20');
-await removeDiscountCode('SAVE20');
-await applyGiftCard('GC-ABCD-1234');
-await removeGiftCard('gc_abc123');
-await complete();
 ```
 
-### Authentication
+### Cart operations pattern
 
 ```typescript
-import { login, register, logout, getCustomer, updateCustomer } from '@spree/next';
-
-await login(email, password);
-await register(email, password, passwordConfirmation);
-await logout();
-const customer = await getCustomer();   // null if not logged in
-await updateCustomer({ first_name: 'John' });
-```
+'use server';
 
-### Addresses
+import { getClient, getCartOptions, requireCartId } from '@spree/next';
 
-```typescript
-import { listAddresses, getAddress, createAddress, updateAddress, deleteAddress } from '@spree/next';
-
-const addresses = await listAddresses();
-const address = await getAddress(addressId);
-await createAddress({ first_name: 'John', address1: '123 Main St', ... });
-await updateAddress(addressId, { city: 'Brooklyn' });
-await deleteAddress(addressId);
-```
-
-### Orders
-
-```typescript
-import { listOrders, getOrder } from '@spree/next';
-
-const orders = await listOrders();
-const order = await getOrder(orderId);
+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);
+}
 ```
 
-### Payment Sessions
-
-Payment session functions use the implicit cart. No `orderId` is needed.
+### Auth operations pattern
 
 ```typescript
-import {
-  createPaymentSession,
-  getPaymentSession,
-  updatePaymentSession,
-  completePaymentSession,
-} from '@spree/next';
-
-const session = await createPaymentSession({ payment_method_id: 'pm_123' });
-
-// Access provider data (e.g., Stripe client secret)
-const clientSecret = session.external_data.client_secret;
-
-const current = await getPaymentSession(sessionId);
-await updatePaymentSession(sessionId, { amount: '50.00' });
-await completePaymentSession(sessionId, { session_result: 'success' });
-```
+'use server';
 
-### Payment Setup Sessions
+import { getClient, setAccessToken, setRefreshToken, getCartToken, getCartId } from '@spree/next';
 
-For saving payment methods outside of checkout (e.g., "Add a credit card" in account settings):
+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);
 
-```typescript
-import {
-  createPaymentSetupSession,
-  getPaymentSetupSession,
-  completePaymentSetupSession,
-} from '@spree/next';
+  // 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
+  }
 
-const session = await createPaymentSetupSession({ payment_method_id: 'pm_123' });
-const current = await getPaymentSetupSession(sessionId);
-await completePaymentSetupSession(sessionId, { session_result: 'success' });
+  return { success: true, user: result.user };
+}
 ```
 
-### Credit Cards & Gift Cards
-
-```typescript
-import { listCreditCards, deleteCreditCard } from '@spree/next';
-import { listGiftCards, getGiftCard } from '@spree/next';
+## Locale Resolution
 
-const cards = await listCreditCards();
-await deleteCreditCard(cardId);
-
-const giftCards = await listGiftCards();
-const giftCard = await getGiftCard(giftCardId);
-```
-
-## Using Server Actions in Forms
+`getLocaleOptions()` reads country and locale from cookies (set by middleware or explicitly). All data-fetching server actions should use this:
 
 ```typescript
-import { addItem, getCart } from '@spree/next';
+'use server';
 
-export default async function CartPage() {
-  const cart = await getCart();
+import { getClient, getLocaleOptions } from '@spree/next';
 
-  async function handleAddItem(formData: FormData) {
-    'use server';
-    await addItem(formData.get('variantId') as string, 1);
-  }
+export async function getProducts(params?: { limit?: number }) {
+  const options = await getLocaleOptions();
+  return getClient().products.list(params, options);
+}
 
-  return <form action={handleAddItem}>...</form>;
+export async function getCategory(idOrPermalink: string) {
+  const options = await getLocaleOptions();
+  return getClient().categories.get(idOrPermalink, undefined, options);
 }
 ```
 
-## Localization
-
-### Automatic (recommended)
+## Middleware
 
-Data functions automatically read locale and country from cookies. Use the included middleware to set cookies based on the URL:
+Handles URL-based country/locale routing. Detects country from cookies, geo headers (Vercel/Cloudflare), or defaults, then redirects to `/{country}/{locale}/...`:
 
 ```typescript
 // middleware.ts
@@ -262,31 +190,6 @@ export const config = {
 };
 ```
 
-Then data functions work without any locale arguments:
-
-```typescript
-// Locale/country auto-read from cookies — no options needed
-const products = await listProducts({ limit: 10 });
-const category = await getCategory('clothing/shirts');
-```
-
-Use the `setLocale` server action in country/language switchers:
-
-```typescript
-import { setLocale } from '@spree/next';
-
-await setLocale({ country: 'de', locale: 'de' });
-```
-
-### Manual override
-
-You can still pass locale options explicitly — they override the auto-detected values:
-
-```typescript
-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`:
@@ -331,31 +234,14 @@ For more details, see [Webhooks](../../core-concepts/webhooks.md).
 
 ## TypeScript
 
-All types are re-exported from `@spree/sdk`:
+Import types directly from `@spree/sdk`:
 
 ```typescript
 import type {
-  Product,
-  Order,
-  LineItem,
-  Variant,
-  Category,
-  Country,
-  Currency,
-  Locale,
-  Address,
-  Customer,
-  CreditCard,
-  GiftCard,
-  Fulfillment,
-  DeliveryRate,
-  Payment,
-  PaymentMethod,
-  PaymentSession,
-  PaymentSetupSession,
-  PaginatedResponse,
-  ProductFiltersResponse,
-  AddressParams,
-  SpreeError,
-} from '@spree/next';
+  Product, Order, Cart, LineItem, Variant,
+  Category, Country, Currency, Address, Customer,
+  CreditCard, GiftCard, Fulfillment, DeliveryRate,
+  Payment, PaymentSession, PaginatedResponse,
+  AddressParams, SpreeError,
+} from '@spree/sdk';
 ```