brainerce 1.58.1 → 1.63.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
 
@@ -45,13 +62,14 @@ Every Brainerce storefront must include **all mandatory features** below. Featur
 | Login + verification branch                              | `client.loginCustomer()`                                                                                                                                     | ✅          |
 | Forgot / reset password                                  | `client.forgotPassword()`, `client.resetPassword()`                                                                                                          | ✅          |
 | OAuth sign-in buttons + callback handler                 | `client.getAvailableOAuthProviders()`                                                                                                                        | ✅          |
-| Account area (profile + order history)                   | `client.getMyProfile()`, `client.getMyOrders()`                                                                                                              | ✅          |
+| Account area (profile + order history)                   | `client.getMyProfile()`, `client.updateMyProfile()`, `client.getMyOrders()`                                                                                  | ✅          |
 | Loyalty & rewards (points balance + tiers + redeem)      | `client.getLoyaltyStatus()`, `client.getAvailableRewards()`, `client.getRecommendedReward()`, `client.redeemLoyaltyReward(id)`, `client.reportSocialShare()` | conditional |
 | Loyalty paid membership (premium subscription)           | `client.getMembershipPlans()`, `client.getMySavedPaymentMethods()`, `client.subscribeToMembership(params)`, `client.cancelMembership()`                      | conditional |
 | Embeddable loyalty widget (points + rewards on ANY site) | `client.getLoyaltyWidgetSession()`                                                                                                                           | conditional |
 | Global header: cart count + search autocomplete          | `client.getCart()`, `client.getSearchSuggestions(query)`                                                                                                     | ✅          |
 | Discount banners + product badges                        | `client.getDiscountBanners()`, `client.getProductDiscountBadge(productId)`                                                                                   | ✅          |
 | Product reviews on PDP + JSON-LD aggregateRating         | `client.listProductReviews(id)`, `client.submitProductReview(id, …)`                                                                                         | ✅          |
+| Customer photos on reviews                               | `client.uploadReviewPhoto(productId, file)`, then `imageKeys` on submit                                                                                      | conditional |
 | Site chrome (header + footer + announcement bar)         | `client.content.header.get()`, `client.content.footer.get()`, `client.content.announcement.list()`                                                           | ✅          |
 | FAQ page                                                 | `client.content.faq.get('main', locale)`                                                                                                                     | conditional |
 | Static pages catch-all (`/pages/[slug]`)                 | `client.content.page.getBySlug(slug, locale)`                                                                                                                | conditional |
@@ -68,7 +86,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
@@ -81,6 +99,7 @@ Violating any of these causes production incidents or broken orders. Read them b
 
 - ALWAYS handle the `requiresVerification` flag in `registerCustomer` and `loginCustomer` responses. If true, route to the verify-email step BEFORE treating the user as logged in.
 - ALWAYS build the verify-email, forgot-password, and reset-password flows even when the store currently has email verification disabled. They auto-hide when unused.
+- ALWAYS read `requireBirthday` from `getStoreInfo()` before rendering the signup form. When it is true the merchant made the birthday mandatory on that sales channel, and `registerCustomer` returns HTTP 400 unless you send both `birthMonth` (1-12) and `birthDay` (1-31). Month and day only, never a year.
 - ALWAYS build OAuth button placeholders and a callback handler even when no OAuth provider is configured.
 - NEVER silently swallow auth errors. Render the specific error (invalid credentials, expired token, rate limited).
 
@@ -160,10 +179,12 @@ These sequences are non-negotiable. The order of SDK calls matters.
 
 ### Registration flow
 
-1. Collect email, password, first name, last name.
+1. Collect email, password, first name, last name. Read `requireBirthday` from `getStoreInfo()`: when it is true, collect a birthday month and day as well, because the register call is rejected without them.
 2. Call `registerCustomer`:
    ```ts
    const result = await client.registerCustomer({ email, password, firstName, lastName });
+   // Channel requires a birthday? Send both fields, never a year:
+   // { email, password, firstName, lastName, birthMonth: 4, birthDay: 17 }
    ```
 3. Branch on `result.requiresVerification`:
    - `true` → store token temporarily, route to verify-email UI (do NOT set token yet)
