brainerce 2.0.2 → 2.2.0

package/README.md

@@ -49,31 +49,35 @@ yarn add brainerce
 
 Every Brainerce storefront must include **all mandatory features** below. Features auto-hide when the underlying capability is disabled, so build them all anyway; they'll appear the moment the store owner enables them.
 
-| Feature                                                  | SDK entry point                                                                                                                                              | Mandatory   |
-| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- |
-| Product list with search, filter, pagination             | `client.getProducts()`, `client.getSearchSuggestions(query)`                                                                                                 | ✅          |
-| Product detail with variant picker, stock, price         | `client.getProductBySlug()` + helpers                                                                                                                        | ✅          |
-| Buyer customization fields (engraving, uploads, select)  | `product.customizationFields`, `client.uploadCustomizationFile()`                                                                                            | ✅          |
-| Cart (add, update, remove, coupon, totals)               | `client.addToCart()`, `getCartTotals(cart)`                                                                                                                  | ✅          |
-| Inventory reservation countdown                          | Cart expiry timestamp from `client.getCart(cartId)`                                                                                                          | ✅          |
-| Full checkout end-to-end with payment                    | `setShippingAddress → selectShippingMethod → getPaymentProviders → pay → handlePaymentSuccess → waitForOrder`                                                | ✅          |
-| Order confirmation (clear cart + wait for real order)    | `client.handlePaymentSuccess()`, `client.waitForOrder()`                                                                                                     | ✅          |
-| Register + email verification flow                       | `client.registerCustomer()`, `client.verifyEmail()`                                                                                                          | ✅          |
-| 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.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.smartGetCart()`, `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 |
-| Multi-language + RTL (when i18n enabled)                 | `client.setLocale()`, `client.getStoreDirection(locale)`                                                                                                     | conditional |
+| Feature                                                     | SDK entry point                                                                                                                                              | Mandatory   |
+| ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- |
+| Product list with search, filter, pagination                | `client.getProducts()`, `client.getSearchSuggestions(query)`                                                                                                 | ✅          |
+| Product detail with variant picker, stock, price            | `client.getProductBySlug()` + helpers                                                                                                                        | ✅          |
+| Buyer customization fields (engraving, uploads, select)     | `product.customizationFields`, `client.uploadCustomizationFile()`                                                                                            | ✅          |
+| Cart (add, update, remove, coupon, totals)                  | `client.addToCart()`, `getCartTotals(cart)`                                                                                                                  | ✅          |
+| Inventory reservation countdown                             | Cart expiry timestamp from `client.getCart(cartId)`                                                                                                          | ✅          |
+| Full checkout end-to-end with payment                       | `setShippingAddress → selectShippingMethod → getPaymentProviders → pay → handlePaymentSuccess → waitForOrder`                                                | ✅          |
+| Gift card redemption at checkout                            | `client.applyGiftCard(checkoutId, code)`, `client.removeGiftCard(checkoutId, tenderId)`, `client.checkGiftCardBalance(code)`                                 | conditional |
+| Order confirmation (clear cart + wait for real order)       | `client.handlePaymentSuccess()`, `client.waitForOrder()`                                                                                                     | ✅          |
+| Register + email verification flow                          | `client.registerCustomer()`, `client.verifyEmail()`                                                                                                          | ✅          |
+| 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.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.smartGetCart()`, `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 |
+| Multi-language + RTL (when i18n enabled)                    | `client.setLocale()`, `client.getStoreDirection(locale)`                                                                                                     | conditional |
+| Donation page (only when `getStoreInfo().donationsEnabled`) | `client.createDonation(input)`, `client.getDonation(id)`                                                                                                     | conditional |
+
+**⛔ The donation page is the one row that does NOT auto-hide.** Every other conditional feature above renders nothing until the merchant configures it, which is why you build them all anyway. `createDonation` is _rejected_ while donations are closed, so a donation page built for a store that has not opened them collects a donor's name, email and card details and then fails on submit. Gate that one on `getStoreInfo().donationsEnabled` and build nothing when it is false.
 
 ---
 
@@ -88,6 +92,7 @@ Violating any of these causes production incidents or broken orders. Read them b
 - NEVER hardcode product data, categories, or store copy. Brainerce is the database.
 - 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.
+- ALWAYS read merchant settings from `client.getStoreCapabilities()` rather than hardcoding them. The low-stock threshold, the reservation timeout, whether back-in-stock alerts are offered and which optional features exist are all per sales channel. A hardcoded `5` is wrong on every store whose merchant chose something else. Call it once at app start and share the result; it is per channel, not per product. One exception, because `getStoreCapabilities()` is vibe-coded mode only: read `donationsEnabled` from `getStoreInfo()`, which works in every mode and carries the same fact as `features.hasDonations`.
 
 ### State management
 
@@ -111,6 +116,32 @@ Violating any of these causes production incidents or broken orders. Read them b
 - NEVER use the checkout total as the cart total; they diverge (tax, shipping, discounts). Display `checkout.lineItems` on the summary, not `cart.items`.
 - The reservation timer is a hard guarantee. Display the countdown from the cart and let the SDK handle expiry.
 
