brainerce 1.23.13 → 1.23.14

package/README.md

@@ -4,7 +4,17 @@ Official SDK for building e-commerce storefronts with **Brainerce Platform**.
 
 This SDK provides a complete solution for vibe-coded sites, AI-built stores (Cursor, Lovable, v0), and custom storefronts to connect to Brainerce's unified commerce API.
 
-> **AI Agents / Vibe Coders:** Use the MCP server for AI-powered store building: `npx @brainerce/mcp-server`. It provides docs, code templates, and live store capabilities to any AI tool (Cursor, Lovable, Claude Code).
+> **AI Agents / Vibe Coders (Cursor, Lovable, Claude Code, VS Code):** Use the MCP server for AI-powered store building: `npx @brainerce/mcp-server`. It provides docs, code templates, and live store capabilities directly inside your IDE.
+> Note: the MCP server runs inside your IDE — it is not available in chat-only tools like Google AI Studio or ChatGPT.
+
+## Two SDK modes — choose the right one
+
+| Mode           | Config key               | Use for                            | Where to run                        |
+| -------------- | ------------------------ | ---------------------------------- | ----------------------------------- |
+| **Storefront** | `salesChannelId: 'vc_*'` | Building the customer-facing store | Browser / client-side               |
+| **Admin**      | `apiKey: 'brainerce_*'`  | Managing products, team, settings  | Server only — never in browser code |
+
+> **Building a storefront?** You only need your **Sales Channel ID** (`vc_*`) from the Brainerce dashboard under **Sales Channels**. No API key needed. API keys are a server-side admin secret.
 
 ## Installation
 
@@ -18,27 +28,218 @@ yarn add brainerce
 
 ---
 
