brainerce 1.58.1 → 1.59.0

package/README.md

@@ -7,14 +7,31 @@ This SDK provides a complete solution for vibe-coded sites, AI-built stores (Cur
 > **AI Agents / Vibe Coders (Cursor, Lovable, Claude Code, VS Code):** Use the MCP server for AI-powered store building: `npx @brainerce/mcp-server`. It provides docs, code templates, and live store capabilities directly inside your IDE.
 > Note: the MCP server runs inside your IDE — it is not available in chat-only tools like Google AI Studio or ChatGPT.
 
-## Two SDK modes — choose the right one
+## Three SDK modes — choose the right one
 
-| Mode           | Config key               | Use for                            | Where to run                        |
-| -------------- | ------------------------ | ---------------------------------- | ----------------------------------- |
-| **Storefront** | `salesChannelId: 'vc_*'` | Building the customer-facing store | Browser / client-side               |
-| **Admin**      | `apiKey: 'brainerce_*'`  | Managing products, team, settings  | Server only — never in browser code |
+The exported class is **`BrainerceClient`**. Which mode you get is decided by which key you pass to its constructor:
+
+| Mode              | Config key               | Use for                                  | Where to run                        |
+| ----------------- | ------------------------ | ---------------------------------------- | ----------------------------------- |
+| **Sales channel** | `salesChannelId: 'vc_*'` | Building the customer-facing store       | Browser / client-side               |
+| **Storefront**    | `storeId`                | A public storefront on a published store | Browser / client-side               |
+| **Admin**         | `apiKey: 'brainerce_*'`  | Managing products, team, settings        | Server only — never in browser code |
+
+```ts
+import { BrainerceClient } from 'brainerce';
+
+const client = new BrainerceClient({ salesChannelId: 'vc_abc123' });
+```
+
+**If you pass more than one, `apiKey` wins, then `salesChannelId`, then `storeId`.** An `apiKey` puts the client in admin mode no matter what else you passed, so never add one "just to also read a channel" — it changes every route the client calls. Passing none throws `BrainerceClient: either salesChannelId, apiKey, or storeId is required`.
+
+Ask the client which mode it is in with `isSalesChannelMode()`, `isStorefrontMode()` or `isAdminMode()` — exactly one returns `true`. (`isVibeCodedMode()` is a deprecated alias of `isSalesChannelMode()`.)
+
+Not every method works in every mode. A handful — `getPaymentStatus()`, `confirmSdkPayment()`, `waitForOrder()` — are **sales-channel mode only** and throw `BrainerceError` 400 elsewhere. `storeId` mode is **not** read-only: it can create carts, run a checkout to a real order, and register/log in customers; what it cannot reach is the admin surface.
 
 > **Building a storefront?** You only need your **Sales Channel ID** (`vc_*`) from the Brainerce dashboard under **Sales Channels**. No API key needed. API keys are a server-side admin secret.
+>
+> `connectionId` is the deprecated alias of `salesChannelId`. It still works, logs a deprecation warning on every construction, and is removed in SDK 2.0.
 
 ## Installation
 
@@ -68,7 +85,7 @@ Violating any of these causes production incidents or broken orders. Read them b
 - ALWAYS call SDK client methods. Never reconstruct REST URLs or call `fetch` directly.
 - NEVER invent SDK method names. If it's not in this README or in `get-sdk-docs`, it doesn't exist.
 - NEVER hardcode product data, categories, or store copy — Brainerce is the database.
-- NEVER use `submitGuestOrder()` or `createOrder()` — they bypass payment and produce unpaid orders.
+- NEVER use `submitGuestOrder()`, `createGuestOrder()` or `createOrder()` on a store that takes payment — they `POST /orders` directly, never touch `/payment/intent`, and produce an order nobody has paid for. They exist only for cash-on-delivery, manual-invoice and sandbox stores. Everything else goes through the checkout sequence below.
 - ALWAYS use SDK helpers (`getCartTotals`, `formatPrice`, `getProductPriceInfo`, `getCartItemImage`, `getCartItemName`, `getVariantPrice`, `getStockStatus`, `getDescriptionContent`) instead of reading raw fields.
 
 ### State management
@@ -419,7 +436,7 @@ await client.addToCart(cart.id, {
 });
 ```
 
-Money on the wire is **always strings** (`priceDelta: "5.00"`). Validation failures arrive as a structured 400 envelope on `BrainerceError.details` with `code: 'MODIFIER_VALIDATION_FAILED'` and `errors[]` — see INTEGRATION-RULES.md "Modifier validation errors" for the full code list.
+Money on the wire is **always strings** (`priceDelta: "5.00"`). Validation failures arrive as a structured 400 envelope on `BrainerceError.details` with `code: 'MODIFIER_VALIDATION_FAILED'`; the per-issue list is nested at `details.errors[]`, so from the SDK it reads `err.details.details.errors` (`err.details` is the whole response body) — see INTEGRATION-RULES.md "Modifier validation errors" for the full code list.
 
 Full rendering guide: [Core Integration §2.9](https://brainerce.com/docs/integration/core). Restaurant features (scheduled availability, nested combos to depth 3, downsell modifiers): [Optional Features "Restaurant / build-your-own products"](https://brainerce.com/docs/integration/optional).
 
@@ -573,14 +590,16 @@ if (result.tracked) {
   // Continue with payment flow...
 }
 
-// ✅ ALTERNATIVE - Use submitGuestOrder() for simple checkout without payment UI
+// ⚠️ CASH-ON-DELIVERY / SANDBOX ONLY - submitGuestOrder() places the order with
+// NO payment collected. Never call it on a store with a payment provider.
 const order = await client.submitGuestOrder();
 ```
 
 **Rule of thumb:**
 
-- Guest user + Session cart → `startGuestCheckout()` or `submitGuestOrder()`
+- Guest user + Session cart → `startGuestCheckout()`
 - Logged-in user + Server cart → `createCheckout({ cartId })`
+- Store that collects no money at checkout (cash on delivery, manual invoice, sandbox) → `submitGuestOrder()`
 
 ### 2. ⛔ NEVER Create Local Interfaces - Use SDK Types!
 
@@ -1072,6 +1091,9 @@ if (!address.country) {
 // guaranteed) the same ISO 3166-2 subdivision code this store's own region
 // lists use. Validate against destinations.regions before trusting it;
 // never assign a code the region <select> wouldn't recognize.
+// NOTE: getShippingDestinations() is CHANNEL-ONLY — it needs a `salesChannelId`
+// client. In `storeId` (public storefront) mode it targets a path the API does not
+// expose and returns 404, so drive the region <select> from your own list there.
 const destinations = await client.getShippingDestinations();
 const validRegions = destinations.regions[address.country] ?? [];
 const region = validRegions.some((r) => r.code === address.region) ? address.region : '';
@@ -1666,27 +1688,58 @@ function SearchInput() {
 
 #### Product Type Definition
 
+> **The shipped `.d.ts` is the authority.** These are abridged for reading —
+> import the real types (`import type { Product, ProductVariant } from 'brainerce'`)
+> rather than retyping them. See the Critical Rule: _never write your own copies
+> of SDK types._
+
 ```typescript
 interface Product {
   id: string;
   name: string;
-  description?: string | null;
-  descriptionFormat?: 'text' | 'html' | 'markdown'; // Format of description content
+  slug?: string | null; // link target for /products/{slug}
+  localeSlugs?: Record<string, string> | null; // per-locale slugs for hreflang / sitemaps
+  description?: string | null; // HTML — sanitize before rendering (may contain <video>/<iframe>)
+  descriptionFormat?: 'text' | 'html' | 'markdown' | null;
   sku: string;
+  gtin?: string | null; // EAN/UPC/ISBN — emitted in Product JSON-LD
+  mpn?: string | null; // Manufacturer Part Number — emitted in Product JSON-LD
+  faq?: Array<{ q: string; a: string }> | null; // render as a FAQ section + buildProductFaqJsonLd()
   basePrice: string; // Decimal as string — use parseFloat() for calculations
   salePrice?: string | null;
   salePriceStartsAt?: string | null; // ISO 8601 — sale-price effective window start
   salePriceEndsAt?: string | null; // ISO 8601 — sale-price window end; feeds buildProductJsonLd's priceValidUntil
+  costPrice?: string | null; // COGS — admin (apiKey) reads only
   priceMin?: string | null; // Lowest variant price (VARIABLE products only)
   priceMax?: string | null; // Highest variant price (VARIABLE products only)
   priceVaries?: boolean; // true when range should be shown ("₪49 – ₪199")
+  // Region FX overlay — present ONLY with getProducts({ regionId }). DISPLAY-ONLY;
+  // basePrice/salePrice stay in the store currency. Use formatProductPrice().
+  displayPrice?: string;
+  displaySalePrice?: string;
+  displayPriceMin?: string;
+  displayPriceMax?: string;
+  displayCurrency?: string; // ISO 4217 of the display* fields
   status: string; // e.g. "active" | "draft"
   type: 'SIMPLE' | 'VARIABLE';
+  isDownloadable?: boolean;
+  downloads?: DownloadFile[] | null; // when isDownloadable
   images?: ProductImage[];
   inventory?: InventoryInfo | null;
   variants?: ProductVariant[];
   categories?: Array<{ id: string; name: string; slug?: string | null }>; // NOT string[] — use slug to link to /category/{slug}
+  brands?: Array<{ id: string; name: string }>; // objects, not string[]
   tags?: string[];
+  metafields?: ProductMetafield[]; // custom fields — check field.type before rendering
+  customizationFields?: ProductCustomizationField[]; // buyer input (engraving, uploads…)
+  modifierGroups?: ModifierGroup[]; // add-ons / options priced per selection
+  discount?: ProductDiscount | null; // active rule-based discount on this product
+  avgRating?: number; // feeds JSON-LD aggregateRating
+  reviewCount?: number;
+  needsSync: boolean; // REQUIRED — always returned
+  taxBehavior?: 'taxable' | 'exempt';
+  menuOrder?: number | null;
+  channelPublishes?: Array<{ salesChannel: { id: string; name: string; connectionId: string } }>; // admin mode only
   createdAt: string;
   updatedAt: string;
 }
@@ -1695,28 +1748,48 @@ interface ProductImage {
   url: string;
   position?: number;
   isMain?: boolean;
+  alt?: string;
+  // admin (apiKey) mode only: id, key, thumbnailUrl, width, height, size, mimeType, createdAt
 }
 
 interface ProductVariant {
   id: string;
+  productId: string; // REQUIRED — parent product
   sku?: string | null;
   name?: string | null;
-  price?: number | null;
-  salePrice?: number | null;
-  attributes?: Record<string, string>;
+  price?: string | null; // STRING, not number — parseFloat() before any math
+  salePrice?: string | null; // STRING, not number
+  costPrice?: string | null; // COGS override — admin (apiKey) reads only
+  // Region FX overlay — present ONLY with getProducts({ regionId }). Display-only.
+  displayPrice?: string;
+  displaySalePrice?: string;
+  displayCurrency?: string;
+  attributes?: Record<string, string> | null; // e.g. { "Color": "Red", "Size": "M" }
+  options?: Array<{ name: string; value: string }>; // alternative shape — use getVariantOptions()
   inventory?: InventoryInfo | null;
+  image?: string | { url: string; thumbnailUrl?: string } | null;
+  position: number; // REQUIRED — display order
+  status?: string | null;
+  createdAt: string; // REQUIRED
+  updatedAt: string; // REQUIRED
 }
 
 interface InventoryInfo {
   total: number;
   reserved: number;
   available: number;
-  trackingMode?: 'TRACKED' | 'UNLIMITED' | 'DISABLED';
+  trackingMode: InventoryTrackingMode; // REQUIRED — 'TRACKED' | 'UNLIMITED' | 'DISABLED'
   inStock: boolean; // Pre-calculated - use this for display!
   canPurchase: boolean; // Pre-calculated - use this for add-to-cart
+  lastInventorySyncAt?: string | null; // admin mode only
 }
 ```
 
+> **Variant prices are strings.** `variant.price` and `variant.salePrice` are
+> `string | null`, exactly like `product.basePrice`. `variant.price > 100` compares
+> lexicographically and silently returns the wrong answer — always `parseFloat()`
+> first, or use `getVariantPrice(variant)` / `formatVariantPrice(variant)`.
+
 #### Product Metafields (Custom Fields)
 
 Products can have custom fields (metafields) defined by the store owner, such as "Material", "Care Instructions", or "Warranty".
@@ -1907,15 +1980,20 @@ await client.addToCart(cartId, {
 | GALLERY          | `string[]` (URLs)     | Multi-file upload   |
 | DIMENSION/WEIGHT | `{ value, unit }`     | Value + unit inputs |
 
-**Admin methods** (require API key):
-
-```typescript
-// Set which customer-input definitions apply to a product
-await client.setProductCustomizationFields(productId, [definitionId1, definitionId2]);
-
-// Get current assignments
-const fields = await client.getProductCustomizationFields(productId);
-```
+**Assigning fields to a product is dashboard-only — there is no SDK path to it.**
+`client.setProductCustomizationFields()` and `client.getProductCustomizationFields()`
+target `/api/v1/metafield-definitions/products/:productId/customization-fields`, which
+the public API does not expose; both return **404**. Those routes exist only on the
+dashboard API (`/api/stores/:storeId/metafield-definitions/products/:productId/customization-fields`),
+behind Clerk auth. Choose which customer-input definitions apply to a product in the
+dashboard.
+
+> **Two different things share the name `getProductCustomizationFields`.** The
+> **exported helper** used above — `import { getProductCustomizationFields } from 'brainerce'`
+> — is a pure function that reads the definitions off a product you already fetched. It
+> works in every mode and is the one you want. The **client method** of the same name,
+> which writes the assignment, is the one that 404s. Reading is fully covered without it:
+> `product.customizationFields` is already on every product response.
 
 > **Note:** `customizationFields` is only present when the product has customer input fields assigned. After checkout, customization values are preserved in the order as `item.customizations`.
 
@@ -2117,9 +2195,17 @@ const totals = getCartTotals(cart);
 
 ---
 
-### Guest Checkout (Submit Order)
+### Guest Checkout (Submit Order) — no payment collected
 
-> **Note:** `startGuestCheckout()` is the preferred method for guest checkout — it creates a full checkout session from the session cart. `submitGuestOrder()` still works as a simpler alternative for basic orders.
+> **⛔ Not for stores that take payment.** `submitGuestOrder()` posts the order
+> straight to `POST /orders`. It never creates a payment intent, so the order is
+> created **unpaid** and no card is ever charged. Use it only where checkout
+> collects no money — cash on delivery, manual invoicing, or a sandbox store.
+>
+> For every other store use `startGuestCheckout()`, which creates a real checkout
+> session from the session cart and hands you a `checkoutId` to run the payment
+> flow against. This is the same rule as the Critical Rule above; the two used to
+> disagree.
 
 ```typescript
 // Make sure cart has items, customer email, and shipping address
@@ -2227,7 +2313,8 @@ if (checkout.tracked) {
   const order = await client.completeGuestCheckout(checkout.checkoutId);
   console.log('Order created:', order.orderId);
 } else {
-  // Fallback to regular guest checkout
+  // Fallback — NO payment is collected on this path. Only reachable on a
+  // cash-on-delivery / manual-invoice / sandbox store.
   const order = await client.submitGuestOrder();
 }
 ```
@@ -2426,8 +2513,11 @@ await client.getProduct('prod_tshirt', { regionId: 'region_eu' });
 await client.getProductBySlug('blue-shirt', { regionId: 'region_eu' });
 ```
 
-> **Display-only** — like checkout, `regionId` here does not charge the region
-> currency; it only changes what you render until currency-lock ships. Works in
+> **Display-only, and unlike checkout.** `regionId` on a _product read_ never
+> affects what is charged — it only changes what you render. `regionId` on
+> `createCheckout()` is different: it CAN charge the region currency (see
+> FX-at-checkout above). Do not carry the "display-only" assumption from here into
+> the checkout step. Works in
 > **all three modes** — vibe-coded (`vc_*`/`salesChannelId`), storefront (`storeId`),
 > and admin (`apiKey`). The response gains `displayPrice` whenever a daily FX rate
 > exists for the store/region currency pair in **either** direction (the overlay
@@ -2917,16 +3007,21 @@ if (paypalProvider) {
 }
 ```
 
-#### Get Payment Configuration (Single Provider)
+#### Get Payment Configuration (Single Provider) — DEPRECATED
 
-If you only need the default provider, use this simpler method:
+> **`getPaymentConfig()` is `@deprecated`.** It only ever describes one provider, so
+> a store with an additive express method (PayPal, a wallet) renders wrong. Use
+> `getPaymentProviders()` above. This section documents the legacy shape for code
+> that still calls it.
 
 ```typescript
 const config = await client.getPaymentConfig();
 
 // Returns:
 // {
-//   provider: 'stripe' | 'paypal',
+//   provider: string,             // 'stripe' | 'paypal' | 'grow' | 'cardcom' | any
+//                                 //  installed marketplace payment app — NOT a
+//                                 //  closed union. Never switch on it exhaustively.
 //   publicKey: 'pk_live_xxx...',  // Stripe publishable key or PayPal client ID
 //   supportedMethods: ['card', 'ideal', 'bancontact'],
 //   testMode: false
@@ -2943,13 +3038,74 @@ const intent = await client.createPaymentIntent(checkout.id);
 // Returns:
 // {
 //   id: 'pi_xxx...',
-//   clientSecret: 'pi_xxx_secret_xxx',  // Used by Stripe.js/PayPal SDK
-//   amount: 9999,  // In cents
+//   clientSecret: 'pi_xxx_secret_xxx',  // See the note below — NOT always a secret
+//   amount: '99.99',                    // DECIMAL STRING, not cents. parseFloat() it.
 //   currency: 'USD',
-//   status: 'requires_payment_method'
+//   status: 'requires_payment_method',
+//   provider: 'stripe',                 // which processor took the intent
+//   clientSdk: { renderType: 'sdk-widget', /* … */ },  // HOW to render — see below
 // }
 ```
 
+> **`amount` is a decimal string in the charged currency (`"99.99"`), never an
+> integer of cents.** `parseFloat()` it before any math; do not divide by 100.
+
+**`provider` and `clientSdk` are the two fields that decide what you render**, and
+both are omitted from most copy-paste snippets. `clientSdk.renderType` is one of
+`'sdk-widget' | 'iframe' | 'redirect' | 'sandbox' | 'embedded-fields'`:
+
+| `renderType`   | What `clientSecret` holds | What to do                                                                                       |
+| -------------- | ------------------------- | ------------------------------------------------------------------------------------------------ |
+| `'sandbox'`    | (unused)                  | No payment UI — complete the checkout directly                                                   |
+| `'sdk-widget'` | Client secret / auth code | Load `clientSdk.scriptUrl`, init with `clientSdk.initConfig`, mount into `clientSdk.containerId` |
+| `'iframe'`     | **A URL**                 | Load it in an iframe (inline if its path contains `/embed/`, else in a modal)                    |
+| `'redirect'`   | **A URL**                 | Navigate the top-level window to it; on return call `confirmSdkPayment()`                        |
+
+Branch on `clientSdk?.renderType`. **Never** branch on "does `clientSdk` exist" —
+every provider returns one, sandbox included — and never hard-code by provider name.
+Only `provider === 'stripe'` has a `clientSdk.initConfig.publishableKey`.
+
+#### Confirm an SDK / redirect payment
+
+```typescript
+// confirmSdkPayment(checkoutId, providerResponseData?) => Promise<{ confirmed: boolean }>
+await client.confirmSdkPayment(checkoutId);
+
+// With the provider's own callback payload (transactionId, transactionToken,
+// confirmation_number, …) when its SDK hands you one:
+await client.confirmSdkPayment(checkoutId, { transactionId: 'txn_123' });
+```
+
+Call it in two places:
+
+- **In an in-page SDK's success callback** (`renderType: 'sdk-widget'`) — it tells
+  the backend the payment succeeded, which triggers order creation.
+- **On the return page from a `renderType: 'redirect'` provider** — redirect
+  providers don't capture until the server confirms, so this is what makes the
+  backend verify with the provider and capture.
+
+It is **idempotent** (safe if a webhook already captured) and safe to skip on
+failure — `getPaymentStatus()` / `waitForOrder()` re-verify server-side. Wrap it in
+`try/catch` and carry on:
+
+```typescript
+try {
+  await client.confirmSdkPayment(checkoutId);
+} catch {
+  // Not fatal — polling re-verifies.
+}
+const result = await client.waitForOrder(checkoutId);
+```
+
+Do **not** call it on your `cancelUrl` — the buyer abandoned; just let them retry.
+
+`confirmGrowPayment()` is a deprecated wrapper around this method; call
+`confirmSdkPayment()` directly.
+
+> `confirmSdkPayment()`, `getPaymentStatus()`, `createPaymentIntent()`,
+> `getPaymentProviders()` and `waitForOrder()` are **sales-channel mode only** —
+> they throw `BrainerceError` 400 on a `storeId` or `apiKey` client.
+
 **Routing to a specific provider (`providerId`).** With `getPaymentProviders()` you
 render additive **express buttons** (e.g. PayPal as a `WALLET`) alongside the primary
 card form. When the buyer taps one, pass that provider's `id` so the charge routes to
@@ -2974,7 +3130,10 @@ selectable.
 Use the client secret with Stripe.js to collect payment:
 
 ```typescript
-// Initialize Stripe.js with the public key from getPaymentConfig()
+// Initialize Stripe.js with the publishable key. Prefer
+// intent.clientSdk.initConfig.publishableKey (per-intent, correct for the
+// provider that actually took the charge); config.publicKey is the deprecated
+// getPaymentConfig() fallback.
 const stripe = await loadStripe(config.publicKey);
 
 // Create Elements and Payment Element
@@ -3131,7 +3290,10 @@ export default function CheckoutPaymentPage() {
         const checkoutId = new URLSearchParams(window.location.search).get('checkout_id');
         if (!checkoutId) throw new Error('No checkout ID');
 
-        // Get payment configuration
+        // Get payment configuration.
+        // NOTE: getPaymentConfig() is @deprecated — single-provider only. In new
+        // code use getPaymentProviders() and render additive express methods
+        // alongside the primary card form. Kept here as a minimal Stripe example.
         const config = await client.getPaymentConfig();
         setPaymentConfig(config);
 
@@ -3306,10 +3468,23 @@ if (intent.clientSdk?.renderType === 'sandbox') {
 
 #### Register Customer
 
+> **Password policy — enforced on `registerCustomer()` AND `resetPassword()`.**
+> At least **8 characters**, with at least one **lowercase** letter, one
+> **uppercase** letter, one **digit**, and one **special character**
+> (`/^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)(?=.*[^a-zA-Z0-9]).{8,}$/`). A password that
+> fails returns HTTP 400 with the message _"Password must contain at least 1
+> uppercase letter, 1 lowercase letter, 1 number, and 1 special character"_.
+>
+> `securepassword123` fails (no uppercase, no special). `Password123` fails (no
+> special). `SecurePass123!` passes. Mirror the full rule in your own client-side
+> validation and in the field's helper text — a form that only says "min 8
+> characters" produces a 400 the shopper cannot explain, and render the server's
+> message verbatim when one comes back.
+
 ```typescript
 const auth = await client.registerCustomer({
   email: 'customer@example.com',
-  password: 'securepassword123',
+  password: 'SecurePass123!',
   firstName: 'John',
   lastName: 'Doe',
 });
@@ -3319,7 +3494,8 @@ if (auth.requiresVerification) {
   localStorage.setItem('verificationToken', auth.token);
   window.location.href = '/verify-email';
 } else {
-  setCustomerToken(auth.token);
+  client.setCustomerToken(auth.token);
+  await client.syncCartOnLogin(); // REQUIRED — claims the guest cart onto the account
   // Redirect back to store, not /account
   window.location.href = '/';
 }
@@ -3328,8 +3504,9 @@ if (auth.requiresVerification) {
 #### Login Customer
 
 ```typescript
-const auth = await client.loginCustomer('customer@example.com', 'password123');
-setCustomerToken(auth.token);
+const auth = await client.loginCustomer('customer@example.com', 'SecurePass123!');
+client.setCustomerToken(auth.token);
+await client.syncCartOnLogin(); // REQUIRED — claims the guest cart onto the account
 
 // Best practice: redirect back to previous page or home
 const returnUrl = localStorage.getItem('returnUrl') || '/';
@@ -3337,6 +3514,13 @@ localStorage.removeItem('returnUrl');
 window.location.href = returnUrl;
 ```
 
+> **`setCustomerToken()` is a plain field setter — it does not touch the cart.**
+> Always follow it with `await client.syncCartOnLogin()`. Skip it and the
+> shopper's guest cart is never attached to their account, which quietly breaks
+> every identity-keyed feature: first-order discounts, per-customer coupon caps,
+> and abandoned-cart recovery. Same rule after `verifyEmail()` and after
+> `exchangeOAuthCode()`.
+
 > **Best Practice:** Before showing login page, save the current URL with `localStorage.setItem('returnUrl', window.location.pathname)`. After login, redirect back to that URL. This is how Amazon, Shopify, and most e-commerce sites work.
 
 #### Forgot Password
@@ -3352,7 +3536,7 @@ await client.forgotPassword('customer@example.com');
 ```typescript
 // On /reset-password page, extract token from URL
 const token = new URLSearchParams(window.location.search).get('token');
-const result = await client.resetPassword(token!, 'newSecurePassword123');
+const result = await client.resetPassword(token!, 'NewSecurePass123!');
 // result.message = "Password has been reset successfully"
 ```
 
@@ -3555,7 +3739,7 @@ When `requiresVerification` is true in the registration response, the customer n
 ```typescript
 const auth = await client.registerCustomer({
   email: 'customer@example.com',
-  password: 'securepassword123',
+  password: 'SecurePass123!',
   firstName: 'John',
 });
 
@@ -4495,11 +4679,9 @@ await client.createAttributeOption(sizeAttr.id, {
   source: 'GLOBAL',
 });
 
-// Get options, update, delete
+// Get options, update the attribute, delete the attribute
 const options = await client.getAttributeOptions(colorAttr.id);
 await client.updateAttribute(colorAttr.id, { displayType: 'IMAGE_SWATCH' });
-await client.updateAttributeOption(colorAttr.id, options[0].id, { swatchColor: '#CC0000' });
-await client.deleteAttributeOption(colorAttr.id, options[0].id);
 await client.deleteAttribute(colorAttr.id);
 
 // Storefront: render swatches from product data
@@ -4510,6 +4692,15 @@ const swatches = getProductSwatches(product);
 // Returns: [{ attributeName: 'Color', displayType: 'COLOR_SWATCH', options: [{ name: 'Red', swatchColor: '#FF0000', ... }] }]
 ```
 
+> **Editing or deleting a single option is dashboard-only.** `/api/v1/attributes/:id/options`
+> exposes exactly two verbs — `GET` (list) and `POST` (add). There is no per-option route
+> on the public API, so `client.updateAttributeOption()` and `client.deleteAttributeOption()`
+> return **404**. The per-option routes exist only on the dashboard API
+> (`PUT` / `DELETE /api/stores/:storeId/attributes/:id/options/:optionId`), behind Clerk
+> auth. Recolour a swatch or drop an option in the dashboard. Everything else on
+> attributes — create, list, `updateAttribute`, `deleteAttribute`, `getAttributeOptions`,
+> `createAttributeOption` — works from the SDK as shown above.
+
 ### Shipping Configuration
 
 ```typescript
@@ -4845,8 +5036,9 @@ vibe-coded site **only if** it has been explicitly published to that
 connection. Entities with no publish rows are invisible to every vibe-coded
 site, including in product responses (the related categories/brands/tags
 arrays and the metafields array on each product are filtered the same way).
-Merchants publish through the dashboard's per-row Platforms cell or via the
-admin SDK below.
+Merchants publish through the dashboard's per-row Platforms cell; for
+categories, tags and brands the admin SDK below does the same thing. Custom
+fields are the exception — see the note under the snippet.
 
 ```typescript
 // Publish a product to a sales channel (accepts record ID or vc_* connection ID)
@@ -4856,24 +5048,38 @@ await client.unpublishProductFromSalesChannel('prod_id', 'vc_conn_id');
 
 // Publish a category to a specific vibe-coded site
 await client.publishCategoryToVibeCodedSite('cat_id', 'conn_id');
-// Tag, brand, metafield definition follow the same shape:
+// Tag and brand follow the same shape:
 await client.publishTagToVibeCodedSite('tag_id', 'conn_id');
 await client.publishBrandToVibeCodedSite('brand_id', 'conn_id');
-await client.publishMetafieldDefinitionToVibeCodedSite('def_id', 'conn_id');
 
 // Unpublish — entity is no longer visible to that site (but stays visible
 // to every other site if no other publishes exist).
 await client.unpublishCategoryFromVibeCodedSite('cat_id', 'conn_id');
 await client.unpublishTagFromVibeCodedSite('tag_id', 'conn_id');
 await client.unpublishBrandFromVibeCodedSite('brand_id', 'conn_id');
-await client.unpublishMetafieldDefinitionFromVibeCodedSite('def_id', 'conn_id');
 
 // Read which sites an entity is published to via the admin list/get response —
-// `vibeCodedPublishes` is included on every list/get for these 4 entity types:
+// `channelPublishes` is included on every list/get for these 4 entity types:
 const cat = await client.getCategory('cat_id');
-cat.vibeCodedPublishes; // [{ connection: { id, name, connectionId } }, ...]
+cat.channelPublishes; // [{ salesChannel: { id, name, connectionId } }, ...]
 ```
 
+> **Custom fields are the exception — publish them in the dashboard.**
+> `client.publishMetafieldDefinitionToVibeCodedSite()` and
+> `client.unpublishMetafieldDefinitionFromVibeCodedSite()` target
+> `/api/v1/metafield-definitions/:id/publish-vibe-coded`, which the public API does not
+> expose; both return **404**. Only the dashboard API carries those routes
+> (`POST /api/stores/:storeId/metafield-definitions/:id/publish` and `…/unpublish`),
+> behind Clerk auth. **Reading is unaffected** — `getMetafieldDefinitions()` and
+> `getMetafieldDefinition()` both return `channelPublishes` exactly like the other three
+> entity types, so you can still see which sites a custom field is published to; you just
+> cannot change it from the SDK.
+
+> **`vibeCodedPublishes` and its `connection` sub-key are deprecated.** Both are
+> still emitted as back-compat aliases of `channelPublishes` / `salesChannel` and
+> are removed in SDK 2.0. Read `channelPublishes[].salesChannel` in new code —
+> the customer section below already does.
+
 **Cross-account isolation:** publishing only succeeds when the entity and the
 target vibe-coded connection both belong to the same account. Cross-account
 calls fail with `404 Not Found` (the connection ID is treated as if it doesn't
@@ -4919,48 +5125,33 @@ not prevent that person from buying on that storefront, and the row comes back
 the next time they sign in or order there. There is no API to bar a customer
 from a sales channel.
 
-### Store Team Management
-
-Each store has its own team with roles (`OWNER`, `MANAGER`, `STAFF`, `VIEWER`) and granular permissions.
-
-```typescript
-// List team members + pending invitations for a store
-const { members, invitations } = await client.getStoreTeam('store_id');
-
-// Invite a new member
-const invitation = await client.inviteStoreMember('store_id', {
-  email: 'newmember@example.com',
-  role: 'MANAGER', // 'MANAGER' | 'STAFF' | 'VIEWER'
-  salesChannelIds: ['vc_abc123'], // optional: restrict to vibe-coded channels (connectionId); omit/[] = all channels
-});
-
-// Update member role or set custom permissions
-await client.updateStoreMember('store_id', 'member_id', { role: 'STAFF' });
-await client.updateStoreMember('store_id', 'member_id', {
-  permissions: ['VIEW_PRODUCTS', 'VIEW_ORDERS', 'FULFILL_ORDERS'], // overrides role defaults
-});
-
-// Replace a member's vibe-coded sales-channel scope ([] clears all restrictions)
-await client.updateStoreMemberSalesChannels('store_id', 'member_id', {
-  salesChannelIds: ['vc_abc123', 'vc_def456'],
-});
-
-// Remove a member
-await client.removeStoreMember('store_id', 'member_id');
-
-// Manage invitations
-await client.resendStoreInvitation('store_id', 'inv_id');
-await client.revokeStoreInvitation('store_id', 'inv_id');
-
-// Get all stores accessible to the current user (owned + shared)
-const stores = await client.getMyStores();
-// [{ id, name, role: 'OWNER', context: 'owner' }, { id, name, role: 'MANAGER', context: 'member' }]
-
-// Get user's permissions for a specific store
-const { role, permissions } = await client.getMyStorePermissions('store_id');
-```
-
-> **Note:** The previous account-level team methods (`getTeamMembers`, `inviteTeamMember`, etc.) are deprecated. Use the store-level methods above instead.
+### Store Team Management — dashboard-only
+
+Each store has its own team with roles (`OWNER`, `MANAGER`, `STAFF`, `VIEWER`) and
+granular permissions, including per-sales-channel scoping. **Managing it is a dashboard
+operation. There is no SDK path to it, and this is deliberate.**
+
+This section previously showed nine store-level team calls. They do not work:
+`getStoreTeam`, `inviteStoreMember`, `updateStoreMember`, `updateStoreMemberSalesChannels`,
+`removeStoreMember`, `resendStoreInvitation` and `revokeStoreInvitation` call
+`/api/v1/stores/:storeId/team…`, and `getMyStores` / `getMyStorePermissions` call
+`/api/v1/me/stores…`. The public API exposes neither prefix, so every one of them returns
+**404**.
+
+**This is not a path typo waiting on a fix.** The real endpoints exist at
+`/api/stores/:storeId/team…`, guarded by `DashboardOnlyGuard`, which rejects API-key
+principals _by design_: an API key carries a `storeId` but never a `userId`, and the
+team service resolves a missing `userId` to an OWNER role. Failing closed at the boundary
+is what stops an API key from escalating its own team permissions. Pointing the SDK at
+the correct path would earn a `403` instead of a `404`. Invite, re-scope and remove
+members in the dashboard.
+
+> **The older account-level methods are not the workaround.** `getTeamMembers`,
+> `getTeamInvitations`, `inviteTeamMember`, `resendTeamInvitation`, `revokeTeamInvitation`,
+> `updateTeamMemberRole` and `removeTeamMember` do still reach `/api/v1/team/…` — but they
+> manage the **account** team, not a store's, and all seven are `@deprecated`. Their JSDoc
+> tells you to migrate to the store-level methods named above; ignore that advice, because
+> those methods 404. Don't build new integrations on either family.
 
 ### Email Settings & Templates
 
@@ -5030,10 +5221,6 @@ const { summarized, summary } = await client.summarizeBotConversation(conversati
 ### Sync Conflict Resolution
 
 ```typescript
-// Product sync conflicts
-const conflicts = await client.getSyncConflicts();
-await client.resolveSyncConflict('conflict_id', 'MERGE'); // or 'CREATE_NEW'
-
 // Metafield conflicts
 const metafieldConflicts = await client.getMetafieldConflicts();
 await client.resolveMetafieldConflict('conflict_id', {
@@ -5042,6 +5229,12 @@ await client.resolveMetafieldConflict('conflict_id', {
 await client.ignoreMetafieldConflict('conflict_id');
 ```
 
+> **Product sync conflicts are dashboard-only.** `client.getSyncConflicts()` and
+> `client.resolveSyncConflict()` call `/api/v1/sync-conflicts`, which the public API does
+> not expose; both return **404**. Review a product conflict and pick `MERGE` or
+> `CREATE_NEW` in the dashboard. The three metafield-conflict methods above are a separate
+> surface (`/api/v1/metafield-conflicts`) and do work with an API key.
+
 ### OAuth Provider Configuration
 
 ```typescript
@@ -5059,7 +5252,7 @@ await client.deleteOAuthProvider('GOOGLE');
 
 ### Modifier Groups Management
 
-12 admin methods covering group / modifier / attachment CRUD. Money fields are decimal strings on the wire (`priceDelta: "5.00"`). Server-side validation failures arrive as a `MODIFIER_VALIDATION_FAILED` envelope on `BrainerceError.details`.
+12 admin methods covering group / modifier / attachment CRUD. Money fields are decimal strings on the wire (`priceDelta: "5.00"`). Server-side validation failures arrive as a `MODIFIER_VALIDATION_FAILED` envelope on `BrainerceError.details`, with the per-issue list nested at `err.details.details.errors`.
 
 ```typescript
 // Group CRUD
@@ -5920,7 +6113,9 @@ export default function RegisterPage() {
           <input placeholder="Last Name" value={lastName} onChange={e => setLastName(e.target.value)} required className="border p-2 rounded" />
         </div>
         <input type="email" placeholder="Email" value={email} onChange={e => setEmail(e.target.value)} required className="w-full border p-2 rounded" />
-        <input type="password" placeholder="Password (min 8 characters)" value={password} onChange={e => setPassword(e.target.value)} required minLength={8} className="w-full border p-2 rounded" />
+        {/* The API rejects anything weaker: 8+ chars with a lowercase, an uppercase,
+            a digit AND a special character. `minLength={8}` alone lets a 400 through. */}
+        <input type="password" placeholder="8+ chars, upper + lower + number + symbol" value={password} onChange={e => setPassword(e.target.value)} required minLength={8} pattern="(?=.*[a-z])(?=.*[A-Z])(?=.*\d)(?=.*[^a-zA-Z0-9]).{8,}" title="At least 8 characters with one uppercase letter, one lowercase letter, one number and one special character" className="w-full border p-2 rounded" />
         <button type="submit" disabled={loading} className="w-full bg-black text-white py-3 rounded">
           {loading ? 'Creating Account...' : 'Create Account'}
         </button>
@@ -6344,7 +6539,8 @@ const handleAddToCart = async (productId: string, quantity: number) => {
   }
 };
 
-// Checkout with toast feedback
+// Checkout with toast feedback (cash-on-delivery / sandbox store — a store that
+// takes payment must run the checkout + payment-intent flow instead)
 const handleCheckout = async () => {
   try {
     const order = await client.submitGuestOrder();
@@ -6420,6 +6616,7 @@ export function useBrainerceAction<T>() {
 const { execute, isLoading } = useBrainerceAction();
 
 const handlePlaceOrder = () => {
+  // Cash-on-delivery / sandbox only — submitGuestOrder() collects no payment.
   execute(() => client.submitGuestOrder(), {
     successMessage: 'Order placed successfully!',
     onSuccess: (order) => navigate(`/order/${order.orderId}`),