+### Gift cards
+
+- **A gift card is a means of payment, not a discount.** `applyGiftCard` does NOT change `checkout.total`, and tax stays calculated on the full order value. What drops is `checkout.providerAmountDue`, the amount the payment provider will be charged. Render the card on **its own line below the total** ("Gift card −₪54.50", then "Amount due ₪150.50"), never inside the discount block and never added to `discountAmount`. Folding it in understates the taxable base to the shopper and on their receipt.
+- ALWAYS render applied cards from `checkout.tenders` (`{ tenderId, amountApplied }[]`), re-read with `getCheckout(checkoutId)`. A storefront that only remembers what `applyGiftCard` returned loses the card on a page reload while the hold is still live on the server, so the shopper applies it twice or is shown an amount the provider will not charge.
+- ALWAYS remove with `removeGiftCard(checkoutId, tenderId)`, never by code. A checkout can carry several cards, and the code is never echoed back.
+- NEVER try to tell refusals apart. An unknown code, an expired one, a spent one, a disabled one and one in the wrong currency all return the **same** HTTP 400 with the same message, on purpose: a response that distinguished them is an oracle for walking the code space. Show one message ("we can't use this code") and let the shopper re-type it. `checkGiftCardBalance` answers identically for unknown, disabled and expired cards.
+- Apply and remove cards **before** you create the payment intent. Once the checkout is `PAYMENT_PENDING` / `PAYMENT_PROCESSING` these calls fail with `CHECKOUT_LOCKED`, which is what stops a card being applied behind a charge that was already quoted.
+- NEVER subtract the card yourself when charging. `createPaymentIntent` already nets live gift cards off server-side; charge the intent's own `amount`.
+- When `providerAmountDue` is `'0.00'` the cards cover the whole order. There is nothing for a provider to charge: skip the payment step and call `completeCheckout(checkoutId)` — it is allowed in exactly this case and produces a real paid order. **Then still clear the cart**, with `handlePaymentSuccess(checkoutId)`, exactly as you would after a payment. `completeCheckout` returns `{ orderId }`, so there is no `waitForOrder` poll to do, but skipping the cart clear leaves the shopper looking at items they have just bought.
+- A card pays only in **its own currency**. There is no conversion, so a USD card is refused on an ILS checkout like any other unusable code.
+
+**Administering cards (admin `apiKey` only — see [Gift Cards (administration)](#gift-cards-administration)):**
+
+- ⛔ **`issueGiftCard` and `reissueGiftCard` return `plaintextCode` exactly once.** The platform stores only an HMAC of it. No later call, no dashboard screen and no database query can produce it again, so an integrator that logs the response and moves on has destroyed a card that a customer paid for. Persist it or deliver it in the same code path that made the call. The one recovery that exists is retrying the SAME `Idempotency-Key` within 24 hours, which replays the identical body; miss that window and the value is stranded on a card nobody can spend.
+- ⛔ **`reissueGiftCard` is not a resend.** It mints a new code, moves the whole balance onto it, and **revokes the old card** — a printed card in a customer's hand stops working the moment the call returns. Use it when a code is lost, never to "email it again".
+- **A `note` is mandatory** on `issueGiftCard`, `reissueGiftCard` and `adjustGiftCardBalance` (3-500 characters), and is written to the append-only ledger permanently. It is the row a finance review reads a year later, so write the reason, not `"api"`.
+- **There is no delete.** Not one route, not in bulk, not ever — the ledger is append-only and a card can carry a statutory retention life. `setGiftCardStatus(id, 'DISABLED')` is the reversible substitute. `bulkSetGiftCardStatus` takes `ACTIVE` and `DISABLED` only; `REVOKED` is refused there because revoking in bulk would strand balances with no replacement to move them to.
+- **Ask for the least scope you need.** `gift_cards:issue` mints stored value and `gift_cards:adjust` rewrites a balance; neither is implied by `gift_cards:read`. This platform grants them self-serve, where Shopify makes you ask their support for the equivalent — which puts the whole weight on asking for less. ⛔ **Never mint `gift_cards:*` for a read-only integration**: the wildcard matches the resource, not the action, so one string hands a BI sync the power to mint and to rewrite balances.
+- **Liability is per currency.** `getGiftCardLiability()` returns `byCurrency`, because balances in different currencies do not add up. Read the array, never the top-level figure alone, on a store that sells in more than one.
+
+### Donations
+
+- NEVER route a donation through the cart or the checkout. A donation has no line item, no quantity, no shipping and no order, and it is reported separately from sales. It has its own pair, `createDonation` / `getDonation`. The tell that you have modelled it wrong is the amount: a cart cannot let a donor type one, so a "Donation $18" product is the wrong shape — and it files every gift into the merchant's sales figures.
+- NEVER treat `createDonation` resolving as a completed gift. It returns `status: 'PENDING'` and a provider intent; the money has not moved. Complete the intent, then poll `getDonation(id)` for `PAID`. Nothing receipt-shaped before that.
+- ALWAYS gate the donation page on `getStoreInfo().donationsEnabled`. Unlike every other conditional feature in this SDK it does NOT auto-hide: `createDonation` is rejected while donations are closed, so a page built early collects a donor's details and then fails.
+
 ### Token handling
 
 - Customer auth tokens (`result.token` from `loginCustomer`/`registerCustomer`) should be passed to `client.setCustomerToken(token)`. The SDK stores session state internally. `setCustomerToken` is a plain setter, so always follow it with `await client.syncCartOnLogin()`, or the shopper's guest cart is never attached to their account and identity-keyed features (first-order discounts, per-customer usage caps, abandoned-cart recovery) misbehave.
@@ -177,6 +208,58 @@ These sequences are non-negotiable. The order of SDK calls matters.
    ```
 7. Display `checkout.lineItems` (not `cart.items`) on the order summary.
 
+If the store has gift cards on, the redemption field goes between step 3 and step 4 — see the flow below.
+
+### Gift card redemption flow
+
+Conditional: in `salesChannelId` mode, build it when `getStoreCapabilities().features.hasGiftCards` is true. That call is channel-only and `getStoreInfo()` carries no gift-card flag, so in `storeId` mode there is no switch to read — build the field anyway; a code on a store without cards is just refused. (Admin mode does have one: `getGiftCardLiability().enabled`. It gates **issuing**, not redemption, so it is not a reason to hide the field either.) It sits **inside** the checkout, after shipping is picked and **before** the payment intent, because applying a card changes what the provider is asked for.
+
+This flow is redemption only. Issuing, re-issuing, adjusting and disabling cards are admin-key operations — see [Gift Cards (administration)](#gift-cards-administration).
+
+1. Offer the field on the checkout page (optionally with a "check balance" affordance):
+
+   ```ts
+   const { balance, currency, usable } = await client.checkGiftCardBalance(code);
+   // usable === false for an unknown, disabled OR expired card — all identical, by design.
+   // Never render "expired" or "not found"; you do not know which it was.
+   ```
+
+2. Apply it. The card is a **tender**, so the total does not move:
+
+   ```ts
+   const { tenderId, amountApplied, providerAmountDue } = await client.applyGiftCard(
+     checkoutId,
+     code
+   );
+   // checkout.total is UNCHANGED. providerAmountDue is what the card leaves for the provider.
+   ```
+
+   Every refusal is one HTTP 400 with one message. Show a single "we can't use this code" and let the shopper re-enter it.
+
+3. Re-read the checkout and render from it, never from what you remembered:
+
+   ```ts
+   const checkout = await client.getCheckout(checkoutId);
+   checkout.tenders; // [{ tenderId, amountApplied }] — oldest first, survives a reload
+   checkout.providerAmountDue; // '0.00' means nothing is owed
+   ```
+
+   Summary order: subtotal → discounts → shipping → tax → **total** → one line per gift card → **amount due**.
+
+4. Removing takes the `tenderId`, never the code — a checkout can carry several cards:
+
+   ```ts
+   const { providerAmountDue } = await client.removeGiftCard(checkoutId, tenderId);
+   ```
+
+   Nothing was ever debited, so the held value goes straight back to the card.
+
+5. Then branch on what is still owed:
+   - `providerAmountDue > '0.00'` → the normal payment step. `createPaymentIntent` already nets the cards off; charge the intent's `amount` and never subtract anything yourself.
+   - `providerAmountDue === '0.00'` → there is no charge to make. Skip the provider entirely and call `completeCheckout(checkoutId)`, then `handlePaymentSuccess(checkoutId)` to clear the cart. It returns `{ orderId }` directly, so no `waitForOrder` poll is needed here.
+
+⛔ Do all of this **before** creating the payment intent. Once the checkout is `PAYMENT_PENDING` / `PAYMENT_PROCESSING`, apply and remove both fail with `CHECKOUT_LOCKED`.
+
 ### Registration flow
 
 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.
@@ -306,33 +389,33 @@ the credential, no customer token needed.
 
 The SDK exports these utility functions for common UI tasks:
 
-| Function                                       | Purpose                                                                                        | Example                                                |
-| ---------------------------------------------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
-| `formatPrice(amount, { currency?, locale? })`  | Format prices for display                                                                      | `formatPrice("99.99", { currency: 'USD' })` → `$99.99` |
-| `getPriceDisplay(amount, currency?, locale?)`  | Alias for `formatPrice`                                                                        | Same as above                                          |
-| `getDescriptionContent(product)`               | Get product description (HTML or text)                                                         | `getDescriptionContent(product)`                       |
-| `isHtmlDescription(product)`                   | Check if description is HTML                                                                   | `isHtmlDescription(product)` → `true/false`            |
-| `getStockStatus(inventory)`                    | Get human-readable stock status                                                                | `getStockStatus(inventory)` → `"In Stock"`             |
-| `getProductPrice(product)`                     | Get effective price (handles sales)                                                            | `getProductPrice(product)` → `29.99`                   |
-| `getProductPriceInfo(product)`                 | Get price + sale info + discount % (falls back to `priceMin` when `basePrice=0` on VARIABLE)   | `{ price, isOnSale, discountPercent }`                 |
-| `getVariantPrice(variant, basePrice)`          | Get variant price with fallback                                                                | `getVariantPrice(variant, '29.99')` → `34.99`          |
-| `getCartTotals(cart, shippingPrice?)`          | Calculate cart subtotal/discount/total                                                         | `{ subtotal, discount, shipping, total }`              |
-| `getCartItemName(item)`                        | Get name from nested cart item (product + variant)                                             | `getCartItemName(item)` → `"Blue T-Shirt - Large"`     |
-| `getCartItemImage(item)`                       | Get image URL from cart item                                                                   | `getCartItemImage(item)` → `"https://..."`             |
-| `getVariantOptions(variant)`                   | Get variant attributes as array                                                                | `[{ name: "Color", value: "Red" }]`                    |
-| `isCouponApplicableToProduct(coupon, product)` | Check if coupon applies                                                                        | `isCouponApplicableToProduct(coupon, product)`         |
-| `isAllowedPaymentUrl(url, options?)`           | Validate a payment URL host                                                                    | `isAllowedPaymentUrl(intent.clientSecret)` → `true`    |
-| `safePaymentRedirect(url, options?)`           | Validate then `window.location.href`                                                           | `safePaymentRedirect(intent.clientSecret)`             |
-| `buildProductJsonLd(product, opts)`            | schema.org Product JSON-LD (PDPs only)                                                         | See SEO section                                        |
-| `buildArticleJsonLd(post, opts)`               | schema.org Article JSON-LD for blog posts                                                      | See SEO section                                        |
-| `buildOrganizationJsonLd(store, opts)`         | schema.org Organization for the homepage                                                       | See SEO section                                        |
-| `buildBreadcrumbJsonLd(items)`                 | schema.org BreadcrumbList                                                                      | See SEO section                                        |
-| `buildProductFaqJsonLd(product)`               | schema.org FAQPage from `product.faq` (null when empty); render the same pairs as visible text | `const faq = buildProductFaqJsonLd(product)`           |
-| `jsonLdScriptProps(data)`                      | XSS-safe `<script type="application/ld+json">` props                                           | `<script {...jsonLdScriptProps(data)} />`              |
-| `getBlogSitemapEntries(client, opts)`          | Paginate published posts into sitemap entries                                                  | See SEO section                                        |
-| `getProductSitemapEntries(client, opts)`       | ALL published products into sitemap entries (no 100-item clamp)                                | See SEO section                                        |
-| `getCategorySitemapEntries(client, opts)`      | Category tree into sitemap entries                                                             | See SEO section                                        |
-| `client.resolveSlugRedirect(type, slug)`       | Renamed slug → current slug (301 support in not-found paths)                                   | See SEO section                                        |
+| Function                                       | Purpose                                                                                                                               | Example                                                            |
+| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
+| `formatPrice(amount, { currency?, locale? })`  | Format prices for display                                                                                                             | `formatPrice("99.99", { currency: 'USD' })` → `$99.99`             |
+| `getPriceDisplay(amount, currency?, locale?)`  | Alias for `formatPrice`                                                                                                               | Same as above                                                      |
+| `getDescriptionContent(product)`               | Get product description (HTML or text)                                                                                                | `getDescriptionContent(product)`                                   |
+| `isHtmlDescription(product)`                   | Check if description is HTML                                                                                                          | `isHtmlDescription(product)` → `true/false`                        |
+| `getStockStatus(inventory, opts?)`             | Human-readable stock status. ⛔ `lowStockThreshold` defaults to `0`, so it NEVER says "Low Stock" until you pass the merchant's value | `getStockStatus(inventory, { lowStockThreshold })` → `"Low Stock"` |
+| `getProductPrice(product)`                     | Get effective price (handles sales)                                                                                                   | `getProductPrice(product)` → `29.99`                               |
+| `getProductPriceInfo(product)`                 | Get price + sale info + discount % (falls back to `priceMin` when `basePrice=0` on VARIABLE)                                          | `{ price, isOnSale, discountPercent }`                             |
+| `getVariantPrice(variant, basePrice)`          | Get variant price with fallback                                                                                                       | `getVariantPrice(variant, '29.99')` → `34.99`                      |
+| `getCartTotals(cart, shippingPrice?)`          | Calculate cart subtotal/discount/total                                                                                                | `{ subtotal, discount, shipping, total }`                          |
+| `getCartItemName(item)`                        | Get name from nested cart item (product + variant)                                                                                    | `getCartItemName(item)` → `"Blue T-Shirt - Large"`                 |
+| `getCartItemImage(item)`                       | Get image URL from cart item                                                                                                          | `getCartItemImage(item)` → `"https://..."`                         |
+| `getVariantOptions(variant)`                   | Get variant attributes as array                                                                                                       | `[{ name: "Color", value: "Red" }]`                                |
+| `isCouponApplicableToProduct(coupon, product)` | Check if coupon applies                                                                                                               | `isCouponApplicableToProduct(coupon, product)`                     |
+| `isAllowedPaymentUrl(url, options?)`           | Validate a payment URL host                                                                                                           | `isAllowedPaymentUrl(intent.clientSecret)` → `true`                |
+| `safePaymentRedirect(url, options?)`           | Validate then `window.location.href`                                                                                                  | `safePaymentRedirect(intent.clientSecret)`                         |
+| `buildProductJsonLd(product, opts)`            | schema.org Product JSON-LD (PDPs only)                                                                                                | See SEO section                                                    |
+| `buildArticleJsonLd(post, opts)`               | schema.org Article JSON-LD for blog posts                                                                                             | See SEO section                                                    |
+| `buildOrganizationJsonLd(store, opts)`         | schema.org Organization for the homepage                                                                                              | See SEO section                                                    |
+| `buildBreadcrumbJsonLd(items)`                 | schema.org BreadcrumbList                                                                                                             | See SEO section                                                    |
+| `buildProductFaqJsonLd(product)`               | schema.org FAQPage from `product.faq` (null when empty); render the same pairs as visible text                                        | `const faq = buildProductFaqJsonLd(product)`                       |
+| `jsonLdScriptProps(data)`                      | XSS-safe `<script type="application/ld+json">` props                                                                                  | `<script {...jsonLdScriptProps(data)} />`                          |
+| `getBlogSitemapEntries(client, opts)`          | Paginate published posts into sitemap entries                                                                                         | See SEO section                                                    |
+| `getProductSitemapEntries(client, opts)`       | ALL published products into sitemap entries (no 100-item clamp)                                                                       | See SEO section                                                    |
+| `getCategorySitemapEntries(client, opts)`      | Category tree into sitemap entries                                                                                                    | See SEO section                                                    |
+| `client.resolveSlugRedirect(type, slug)`       | Renamed slug → current slug (301 support in not-found paths)                                                                          | See SEO section                                                    |
 
 ```typescript
 import {
@@ -352,8 +435,11 @@ const priceText = formatPrice(product.basePrice, { currency: 'USD' }); // "$99.9
 // Get product description (handles HTML vs plain text)
 const description = getDescriptionContent(product);
 
-// Get stock status text
-const stockText = getStockStatus(product.inventory); // "In Stock", "Low Stock", "Out of Stock"
+// Get stock status text. Pass the merchant's threshold, or it never says
+// "Low Stock": the option defaults to 0, which disables the low-stock state.
+const caps = await client.getStoreCapabilities();
+const lowStockThreshold = caps.connection.lowStockWarning ? caps.connection.lowStockThreshold : 0; // the merchant switched low-stock messaging off
+const stockText = getStockStatus(product.inventory, { lowStockThreshold }); // "In Stock", "Low Stock", "Out of Stock"
 
 // Get effective price (handles sale prices automatically)
 const price = getProductPrice(product); // Returns number: 29.99
@@ -384,8 +470,9 @@ const itemImage = getCartItemImage(cartItem); // "https://..."
 const { hasPayments, providers } = await client.getPaymentProviders();
 
 if (!hasPayments) {
-  // Show error - payment is not configured
-  return <div>Payment not configured for this store</div>;
+  // NORMAL for a new store, not an error. Build the rest of checkout anyway and
+  // scope this notice to the payment step; never ship a disabled Pay button.
+  return <div>Payment is not set up for this store yet</div>;
 }
 
 // Show payment forms for available providers
@@ -420,7 +507,7 @@ Products can expose `customizationFields`, the merchant-defined inputs the buyer
 ```typescript
 if (product.customizationFields?.length) {
   // Render a form control per field using field.type (TEXT, SELECT,
-  // MULTI_SELECT, IMAGE, GALLERY, DATE, ...) — see INTEGRATION.md §2.8
+  // MULTI_SELECT, IMAGE, GALLERY, DATE, ...) — see the Core Integration guide §2.8
 }
 
 // For IMAGE / GALLERY fields: upload first
@@ -456,7 +543,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'`; 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.
+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 [Rules & Reference "Modifier validation errors"](https://brainerce.com/docs/integration/rules) 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).
 
@@ -1223,26 +1310,25 @@ export function getCartItemCount(): number {
   return client.getSmartCartItemCount();
 }
 
-// ----- Customer Token Helpers -----
+// ----- Customer Session -----
+// The auth token must NEVER live in localStorage: any XSS on the page reads it
+// and the attacker is that customer until it expires. Hand it to your own
+// server, which sets an HttpOnly cookie the browser cannot read back.
 
-export function setCustomerToken(token: string | null): void {
-  if (token) {
-    localStorage.setItem('customerToken', token);
-    client.setCustomerToken(token);
-  } else {
-    localStorage.removeItem('customerToken');
-    client.clearCustomerToken();
-  }
+export async function startSession(token: string): Promise<void> {
+  client.setCustomerToken(token);
+  await fetch('/api/auth/session', { method: 'POST', body: JSON.stringify({ token }) });
 }
 
-export function restoreCustomerToken(): string | null {
-  const token = localStorage.getItem('customerToken');
-  if (token) client.setCustomerToken(token);
-  return token;
+export async function endSession(): Promise<void> {
+  client.clearCustomerToken();
+  await fetch('/api/auth/logout', { method: 'POST' });
 }
 
-export function isLoggedIn(): boolean {
-  return !!localStorage.getItem('customerToken');
+// Session state comes from the server, not from a JS-readable flag.
+export async function getCurrentCustomer() {
+  const res = await fetch('/api/auth/me');
+  return res.ok ? res.json() : null;
 }
 ```
 
@@ -2387,6 +2473,8 @@ await client.removeCheckoutCoupon(checkoutId);
 
 > **Important:** if a checkout session already exists, always use `applyCheckoutCoupon(checkoutId, code)`, not `applyCoupon(cartId, code)`. Applying to the cart after checkout is created does not update the checkout total, so payment will charge the original amount.
 
+> **A gift card is not a coupon.** It has its own pair, `applyGiftCard(checkoutId, code)` / `removeGiftCard(checkoutId, tenderId)`, it never touches `discountAmount`, and it never moves `checkout.total` — a card is a means of payment, so what it reduces is `providerAmountDue`. See [Gift Cards](#gift-cards-a-tender-not-a-discount).
+
 #### Cart Totals
 
 ```typescript
@@ -2977,6 +3065,48 @@ enforcement.
 - `per_option` → each SELECT option has its own price
 - `conditional` → surcharge when NUMBER value meets condition (gt, gte, lt, lte, eq)
 
+#### Gift Cards (a tender, not a discount)
+
+All three modes. **Reading the switch is channel-only**, though: `getStoreCapabilities().features.hasGiftCards` exists on a `salesChannelId` client and that call throws in the other two modes. `getStoreInfo()` carries no gift-card flag, so a `storeId` integration has no capability probe — build the field unconditionally there. An admin (`apiKey`) client can read `getGiftCardLiability().enabled`, but that switch gates **issuing**, not redemption, so it is not a reason to hide the field. Nothing breaks if the store has no cards: an unusable code is simply refused.
+
+Issuing and managing cards is a separate, admin-key surface: [Gift Cards (administration)](#gift-cards-administration).
+
+```typescript
+// Optional pre-check before applying. Rate limited (5/min).
+const { balance, currency, usable } = await client.checkGiftCardBalance(code);
+// usable === false covers unknown, disabled AND expired — you cannot tell which.
+
+// Apply. The order total does NOT change; tax stays on the full value.
+const { tenderId, amountApplied, providerAmountDue } = await client.applyGiftCard(checkoutId, code);
+// amountApplied: '54.50'      — only what the order still owed; the rest stays on the card
+// providerAmountDue: '150.50' — what the provider will be charged
+
+// Render from the checkout, not from the response above — the hold is server-side.
+const checkout = await client.getCheckout(checkoutId);
+checkout.total; // unchanged by the card
+checkout.tenders; // [{ tenderId, amountApplied }], oldest first
+checkout.providerAmountDue; // total − every applied card
+
+// Remove by tenderId, never by code. Held value goes straight back to the card.
+await client.removeGiftCard(checkoutId, tenderId);
+```
+
+Summary layout — the card belongs **below** the total, never in the discount block:
+
+```
+Subtotal      ₪160.00
+Discount      −₪0.00
+Shipping      ₪20.00
+Tax           ₪25.00
+Total         ₪205.00      ← unchanged; this is what tax was calculated on
+Gift card     −₪54.50      ← its own line, below the total
+Amount due    ₪150.50      ← checkout.providerAmountDue, what the provider is charged
+```
+
+**Every refusal is the same 400 with the same message.** Unknown, expired, spent, disabled and wrong-currency are indistinguishable on purpose — a response that told them apart is an oracle for walking the code space. Show one message and let the shopper re-type the code. A card also pays only in its own currency; there is no conversion.
+
+**Apply and remove before `createPaymentIntent`.** Once the checkout is `PAYMENT_PENDING` / `PAYMENT_PROCESSING`, both calls fail with `CHECKOUT_LOCKED`. The intent's `amount` already has live cards netted off server-side, so never subtract anything yourself. If `providerAmountDue` is `'0.00'` the cards cover the order: skip the provider, call `completeCheckout(checkoutId)` (it returns `{ orderId }`), then `handlePaymentSuccess(checkoutId)` to clear the cart.
+
 #### Checkout Type Definition
 
 ```typescript
@@ -2993,14 +3123,39 @@ interface Checkout {
   shippingAmount: string;
   taxAmount: string; // "0" in inclusive (VAT) mode — see taxBreakdown.totalTax
   taxBreakdown?: TaxBreakdown | null; // { totalTax, pricesIncludeTax, breakdown[] }
+  // breakdown[] is ONE ROW PER TAX and is often more than one row (Canada charges
+  // GST + PST/QST). Loop it; never read breakdown[0].
   total: string;
   couponCode?: string | null;
+  // Gift cards held against this checkout, oldest first. Read these to re-render
+  // applied cards after a reload — the hold lives on the server, not in your state.
+  tenders?: Array<{ tenderId: string; amountApplied: string }>;
+  // What the payment provider will be charged: `total` minus every gift card.
+  // `total` above is deliberately NOT reduced — a gift card is a means of payment,
+  // not a discount, and tax stays calculated on the full order value.
+  providerAmountDue?: string;
   notes?: string | null; // Order note from setCheckoutCustomer/setShippingAddress
   items: CheckoutLineItem[];
   itemCount: number;
   availableShippingRates?: ShippingRate[];
 }
 
+// Returned by applyGiftCard. Note what is NOT here: the code, the card id, or
+// anything about who owns it.
+interface CheckoutTender {
+  tenderId: string; // pass to removeGiftCard; a checkout can carry several cards
+  amountApplied: string; // capped at what the order still owes
+  providerAmountDue: string; // what the provider will be charged after this card
+}
+
+// Returned by checkGiftCardBalance. Identical for an unknown code, a disabled
+// card and an expired one — by design.
+interface GiftCardBalance {
+  balance: string; // spendable balance, or '0.00' when the card cannot be used
+  currency: string;
+  usable: boolean;
+}
+
 type CheckoutStatus = 'PENDING' | 'SHIPPING_SET' | 'PAYMENT_PENDING' | 'COMPLETED' | 'FAILED';
 
 interface ShippingRate {
@@ -3217,9 +3372,11 @@ const { hasPayments, providers, defaultProvider } = await client.getPaymentProvi
 const expressMethods = providers.filter(p => p.isAdditive);   // e.g. PayPal
 const primary = defaultProvider && !defaultProvider.isAdditive ? defaultProvider : undefined;
 
-// Build dynamic UI based on available providers
+// Build dynamic UI based on available providers.
+// hasPayments:false is NORMAL for a new store, not an error: build the whole checkout
+// anyway and scope this notice to the payment step. Never ship a disabled Pay button.
 if (!hasPayments) {
-  return <div>Payment not configured for this store</div>;
+  return <div>Payment is not set up for this store yet</div>;
 }
 
 const stripeProvider = providers.find(p => p.provider === 'stripe');
@@ -4511,6 +4668,126 @@ console.log(store.language); // 'en', 'he', etc.
 
 ---
 
+### Store Capabilities
+
+What the merchant actually configured on this sales channel. **Build against this instead of hardcoding.** Vibe-coded (`salesChannelId`) mode only: the payload belongs to one sales channel, so `storeId` mode has no channel to read it from and an admin `apiKey` addresses the store rather than any single channel. Calling it in another mode throws a `BrainerceError` with status 400.
+
+Fetch it **once** at app start and share it (React context, a store, a module-level cache). It is per channel, not per product, so a fetch per page is repeated work.
+
+```typescript
+const caps = await client.getStoreCapabilities();
+
+// --- store: identity + language ---
+caps.store.name; // Parent store name
+caps.store.channelName; // This channel's display name
+caps.store.currency; // 'USD', 'ILS', ...
+caps.store.language; // 'en', 'he', ...
+caps.store.i18n; // present ONLY when multi-language is enabled
+
+// --- connection: this channel's settings ---
+caps.connection.lowStockWarning; // false = show no low-stock treatment at all
+caps.connection.lowStockThreshold; // units at or below which stock is "low"
+caps.connection.stockAlertsEnabled; // false = do not render "email me when back"
+caps.connection.requireBirthday; // true = birthday required on the signup form
+caps.connection.requireEmailVerification;
+caps.connection.reservationStrategy; // 'ON_CART' | 'ON_CHECKOUT' | 'ON_PAYMENT'
+caps.connection.reservationTimeout; // minutes before a reservation expires
+caps.connection.ordersWriteEnabled;
+caps.connection.guestCheckoutTracking;
+caps.connection.sandboxPaymentsEnabled;
+caps.connection.allowedScopes;
+
+// --- features: which optional features exist ---
+caps.features.paymentProviders; // [{ name, provider }] — empty means checkout cannot take money yet
+caps.features.oauthProviders; // [{ provider, isEnabled }]
+caps.features.hasShippingZones;
+caps.features.hasDiscountRules;
+caps.features.hasCoupons;
+caps.features.hasDownloadableProducts;
+caps.features.hasCheckoutCustomFields;
+caps.features.hasGiftCards; // a per-store switch, not a count — see below
+caps.features.hasContent;
+caps.features.hasLoyaltyProgram;
+caps.features.hasReferralProgram;
+caps.features.hasBirthdayRewards;
+caps.features.hasBadges;
+caps.features.hasPaidMembership;
+caps.features.hasAiRewardRecommendation;
+```
+
+**`hasGiftCards` is a switch, not a count.** A store that has issued no cards yet still reports `true` the moment the merchant enables the feature, so build the redemption field on `true` and do not wait for a card to exist. Like every other conditional feature here it auto-hides, and the day a card is issued the storefront already honours it.
+
+**Honour the switch before the number.** `lowStockWarning` is a separate flag from `lowStockThreshold`. When it is off the merchant deliberately turned the urgency messaging off, and a storefront that reads only the threshold keeps showing "Only 3 left" anyway:
+
+```typescript
+const lowStockThreshold = caps.connection.lowStockWarning ? caps.connection.lowStockThreshold : 0; // 0 disables the low-stock state in getStockStatus()
+
+const stockText = getStockStatus(product.inventory, { lowStockThreshold });
+```
+
+**Never let this call break the page.** A brand-new store is empty and the fetch can fail. Catch it and fall back to your own defaults rather than blocking the render:
+
+```typescript
+const caps = await client.getStoreCapabilities().catch(() => null);
+const lowStockThreshold = caps
+  ? caps.connection.lowStockWarning
+    ? caps.connection.lowStockThreshold
+    : 0
+  : 5; // platform default
+```
+
+The full response type is exported as `StoreCapabilities`:
+
+```typescript
+import type { StoreCapabilities } from 'brainerce';
+```
+
+---
+
+### Donations (start & read back)
+
+Vibe-coded (`salesChannelId`) or storefront (`storeId`) mode. An admin `apiKey` client throws: a donation is a donor-facing act, and the key is for managing gifts after the fact.
+
+```typescript
+// Gate first — this page does NOT auto-hide.
+const store = await brainerce.getStoreInfo();
+if (!store.donationsEnabled) return null;
+
+const donation = await brainerce.createDonation({
+  amount: 180, // number, the gift itself — EXCLUDES feeCoverAmount
+  feeCoverAmount: 6.3, // optional, charged ON TOP of the gift
+  donorEmail: 'sarah@example.com', // required
+  donorName: 'Sarah Cohen', // optional
+  isAnonymous: false, // optional — hides the name on PUBLIC surfaces only
+  tributeType: 'IN_MEMORY', // optional: 'IN_HONOR' | 'IN_MEMORY'; needs tributeName
+  tributeName: 'Avraham Cohen',
+  message: 'From the whole family.', // optional, plain text — never render as HTML
+  returnPath: '/thank-you', // optional PATH on your storefront. A full URL is rejected.
+});
+// → {
+//     donationId: 'don_…',
+//     status: 'PENDING',        // ⛔ NOT a paid gift
+//     amount: '180.00',         // the gift
+//     feeCoverAmount: '6.30',
+//     chargeAmount: '186.30',   // what the card is actually charged
+//     currency: 'ILS',
+//     payment: { intentId, clientSecret?, clientSdk?, redirectUrl?, providerType }
+//   }
+
+const settled = await brainerce.getDonation(donation.donationId);
+// → {
+//     id, status: 'PENDING' | 'PAID' | 'FAILED' | 'CANCELLED',
+//     amount, feeCoverAmount, currency,
+//     donorName,   // null when the gift was marked anonymous
+//     tributeType, tributeName,
+//     paidAt       // null until PAID
+//   }
+```
+
+Complete `donation.payment` with the provider exactly as you would a checkout intent — `clientSecret` for an embedded SDK, `redirectUrl` for a hosted page — then poll `getDonation()` until `status === 'PAID'`. Both calls are rate limited to 5 requests per minute. The read-back payload carries no failure reason and withholds the donor name on an anonymous gift, so it is safe to render straight onto a public page.
+
+See [Donation Page](#donation-page) for the full walkthrough and the things it deliberately does not do.
+
 ### Traffic Analytics (built-in, no GA4 needed)
 
 Brainerce has a **native cookieless analytics pipeline** covering visits, visitors, countries, sources, devices and the conversion funnel, visible in the merchant dashboard under **Dashboard → Traffic**. You don't need GA4, Meta Pixel, or any third-party script.
@@ -5033,12 +5310,21 @@ const mobileOnlyZone = await client.createShippingZone({
 const rates = await client.getZoneShippingRates('zone_id');
 await client.createZoneShippingRate('zone_id', {
   name: 'Standard Shipping',
-  type: 'flat',
-  price: 5.99,
-  estimatedDays: '3-5',
+  type: 'FLAT_RATE',
+  rateConfig: { amount: 5.99 },
+  minDeliveryDays: 3,
+  maxDeliveryDays: 5,
 });
 ```
 
+**`type` is one of `FLAT_RATE`, `FREE`, `WEIGHT_BASED`, `PRICE_BASED`,
+`LOCAL_PICKUP`** — uppercase, and `FLAT_RATE` rather than `FLAT`. The price
+goes inside `rateConfig`, whose shape follows `type`: `FLAT_RATE` takes
+`{ amount }`, the two tiered types take tier arrays, and `FREE` and
+`LOCAL_PICKUP` take none. Unknown top-level properties are rejected rather
+than ignored, so a leftover `price` or `estimatedDays` fails the call with 400
+even though everything else is correct.
+
 ### App Store Shipping (live carrier rates)
 
 Once a merchant installs a shipping app from the Brainerce App Store (EasyPost, Shippo, or any
@@ -5179,6 +5465,58 @@ await client.createTaxRate({
 });
 ```
 
+#### Two taxes on the same sale (`stackable`)
+
+By default exactly **one** rate applies to a line: the most specific match wins
+(postal code beats region beats country) and every other match is discarded.
+`stackable: true` opts a rate into being **summed** with the other stackable
+rates that match the same address, all charged on the same pre-tax base. Never
+tax-on-tax — Quebec stopped compounding QST on GST in 2013.
+
+Canada is the case you will hit. A country-level GST row plus a province row:
+
+```typescript
+await client.createTaxRate({ name: 'GST', rate: 5, country: 'CA', stackable: true });
+await client.createTaxRate({
+  name: 'QST',
+  rate: 9.975,
+  country: 'CA',
+  region: 'QC',
+  stackable: true,
+});
+// A Quebec checkout is taxed 14.975% and taxBreakdown.breakdown has TWO rows.
+
+// HST already contains the federal 5%, so it is ONE rate left non-stackable —
+// it wins alone at 13% and never adds the GST row underneath it.
+await client.createTaxRate({ name: 'HST', rate: 13, country: 'CA', region: 'ON' });
+```
+
+`stackable` defaults to `false`, so every rate that existed before this field
+keeps the most-specific-wins behaviour unchanged. Stacking never crosses a tax
+class either: a class-specific rate **replaces** the Standard rates rather than
+adding to them, so a class that needs GST plus a reduced QST needs both rows
+created in that class.
+
+#### Country presets
+
+`applyTaxPreset` writes a country's whole rate table in one call, already
+flagged, instead of thirteen provinces entered by hand:
+
+```typescript
+const presets = await client.getTaxPresets();
+// [{ key: 'CA', country: 'CA', label: 'Canada — GST, HST, PST, QST', rateCount: 11, … }]
+
+const { created } = await client.applyTaxPreset('CA'); // created === 11
+```
+
+It writes federal GST 5% country-wide, one combined HST row for ON/NB/NL/NS/PE,
+and PST/RST/QST for BC/SK/MB/QC on top of the GST. Alberta and the territories
+need no row. It throws **409** when the store already has rates for that
+country — delete those first if you meant to replace them — so a double call
+cannot double every province. Rates land in the Standard tax class.
+
+Brainerce does not register the store for GST/HST and does not file returns.
+
 ### Tax Classes
 
 Tax classes let you charge different rates for different product types (e.g.
@@ -5439,20 +5777,27 @@ Each store has its own team with roles (`OWNER`, `MANAGER`, `STAFF`, `VIEWER`) a
 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 section previously showed store-level team calls. **Since SDK 2.1.1 they throw a
+`BrainerceError` that says so, instead of returning a bare 404.** Ten methods are
+affected: `getStoreTeam`, `inviteStoreMember`, `updateStoreMember`,
+`updateStoreMemberSalesChannels`, `removeStoreMember`, `resendStoreInvitation`,
+`revokeStoreInvitation`, `acceptStoreInvitation`, `getMyStores` and
+`getMyStorePermissions`.
 
 **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 correct path would earn a `403` instead of a `404` — which is why the SDK now raises
+that `403` locally rather than sending a request that cannot succeed. Invite, re-scope
+and remove members in the dashboard.
+
+`getStoreInvitationByToken(token)` is the **one exception and it works**: the lookup
+route is `@Public()`, and it was only ever failing because the SDK asked for
+`/api/v1/store-invitations/…` instead of `/api/store-invitations/…`. That path is fixed.
+Use it to render an invitation-acceptance page; the acceptance itself must happen in the
+dashboard, because it is matched against the invited user's own email address.
 
 > **The older account-level methods are not a substitute for this.** `getTeamMembers`,
 > `getTeamInvitations`, `inviteTeamMember`, `resendTeamInvitation`, `revokeTeamInvitation`,
@@ -5739,6 +6084,288 @@ const { queued } = await client.aiTranslateBulk(storeId, {
 
 ---
 
+### Gift Cards (administration)
+
+Eight admin-key methods that issue, read, re-issue, adjust and disable stored
+value. This is the merchant half of the feature; the storefront half — apply,
+remove, check a balance — is [Gift Cards (a tender, not a discount)](#gift-cards-a-tender-not-a-discount)
+and needs no API key.
+
+Every call reaches the same service the dashboard runs, so the rules below hold
+whether a person or a key is acting.
+
+| Method                                              | Route                             | Scope              |
+| --------------------------------------------------- | --------------------------------- | ------------------ |
+| `listGiftCards(params?)`                            | `GET /v1/gift-cards`              | `gift_cards:read`  |
+| `getGiftCardLiability()`                            | `GET /v1/gift-cards/liability`    | `gift_cards:read`  |
+| `getGiftCard(giftCardId)`                           | `GET /v1/gift-cards/{id}`         | `gift_cards:read`  |
+| `issueGiftCard(data)`                               | `POST /v1/gift-cards`             | `gift_cards:issue` |
+| `reissueGiftCard(giftCardId, note)`                 | `POST /v1/gift-cards/{id}/reissue` | `gift_cards:issue` |
+| `adjustGiftCardBalance(giftCardId, delta, note)`    | `PATCH /v1/gift-cards/{id}/adjust` | `gift_cards:adjust` |
+| `setGiftCardStatus(giftCardId, status)`             | `PATCH /v1/gift-cards/{id}/status` | `gift_cards:write` |
+| `bulkSetGiftCardStatus(giftCardIds, status)`        | `PATCH /v1/gift-cards/bulk/status` | `gift_cards:write` |
+
+#### ⛔ The code is returned exactly once
+
+`issueGiftCard` and `reissueGiftCard` are the only two moments `plaintextCode`
+exists in readable form anywhere. The platform keeps an HMAC of it and nothing
+else, so **no API call, no dashboard screen and no database query can produce it
+again**. An integration that discards the response has destroyed a card that is
+still on the books as a liability.
+
+```typescript
+import type { IssuedGiftCardAdmin } from 'brainerce';
+
+const card: IssuedGiftCardAdmin = await admin.issueGiftCard({
+  amount: '200.00', // decimal STRING, greater than zero
+  note: 'Goodwill for order ORD-20260902-0041, damaged in transit',
+  recipientEmail: 'dana@example.com',
+});
+
+await deliverToCustomer(card.plaintextCode); // ← your only chance
+// card.giftCardId, card.last4 are safe to store. card.plaintextCode is not:
+// never log it, never persist it in plaintext, never put it in an error message.
+```
+
+The **one** recovery that exists is an idempotent retry. Send an
+`Idempotency-Key` header on the issue call and re-sending the identical request
+with the same key inside 24 hours replays the whole cached response — code
+included — with `X-Idempotent-Replayed: true` on it. Outside that window there is
+nothing to replay, and the value sits on a card nobody can spend. Send the key.
+
+#### Reading cards
+
+```typescript
+import type { GiftCardAdmin, GiftCardAdminDetail, GiftCardLiability } from 'brainerce';
+
+const { data, meta } = await admin.listGiftCards({
+  page: 1,
+  limit: 50, // hard cap 100
+  filter: 'withBalance', // 'all' | 'active' | 'withBalance' | 'expired' | 'disabled'
+  search: 'V2D3', // last FOUR of a code, or part of a recipient email
+});
+
+const card: GiftCardAdminDetail = await admin.getGiftCard(data[0].id);
+card.transactions; // the full append-only ledger, newest first
+```
+
+**`search` cannot match a full code.** Only an HMAC is stored, so there is
+nothing to search against; the last four characters and the recipient email are
+the whole of it. That is also what a merchant reads off a support email.
+
+Two filters behave in ways worth knowing before you build a UI on them:
+
+- `disabled` returns `DISABLED` **and** `REVOKED` cards, not just disabled ones.
+- `expired` matches on `expiresAt` being in the past regardless of status, and
+  expiry is derived at read time rather than stamped by a job — so a card that
+  lapsed a second ago is already in this filter, and `expired: true` on the row
+  is true the moment validity ends.
+
+An expired card's balance is deliberately **not** zeroed, and `expiredAt` is
+stamped only if an expiry was ever processed.
+
+```typescript
+const liability: GiftCardLiability = await admin.getGiftCardLiability();
+liability.byCurrency; // [{ currency: 'ILS', active, held, expiredNotWrittenOff }, ...]
+```
+
+This is the month-end close figure. **Read `byCurrency`** if the store sells in
+more than one: balances in different currencies do not add up, so the top-level
+`active` / `held` / `expiredNotWrittenOff` cover one currency only and are not a
+total. `expiredNotWrittenOff` is reported apart from both sides on purpose —
+whether expiry extinguishes the obligation is an open legal question, so the
+platform never folds it into either.
+
+`liability.enabled` is the one admin-mode capability probe for this feature. It
+says whether the store may **issue**; redemption is not gated on it.
+
+#### ⛔ Re-issue is not a resend
+
+`reissueGiftCard` is the answer to a customer who lost their code. It mints a new
+code, moves the **whole** balance onto it, and **revokes the old card**:
+
+```typescript
+import type { ReissuedGiftCardAdmin } from 'brainerce';
+
+const replacement: ReissuedGiftCardAdmin = await admin.reissueGiftCard(
+  giftCardId,
+  'Customer lost the original code — support ticket 8812'
+);
+replacement.plaintextCode; // once, same rules as issuance
+replacement.movedAmount; // what came across from the revoked card
+replacement.deliveredTo; // email it was sent to, or null → you must hand it over
+```
+
+The old code stops working the moment this returns. If the customer is still
+holding a printed card, it is now worthless — so do not reach for this when
+someone simply wants the email again.
+
+Three things it deliberately does:
+
+- **Refuses while a checkout holds value on the card.** A live hold means a
+  shopper is mid-payment against it; moving the balance out from under them would
+  strand a provider charge already in flight. Holds are short, so waiting is the
+  correct advice rather than a workaround.
+- **Carries the ORIGINAL expiry forward.** Re-issue cannot be used to restart an
+  expiry clock, because the clock carries statutory notice duties.
+- **Works even when the store has gift cards switched off.** Unlike issuance it
+  is not gated on that switch: it moves value that already exists, total
+  liability is identical before and after, and a store that turned the feature
+  off still owes every card already in a customer's hand.
+
+It also refuses a card that is already `REVOKED` ("re-issue the replacement
+instead"), one with no balance left to move, and one that changed underneath the
+call. Those messages are explanatory, unlike the storefront's deliberately
+uniform refusals — surface them to the merchant.
+
+#### Adjusting a balance
+
+```typescript
+const { balanceAfter } = await admin.adjustGiftCardBalance(
+  giftCardId,
+  '-25.00', // SIGNED decimal string: '25.00' credits, '-25.00' debits. Never zero
+  'Chargeback on the original order'
+);
+```
+
+A debit cannot take the balance below what live checkout holds have already
+reserved. That refusal names the held amount, so it is actionable: wait for the
+checkout to complete or be released, then retry.
+
+#### Status, and the absence of delete
+
+```typescript
+await admin.setGiftCardStatus(giftCardId, 'DISABLED'); // 'ACTIVE' | 'DISABLED' | 'REVOKED'
+const { updated } = await admin.bulkSetGiftCardStatus(ids, 'DISABLED'); // ACTIVE | DISABLED only
+```
+
+⛔ **There is no delete — not one route, not in bulk, not ever.** The ledger is
+append-only and a card may carry a statutory retention life. Disabling is the
+reversible substitute, and it is what "off" actually means here: it stops **new**
+holds. It deliberately does not touch a hold a checkout is already carrying,
+because pulling value out from under a shopper mid-payment would strand a
+provider charge that has already left.
+
+`bulkSetGiftCardStatus` takes `ACTIVE` and `DISABLED` only. **`REVOKED` is
+refused in bulk**: revoking belongs to re-issue, which moves the balance to a
+replacement first, and revoking a page of cards would strand every balance on
+them with nowhere to go. Cards already revoked are skipped rather than
+reactivated — a revoked code put back into circulation beside its replacement
+would make the same value spendable twice — so `updated` is the honest count and
+can be lower than the number of ids you sent. Maximum **200 ids** per call.
+
+#### Scopes are separable on purpose
+
+`gift_cards:issue` mints stored value. `gift_cards:adjust` rewrites a balance.
+Neither is implied by `gift_cards:read`, and that separation is the whole control
+surface here: Shopify makes a merchant contact their support for the equivalent
+permission, while this platform grants it self-serve. Ask for the least your
+integration needs.
+
+⛔ **`gift_cards:*` is not "gift cards, read-only".** The wildcard matches the
+**resource**, so one string grants `read`, `write`, `issue` **and** `adjust`
+together. A reporting or BI integration that asks for it has been handed the
+power to mint money and to rewrite balances. Enumerate the scopes instead.
+
+Note the underscore: the scope is `gift_cards:read`, not `gift-cards:read`. A key
+minted with the hyphen matches nothing and every call 403s with
+`INSUFFICIENT_SCOPE`, which reads like a permissions bug rather than a typo.
+
+#### Rules that hold on every call
+
+- **A `note` is mandatory** on issue, re-issue and adjust — 3 to 500 characters —
+  and is written to the append-only ledger permanently. It is the row a finance
+  review reads a year from now, so write the reason, not `"api"`.
+- **Money is decimal strings, never numbers.** `amount`, `delta`, every balance.
+  A JSON number is a float, and the one thing that must not happen to stored
+  value is arriving a cent short because it went through a double on the way in.
+- **There is no `currency` parameter on issue.** A card is always minted in the
+  store's own currency, and a card pays only in its own currency with no
+  conversion — so this API cannot issue a EUR card on an ILS store to compensate
+  a foreign-currency customer. Neither half of that is configurable.
+- **Issuing is refused while gift cards are switched off for the store**, with a
+  400 that says so. The feature is off by default. Re-issue, adjust and status
+  are not gated on it.
+- **All five write routes accept `Idempotency-Key`.** Send it on issue and
+  re-issue especially: without one, a retried timeout mints a *second* card and a
+  real liability nobody asked for.
+
+#### Type definitions
+
+```typescript
+interface GiftCardAdmin {
+  id: string;
+  maskedCode: string; // '••••-••••-••••-••••-V2D3'
+  codeLast4: string;
+  initialAmount: string; // decimal strings, all of them
+  balance: string; // settled value on the card
+  heldAmount: string; // reserved by a checkout in progress, not available to spend
+  spendable: string; // balance - heldAmount
+  currency: string;
+  status: 'ACTIVE' | 'DISABLED' | 'REVOKED';
+  customerId: string | null;
+  recipientEmail: string | null;
+  expiresAt: string | null;
+  expiredAt: string | null; // stamped if an expiry was processed; balance is NOT zeroed
+  expired: boolean; // derived at read time
+  createdAt: string;
+}
+
+interface GiftCardTransaction {
+  id: string;
+  type: 'ISSUE' | 'REDEEM' | 'REFUND' | 'ADJUST' | 'EXPIRE';
+  amount: string; // signed; negative debits the card
+  balanceAfter: string;
+  orderId: string | null;
+  actorUserId: string | null;
+  note: string | null;
+  createdAt: string;
+}
+
+interface GiftCardAdminDetail extends GiftCardAdmin {
+  recipientName: string | null;
+  orderId: string | null;
+  transactions: GiftCardTransaction[]; // append-only; nothing here is ever rewritten
+}
+
+interface GiftCardLiability {
+  active: string;
+  held: string;
+  expiredNotWrittenOff: string;
+  currency: string | null;
+  byCurrency: Array<{
+    currency: string;
+    active: string;
+    held: string;
+    expiredNotWrittenOff: string;
+  }>;
+  enabled: boolean; // may the store ISSUE? Redemption is not gated on this
+}
+
+interface IssuedGiftCardAdmin {
+  giftCardId: string;
+  plaintextCode: string; // ⚠️ returned EXACTLY ONCE
+  last4: string;
+}
+
+interface ReissuedGiftCardAdmin extends IssuedGiftCardAdmin {
+  movedAmount: string;
+  deliveredTo: string | null; // null → the merchant must hand the code over
+}
+
+interface IssueGiftCardAdminDto {
+  amount: string; // decimal string, greater than zero
+  note: string; // REQUIRED, 3-500 chars, permanent on the ledger
+  customerId?: string;
+  expiresAt?: string; // ISO 8601, must be in the future. Omit for no expiry
+  recipientEmail?: string;
+  recipientName?: string;
+  personalMessage?: string;
+}
+```
+
+---
+
 ## Complete Page Examples
 
 ### Home Page
@@ -6289,6 +6916,7 @@ export default function CheckoutPage() {
 > - Split the page into two phases. Fetching rates and completing the order in one submit means the shopper never gets to choose, and you silently charge whichever rate came back first.
 > - `email` is required on `setShippingAddress`, for logged-in shoppers too. It is validated before any service code runs, so the server cannot fill it in from the customer record.
 > - Guest session cart is created automatically by `smart*` methods
+> - A gift-card field belongs on the shipping phase, before the order is placed. It does not change the total shown here — it reduces `checkout.providerAmountDue`, which you render as a separate "Amount due" line below the total. See [Gift card redemption flow](#gift-card-redemption-flow)
 > - Call `client.onCheckoutComplete()` after successful payment to clear the session cart
 > - Call `client.syncCartOnLogin()` when a user logs in to merge their guest cart
 
@@ -6852,6 +7480,61 @@ The merchant reads the demand at `Products → Back-in-Stock Waitlist`: products
 
 ---
 
+## Donation Page
+
+**SDK >= 2.1.** A donation page, for a store that takes gifts as well as — or instead of — selling things.
+
+```typescript
+// 1. Gate the page. This one does not auto-hide.
+const store = await brainerce.getStoreInfo();
+if (!store.donationsEnabled) return null;
+
+// 2. Start the donation.
+const donation = await brainerce.createDonation({
+  amount: 180, // the gift
+  feeCoverAmount: 6.3, // only when the donor ticked "cover the fee"
+  donorEmail: 'sarah@example.com',
+  donorName: 'Sarah Cohen',
+  isAnonymous: false,
+  tributeType: 'IN_MEMORY', // or 'IN_HONOR'
+  tributeName: 'Avraham Cohen',
+  message: 'From the whole family.',
+  returnPath: '/thank-you',
+});
+// → { donationId, status: 'PENDING', amount, feeCoverAmount, chargeAmount, currency, payment }
+
+// 3. Complete donation.payment with the provider — same shape as a checkout intent.
+
+// 4. ONLY NOW may you thank anyone.
+const settled = await brainerce.getDonation(donation.donationId);
+if (settled.status === 'PAID') {
+  show(`Thank you, ${settled.donorName ?? 'friend'}`); // null when anonymous
+}
+```
+
+**⛔ A donation is not a checkout.** No line item, no quantity, no shipping, no order, and it is reported separately from sales. Do not route it through the cart and do not model it as a product — the amount is the tell, because a cart cannot let a donor type one. A "Donation $18" product also files every gift into the merchant's sales figures.
+
+**⛔ `createDonation` resolving is not a completed gift.** It returns `status: 'PENDING'` and a provider intent; the money has not moved. The gift becomes `PAID` only when the provider's webhook confirms it — the same reason you call `waitForOrder()` after a checkout instead of trusting the payment callback. Do not thank the donor, show the amount as given, or send anything receipt-shaped before `getDonation()` reads `PAID`.
+
+**The fee cover is charged on top, never taken out.** `amount` is the gift and stays the gift; `feeCoverAmount` is extra; `chargeAmount` is what the card is charged. Between 55% and 60% of donors accept the fee when a form offers it, which makes it the highest-value checkbox on the page.
+
+**`returnPath` is a path, not a URL.** `/thank-you`, on your own storefront. A full URL is rejected: the payment provider redirects a real browser to this value, so accepting one from the page would be an open redirect.
+
+**A tribute needs a name.** Setting `tributeType` without `tributeName` is rejected, so make the name required the moment a tribute type is chosen.
+
+**"Anonymous" is a public-surface flag, not privacy.** It withholds `donorName` from `getDonation()` so the payload is safe to render on a public page. The organisation still sees who gave. Say that on the form — donors read "anonymous" as "untraceable", and it is not.
+
+**Rate limit:** 5 requests per minute on both calls. Create is capped because an unauthenticated endpoint that mints payment intents is a card-testing instrument; read-back is capped because an id that either resolves or 404s can be enumerated. Poll a handful of times after the donor returns, never on a one-second interval.
+
+**What it does not do:**
+
+- **No receipts.** Brainerce records the donation. It does not issue a tax receipt and does not file anything with any tax authority.
+- **No recurring donations from the storefront.** Standing orders exist, but a donor cannot start one themselves — the merchant arms it from the dashboard for a customer who already saved a card. Do not build a "monthly" toggle that calls `createDonation`: it would quietly produce a one-off gift.
+- **No funds, campaigns or goal meters.**
+- **No admin mode.** Both methods throw with an `apiKey` client. A donation is a donor-facing act; use `salesChannelId` or `storeId`.
+
+---
+
 ## Storefront Bot (AI chat widget)
 
 Add the store's AI shopping assistant with one line. Configuration (name, avatar, colors, greeting, starter questions, guardrails) is normally set in the merchant dashboard, and the widget renders nothing until the bot is switched Live there. Those same settings are also readable/writable via `client.getBotSettings()` / `client.updateBotSettings()`, and conversation transcripts + summarization via `client.listBotConversations()` / `client.summarizeBotConversation()`. See [Storefront Bot Settings](#storefront-bot-settings) and [Storefront Bot Conversations](#storefront-bot-conversations) in the Admin API Reference.
@@ -6929,33 +7612,35 @@ export async function POST(req: Request) {
 
 ### Webhook Events
 
-**These 21 event types are what a subscription can actually register.** The
+**These 23 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, by 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                                                                                                                                                                             |
+| Event                 | Description                                                                                                                                                                                                                                         |
+| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `order.created`       | New order placed (any payment status)                                                                                                                                                                                                               |
+| `order.updated`       | Order metadata changed (status, address, items)                                                                                                                                                                                                     |
+| `order.paid`          | Order is paid, by 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                                                                                                                                                                                                                      |
+| `donation.paid`       | A donation settled. `createDonation` returns `PENDING` and this is the only signal money actually moved, so a receipting integration waits for it. The payload carries both the donor's intended `amount` and the `chargedAmount` the provider took |
+| `donation.refunded`   | A settled donation was refunded. There is no `REFUNDED` donation status — this event is how you learn                                                                                                                                               |
 
 Payload shapes for each are in the
 [Event Catalogue](https://brainerce.com/docs/webhooks/events).
@@ -6964,7 +7649,7 @@ Payload shapes for each are in the
 just merchant-created customers, so a storefront that registers customers will
 start seeing it.
 
-The `WebhookEventType` type matches this table exactly as of SDK 2.0.2 —
+The `WebhookEventType` type matches this table exactly as of SDK 2.1.0 —
 `isWebhookEventType(event, 'customer.created')` and
 `createWebhookHandler({ 'order.paid': … })` both compile and match the
 subscribable set. (Previous SDK versions shipped a stale 15-entry type that
@@ -7054,6 +7739,7 @@ When building a store, implement these pages:
 - [ ] **Auth Callback** (`/auth/callback`) - Handle OAuth redirects from Google/Facebook/GitHub
 - [ ] **Verify Email** (`/verify-email`) - Email verification with 6-digit code (if store requires it)
 - [ ] **Account** (`/account`) - Profile, addresses, and full order history (per-item customizations, shipping & tracking, payment status, status timeline)
+- [ ] **Donate** (`/donate`) - ONLY when `getStoreInfo().donationsEnabled` is true. One form, outside the cart: preset amounts + a free "other amount", email, optional tribute, anonymous checkbox, "cover the fee" checkbox. Do not build it for a store that has not opened donations — the endpoint rejects every submission
 
 ### ⚠️ Payment Page is REQUIRED
 
@@ -7213,8 +7899,8 @@ const handlePlaceOrder = () => {
 - Import types from the SDK
 - Handle loading states and errors
 - **Use toast notifications (Sonner) for user feedback on actions**
-- Persist cart ID in localStorage
-- Persist customer token after login
+- **Let the SDK persist the cart** — it keeps the cart reference in `brainerce_session` itself. Do not write your own cart-to-localStorage code; a second copy drifts out of sync with the server
+- **NEVER put the customer token in `localStorage`** — any XSS reads it and the attacker is that customer until it expires. Hold it in memory with `setCustomerToken()`, or front the SDK with a BFF proxy (`proxyMode: true`) that keeps it in an HttpOnly cookie
 - **Use `isHtmlDescription(product)` helper and render HTML with `dangerouslySetInnerHTML` when it returns true**
 - **Wrap SDK calls in try/catch and show error toasts**