brainerce 1.39.0 → 1.42.0

package/README.md

@@ -46,6 +46,7 @@ Every Brainerce storefront must include **all mandatory features** below. Featur
 | Forgot / reset password                                 | `client.forgotPassword()`, `client.resetPassword()`                                                           | ✅          |
 | OAuth sign-in buttons + callback handler                | `client.getAvailableOAuthProviders()`                                                                         | ✅          |
 | Account area (profile + order history)                  | `client.getMyProfile()`, `client.getMyOrders()`                                                               | ✅          |
+| Loyalty & rewards (points balance + redeem)             | `client.getLoyaltyStatus()`, `client.getAvailableRewards()`, `client.redeemLoyaltyReward(id)`                 | conditional |
 | Global header: cart count + search autocomplete         | `client.getCart()`, `client.getSearchSuggestions(query)`                                                      | ✅          |
 | Discount banners + product badges                       | `client.getDiscountBanners()`, `client.getProductDiscountBadge(productId)`                                    | ✅          |
 | Product reviews on PDP + JSON-LD aggregateRating        | `client.listProductReviews(id)`, `client.submitProductReview(id, …)`                                          | ✅          |
@@ -376,7 +377,7 @@ await client.addToCart(cart.id, {
 
 Money on the wire is **always strings** (`priceDelta: "5.00"`). Validation failures arrive as a structured 400 envelope on `BrainerceError.details` with `code: 'MODIFIER_VALIDATION_FAILED'` and `errors[]` — see INTEGRATION-RULES.md "Modifier validation errors" for the full code list.
 
-Full rendering guide: [Core Integration §2.9](https://brainerce.com/docs/integration/core). Restaurant features (allergens, scheduled availability, nested combos to depth 3, downsell modifiers): [Optional Features "Restaurant / build-your-own products"](https://brainerce.com/docs/integration/optional).
+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).
 
 ### Content (FAQ / Footer / Header / Announcements / Pages)
 
@@ -400,7 +401,7 @@ if (!page) notFound();
 
 All `get` / `getBySlug` return `null` on 404 — render a hard-coded fallback so the page never crashes when the merchant hasn't seeded yet.
 
-**Security**: `FAQ.items[i].answer`, `RICH_TEXT.html`, and `PAGE.html` are **merchant-authored HTML**. The server does NOT pre-sanitize (merchants may embed iframes). ALWAYS sanitize before injecting:
+**Security**: `FAQ.items[i].answer`, `RICH_TEXT.html`, `PAGE.html`, and `Product.description` are **merchant-authored HTML**. The server does NOT pre-sanitize FAQ/RICH_TEXT/PAGE (merchants may embed iframes); `Product.description` is server-sanitized on write but you still sanitize on render. `Product.description` may contain `<video>` and host-locked YouTube/Vimeo `<iframe>` embeds — allow those tags (iframe restricted to `www.youtube.com` / `www.youtube-nocookie.com` / `player.vimeo.com`) and add those hosts to your CSP `frame-src`. ALWAYS sanitize before injecting:
 
 ```typescript
 import DOMPurify from 'isomorphic-dompurify';
@@ -2375,7 +2376,16 @@ const checkoutId = checkout.id;
 
 #### Get All Payment Providers (Recommended)
 
-Use this method to get ALL enabled payment providers and build dynamic UI:
+Use this method to get ALL enabled payment providers and build dynamic UI.
+
+**Primary vs. additive methods (Shopify-parity).** Each provider carries a
+`methodType`. A `CREDIT_CARD` provider is the *primary* card processor — the
+single method that settles the order (`defaultProvider`, `isAdditive: false`,
+`presentation: 'card_form'`). Everything else is *additive* (`isAdditive: true`),
+e.g. PayPal is a `'WALLET'` with `presentation: 'express_button'`. Render additive
+methods as accelerated-checkout **express buttons above the card form** — they sit
+*alongside* the primary, never replace it. (Exception: a wallet-only store has no
+card processor, so its wallet becomes the `defaultProvider` and stands alone.)
 
 ```typescript
 const { hasPayments, providers, defaultProvider } = await client.getPaymentProviders();
@@ -2391,7 +2401,10 @@ const { hasPayments, providers, defaultProvider } = await client.getPaymentProvi
 //       publicKey: 'pk_live_xxx...',
 //       supportedMethods: ['card', 'ideal'],
 //       testMode: false,
-//       isDefault: true
+//       isDefault: true,
+//       methodType: 'CREDIT_CARD',   // primary card processor
+//       presentation: 'card_form',
+//       isAdditive: false
 //     },
 //     {
 //       id: 'provider_yyy',
@@ -2400,12 +2413,20 @@ const { hasPayments, providers, defaultProvider } = await client.getPaymentProvi
 //       publicKey: 'client_id_xxx...',
 //       supportedMethods: ['paypal'],
 //       testMode: false,
-//       isDefault: false
+//       isDefault: false,
+//       methodType: 'WALLET',        // additive — render as an express button
+//       presentation: 'express_button',
+//       isAdditive: true
 //     }
 //   ],
-//   defaultProvider: { ... }  // The default provider (first one)
+//   defaultProvider: { ... }  // The settling primary (never an additive wallet
+//                             // while a card processor is installed)
 // }
 
+// Recommended pattern: express buttons (additive) above the primary card form.
+const expressMethods = providers.filter(p => p.isAdditive);   // e.g. PayPal
+const primary = defaultProvider && !defaultProvider.isAdditive ? defaultProvider : undefined;
+
 // Build dynamic UI based on available providers
 if (!hasPayments) {
   return <div>Payment not configured for this store</div>;
@@ -2459,6 +2480,25 @@ const intent = await client.createPaymentIntent(checkout.id);
 // }
 ```
 
+**Routing to a specific provider (`providerId`).** With `getPaymentProviders()` you
+render additive **express buttons** (e.g. PayPal as a `WALLET`) alongside the primary
+card form. When the buyer taps one, pass that provider's `id` so the charge routes to
+it instead of the store's default card processor:
+
+```typescript
+const { providers } = await client.getPaymentProviders();
+const paypal = providers.find((p) => p.isAdditive && p.provider === 'paypal');
+
+// Buyer tapped the PayPal express button:
+const intent = await client.createPaymentIntent(checkout.id, {
+  providerId: paypal.id,
+});
+```
+
+Omit `providerId` to settle through the primary card processor (`defaultProvider`).
+The platform scopes it to the store, so only that store's own installed providers are
+selectable.
+
 #### Confirm Payment with Stripe.js
 
 Use the client secret with Stripe.js to collect payment:
@@ -2873,6 +2913,32 @@ const { data: orders, meta } = await client.getMyOrders({
 });
 ```
 
+#### Loyalty & Rewards
+
+Storefront-mode only (requires `storeId` + `customerToken`). Let logged-in
+customers check their points balance, enroll, and redeem rewards for one-time
+coupons that apply at checkout.
+
+```typescript
+// Current status — points balance + program display config.
+// `program` is null if the store has no loyalty program.
+const status = await client.getLoyaltyStatus();
+if (status.enrolled) {
+  console.log(`${status.pointsBalance} ${status.program?.pointsName}`);
+}
+
+// Enroll (idempotent) — only if the program is ACTIVE.
+await client.enrollInLoyalty();
+
+// Rewards the customer can redeem, cheapest first.
+const rewards = await client.getAvailableRewards();
+
+// Redeem → spends points, returns a one-time coupon code to apply to the cart.
+const { couponCode, discountValue, pointsBalance } =
+  await client.redeemLoyaltyReward(rewards[0].id);
+await client.applyCoupon(cartId, couponCode);
+```
+
 #### Auth Response Type
 
 ```typescript
@@ -3424,6 +3490,8 @@ client.trackEvent({ eventType: 'engagement', path: '/products/shoes', engagedMs:
 
 > `trackEvent()` is fire-and-forget — errors are silently swallowed so a failed beacon never breaks your storefront. Available in `salesChannelId` and `storeId` modes.
 
+> **Analytics always goes directly to the Brainerce API** (`keepalive` beacon), even when you route the rest of the SDK through a same-origin BFF proxy (`proxyMode` / `baseUrl: '/api/store'`). This is deliberate: a beacon relayed through your server would arrive from the server's datacenter IP and mis-geolocate **every** visitor to that region (e.g. a Vercel US function → all visitors show as US). When `proxyMode` is on — or `baseUrl` shares the page origin — the SDK auto-targets `https://api.brainerce.com` for beacons; override with `analyticsBaseUrl` only if your API is self-hosted.
+
 **Privacy:** cookieless, no PII stored. The visitor IP is resolved to a country server-side and then discarded. No cookie-consent banner required under GDPR/ePrivacy.
 
 ---

package/dist/index.d.mts

@@ -112,6 +112,32 @@ interface BrainerceClientOptions {
      * ```
      */
     proxyMode?: boolean;
+    /**
+     * Base URL used for analytics beacons (`trackEvent`) ONLY — everything else
+     * keeps using `baseUrl`.
+     *
+     * Analytics must reach the Brainerce API **directly from the browser** so the
+     * visitor's real IP — and therefore country — is preserved. If a beacon is routed
+     * through a same-origin BFF proxy (see `proxyMode`), it arrives at the backend from
+     * the proxy server's datacenter IP instead (e.g. a Vercel US region), and every
+     * visitor is mis-geolocated to that datacenter.
+     *
+     * You normally do NOT need to set this: when `proxyMode` is on (or `baseUrl` shares
+     * the current page's origin), the SDK automatically sends analytics to
+     * `https://api.brainerce.com`. Set it explicitly only when your Brainerce API lives
+     * at a custom / self-hosted origin.
+     *
+     * @example
+     * ```typescript
+     * const client = new BrainerceClient({
+     *   connectionId: 'vc_abc123...',
+     *   baseUrl: '/api/store',   // products / cart / auth go through the BFF proxy
+     *   proxyMode: true,
+     *   // analytics auto-routes direct to https://api.brainerce.com — no config needed
+     * });
+     * ```
+     */
+    analyticsBaseUrl?: string;
 }
 interface StoreInfo {
     id: string;
@@ -222,6 +248,51 @@ interface CustomerProfile {
     createdAt: string;
     updatedAt: string;
 }
+/** A store's loyalty program status for a logged-in customer. */
+interface LoyaltyStatus {
+    /** Whether the customer has a membership in the program. */
+    enrolled: boolean;
+    /** Redeemable points balance (pending earns excluded). */
+    pointsBalance: number;
+    /** Total points ever earned (confirmed). */
+    lifetimeEarned: number;
+    /** Program display config, or null when the store has no loyalty program. */
+    program: {
+        /** Display name for points (e.g. "points", "coins"). */
+        pointsName: string;
+        /** Points needed to redeem one unit of store currency. */
+        currencyRatio: number;
+        status: 'DRAFT' | 'ACTIVE' | 'PAUSED';
+    } | null;
+}
+/** A reward a customer can redeem points for (fixed-amount discount coupon). */
+interface LoyaltyReward {
+    id: string;
+    name: string;
+    description: string | null;
+    /** Points required to redeem this reward. */
+    pointsCost: number;
+    /** Fixed discount amount the minted coupon is worth, in store currency. */
+    discountValue: number;
+    /** Minimum order amount for the coupon to apply, or null. */
+    minOrderAmount: number | null;
+    /** How many times a single customer may redeem this reward. */
+    maxUsesPerUser: number;
+    isActive: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+/** Result of redeeming a reward — a one-time coupon plus the new balance. */
+interface RedeemRewardResult {
+    /** The minted one-time coupon code to apply at checkout. */
+    couponCode: string;
+    /** Fixed discount amount the coupon is worth. */
+    discountValue: number;
+    /** Points spent on this redemption. */
+    pointsSpent: number;
+    /** The customer's remaining points balance after redemption. */
+    pointsBalance: number;
+}
 interface ProductMetafield {
     id: string;
     definitionId: string;
@@ -256,13 +327,20 @@ interface Product {
      */
     localeSlugs?: Record<string, string> | null;
     /**
-     * Product description as HTML. **Always sanitize before rendering**, e.g.:
+     * Product description as HTML. May contain self-hosted `<video>` and
+     * host-locked YouTube/Vimeo `<iframe>` embeds. **Always sanitize before
+     * rendering**, e.g.:
      *
      *     import { sanitizeHTML } from '@brainerce/utils';
      *     <div dangerouslySetInnerHTML={{ __html: sanitizeHTML(product.description) }} />
      *
-     * The backend strips dangerous tags/attributes on write, but storefronts should
-     * still treat product description as untrusted HTML and sanitize on render.
+     * The backend strips dangerous tags/attributes on write, but storefronts
+     * should still treat this as untrusted HTML and sanitize on render. Your
+     * sanitizer must allow `video`/`source` and — for embeds — `iframe` restricted
+     * to the hosts `www.youtube.com`, `www.youtube-nocookie.com`,
+     * `player.vimeo.com` (never arbitrary iframes). Sizing is on the `width`/
+     * `height` attributes (inline `style` is stripped). If you set a CSP, add
+     * those three hosts to `frame-src` or embeds render blank.
      */
     description?: string | null;
     descriptionFormat?: 'text' | 'html' | 'markdown' | null;
@@ -443,6 +521,14 @@ interface WriteProductReviewInput {
     rating: number;
     body?: string;
 }
+/**
+ * @deprecated Use `WriteProductReviewInput`. Customers no longer pass author info
+ * directly; it's derived from the authenticated customer profile.
+ */
+interface SubmitProductReviewInput extends WriteProductReviewInput {
+    authorName?: string;
+    authorEmail?: string;
+}
 /**
  * Returned by `client.getMyProductReview(productId)`. Tells the storefront which
  * UI to render: sign-in / not-eligible / submit / edit.
@@ -1064,7 +1150,14 @@ interface CreateProductDto {
     status?: 'active' | 'draft';
     type?: 'SIMPLE' | 'VARIABLE';
     isDownloadable?: boolean;
+    /** Existing category IDs to assign. Unknown/cross-store IDs are rejected with 400. To assign by name (auto-creating if missing), use `categoryNames`. */
     categories?: string[];
+    /** Category names to assign — matched case-insensitively and auto-created if none exists. Merged with any IDs in `categories`. */
+    categoryNames?: string[];
+    /** Existing brand IDs to assign. Unknown/cross-store IDs are rejected with 400. To assign by name (auto-creating if missing), use `brandNames`. */
+    brands?: string[];
+    /** Brand names to assign — matched case-insensitively and auto-created if none exists. Merged with any IDs in `brands`. */
+    brandNames?: string[];
     tags?: string[];
     images?: ProductImage[];
 }
@@ -1078,7 +1171,14 @@ interface UpdateProductDto {
     costPrice?: number | null;
     status?: 'active' | 'draft';
     isDownloadable?: boolean;
+    /** Existing category IDs to assign (replaces the current set). Pass `[]` to clear. Unknown/cross-store IDs are rejected with 400. To assign by name (auto-creating if missing), use `categoryNames`. */
     categories?: string[];
+    /** Category names to assign — matched case-insensitively and auto-created if missing. Additive: added to `categories` (or to the product's current categories when `categories` is omitted). */
+    categoryNames?: string[];
+    /** Existing brand IDs to assign (replaces the current set). Pass `[]` to clear. Unknown/cross-store IDs are rejected with 400. To assign by name (auto-creating if missing), use `brandNames`. */
+    brands?: string[];
+    /** Brand names to assign — matched case-insensitively and auto-created if missing. Additive: added to `brands` (or to the product's current brands when `brands` is omitted). */
+    brandNames?: string[];
     tags?: string[];
     images?: ProductImage[];
 }
@@ -3098,6 +3198,18 @@ interface PaymentClientSdk {
  *
  * **Alias:** `PaymentProvider` is the same type (use either name).
  */
+/**
+ * Payment-method taxonomy (Shopify-parity). `CREDIT_CARD` is a *primary* card
+ * processor — the single method that settles the order; everything else is an
+ * *additive* method (wallet/alt/local/redeemable) that coexists alongside it.
+ */
+type PaymentMethodType = 'CREDIT_CARD' | 'WALLET' | 'OFFSITE' | 'LOCAL' | 'REDEEMABLE';
+/**
+ * How a storefront should render a payment method. `card_form` = the main card
+ * fields; `express_button` = an accelerated-checkout button (render it ABOVE the
+ * card form, like PayPal / Apple Pay); `redirect` = send the buyer offsite.
+ */
+type PaymentPresentation = 'card_form' | 'express_button' | 'redirect' | 'local_option' | 'redeemable_field';
 interface PaymentProviderConfig {
     /** Provider ID (use this when creating payment intents) */
     id: string;
@@ -3113,8 +3225,26 @@ interface PaymentProviderConfig {
     supportedMethods: string[];
     /** Whether this is test/sandbox mode */
     testMode: boolean;
-    /** Whether this is the default provider */
+    /**
+     * Whether this is the store's default *settling* provider. Only a primary
+     * (`methodType: 'CREDIT_CARD'`) provider is ever the default — an additive
+     * wallet never becomes the default while a card processor is installed.
+     */
     isDefault: boolean;
+    /**
+     * Payment-method taxonomy — primary card processor vs additive wallet/alt.
+     * Use it to place the method: primary → the main card form; additive → an
+     * express button. See `presentation`.
+     */
+    methodType: PaymentMethodType;
+    /** Rendering hint derived from `methodType` (card_form | express_button | …). */
+    presentation: PaymentPresentation;
+    /**
+     * True for wallet/alternative methods (e.g. PayPal) that are shown *alongside*
+     * the primary card processor rather than replacing it. Render these as
+     * accelerated-checkout express buttons above the card form.
+     */
+    isAdditive: boolean;
     /** Client-side SDK configuration for providers that render a widget */
     clientSdk?: PaymentClientSdk;
 }
@@ -4773,7 +4903,13 @@ interface CheckoutCustomFieldDefinition {
     key: string;
     name: string;
     description?: string | null;
-    type: 'TEXT' | 'TEXTAREA' | 'NUMBER' | 'BOOLEAN' | 'SELECT' | 'DATE';
+    /**
+     * `IMAGE` renders a file-upload control; its value is the uploaded file URL
+     * (validated server-side to be a store-hosted upload). `GALLERY` and
+     * `MULTI_SELECT` are NOT supported for checkout fields — those are
+     * product-metafield-only (`ProductCustomizationField` / `MetafieldType`).
+     */
+    type: 'TEXT' | 'TEXTAREA' | 'NUMBER' | 'BOOLEAN' | 'SELECT' | 'DATE' | 'IMAGE';
     required: boolean;
     position: number;
     visibility: CheckoutFieldVisibility;
@@ -5427,6 +5563,8 @@ declare class BrainerceClient {
     private readonly storeId?;
     private readonly connectionId?;
     private readonly baseUrl;
+    /** Direct API base for analytics beacons — bypasses any same-origin BFF proxy so the visitor's real IP (hence country) reaches the backend. */
+    private readonly analyticsBaseUrl;
     private readonly timeout;
     private customerToken;
     private customerCartId;
@@ -5596,6 +5734,20 @@ declare class BrainerceClient {
      * ```
      */
     trackEvent(payload?: TrackEventPayload): Promise<void>;
+    /**
+     * Resolve the base URL for analytics beacons. Analytics must go DIRECTLY to the
+     * Brainerce API (never through a same-origin BFF proxy) so the visitor's real IP —
+     * hence country — reaches the backend. Explicit `analyticsBaseUrl` wins; otherwise
+     * use the direct API when `baseUrl` is a same-origin proxy, else the (already-direct)
+     * `baseUrl` (which may be a custom / self-hosted Brainerce API).
+     */
+    private resolveAnalyticsBaseUrl;
+    /**
+     * Fire-and-forget analytics beacon sent directly to `analyticsBaseUrl`. Uses
+     * `keepalive` so it survives page unload (engagement events fired on pagehide),
+     * omits credentials (cookieless), and never throws.
+     */
+    private sendAnalyticsBeacon;
     /**
      * Get a list of products with pagination and filtering
      * Works in vibe-coded, storefront (public), and admin mode
@@ -7930,6 +8082,14 @@ declare class BrainerceClient {
      *
      * @returns Payment providers config with hasPayments flag and provider list
      *
+     * Each provider carries a `methodType` (Shopify-parity taxonomy) and a derived
+     * `isAdditive` / `presentation`. There is at most ONE primary card processor
+     * (`methodType: 'CREDIT_CARD'`, the `defaultProvider`) that settles the order;
+     * additive methods (`isAdditive: true`, e.g. PayPal as a `'WALLET'`) are shown
+     * *alongside* it as accelerated-checkout express buttons — they never replace
+     * the card form. A wallet-only store is the one exception: with no card
+     * processor installed, the wallet becomes the `defaultProvider` and stands alone.
+     *
      * @example
      * ```typescript
      * const { providers, hasPayments, defaultProvider } = await client.getPaymentProviders();
@@ -7939,27 +8099,21 @@ declare class BrainerceClient {
      *   return;
      * }
      *
-     * // Find specific providers
-     * const stripeProvider = providers.find(p => p.provider === 'stripe');
-     * const paypalProvider = providers.find(p => p.provider === 'paypal');
-     *
-     * // Initialize Stripe if available (with Connect account support)
-     * if (stripeProvider) {
-     *   const stripe = await loadStripe(stripeProvider.publicKey, {
-     *     stripeAccount: stripeProvider.stripeAccountId, // For Stripe Connect
-     *   });
-     *   // Show Stripe payment form
-     * }
-     *
-     * // Initialize PayPal if available
-     * if (paypalProvider) {
-     *   // Load PayPal SDK with paypalProvider.publicKey as client-id
-     *   // Show PayPal buttons
+     * // Render additive methods (wallets) as express buttons ABOVE the card form.
+     * const expressMethods = providers.filter(p => p.isAdditive); // e.g. PayPal
+     * for (const m of expressMethods) {
+     *   // m.presentation === 'express_button' — render an express/accelerated button
+     *   // and call createPaymentIntent({ providerId: m.id }) when the buyer taps it.
      * }
      *
-     * // Or use the default provider for a simpler single-provider flow
-     * if (defaultProvider) {
-     *   console.log(`Using default: ${defaultProvider.name} (${defaultProvider.provider})`);
+     * // Render the primary card processor (the settling default) as the main form.
+     * if (defaultProvider && !defaultProvider.isAdditive) {
+     *   if (defaultProvider.provider === 'stripe') {
+     *     const stripe = await loadStripe(defaultProvider.publicKey, {
+     *       stripeAccount: defaultProvider.stripeAccountId, // For Stripe Connect
+     *     });
+     *     // Show the Stripe card form
+     *   }
      * }
      * ```
      */
@@ -8000,6 +8154,16 @@ declare class BrainerceClient {
      * ```
      */
     createPaymentIntent(checkoutId: string, options?: {
+        /**
+         * Route the charge to a specific installed provider — pass the `id` from a
+         * `getPaymentProviders()` entry. This is how you wire an additive express
+         * button (e.g. PayPal as a `WALLET`): when the buyer taps it, call
+         * `createPaymentIntent(checkoutId, { providerId: m.id })`. Omit to settle
+         * through the store's primary card processor (`defaultProvider`). The
+         * platform scopes this to the store, so only that store's own installed
+         * providers are selectable.
+         */
+        providerId?: string;
         successUrl?: string;
         cancelUrl?: string;
         /**
@@ -8450,6 +8614,54 @@ declare class BrainerceClient {
         phone?: string;
         acceptsMarketing?: boolean;
     }): Promise<CustomerProfile>;
+    /**
+     * Get the logged-in customer's loyalty status: enrollment, points balance,
+     * lifetime earned, and the program's display config (requires customerToken).
+     * Only available in storefront mode. `program` is null when the store has no
+     * loyalty program.
+     *
+     * @example
+     * ```typescript
+     * client.setCustomerToken(auth.token);
+     * const status = await client.getLoyaltyStatus();
+     * if (status.enrolled) console.log(`${status.pointsBalance} ${status.program?.pointsName}`);
+     * ```
+     */
+    getLoyaltyStatus(): Promise<LoyaltyStatus>;
+    /**
+     * Enroll the logged-in customer in the store's loyalty program (requires
+     * customerToken). Idempotent — returns the same status shape as
+     * getLoyaltyStatus(). Only available in storefront mode.
+     *
+     * @example
+     * ```typescript
+     * const status = await client.enrollInLoyalty();
+     * ```
+     */
+    enrollInLoyalty(): Promise<LoyaltyStatus>;
+    /**
+     * List the rewards the customer can redeem points for (active rewards, cheapest
+     * first). Requires customerToken. Only available in storefront mode.
+     *
+     * @example
+     * ```typescript
+     * client.setCustomerToken(auth.token);
+     * const rewards = await client.getAvailableRewards();
+     * ```
+     */
+    getAvailableRewards(): Promise<LoyaltyReward[]>;
+    /**
+     * Redeem a reward: spends the customer's points and mints a one-time coupon
+     * that applies at checkout (requires customerToken). Only available in
+     * storefront mode.
+     *
+     * @example
+     * ```typescript
+     * const { couponCode, pointsBalance } = await client.redeemLoyaltyReward('rw_123');
+     * // apply couponCode to the cart at checkout
+     * ```
+     */
+    redeemLoyaltyReward(rewardId: string): Promise<RedeemRewardResult>;
     /**
      * Get the current customer's orders (requires customerToken)
      * Works in vibe-coded and storefront modes
@@ -9614,7 +9826,7 @@ declare class BrainerceError extends Error {
     constructor(message: string, statusCode: number, details?: unknown);
 }
 
-declare const SDK_VERSION = "1.36.1";
+declare const SDK_VERSION = "1.42.0";
 
 /**
  * Verify a webhook signature from Brainerce
@@ -9754,4 +9966,4 @@ declare function formatVariantPrice(variant: Pick<ProductVariant, 'price' | 'sal
 /** Format any numeric amount as currency. Useful for cart totals, fees, etc. */
 declare function formatMoney(amount: number, currency: string, locale?: string): string;
 
-export { type AddToCartDto, type AnnouncementContent, type AnnouncementSeverity, type AppliedDiscount, type ApplyCouponDto, type AttachModifierGroupInput, type Attribute, type AttributeOption, type AttributeSource, type BrainerceApiError, BrainerceClient, type BrainerceClientOptions, BrainerceError, type Brand, type BulkInventoryResponse, type BulkSaveVariantsDto, type BulkSaveVariantsResponse, type BulkVariantInput, type Cart, type CartAppliedDiscount, type CartBundleOffer, type CartBundlesResponse, type CartIncludeOption, type CartIncludeOptions, type CartItem, type CartItemModifierLine, type CartNudge, type CartRecommendationsResponse, type CartStatus, type CartUpgradeSuggestion, type CartUpgradesResponse, type CartWithIncludes, type Category, type CategoryNode, type CategorySuggestion, type Checkout, type CheckoutAddress, type CheckoutBumpsResponse, type CheckoutCustomFieldDefinition, type CheckoutFieldPricing, type CheckoutFieldVisibility, type CheckoutLineItem, type CheckoutPrefillData, type CheckoutStatus, type CompleteCheckoutResponse, type CompleteDraftDto, type ConfigureOAuthProviderDto as ConfigureOAuthProviderInput, type ConflictStatus, type ConnectorPlatform, type ContactFormFieldType, type ContactFormFieldValidation, type ContactFormPublic, type ContactFormPublicField, type ContactFormSummary, type Content, type ContentDataMap, type ContentStatus, type ContentSummary, type ContentType, type Coupon, type CouponCreateResponse, type CouponQueryParams, type CouponStatus, type CouponType, type CouponValidationWarning, type CreateAddressDto, type CreateAttributeDto as CreateAttributeInput, type CreateAttributeOptionDto as CreateAttributeOptionInput, type CreateBrandDto as CreateBrandInput, type CreateCategoryDto as CreateCategoryInput, type CreateCheckoutDto, type CreateContentInput, type CreateCouponDto, type CreateCustomApiDto, type CreateCustomerDto, type CreateEmailTemplateDto as CreateEmailTemplateInput, type CreateGuestOrderDto, type CreateInquiryInput, type CreateInquiryResponse, type CreateMetafieldDefinitionDto as CreateMetafieldDefinitionInput, type CreateModifierGroupInput, type CreateModifierInput, type CreateOrderDto, type CreateProductDto, type CreateRefundDto, type CreateShippingRateDto as CreateShippingRateInput, type CreateShippingZoneDto as CreateShippingZoneInput, type CreateTagDto as CreateTagInput, type CreateTaxRateDto as CreateTaxRateInput, type CreateVariantDto, type CustomApiAuthType, type CustomApiConnectionStatus, type CustomApiCredentials, type CustomApiIntegration, type CustomApiSyncConfig, type CustomApiSyncDirection, type CustomApiTestResult, type Customer, type CustomerAddress, type CustomerAuthResponse, type CustomerOAuthProvider, type CustomerProfile, type CustomerQueryParams, type DeleteProductResponse, type DiscountBanner, type DiscountRuleType, type DownloadFile, type DraftLineItem, type EditInventoryDto, type EmailDomain, type EmailEventSettings, type EmailEventType, type EmailSettings, type EmailTemplate, type EmailTemplatePreview, type EmailTemplatesResponse, type EmailVerificationResponse, type ExtendReservationResponse, type FaqContent, type FaqItem, type FooterColumn, type FooterContent, type FooterLink, type FooterSocialLink, type FormatPriceOptions, type FormatProductPriceOptions, type FreeAllocationPolicy, type FulfillOrderDto, type GuestCheckoutStartResponse, type GuestOrderResponse, type HeaderContent, type HeaderCta, type HeaderLogo, type HeaderNavItem, type InsufficientStockError, type InventoryInfo, type InventoryReservationStrategy, type InventorySyncStatus, type InventoryTrackingMode, type InvitationStatus, type InviteMemberDto as InviteMemberInput, type InviteStoreMemberDto as InviteStoreMemberInput, type ListModifierGroupsParams, type LocalCart, type LocalCartItem, type LockedVariant, type MergeCartsDto, type MetafieldConflict, type MetafieldConflictResolution, type MetafieldDefinition, type MetafieldType, type Modifier, type ModifierGroup, type ModifierSelection, type ModifierSelectionType, type ModifierValidationCode, type ModifierValidationError, type OAuthAuthorizeResponse, type OAuthCallbackResponse, type OAuthConnection, type OAuthConnectionsResponse, type OAuthProviderConfig, type OAuthProviderType, type OAuthProvidersResponse, type Order, type OrderAddress, type OrderBump, type OrderCustomer, type OrderDownloadLink, type OrderItem, type OrderQueryParams, type OrderStatus, type OrderStatusChange, type PageContent, type PageSeo, type PaginatedResponse, type PaymentClientSdk, type PaymentConfig, type PaymentIntent, type PaymentProvider, type PaymentProviderConfig, type PaymentProvidersConfig, type PaymentStatus, type PaymentUrlOptions, type PickupLocation, type PlatformCouponCapabilities, type PlatformMetafieldMetadata, type PreviewEmailTemplateDto as PreviewEmailTemplateInput, type Product, type ProductAttributeInput, type ProductAvailability, type ProductCustomizationField, type ProductDiscount, type ProductDiscountBadge, type ProductImage, type ProductMetafield, type ProductMetafieldValue, type ProductModifierGroupAttachment, type ProductQueryParams, type ProductRecommendation, type ProductRecommendationsResponse, type ProductRelationType, type ProductSuggestion, type ProductVariant, type PublicMetafieldDefinition, type PublishProductResponse, RTL_LOCALES, type RecommendationVariant, type ReconcileInventoryResponse, type Refund, type RefundLineItem, type RefundLineItemResponse, type RefundType, type RegisterCustomerDto, type ReservationInfo, type ResolveMetafieldConflictDto as ResolveMetafieldConflictInput, type ResolveSyncConflictDto as ResolveSyncConflictInput, type RichTextContent, SDK_VERSION, type SearchSuggestions, type SelectPickupLocationDto, type SelectShippingMethodDto, type SendInvoiceDto, type SessionCartRef, type SetBillingAddressDto, type SetCheckoutCustomFieldsDto, type SetCheckoutCustomerDto, type SetDefinitionProductsDto as SetDefinitionProductsInput, type SetMetafieldPlatformsDto as SetMetafieldPlatformsInput, type SetShippingAddressDto, type SetShippingAddressResponse, type ShippingDestinations, type ShippingLine, type ShippingRate, type ShippingRateConfig, type ShippingRateType, type ShippingZone, type ShippingZoneQueryParams, type StockAvailabilityRequest, type StockAvailabilityResponse, type StockAvailabilityResult, type StoreInfo, type StoreInvitation, type StoreInvitationDetails, type StoreMember, type StorePermission, type StoreRole, type StoreTeamResponse, type SupportedLocaleObject, type SyncConflict, type SyncConflictResolution, type SyncJob, type Tag, type TaxBreakdown, type TaxBreakdownItem, type TaxRate, type TaxonomyQueryParams, type TeamInvitation, type TeamInvitationsResponse, type TeamMember, type TeamMembersResponse, type TeamRole, type UpdateAddressDto, type UpdateAttachmentInput, type UpdateAttributeDto as UpdateAttributeInput, type UpdateAttributeOptionDto as UpdateAttributeOptionInput, type UpdateBrandDto as UpdateBrandInput, type UpdateCartItemDto, type UpdateCategoryDto as UpdateCategoryInput, type UpdateContentInput, type UpdateCouponDto, type UpdateCustomApiDto, type UpdateCustomerDto, type UpdateDraftDto, type UpdateEmailSettingsDto as UpdateEmailSettingsInput, type UpdateEmailTemplateDto as UpdateEmailTemplateInput, type UpdateInventoryDto, type UpdateMemberRoleDto as UpdateMemberRoleInput, type UpdateMetafieldDefinitionDto as UpdateMetafieldDefinitionInput, type UpdateModifierGroupInput, type UpdateModifierInput, type UpdateOAuthProviderDto as UpdateOAuthProviderInput, type UpdateOrderDto, type UpdateOrderShippingDto, type UpdateProductDto, type UpdateShippingRateDto as UpdateShippingRateInput, type UpdateShippingZoneDto as UpdateShippingZoneInput, type UpdateStoreMemberDto as UpdateStoreMemberInput, type UpdateTagDto as UpdateTagInput, type UpdateTaxRateDto as UpdateTaxRateInput, type UpdateVariantDto, type UpdateVariantInventoryDto, type UpsertProductMetafieldDto as UpsertProductMetafieldInput, type UserStore, type UserStorePermissions, type VariantInventoryResponse, type VariantPlatformOverlay, type VariantStatus, type WaitForOrderOptions, type WaitForOrderResult, type WebhookEvent, type WebhookEventType, createWebhookHandler, deriveSeoDescription, enableDevGuards, formatMoney, formatPrice, formatProductPrice, formatVariantPrice, getCartItemImage, getCartItemName, getCartTotals, getDescriptionContent, getDirectionForLocale, formatPrice as getPriceDisplay, getProductCustomizationFields, getProductMetafield, getProductMetafieldValue, getProductMetafieldsByType, getProductPrice, getProductPriceInfo, getProductSwatches, getStockStatus, getVariantOptions, getVariantPrice, isAllowedPaymentUrl, isCouponApplicableToProduct, isHtmlDescription, isWebhookEventType, parseWebhookEvent, safePaymentRedirect, stripHtml, verifyWebhook };
+export { type AddToCartDto, type AnnouncementContent, type AnnouncementSeverity, type AppliedDiscount, type ApplyCouponDto, type AttachModifierGroupInput, type Attribute, type AttributeOption, type AttributeSource, type BrainerceApiError, BrainerceClient, type BrainerceClientOptions, BrainerceError, type Brand, type BulkInventoryResponse, type BulkSaveVariantsDto, type BulkSaveVariantsResponse, type BulkVariantInput, type Cart, type CartAppliedDiscount, type CartBundleOffer, type CartBundlesResponse, type CartIncludeOption, type CartIncludeOptions, type CartItem, type CartItemModifierLine, type CartNudge, type CartRecommendationsResponse, type CartStatus, type CartUpgradeSuggestion, type CartUpgradesResponse, type CartWithIncludes, type Category, type CategoryNode, type CategorySuggestion, type Checkout, type CheckoutAddress, type CheckoutBumpsResponse, type CheckoutCustomFieldDefinition, type CheckoutFieldPricing, type CheckoutFieldVisibility, type CheckoutLineItem, type CheckoutPrefillData, type CheckoutStatus, type CompleteCheckoutResponse, type CompleteDraftDto, type ConfigureOAuthProviderDto as ConfigureOAuthProviderInput, type ConflictStatus, type ConnectorPlatform, type ContactFormFieldType, type ContactFormFieldValidation, type ContactFormPublic, type ContactFormPublicField, type ContactFormSummary, type Content, type ContentDataMap, type ContentStatus, type ContentSummary, type ContentType, type Coupon, type CouponCreateResponse, type CouponQueryParams, type CouponStatus, type CouponType, type CouponValidationWarning, type CreateAddressDto, type CreateAttributeDto as CreateAttributeInput, type CreateAttributeOptionDto as CreateAttributeOptionInput, type CreateBrandDto as CreateBrandInput, type CreateCategoryDto as CreateCategoryInput, type CreateCheckoutDto, type CreateContentInput, type CreateCouponDto, type CreateCustomApiDto, type CreateCustomerDto, type CreateEmailTemplateDto as CreateEmailTemplateInput, type CreateGuestOrderDto, type CreateInquiryInput, type CreateInquiryResponse, type CreateMetafieldDefinitionDto as CreateMetafieldDefinitionInput, type CreateModifierGroupInput, type CreateModifierInput, type CreateOrderDto, type CreateProductDto, type CreateRefundDto, type CreateShippingRateDto as CreateShippingRateInput, type CreateShippingZoneDto as CreateShippingZoneInput, type CreateTagDto as CreateTagInput, type CreateTaxRateDto as CreateTaxRateInput, type CreateVariantDto, type CustomApiAuthType, type CustomApiConnectionStatus, type CustomApiCredentials, type CustomApiIntegration, type CustomApiSyncConfig, type CustomApiSyncDirection, type CustomApiTestResult, type Customer, type CustomerAddress, type CustomerAuthResponse, type CustomerOAuthProvider, type CustomerProfile, type CustomerQueryParams, type DeleteProductResponse, type DiscountBanner, type DiscountRuleType, type DownloadFile, type DraftLineItem, type EditInventoryDto, type EmailDomain, type EmailEventSettings, type EmailEventType, type EmailSettings, type EmailTemplate, type EmailTemplatePreview, type EmailTemplatesResponse, type EmailVerificationResponse, type ExtendReservationResponse, type FaqContent, type FaqItem, type FooterColumn, type FooterContent, type FooterLink, type FooterSocialLink, type FormatPriceOptions, type FormatProductPriceOptions, type FreeAllocationPolicy, type FulfillOrderDto, type GuestCheckoutStartResponse, type GuestOrderResponse, type HeaderContent, type HeaderCta, type HeaderLogo, type HeaderNavItem, type InsufficientStockError, type InventoryInfo, type InventoryReservationStrategy, type InventorySyncStatus, type InventoryTrackingMode, type InvitationStatus, type InviteMemberDto as InviteMemberInput, type InviteStoreMemberDto as InviteStoreMemberInput, type ListModifierGroupsParams, type LocalCart, type LocalCartItem, type LockedVariant, type MergeCartsDto, type MetafieldConflict, type MetafieldConflictResolution, type MetafieldDefinition, type MetafieldType, type Modifier, type ModifierGroup, type ModifierSelection, type ModifierSelectionType, type ModifierValidationCode, type ModifierValidationError, type MyProductReview, type OAuthAuthorizeResponse, type OAuthCallbackResponse, type OAuthConnection, type OAuthConnectionsResponse, type OAuthProviderConfig, type OAuthProviderType, type OAuthProvidersResponse, type Order, type OrderAddress, type OrderBump, type OrderCustomer, type OrderDownloadLink, type OrderItem, type OrderQueryParams, type OrderStatus, type OrderStatusChange, type PageContent, type PageSeo, type PaginatedResponse, type PaymentClientSdk, type PaymentConfig, type PaymentIntent, type PaymentProvider, type PaymentProviderConfig, type PaymentProvidersConfig, type PaymentStatus, type PaymentUrlOptions, type PickupLocation, type PlatformCouponCapabilities, type PlatformMetafieldMetadata, type PreviewEmailTemplateDto as PreviewEmailTemplateInput, type Product, type ProductAttributeInput, type ProductAvailability, type ProductCustomizationField, type ProductDiscount, type ProductDiscountBadge, type ProductImage, type ProductMetafield, type ProductMetafieldValue, type ProductModifierGroupAttachment, type ProductQueryParams, type ProductRecommendation, type ProductRecommendationsResponse, type ProductRelationType, type ProductReview, type ProductReviewAdmin, type ProductSuggestion, type ProductVariant, type PublicMetafieldDefinition, type PublishProductResponse, RTL_LOCALES, type RecommendationVariant, type ReconcileInventoryResponse, type Refund, type RefundLineItem, type RefundLineItemResponse, type RefundType, type RegisterCustomerDto, type ReservationInfo, type ResolveMetafieldConflictDto as ResolveMetafieldConflictInput, type ResolveSyncConflictDto as ResolveSyncConflictInput, type RichTextContent, SDK_VERSION, type SearchSuggestions, type SelectPickupLocationDto, type SelectShippingMethodDto, type SendInvoiceDto, type SessionCartRef, type SetBillingAddressDto, type SetCheckoutCustomFieldsDto, type SetCheckoutCustomerDto, type SetDefinitionProductsDto as SetDefinitionProductsInput, type SetMetafieldPlatformsDto as SetMetafieldPlatformsInput, type SetShippingAddressDto, type SetShippingAddressResponse, type ShippingDestinations, type ShippingLine, type ShippingRate, type ShippingRateConfig, type ShippingRateType, type ShippingZone, type ShippingZoneQueryParams, type StockAvailabilityRequest, type StockAvailabilityResponse, type StockAvailabilityResult, type StoreInfo, type StoreInvitation, type StoreInvitationDetails, type StoreMember, type StorePermission, type StoreRole, type StoreTeamResponse, type SubmitProductReviewInput, type SupportedLocaleObject, type SyncConflict, type SyncConflictResolution, type SyncJob, type Tag, type TaxBreakdown, type TaxBreakdownItem, type TaxRate, type TaxonomyQueryParams, type TeamInvitation, type TeamInvitationsResponse, type TeamMember, type TeamMembersResponse, type TeamRole, type UpdateAddressDto, type UpdateAttachmentInput, type UpdateAttributeDto as UpdateAttributeInput, type UpdateAttributeOptionDto as UpdateAttributeOptionInput, type UpdateBrandDto as UpdateBrandInput, type UpdateCartItemDto, type UpdateCategoryDto as UpdateCategoryInput, type UpdateContentInput, type UpdateCouponDto, type UpdateCustomApiDto, type UpdateCustomerDto, type UpdateDraftDto, type UpdateEmailSettingsDto as UpdateEmailSettingsInput, type UpdateEmailTemplateDto as UpdateEmailTemplateInput, type UpdateInventoryDto, type UpdateMemberRoleDto as UpdateMemberRoleInput, type UpdateMetafieldDefinitionDto as UpdateMetafieldDefinitionInput, type UpdateModifierGroupInput, type UpdateModifierInput, type UpdateOAuthProviderDto as UpdateOAuthProviderInput, type UpdateOrderDto, type UpdateOrderShippingDto, type UpdateProductDto, type UpdateShippingRateDto as UpdateShippingRateInput, type UpdateShippingZoneDto as UpdateShippingZoneInput, type UpdateStoreMemberDto as UpdateStoreMemberInput, type UpdateTagDto as UpdateTagInput, type UpdateTaxRateDto as UpdateTaxRateInput, type UpdateVariantDto, type UpdateVariantInventoryDto, type UpsertProductMetafieldDto as UpsertProductMetafieldInput, type UserStore, type UserStorePermissions, type VariantInventoryResponse, type VariantPlatformOverlay, type VariantStatus, type WaitForOrderOptions, type WaitForOrderResult, type WebhookEvent, type WebhookEventType, type WriteProductReviewInput, createWebhookHandler, deriveSeoDescription, enableDevGuards, formatMoney, formatPrice, formatProductPrice, formatVariantPrice, getCartItemImage, getCartItemName, getCartTotals, getDescriptionContent, getDirectionForLocale, formatPrice as getPriceDisplay, getProductCustomizationFields, getProductMetafield, getProductMetafieldValue, getProductMetafieldsByType, getProductPrice, getProductPriceInfo, getProductSwatches, getStockStatus, getVariantOptions, getVariantPrice, isAllowedPaymentUrl, isCouponApplicableToProduct, isHtmlDescription, isWebhookEventType, parseWebhookEvent, safePaymentRedirect, stripHtml, verifyWebhook };