brainerce 2.0.2 → 2.1.0

package/README.md

@@ -57,6 +57,7 @@ Every Brainerce storefront must include **all mandatory features** below. Featur
 | 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()`                                                                                                                                     | ✅          |
@@ -74,6 +75,9 @@ Every Brainerce storefront must include **all mandatory features** below. Featur
 | 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,23 @@ 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.
+
+### 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 +199,56 @@ 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` and admin mode there is no switch to read — build the field anyway; a code on a store without cards is just refused. 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.
+
+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 +378,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 +424,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 +459,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 +496,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 +532,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 +1299,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 +2462,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 +3054,46 @@ 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` or admin integration has no capability probe — build the field unconditionally there. Nothing breaks if the store has no cards: an unusable code is simply refused.
+
+```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 +3110,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 +3359,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 +4655,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 +5297,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 +5452,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.
@@ -6289,6 +6614,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 +7178,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,7 +7310,7 @@ 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.
 
@@ -6956,6 +7337,8 @@ anything outside it is rejected rather than silently accepted.
 | `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 +7347,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 +7437,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