@@ -419,7 +440,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 +594,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 +1095,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 +1692,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 +1752,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".
@@ -1834,7 +1911,8 @@ fields.forEach((field) => {
   // field.minLength, field.maxLength: validation for text fields
   // field.minValue, field.maxValue: validation for number fields
   // field.dateAvailability: constraints for DATE/DATETIME fields (blocked
-  //   weekdays/dates, min/max date, business hours + slots) — see
+  //   weekdays/dates, min/max date, leadTimeMinutes/cutoffTime/maxDaysAhead,
+  //   business hours + slots) — see
   //   computeAvailableSlots()/getBusinessHoursForDate()/isDateValueAllowed()
   //   below. DATE values are sent as "YYYY-MM-DD"; DATETIME as one ISO-8601
   //   value — never a date with a slot LABEL glued on ("...T13:00-14:00" is
@@ -1907,15 +1985,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 +2200,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 +2318,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 +2518,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
@@ -2591,7 +2686,8 @@ const updatedCheckout = await client.setCheckoutCustomFields(checkoutId, {
 **DATE / DATETIME fields with availability constraints**
 
 A `DATE`/`DATETIME` field's `dateAvailability` (blocked weekdays, blocked specific
-dates, min/max date range, and — for `DATETIME` — business hours + time
+dates, min/max date range, the relative bounds `leadTimeMinutes` / `cutoffTime` /
+`maxDaysAhead`, and — for `DATETIME` — business hours + time
 slots) is a merchant-configured restriction on which values the customer may
 pick. Use `computeAvailableSlots()` / `getBusinessHoursForDate()` /
 `isDateValueAllowed()` to drive your own date-picker/slot-picker UI — the SDK
@@ -2610,19 +2706,24 @@ const { timezone } = await client.getStoreInfo(); // IANA string, e.g. "Asia/Jer
 const deliveryField = fields.find((f) => f.key === 'delivery_slot');
 const availability = deliveryField?.dateAvailability;
 
+// The clock. Without it leadTimeMinutes/cutoffTime/maxDaysAhead are SKIPPED and
+// the picker offers days the server refuses; `now` defaults to this instant.
+const clock = { timezone };
+
 // Disable days on your calendar of choice. Note the SECOND condition: once
 // businessHours has any entry it is an ALLOWLIST, so a weekday it doesn't
 // mention is closed all day even though the calendar rules accept it.
 const isDayDisabled = (ymd: string) =>
-  !isCalendarDateAllowed(ymd, availability) ||
+  !isCalendarDateAllowed(ymd, availability, clock) ||
   (!!availability?.businessHours?.length &&
-    getBusinessHoursForDate(availability, ymd).length === 0);
+    getBusinessHoursForDate(availability, ymd, clock).length === 0);
 
 // Once the customer picks a day, offer times. computeAvailableSlots() returns
 // [] when the field has no slotDurationMinutes — that is NOT "day closed",
-// which is why the windows are checked separately.
-const slots = computeAvailableSlots(availability, '2026-08-15'); // ["09:00", "09:30", ...]
-const windows = getBusinessHoursForDate(availability, '2026-08-15'); // [{ weekday, open, close }]
+// which is why the windows are checked separately. A day with two windows
+// (mornings and evenings) yields both, in chronological order.
+const slots = computeAvailableSlots(availability, '2026-08-15', clock); // ["09:00", "09:30", ...]
+const windows = getBusinessHoursForDate(availability, '2026-08-15', clock); // [{ weekday, open, close }]
 
 if (slots.length) {
   // Render slot buttons; the submitted time must equal a slot start exactly.
@@ -2646,6 +2747,19 @@ What you read back is normalized, not the string you sent: `YYYY-MM-DD` for
 `DATE`, an ISO-8601 UTC instant for `DATETIME`. Use `parseDateFieldValue()` if
 you want to apply the exact same parse client-side before submitting.
 
+**Relative bounds.** `leadTimeMinutes` puts the earliest bookable moment at
+`now + leadTime`. `cutoffTime` ("HH:mm", store-local) pushes the earliest
+bookable DATE on by a further day once the store clock reaches it, which is how
+"order by 14:00 for tomorrow" is expressed. `maxDaysAhead` is a rolling ceiling
+counted from today. All three are re-resolved on every call, so unlike an
+absolute `minDate` they never go stale, and all three apply to plain `DATE`
+fields as well. They are accepted on **checkout** custom fields only: a product
+metafield and an order custom field are written by an admin rather than picked
+by a shopper, so there is no ordering moment to measure them from and the API
+rejects them there. `resolveRelativeBounds(availability, clock)` returns the
+concrete dates they currently mean, which is what to show a shopper who asked
+for something too soon.
+
 The backend independently re-validates every submitted value against the same
 constraints at write time — this is a client-side UX aid, not the source of
 enforcement.
@@ -2917,16 +3031,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 +3062,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 +3154,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 +3314,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,12 +3492,37 @@ 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.
+
+> **Birthday fields.** `birthMonth` (1-12) and `birthDay` (1-31) are optional,
+> month and day only, never a year. Send both or neither: one on its own is
+> rejected with HTTP 400, and so is a day the month does not have. When
+> `getStoreInfo().requireBirthday` is true the merchant made the birthday
+> mandatory on that sales channel and a register call without it fails with
+> HTTP 400. That flag only reaches sales-channel mode (`salesChannelId`); a
+> `storeId`-mode storefront never receives it and its register route never
+> enforces it.
+
 ```typescript
 const auth = await client.registerCustomer({
   email: 'customer@example.com',
-  password: 'securepassword123',
+  password: 'SecurePass123!',
   firstName: 'John',
   lastName: 'Doe',
+  // Optional, unless getStoreInfo().requireBirthday is true. Both or neither.
+  birthMonth: 4,
+  birthDay: 17,
 });
 
 // Check if email verification is required
@@ -3319,7 +3530,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 +3540,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 +3550,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 +3572,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"
 ```
 
@@ -3373,6 +3593,12 @@ console.log(profile.firstName);
 console.log(profile.email);
 console.log(profile.addresses);
 
+// Birthday the customer saved: month and day only, never a year. Both fields
+// arrive together or neither does, so testing one is enough.
+if (profile.birthMonth && profile.birthDay) {
+  console.log(`Birthday: ${profile.birthDay}/${profile.birthMonth}`);
+}
+
 // profile.role is a free-form segment the merchant sets from the dashboard
 // (e.g. "wholesale", "vip") — not customer-editable. Use it to gate custom
 // storefront features/UI: wholesale pricing, a VIP section, etc.
@@ -3381,6 +3607,30 @@ if (profile.role === 'wholesale') {
 }
 ```
 
+#### Update Customer Profile
+
+Storefront or vibe-coded mode, requires `customerToken`. The call returns the
+saved `CustomerProfile`, so re-render the form from the response instead of
+from what you sent. `email` and `role` are not customer-editable and are not
+accepted here.
+
+```typescript
+const updated = await client.updateMyProfile({
+  firstName: 'John',
+  lastName: 'Doe',
+  phone: '+15550100',
+  acceptsMarketing: true,
+  // Birthday: month and day only, never a year. Send both or neither, and the
+  // day has to exist in the month (day 31 in February is rejected with 400).
+  birthMonth: 4,
+  birthDay: 17,
+});
+
+// The saved birthday comes back on the response and on getMyProfile(), so the
+// profile form shows what the customer stored instead of two empty fields.
+console.log(updated.birthMonth, updated.birthDay);
+```
+
 #### Get Customer Orders
 
 ```typescript
@@ -3462,10 +3712,15 @@ await client.registerCustomer({ email, password, referralCode: refFromQuery });
 // bonus (held through the program's pending window, like order points).
 ```
 
-Birthday gifts need no SDK calls beyond profile data: set the customer's
-`birthMonth`/`birthDay` (1-12 / 1-31, no year) via `updateMyProfile()` and the
-platform emails a one-time gift coupon ahead of their birthday automatically
-(when the store has it enabled).
+Birthday gifts need no SDK calls beyond profile data: save the customer's
+`birthMonth`/`birthDay` (1-12 / 1-31, month and day only, never a year) via
+`updateMyProfile()` and the platform emails a one-time gift coupon ahead of
+their birthday automatically (when the store has it enabled). Both values come
+back on `getMyProfile()`, on `getCheckoutPrefillData()` and on the `Customer`
+read types, so a profile form renders the birthday the customer already gave
+you rather than an empty pair of fields. `registerCustomer()` accepts the same
+two fields, and a channel with `requireBirthday` turned on insists on them at
+signup.
 
 #### Paid Loyalty Membership
 
@@ -3555,8 +3810,10 @@ 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',
+  // Add birthMonth + birthDay here too when getStoreInfo().requireBirthday is
+  // true, or this call fails with HTTP 400 before any email is sent.
 });
 
 if (auth.requiresVerification) {
@@ -4495,11 +4752,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 +4765,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 +5109,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 +5121,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 +5198,38 @@ 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 a substitute for this.** `getTeamMembers`,
+> `getTeamInvitations`, `inviteTeamMember`, `resendTeamInvitation`, `revokeTeamInvitation`,
+> `updateTeamMemberRole` and `removeTeamMember` do still reach `/api/v1/team/…` — but they
+> manage the **account** team, not a store's. They will not invite anyone to a store or
+> scope a member to a sales channel; only the dashboard does that.
+>
+> **For the account team, they remain the supported call.** All seven are tagged
+> `@deprecated`, which records an intent to retire them — not a migration you can perform
+> today. There is no API-key replacement: the store-level methods named above are
+> dashboard-only. Keep using these until an API-key route ships, and expect the tag to
+> outlive this note.
 
 ### Email Settings & Templates
 
@@ -5030,10 +5299,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 +5307,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 +5330,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
@@ -5889,6 +6160,8 @@ export default function RegisterPage() {
     setLoading(true);
     setError('');
     try {
+      // Add birthMonth + birthDay to this call (both, never a year) when
+      // getStoreInfo().requireBirthday is true for the channel.
       const auth = await client.registerCustomer({ email, password, firstName, lastName });
 
       // Check if email verification is required
@@ -5920,7 +6193,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>
@@ -5988,6 +6263,9 @@ export default function AccountPage() {
           <h2 className="text-xl font-bold mb-4">Profile</h2>
           <p><strong>Name:</strong> {profile.firstName} {profile.lastName}</p>
           <p><strong>Email:</strong> {profile.email}</p>
+          {profile.birthMonth && profile.birthDay && (
+            <p><strong>Birthday:</strong> {profile.birthDay}/{profile.birthMonth}</p>
+          )}
         </div>
 
         <div className="border rounded p-6">
@@ -6109,6 +6387,89 @@ const forms = await brainerce.contactForms.list();
 
 **Rate limit:** 3 submissions per 60 seconds per IP. Include a hidden honeypot field (and do not submit it) — bots that auto-fill every input will be rejected.
 
+**A form keyed `newsletter` is still an inquiry.** The key is a label, not a behaviour: the submission files a message and never touches marketing consent, so that address can never receive a campaign. For a mailing list, use [Newsletter Signup](#newsletter-signup-marketing-opt-in).
+
+---
+
+## Newsletter Signup (marketing opt-in)
+
+**SDK >= 1.60.** The email-capture popup, the footer subscribe bar, the exit-intent modal.
+
+```typescript
+await brainerce.marketing.subscribe({
+  email: 'jane@example.com',
+  locale: 'he', // language of the confirmation email
+  source: 'popup', // free-form, for the merchant's reporting
+  honeypot: hiddenFieldValue, // must be empty
+});
+// → { ok: true }
+```
+
+Also accepts `firstName`, `lastName`, and `sourceMetadata` (referrer, UTM params, the page the popup fired on).
+
+**⛔ It does not subscribe anyone.** The contact is created and mailed a confirmation link; the address is unmailable — and invisible to every campaign audience — until the recipient clicks it. Render **"Check your email to confirm — including your spam folder"** on success, never "You're subscribed". The spam-folder half matters: a confirmation filtered there is the commonest reason a signup never converts, and the 24-hour resend cooldown means no second copy arrives. Single opt-in is not available: without the click, anyone could subscribe anyone else's address.
+
+**⛔ The response carries no information.** `{ ok: true }` is returned identically for a brand-new address, one that confirmed months ago, one inside its 24-hour resend cooldown, and one suppressed after a hard bounce — otherwise the form would become a way to test who shops at this store. Show one message for every success; there is no branch to write.
+
+**Rate limit:** 3 requests per 60 seconds per IP, plus one confirmation email per address per store per 24 hours. A submission inside that cooldown still returns `{ ok: true }` and silently sends nothing — do not treat it as a failure or retry it.
+
+**Locale:** pass it on a multi-language storefront, or the confirmation email falls back to the store's language. `he` and `en` are written; anything else gets English.
+
+**No discount code is minted.** For a "10% off your first order" popup, the merchant creates one coupon with the `customer_first_order` condition and you display that fixed code after a successful call.
+
+The contact appears at `Customers` in the dashboard immediately, with **Accepts marketing** off; it flips on at confirmation. It is an ordinary guest customer record — no password, no account — and is the same row if that person later registers or checks out.
+
+---
+
+## Back-in-Stock Alerts
+
+**SDK >= 1.61.** The "email me when this is back" button on a sold-out product.
+
+```typescript
+await brainerce.stockAlerts.subscribe({
+  email: 'jane@example.com',
+  productId: product.id,
+  variantId: selectedVariant.id, // pass on ANY product with variants
+  locale: 'he', // language of the alert email
+  honeypot: hiddenFieldValue, // must be empty
+});
+// → { ok: true }
+```
+
+**⛔ It is not a subscription.** One email, about one item, carrying a link that stops it. No customer account is created and no marketing consent is granted. Label the button **"Email me when it's back"**, never "Subscribe" — and because it grants no consent, never hide it from a shopper who unsubscribed from your marketing.
+
+**⛔ Render it only when `getStoreInfo().stockAlertsEnabled !== false`, the item is out of stock, AND it cannot be backordered.** Requests for anything else — a storefront whose merchant switched the feature off, an in-stock item, a backorderable one, an untracked one, an unknown product id — are silently ignored, so a button in the wrong place looks like it worked and does nothing.
+
+```typescript
+const store = await brainerce.getStoreInfo();
+// `inv` is the SELECTED VARIANT's inventory when there is one, else the product's.
+const inv = selectedVariant?.inventory ?? product.inventory;
+
+const canOfferStockAlert =
+  store.stockAlertsEnabled !== false &&
+  inv?.trackingMode === 'TRACKED' &&
+  !inv.canPurchase &&
+  (inv.backorderMode ?? 'NONE') === 'NONE';
+```
+
+`backorderMode` is on `InventoryInfo` from SDK 1.61; older backends omit it, so treat `undefined` as `'NONE'`.
+
+The merchant controls the switch — and how many people are emailed per unit restocked — under **Channel settings → Inventory**, alongside the low-stock warning.
+
+**⛔ Pass `variantId` on every variable product.** Without it the alert waits on the product as a whole, so a shopper who wanted the medium is mailed when the small returns and arrives to find their size still gone.
+
+**⛔ The response carries no information.** `{ ok: true }` is returned identically for a new request, a duplicate, an unknown product, an item already in stock, and an address suppressed after a hard bounce — otherwise the button would become a way to read the store's stock levels. Show one message for every success; there is no branch to write.
+
+**Sending is not immediate, and not to everyone.** Availability is `total - reserved`, so an expiring cart briefly lifts a sold-out item above zero; the alert waits for stock to hold for a few minutes, then goes out in waves sized to the units that came back (500 waiting and 3 units restocked is roughly 9 emails, oldest request first). A shopper can therefore sit through a restock without hearing, so never promise "you'll be the first to know".
+
+**Rate limit:** 5 requests per 60 seconds per IP, at most 25 open alerts per address per store, and a 90-day life on an unfired alert. A duplicate request is a no-op, not a second alert; once an alert has fired the person can ask again the next time that item sells out.
+
+**Locale:** pass it on a multi-language storefront, or the alert falls back to the store's language. `he` and `en` are written; anything else gets English.
+
+**What it does not do:** no SMS or WhatsApp, no price-drop alerts, and no merchant-editable template — the body is fixed so it can never start carrying a discount code, which would turn a transactional message into a marketing one needing an unsubscribe link it does not have.
+
+The merchant reads the demand at `Products → Back-in-Stock Waitlist`: products ranked by how many people are waiting, with the addresses behind each number. There is no way to mail those people anything else from there, by design.
+
 ---
 
 ## Storefront Bot (AI chat widget)
@@ -6188,16 +6549,62 @@ export async function POST(req: Request) {
 
 ### Webhook Events
 
-| Event                | Description                     |
-| -------------------- | ------------------------------- |
-| `product.created`    | New product created             |
-| `product.updated`    | Product details changed         |
-| `product.deleted`    | Product removed                 |
-| `inventory.updated`  | Stock levels changed            |
-| `order.created`      | New order received              |
-| `order.updated`      | Order status changed            |
-| `cart.abandoned`     | Cart abandoned (no activity)    |
-| `checkout.completed` | Checkout completed successfully |
+**These 21 event types are what a subscription can actually register.** The
+backend validates the `events` array on create against exactly this list, so
+anything outside it is rejected rather than silently accepted.
+
+| Event                 | Description                                                                                                                                                                                              |
+| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `order.created`       | New order placed (any payment status)                                                                                                                                                                    |
+| `order.updated`       | Order metadata changed (status, address, items)                                                                                                                                                          |
+| `order.paid`          | Order is paid — provider capture **or** a merchant-recorded out-of-band payment (cash on delivery, bank transfer). Never assume a provider was involved; `payment.succeeded` does **not** fire for these |
+| `order.fulfilled`     | All items marked shipped/delivered                                                                                                                                                                       |
+| `order.cancelled`     | Order cancelled (by merchant or customer)                                                                                                                                                                |
+| `order.refunded`      | Order fully or partially refunded                                                                                                                                                                        |
+| `customer.created`    | New customer account created                                                                                                                                                                             |
+| `customer.updated`    | Customer profile or contact details changed                                                                                                                                                              |
+| `customer.deleted`    | Customer account deleted                                                                                                                                                                                 |
+| `product.created`     | New product added to catalog                                                                                                                                                                             |
+| `product.updated`     | Product attributes, variants, or pricing changed                                                                                                                                                         |
+| `product.deleted`     | Product removed from catalog                                                                                                                                                                             |
+| `inventory.updated`   | Stock level changed (any reason)                                                                                                                                                                         |
+| `inventory.low`       | Stock fell below the low-stock threshold                                                                                                                                                                 |
+| `checkout.completed`  | Checkout completed (synonym of `order.created` for now)                                                                                                                                                  |
+| `checkout.abandoned`  | Cart inactive for 1+ hours with no completion                                                                                                                                                            |
+| `payment.succeeded`   | Payment provider confirmed funds captured                                                                                                                                                                |
+| `payment.failed`      | Payment provider rejected the transaction                                                                                                                                                                |
+| `payment.refunded`    | Refund posted to the customer                                                                                                                                                                            |
+| `blog.post.published` | Post went live (manual, scheduled, or SEO Autopilot)                                                                                                                                                     |
+| `blog.post.updated`   | Published post content changed                                                                                                                                                                           |
+
+Payload shapes for each are in the
+[Event Catalogue](https://brainerce.com/docs/webhooks/events).
+
+`customer.created` now fires for **shopper self-signup on your storefront**, not
+just merchant-created customers, so a storefront that registers customers will
+start seeing it.
+
+> **⚠️ The `WebhookEventType` type does not match this table yet — in both
+> directions.** Treat the table, not the type, as the truth about what you can
+> subscribe to.
+>
+> **14 subscribable events are missing from the type:** `order.paid`,
+> `order.fulfilled`, `order.cancelled`, `order.refunded`, `customer.created`,
+> `customer.updated`, `customer.deleted`, `inventory.low`, `checkout.abandoned`,
+> `payment.succeeded`, `payment.failed`, `payment.refunded`,
+> `blog.post.published`, `blog.post.updated`. So
+> `isWebhookEventType(event, 'customer.created')` and a
+> `createWebhookHandler({ 'order.paid': … })` key **fail to compile**, even
+> though both deliver correctly at runtime. Cast the name
+> (`'customer.created' as WebhookEventType`) or read `event.event` as a
+> `string` and switch on it yourself. Do not conclude the event does not exist.
+>
+> **8 names in the type cannot be subscribed to at all:** `coupon.created`,
+> `coupon.updated`, `coupon.deleted`, `cart.created`, `cart.updated`,
+> `cart.abandoned`, `checkout.started`, `checkout.failed`. These compile
+> cleanly and then fail at subscription time. `cart.abandoned` in particular
+> was listed as a supported event here for a long time — use
+> `checkout.abandoned` instead.
 
 ---
 
@@ -6344,7 +6751,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 +6828,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}`),