+## What You Must Build
+
+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()`                                                                 | ✅          |
+| 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.getMyOrders()`                                                               | ✅          |
+| Global header: cart count + search autocomplete         | `client.getCart()`, `client.getSearchSuggestions(query)`                                                      | ✅          |
+| Discount banners + product badges                       | `client.getDiscountBanners()`, `client.getProductDiscountBadge(productId)`                                    | ✅          |
+| Multi-language + RTL (when i18n enabled)                | `client.setLocale()`                                                                                          | conditional |
+
+---
+
+## Critical Rules
+
+Violating any of these causes production incidents or broken orders. Read them before writing SDK code.
+
+### SDK usage
+
+- ALWAYS call SDK client methods. Never reconstruct REST URLs or call `fetch` directly.
+- NEVER invent SDK method names. If it's not in this README or in `get-sdk-docs`, it doesn't exist.
+- NEVER hardcode product data, categories, or store copy — Brainerce is the database.
+- NEVER use `submitGuestOrder()` or `createOrder()` — they bypass payment and produce unpaid orders.
+- ALWAYS use SDK helpers (`getCartTotals`, `formatPrice`, `getProductPriceInfo`, `getCartItemImage`, `getCartItemName`, `getVariantPrice`, `getStockStatus`, `getDescriptionContent`) instead of reading raw fields.
+
+### State management
+
+- The SDK manages cart, checkout, and session state. Do NOT duplicate it in your own Redux/context.
+- Product lists, categories, and inventory counts are NOT client state — fetch on demand.
+- Discount rules and coupon validity are evaluated server-side. Never re-implement them client-side.
+
+### Authentication
+
+- ALWAYS handle the `requiresVerification` flag in `registerCustomer` and `loginCustomer` responses. If true, route to the verify-email step BEFORE treating the user as logged in.
+- ALWAYS build the verify-email, forgot-password, and reset-password flows even when the store currently has email verification disabled. They auto-hide when unused.
+- ALWAYS build OAuth button placeholders and a callback handler even when no OAuth provider is configured.
+- NEVER silently swallow auth errors. Render the specific error (invalid credentials, expired token, rate limited).
+
+### Checkout & orders
+
+- The checkout sequence is strict: `setShippingAddress` → pick a shipping rate → `getPaymentProviders` → provider payment → `handlePaymentSuccess` → `waitForOrder`. Never skip or reorder.
+- ALWAYS call `handlePaymentSuccess(checkoutId)` on the confirmation page — clears the cart so users don't see stale items.
+- ALWAYS call `waitForOrder(checkoutId)` to poll for the real order before showing an order number. The payment callback may return before the order record exists.
+- 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.
+
+### Token handling
+
+- Customer auth tokens (`result.token` from `loginCustomer`/`registerCustomer`) should be passed to `client.setCustomerToken(token)`. The SDK stores session state internally.
+- NEVER put the admin API key (`brainerce_*`) in client code. It is a server-only secret.
+- OAuth callbacks arrive with the token in URL params. Extract and apply the token before redirecting.
+
+### i18n
+
+- NEVER hardcode currency, locale, or language strings — read them from `getStoreInfo()`.
+- NEVER format prices with `toFixed(2)` — use `formatPrice()` from the SDK.
+- When i18n is enabled, call `client.setLocale(locale)` at app init and include a language switcher. For RTL locales (`he`, `ar`), set `<html dir="rtl">` — do NOT add `flex-row-reverse` on top.
+
+### Type safety
+
+- NEVER use `as any` or `as unknown as`. Fix the type, don't hide it.
+- NEVER write your own copies of SDK types (Cart, Product, Order). Import from `'brainerce'`.
+- All prices are **STRINGS** — always `parseFloat()` before math or comparisons.
+- `CartItem` / `CheckoutLineItem` = **NESTED** (`item.product.name`, `item.unitPrice`). `OrderItem` = **FLAT** (`item.name`, `item.price`). Not interchangeable.
+- `Cart` has no `.total` field — call `getCartTotals(cart)`.
+
+---
+
+## Business Flows
+
+These sequences are non-negotiable. The order of SDK calls matters.
+
+### Checkout flow
+
+1. Collect customer email, billing address, shipping address (`line1`, `line2`, `city`, `region`, `postalCode`, `country`). `email` is required.
+2. Submit address to get shipping rates:
+   ```ts
+   const { checkout, rates } = await client.setShippingAddress(checkoutId, {
+     email,
+     firstName,
+     lastName,
+     line1,
+     city,
+     region,
+     postalCode,
+     country,
+   });
+   // rates = available shipping rates; checkout = updated checkout object
+   ```
+3. Let the customer pick a rate, then persist it:
+   ```ts
+   await client.selectShippingMethod(checkoutId, rateId);
+   ```
+4. Fetch available payment providers:
+   ```ts
+   const providers = await client.getPaymentProviders();
+   ```
+   Each provider has a `renderType` — `'sdk-widget'` (Stripe, PayPal, Grow), `'iframe'` (Cardcom), `'redirect'`, `'sandbox'`. Branch on `renderType`, never on provider name.
+5. Confirm payment using the provider's flow (Stripe Elements `stripe.confirmCardPayment`, PayPal button, redirect, etc.).
+6. On the confirmation page, **always call both**:
+   ```ts
+   await client.handlePaymentSuccess(checkoutId); // clears cart
+   const order = await client.waitForOrder(checkoutId); // polls until order exists
+   ```
+7. Display `checkout.lineItems` (not `cart.items`) on the order summary.
+
+### Registration flow
+
+1. Collect email, password, first name, last name.
+2. Call `registerCustomer`:
+   ```ts
+   const result = await client.registerCustomer({ email, password, firstName, lastName });
+   ```
+3. Branch on `result.requiresVerification`:
+   - `true` → store token temporarily, route to verify-email UI (do NOT set token yet)
+   - `false` → `client.setCustomerToken(result.token)`, route to account
+4. On verify-email: collect 6-digit code → `client.verifyEmail(code)`. Offer resend via `client.resendVerificationEmail()`.
+5. After `verifyEmail` resolves: `client.setCustomerToken(result.token)`, route to account.
+
+> Build the verify-email step even if verification is currently disabled — it auto-hides.
+
+### Login flow
+
+1. Collect email + password.
+2. Call `loginCustomer`:
+   ```ts
+   const result = await client.loginCustomer(email, password);
+   ```
+3. Branch on `result.requiresVerification`:
+   - `true` → route to verify-email
+   - `false` → `client.setCustomerToken(result.token)`, route to previous page or account
+4. Always offer OAuth buttons from `client.getAvailableOAuthProviders()` — render the region even when empty, it auto-populates when a provider is enabled.
+5. Render specific errors (bad credentials, rate limited, disabled) — never swallow them.
+
+### Order confirmation flow
+
+1. Read `checkoutId` from URL or session.
+2. `await client.handlePaymentSuccess(checkoutId)` — mandatory, clears cart so purchased items don't show on next visit.
+3. `const order = await client.waitForOrder(checkoutId)` — polls until the webhook writes the order.
+4. Show a spinner during step 3 (webhook may lag). On timeout: show "we're still processing, check your email" with a link to order history — the order WILL appear there.
+5. On success: render order number and line items from the returned `order` object.
+
+### Password reset flow
+
+**Forgot password step:** collect email → `client.forgotPassword(email)` → always show a generic success message (prevents account enumeration, regardless of whether the account exists).
+
+**Reset password step:** read `token` from URL query param → if missing, show error with link back → collect new password → `client.resetPassword(token, newPassword)` → on success route to login → on expired/invalid token show the specific error with link back.
+
+### OAuth flow
+
+1. Get the list of available provider names:
+   ```ts
+   const { providers } = await client.getAvailableOAuthProviders();
+   // providers = ['GOOGLE', 'FACEBOOK', 'GITHUB'] (strings, not objects)
+   ```
+2. For each provider, get the authorization URL:
+   ```ts
+   const { authorizationUrl } = await client.getOAuthAuthorizeUrl(provider, {
+     redirectUrl: `${window.location.origin}/auth/callback`,
+   });
+   window.location.href = authorizationUrl; // full-page redirect, NOT a popup
+   ```
+3. On callback, the URL contains `token` + `oauth_success` (or `oauth_error`) query params:
+   ```ts
+   const token = new URLSearchParams(location.search).get('token');
+   if (token) client.setCustomerToken(token); // then redirect to account
+   ```
+4. On `oauth_error` query param: redirect to login with an error message.
+
+> Build the OAuth button region AND the callback handler even when no providers are configured.
+
+### Inventory reservation flow
+
+- Display the countdown from `cart.reservation?.expiresAt` — refresh once per second (`reservation` is optional; only present when a reservation strategy is active).
+- On expiry: call `client.getCart()` to refresh. Items whose reservation expired are flagged server-side.
+- On the checkout page: if reservation has expired, block payment and show "your cart has expired" with a link back to cart.
+- Do NOT implement your own timer logic — the SDK is the source of truth.
+
+---
+
 ## Quick Reference - Helper Functions
 
 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 %     | `{ 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         | `getCartItemName(item)` → `"Blue T-Shirt"`             |
-| `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)`             |
+| 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                                                               | `getCartItemName(item)` → `"Blue T-Shirt"`             |
+| `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)`             |
 
 ```typescript
 import {
@@ -110,9 +311,9 @@ const paypalProvider = providers.find(p => p.provider === 'paypal');
 ```typescript
 import { BrainerceClient } from 'brainerce';
 
-// Initialize with your Connection ID
+// ✅ salesChannelId (vc_*) is all you need — no API key for storefronts
 const client = new BrainerceClient({
-  connectionId: 'vc_YOUR_CONNECTION_ID',
+  salesChannelId: 'vc_YOUR_SALES_CHANNEL_ID', // found in Brainerce dashboard → Sales Channels
 });
 
 // Fetch products
@@ -649,7 +850,7 @@ Create a file `lib/brainerce.ts`:
 import { BrainerceClient } from 'brainerce';
 
 export const client = new BrainerceClient({
-  connectionId: 'vc_YOUR_CONNECTION_ID', // Your Connection ID from Brainerce
+  salesChannelId: 'vc_YOUR_SALES_CHANNEL_ID', // found in Brainerce dashboard → Sales Channels
 });
 
 // ----- Cart Helpers -----
@@ -1121,6 +1322,9 @@ interface Product {
   sku: string;
   basePrice: number;
   salePrice?: number | null;
+  priceMin?: string | null; // Lowest variant price (VARIABLE products only)
+  priceMax?: string | null; // Highest variant price (VARIABLE products only)
+  priceVaries?: boolean; // true when range should be shown ("₪49 – ₪199")
   status: 'active' | 'draft';
   type: 'SIMPLE' | 'VARIABLE';
   images?: ProductImage[];
@@ -1471,16 +1675,30 @@ console.log(`${count} items in cart`);
 
 #### Apply Coupon
 
+**On the cart page** (before checkout session is created):
+
 ```typescript
 const cart = await client.smartGetCart();
 const updated = await client.applyCoupon(cart.id, 'SAVE20');
 console.log(updated.discountAmount); // "10.00"
 console.log(updated.couponCode); // "SAVE20"
 
-// Remove coupon
 await client.removeCoupon(cart.id);
 ```
 
+**On the checkout page** (checkout session already exists — preferred):
+
+```typescript
+// applyCheckoutCoupon applies to cart AND updates checkout totals atomically
+const checkout = await client.applyCheckoutCoupon(checkoutId, 'SAVE20');
+console.log(checkout.discountAmount); // "10.00"
+console.log(checkout.total); // updated total
+
+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.
+
 #### Cart Totals
 
 ```typescript
@@ -2332,12 +2550,13 @@ function PaymentForm({ checkoutId }: { checkoutId: string }) {
 }
 ```
 
-#### Complete Order After Payment: `completeGuestCheckout()`
+#### Complete Order After Payment: `completeGuestCheckout()` (legacy untracked flow only)
+
+> **Context:** This section describes the **legacy untracked guest checkout** flow where the client must explicitly create the order. In the modern tracked flow (`startGuestCheckout()` → webhook creates the order), you use `handlePaymentSuccess()` + `waitForOrder()` instead (see [Business Flows — Checkout](#checkout-flow) above).
 
-**CRITICAL:** After payment succeeds, you MUST call `completeGuestCheckout()` to create the order on the server and clear the cart.
+**CRITICAL (untracked flow only):** After payment succeeds, you MUST call `completeGuestCheckout()` to create the order on the server.
 
-> **WARNING:** Do NOT use `handlePaymentSuccess()` - it only clears cart state locally
-> and does NOT send the order to the server. Your customer will pay but no order will be created!
+> **WARNING (untracked flow only):** Do NOT use `handlePaymentSuccess()` here — it only clears cart state locally and does NOT create the order on the server. The tracked flow uses `handlePaymentSuccess` + `waitForOrder`; the untracked flow uses `completeGuestCheckout` directly.
 
 ```typescript
 // On your /checkout/success page:
@@ -3014,12 +3233,14 @@ console.log(store.language); // 'en', 'he', etc.
 
 ## Admin API Reference
 
-The Admin API requires an API key (`apiKey`) and provides full access to store configuration and management features.
+> ⛔ **Server-side only.** The `apiKey` (`brainerce_*`) is a privileged secret — NEVER put it in browser code, client bundles, or any code that ships to the user's machine. It belongs in an environment variable on your server. For building the customer-facing storefront, use `salesChannelId` instead (see [Quick Start](#quick-start)).
+
+The Admin API provides full access to store configuration and management features (taxonomy, shipping, team, metafields, etc.) and runs only in server-side code.
 
 ```typescript
-// Initialize in Admin mode
-const client = new BrainerceClient({
-  apiKey: process.env.BRAINERCE_API_KEY, // 'brainerce_*' prefix
+// ✅ Only in server-side code (Node.js, Edge functions, API routes — never in the browser)
+const admin = new BrainerceClient({
+  apiKey: process.env.BRAINERCE_API_KEY, // 'brainerce_*' prefix — keep this secret
 });
 ```
 

package/dist/index.d.mts

@@ -218,6 +218,12 @@ interface Product {
     salePrice?: string | null;
     /** Cost price as string. Use parseFloat() for calculations. */
     costPrice?: string | null;
+    /** Lowest effective variant price (VARIABLE products only). String Decimal, e.g. "19.99". */
+    priceMin?: string | null;
+    /** Highest effective variant price (VARIABLE products only). String Decimal, e.g. "99.99". */
+    priceMax?: string | null;
+    /** True when variant prices differ (VARIABLE products only). Use for "From X – Y" display. */
+    priceVaries?: boolean;
     /** Product status (active, draft). Always returned by backend. */
     status: string;
     type: 'SIMPLE' | 'VARIABLE';
@@ -605,7 +611,7 @@ declare function getProductPrice(product: Pick<Product, 'basePrice' | 'salePrice
  * }
  * ```
  */
-declare function getProductPriceInfo(product: Pick<Product, 'basePrice' | 'salePrice' | 'discount'> | null | undefined): {
+declare function getProductPriceInfo(product: Pick<Product, 'basePrice' | 'salePrice' | 'discount' | 'priceMin' | 'priceVaries'> | null | undefined): {
     price: number;
     originalPrice: number;
     isOnSale: boolean;
@@ -1134,6 +1140,12 @@ interface Coupon {
      * Returns objects with id and name from backend.
      */
     applicableProducts?: EntityRef[] | null;
+    /** Products explicitly excluded from this coupon. */
+    excludedProducts?: EntityRef[] | null;
+    /** Categories this coupon applies to (inclusion list). */
+    applicableCategories?: EntityRef[] | null;
+    /** Categories explicitly excluded from this coupon. */
+    excludedCategories?: EntityRef[] | null;
     combinesWithOther: boolean;
     /** Whether coupon needs sync to platforms */
     needsSync?: boolean;
@@ -1200,6 +1212,12 @@ interface CreateCouponDto {
     conditions?: Record<string, unknown>;
     /** Product IDs this coupon applies to */
     applicableProducts?: string[];
+    /** Product IDs explicitly excluded from this coupon */
+    excludedProducts?: string[];
+    /** Category IDs this coupon applies to */
+    applicableCategories?: string[];
+    /** Category IDs explicitly excluded from this coupon */
+    excludedCategories?: string[];
     combinesWithOther?: boolean;
     /** Platforms to publish this coupon to */
     platforms?: ConnectorPlatform[];
@@ -1222,6 +1240,9 @@ interface UpdateCouponDto {
     maximumDiscount?: number | string | null;
     conditions?: Record<string, unknown> | null;
     applicableProducts?: string[] | null;
+    excludedProducts?: string[] | null;
+    applicableCategories?: string[] | null;
+    excludedCategories?: string[] | null;
     combinesWithOther?: boolean;
 }
 /**
@@ -6397,6 +6418,35 @@ declare class BrainerceClient {
      * ```
      */
     getCheckout(checkoutId: string): Promise<Checkout>;
+    /**
+     * Apply a coupon code to an existing checkout session.
+     *
+     * The coupon is validated, applied to the linked cart, and the checkout
+     * totals (discountAmount, totalAmount) are updated atomically.
+     * Use this instead of `applyCoupon()` when the checkout session is already
+     * created — which is the common case when the customer enters a code on the
+     * checkout page.
+     *
+     * @example
+     * ```typescript
+     * const checkout = await client.applyCheckoutCoupon('checkout_123', 'SAVE20');
+     * console.log('New total:', checkout.total);
+     * console.log('Discount:', checkout.discountAmount);
+     * ```
+     */
+    applyCheckoutCoupon(checkoutId: string, code: string): Promise<Checkout>;
+    /**
+     * Remove a coupon from an existing checkout session.
+     *
+     * Clears the coupon from the linked cart and recalculates the checkout totals.
+     *
+     * @example
+     * ```typescript
+     * const checkout = await client.removeCheckoutCoupon('checkout_123');
+     * console.log('New total:', checkout.total);
+     * ```
+     */
+    removeCheckoutCoupon(checkoutId: string): Promise<Checkout>;
     /**
      * Set customer information on checkout
      *

package/dist/index.d.ts

@@ -218,6 +218,12 @@ interface Product {
     salePrice?: string | null;
     /** Cost price as string. Use parseFloat() for calculations. */
     costPrice?: string | null;
+    /** Lowest effective variant price (VARIABLE products only). String Decimal, e.g. "19.99". */
+    priceMin?: string | null;
+    /** Highest effective variant price (VARIABLE products only). String Decimal, e.g. "99.99". */
+    priceMax?: string | null;
+    /** True when variant prices differ (VARIABLE products only). Use for "From X – Y" display. */
+    priceVaries?: boolean;
     /** Product status (active, draft). Always returned by backend. */
     status: string;
     type: 'SIMPLE' | 'VARIABLE';
@@ -605,7 +611,7 @@ declare function getProductPrice(product: Pick<Product, 'basePrice' | 'salePrice
  * }
  * ```
  */
-declare function getProductPriceInfo(product: Pick<Product, 'basePrice' | 'salePrice' | 'discount'> | null | undefined): {
+declare function getProductPriceInfo(product: Pick<Product, 'basePrice' | 'salePrice' | 'discount' | 'priceMin' | 'priceVaries'> | null | undefined): {
     price: number;
     originalPrice: number;
     isOnSale: boolean;
@@ -1134,6 +1140,12 @@ interface Coupon {
      * Returns objects with id and name from backend.
      */
     applicableProducts?: EntityRef[] | null;
+    /** Products explicitly excluded from this coupon. */
+    excludedProducts?: EntityRef[] | null;
+    /** Categories this coupon applies to (inclusion list). */
+    applicableCategories?: EntityRef[] | null;
+    /** Categories explicitly excluded from this coupon. */
+    excludedCategories?: EntityRef[] | null;
     combinesWithOther: boolean;
     /** Whether coupon needs sync to platforms */
     needsSync?: boolean;
@@ -1200,6 +1212,12 @@ interface CreateCouponDto {
     conditions?: Record<string, unknown>;
     /** Product IDs this coupon applies to */
     applicableProducts?: string[];
+    /** Product IDs explicitly excluded from this coupon */
+    excludedProducts?: string[];
+    /** Category IDs this coupon applies to */
+    applicableCategories?: string[];
+    /** Category IDs explicitly excluded from this coupon */
+    excludedCategories?: string[];
     combinesWithOther?: boolean;
     /** Platforms to publish this coupon to */
     platforms?: ConnectorPlatform[];
@@ -1222,6 +1240,9 @@ interface UpdateCouponDto {
     maximumDiscount?: number | string | null;
     conditions?: Record<string, unknown> | null;
     applicableProducts?: string[] | null;
+    excludedProducts?: string[] | null;
+    applicableCategories?: string[] | null;
+    excludedCategories?: string[] | null;
     combinesWithOther?: boolean;
 }
 /**
@@ -6397,6 +6418,35 @@ declare class BrainerceClient {
      * ```
      */
     getCheckout(checkoutId: string): Promise<Checkout>;
+    /**
+     * Apply a coupon code to an existing checkout session.
+     *
+     * The coupon is validated, applied to the linked cart, and the checkout
+     * totals (discountAmount, totalAmount) are updated atomically.
+     * Use this instead of `applyCoupon()` when the checkout session is already
+     * created — which is the common case when the customer enters a code on the
+     * checkout page.
+     *
+     * @example
+     * ```typescript
+     * const checkout = await client.applyCheckoutCoupon('checkout_123', 'SAVE20');
+     * console.log('New total:', checkout.total);
+     * console.log('Discount:', checkout.discountAmount);
+     * ```
+     */
+    applyCheckoutCoupon(checkoutId: string, code: string): Promise<Checkout>;
+    /**
+     * Remove a coupon from an existing checkout session.
+     *
+     * Clears the coupon from the linked cart and recalculates the checkout totals.
+     *
+     * @example
+     * ```typescript
+     * const checkout = await client.removeCheckoutCoupon('checkout_123');
+     * console.log('New total:', checkout.total);
+     * ```
+     */
+    removeCheckoutCoupon(checkoutId: string): Promise<Checkout>;
     /**
      * Set customer information on checkout
      *

package/dist/index.js

@@ -262,9 +262,7 @@ var BrainerceClient = class {
     this.LOCAL_CART_KEY = "brainerce_cart";
     const resolvedSalesChannelId = options.salesChannelId ?? options.connectionId;
     if (!options.apiKey && !options.storeId && !resolvedSalesChannelId) {
-      throw new Error(
-        "BrainerceClient: either salesChannelId, apiKey, or storeId is required"
-      );
+      throw new Error("BrainerceClient: either salesChannelId, apiKey, or storeId is required");
     }
     if (options.apiKey && !options.apiKey.startsWith("brainerce_")) {
       console.warn('BrainerceClient: apiKey should start with "brainerce_"');
@@ -3575,6 +3573,69 @@ var BrainerceClient = class {
       "checkout"
     );
   }
+  /**
+   * Apply a coupon code to an existing checkout session.
+   *
+   * The coupon is validated, applied to the linked cart, and the checkout
+   * totals (discountAmount, totalAmount) are updated atomically.
+   * Use this instead of `applyCoupon()` when the checkout session is already
+   * created — which is the common case when the customer enters a code on the
+   * checkout page.
+   *
+   * @example
+   * ```typescript
+   * const checkout = await client.applyCheckoutCoupon('checkout_123', 'SAVE20');
+   * console.log('New total:', checkout.total);
+   * console.log('Discount:', checkout.discountAmount);
+   * ```
+   */
+  async applyCheckoutCoupon(checkoutId, code) {
+    if (this.isVibeCodedMode()) {
+      return this.withGuards(
+        this.vibeCodedRequest("POST", `/checkout/${checkoutId}/coupon`, { code }),
+        "checkout"
+      );
+    }
+    if (this.storeId && !this.apiKey) {
+      return this.withGuards(
+        this.storefrontRequest("POST", `/checkout/${checkoutId}/coupon`, { code }),
+        "checkout"
+      );
+    }
+    return this.withGuards(
+      this.adminRequest("POST", `/api/v1/checkout/${checkoutId}/coupon`, { code }),
+      "checkout"
+    );
+  }
+  /**
+   * Remove a coupon from an existing checkout session.
+   *
+   * Clears the coupon from the linked cart and recalculates the checkout totals.
+   *
+   * @example
+   * ```typescript
+   * const checkout = await client.removeCheckoutCoupon('checkout_123');
+   * console.log('New total:', checkout.total);
+   * ```
+   */
+  async removeCheckoutCoupon(checkoutId) {
+    if (this.isVibeCodedMode()) {
+      return this.withGuards(
+        this.vibeCodedRequest("DELETE", `/checkout/${checkoutId}/coupon`),
+        "checkout"
+      );
+    }
+    if (this.storeId && !this.apiKey) {
+      return this.withGuards(
+        this.storefrontRequest("DELETE", `/checkout/${checkoutId}/coupon`),
+        "checkout"
+      );
+    }
+    return this.withGuards(
+      this.adminRequest("DELETE", `/api/v1/checkout/${checkoutId}/coupon`),
+      "checkout"
+    );
+  }
   /**
    * Set customer information on checkout
    *
@@ -6972,6 +7033,7 @@ function getProductPriceInfo(product) {
   if (!product) {
     return { price: 0, originalPrice: 0, isOnSale: false, discountAmount: 0, discountPercent: 0 };
   }
+  const resolvedBasePrice = parseFloat(product.basePrice) === 0 && product.priceMin ? product.priceMin : product.basePrice;
   if (product.discount) {
     const ruleOriginal = parseFloat(product.discount.originalPrice) || 0;
     const ruleDiscounted = parseFloat(product.discount.discountedPrice) || 0;
@@ -6985,7 +7047,7 @@ function getProductPriceInfo(product) {
       discountPercent: rulePercent
     };
   }
-  const basePrice = parseFloat(product.basePrice) || 0;
+  const basePrice = parseFloat(resolvedBasePrice) || 0;
   const salePrice = product.salePrice ? parseFloat(product.salePrice) : null;
   const isOnSale = salePrice !== null && salePrice < basePrice;
   const effectivePrice = isOnSale ? salePrice : basePrice;

package/dist/index.mjs

@@ -199,9 +199,7 @@ var BrainerceClient = class {
     this.LOCAL_CART_KEY = "brainerce_cart";
     const resolvedSalesChannelId = options.salesChannelId ?? options.connectionId;
     if (!options.apiKey && !options.storeId && !resolvedSalesChannelId) {
-      throw new Error(
-        "BrainerceClient: either salesChannelId, apiKey, or storeId is required"
-      );
+      throw new Error("BrainerceClient: either salesChannelId, apiKey, or storeId is required");
     }
     if (options.apiKey && !options.apiKey.startsWith("brainerce_")) {
       console.warn('BrainerceClient: apiKey should start with "brainerce_"');
@@ -3512,6 +3510,69 @@ var BrainerceClient = class {
       "checkout"
     );
   }
+  /**
+   * Apply a coupon code to an existing checkout session.
+   *
+   * The coupon is validated, applied to the linked cart, and the checkout
+   * totals (discountAmount, totalAmount) are updated atomically.
+   * Use this instead of `applyCoupon()` when the checkout session is already
+   * created — which is the common case when the customer enters a code on the
+   * checkout page.
+   *
+   * @example
+   * ```typescript
+   * const checkout = await client.applyCheckoutCoupon('checkout_123', 'SAVE20');
+   * console.log('New total:', checkout.total);
+   * console.log('Discount:', checkout.discountAmount);
+   * ```
+   */
+  async applyCheckoutCoupon(checkoutId, code) {
+    if (this.isVibeCodedMode()) {
+      return this.withGuards(
+        this.vibeCodedRequest("POST", `/checkout/${checkoutId}/coupon`, { code }),
+        "checkout"
+      );
+    }
+    if (this.storeId && !this.apiKey) {
+      return this.withGuards(
+        this.storefrontRequest("POST", `/checkout/${checkoutId}/coupon`, { code }),
+        "checkout"
+      );
+    }
+    return this.withGuards(
+      this.adminRequest("POST", `/api/v1/checkout/${checkoutId}/coupon`, { code }),
+      "checkout"
+    );
+  }
+  /**
+   * Remove a coupon from an existing checkout session.
+   *
+   * Clears the coupon from the linked cart and recalculates the checkout totals.
+   *
+   * @example
+   * ```typescript
+   * const checkout = await client.removeCheckoutCoupon('checkout_123');
+   * console.log('New total:', checkout.total);
+   * ```
+   */
+  async removeCheckoutCoupon(checkoutId) {
+    if (this.isVibeCodedMode()) {
+      return this.withGuards(
+        this.vibeCodedRequest("DELETE", `/checkout/${checkoutId}/coupon`),
+        "checkout"
+      );
+    }
+    if (this.storeId && !this.apiKey) {
+      return this.withGuards(
+        this.storefrontRequest("DELETE", `/checkout/${checkoutId}/coupon`),
+        "checkout"
+      );
+    }
+    return this.withGuards(
+      this.adminRequest("DELETE", `/api/v1/checkout/${checkoutId}/coupon`),
+      "checkout"
+    );
+  }
   /**
    * Set customer information on checkout
    *
@@ -6909,6 +6970,7 @@ function getProductPriceInfo(product) {
   if (!product) {
     return { price: 0, originalPrice: 0, isOnSale: false, discountAmount: 0, discountPercent: 0 };
   }
+  const resolvedBasePrice = parseFloat(product.basePrice) === 0 && product.priceMin ? product.priceMin : product.basePrice;
   if (product.discount) {
     const ruleOriginal = parseFloat(product.discount.originalPrice) || 0;
     const ruleDiscounted = parseFloat(product.discount.discountedPrice) || 0;
@@ -6922,7 +6984,7 @@ function getProductPriceInfo(product) {
       discountPercent: rulePercent
     };
   }
-  const basePrice = parseFloat(product.basePrice) || 0;
+  const basePrice = parseFloat(resolvedBasePrice) || 0;
   const salePrice = product.salePrice ? parseFloat(product.salePrice) : null;
   const isOnSale = salePrice !== null && salePrice < basePrice;
   const effectivePrice = isOnSale ? salePrice : basePrice;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brainerce",
-  "version": "1.23.13",
+  "version": "1.23.14",
   "description": "Official SDK for building e-commerce storefronts with Brainerce Platform. Perfect for vibe-coded sites, AI-built stores (Cursor, Lovable, v0), and custom storefronts.",
   "main": "dist/index.js",
   "module": "dist/index.mjs",