brainerce 1.22.0 → 1.23.12

package/dist/index.d.mts

@@ -1,18 +1,21 @@
 interface BrainerceClientOptions {
     /**
-     * Connection ID for vibe-coded sites (starts with "vc_").
-     * This is the simplest way to connect - just use your Connection ID!
+     * Sales Channel ID (starts with "vc_") — the simplest way to connect.
      * Safe to use in frontend applications.
      *
      * @example
      * ```typescript
-     * // Vibe-coded site usage - simplest option!
      * const client = new BrainerceClient({
-     *   connectionId: 'vc_abc123xyz...',
+     *   salesChannelId: 'vc_abc123xyz...',
      * });
      * const products = await client.getProducts();
      * ```
      */
+    salesChannelId?: string;
+    /**
+     * @deprecated Use `salesChannelId` instead. `connectionId` is kept as a
+     * backwards-compatible alias and will be removed in SDK 2.0.
+     */
     connectionId?: string;
     /**
      * Store ID for public storefront access (no API key needed).
@@ -115,17 +118,21 @@ interface StoreInfo {
     name: string;
     currency: string;
     language: string;
-    /** Connection ID (vibe-coded mode only) */
+    /** Sales Channel ID (sales-channel mode only) */
+    salesChannelId?: string;
+    /** @deprecated alias of `salesChannelId` — will be removed in SDK 2.0 */
     connectionId?: string;
-    /** Store name (vibe-coded mode only - same as name) */
+    /** Store name (sales-channel mode only - same as name) */
     storeName?: string;
-    /** Connection status (vibe-coded mode only) */
+    /** Sales channel status (sales-channel mode only) */
+    salesChannelStatus?: string;
+    /** @deprecated alias of `salesChannelStatus` — will be removed in SDK 2.0 */
     status?: string;
-    /** Allowed API scopes (vibe-coded mode only) */
+    /** Allowed API scopes (sales-channel mode only) */
     allowedScopes?: string[];
-    /** Whether orders can be created (vibe-coded mode only) */
+    /** Whether orders can be created (sales-channel mode only) */
     ordersWriteEnabled?: boolean;
-    /** Whether guest checkout is tracked (vibe-coded mode only) */
+    /** Whether guest checkout is tracked (sales-channel mode only) */
     guestCheckoutTracking?: boolean;
     /**
      * Whether new customer registrations require email verification.
@@ -272,18 +279,44 @@ interface Product {
             translations?: Record<string, Record<string, string>> | null;
         } | null;
     }>;
-    /** Vibe-coded sites this product is published to (admin mode only) */
+    /** Sales channels this product is published to (admin mode only) */
+    channelPublishes?: Array<{
+        salesChannel: {
+            id: string;
+            name: string;
+            connectionId: string;
+        };
+        /** @deprecated alias of `salesChannel` — will be removed in SDK 2.0 */
+        connection?: {
+            id: string;
+            name: string;
+            connectionId: string;
+        };
+    }>;
+    /** @deprecated alias of `channelPublishes` — will be removed in SDK 2.0 */
     vibeCodedPublishes?: Array<{
-        connection: {
+        salesChannel: {
+            id: string;
+            name: string;
+            connectionId: string;
+        };
+        connection?: {
             id: string;
             name: string;
             connectionId: string;
         };
     }>;
-    /** Discount info from matching discount rules (storefront/VC mode only) */
+    /** Discount info from matching discount rules (storefront/sales-channel mode only) */
     discount?: ProductDiscount | null;
     /** Recommendations (upsells, cross-sells, related) — included in storefront/VC getProductBySlug response */
     recommendations?: ProductRecommendationsResponse;
+    /**
+     * Modifier groups attached to this product (toppings, sauce, bread type, …).
+     * Effective values (`min`, `max`, `freeQuantity`, etc.) already reflect any
+     * per-attachment overrides. Only present on single-product fetches
+     * (`getProductBySlug`, `getProductById`); omitted from list responses.
+     */
+    modifierGroups?: ModifierGroup[];
     createdAt: string;
     updatedAt: string;
 }
@@ -730,6 +763,21 @@ interface ProductQueryParams {
     minPrice?: number;
     /** Maximum price filter */
     maxPrice?: number;
+    /**
+     * Filter by custom-field (metafield) values. Keys are metafield definition
+     * keys (e.g. "color", "in_stock"); each value is one or more accepted values.
+     * Only definitions with `filterable: true` and a supported type
+     * (SELECT / MULTI_SELECT / BOOLEAN) are honored — others are ignored
+     * server-side.
+     *
+     * @example
+     * ```typescript
+     * client.getProducts({
+     *   metafields: { color: ['red', 'blue'], in_stock: ['true'] },
+     * });
+     * ```
+     */
+    metafields?: Record<string, string | string[]>;
     /** Sort by field (default: menuOrder) */
     sortBy?: 'name' | 'price' | 'createdAt';
     sortOrder?: 'asc' | 'desc';
@@ -1093,6 +1141,33 @@ interface Coupon {
     lastSyncedAt?: string | null;
     /** Per-platform channel overrides */
     channels?: Record<string, Record<string, unknown>> | null;
+    /** Sales channels this coupon is explicitly published to (admin response only). */
+    channelPublishes?: Array<{
+        salesChannel: {
+            id: string;
+            name: string;
+            connectionId: string;
+        };
+        /** @deprecated alias of `salesChannel` — will be removed in SDK 2.0 */
+        connection?: {
+            id: string;
+            name: string;
+            connectionId: string;
+        };
+    }>;
+    /** @deprecated alias of `channelPublishes` — will be removed in SDK 2.0 */
+    vibeCodedPublishes?: Array<{
+        salesChannel: {
+            id: string;
+            name: string;
+            connectionId: string;
+        };
+        connection?: {
+            id: string;
+            name: string;
+            connectionId: string;
+        };
+    }>;
     createdAt: string;
     updatedAt: string;
 }
@@ -1216,6 +1291,34 @@ interface Customer {
     createdAt: string;
     updatedAt: string;
 }
+/**
+ * Display-only summary of a vaulted payment method.
+ *
+ * The underlying provider token is encrypted at rest in the platform
+ * DB and NEVER exposed through any public API. Use the fields below
+ * for UI ("Visa ending in 4242, exp 03/26").
+ */
+interface SavedPaymentMethodSummary {
+    id: string;
+    customerId: string;
+    appInstallationId: string;
+    /** 'credit_card' | 'paypal' | 'bank_account'. Provider-controlled. */
+    paymentMethod: string;
+    /** Card brand (Visa, Mastercard, etc.). May be null for non-card methods. */
+    brand: string | null;
+    /** Last 4 digits. May be null for non-card methods. */
+    last4: string | null;
+    expMonth: number | null;
+    expYear: number | null;
+    isDefault: boolean;
+    /** 'active' | 'expired' | 'invalid'. */
+    status: string;
+    failureReason: string | null;
+    lastUsedAt: string | null;
+    expiresAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
 interface CustomerAddress {
     id: string;
     label?: string;
@@ -1414,6 +1517,10 @@ type CartStatus = 'ACTIVE' | 'MERGED' | 'CONVERTED' | 'ABANDONED';
  * @see Cart
  * @see LocalCartItem for client-side cart items
  */
+/**
+ * Why a cart item is currently not purchasable. `null` means available.
+ */
+type CartItemUnavailableReason = 'PRODUCT_DRAFT' | 'PRODUCT_ARCHIVED' | 'VARIANT_DRAFT' | 'VARIANT_DELETED' | 'INVENTORY_DISABLED' | 'OUT_OF_STOCK';
 interface CartItem {
     /** Unique identifier for this cart line item */
     id: string;
@@ -1424,10 +1531,26 @@ interface CartItem {
     /** Quantity of this item in the cart */
     quantity: number;
     /**
-     * Unit price as a string (e.g., "29.99").
-     * Use parseFloat() for calculations.
+     * Snapshot price captured at add-to-cart time as a string (e.g., "29.99").
+     * Stable until the customer accepts a price refresh. Use parseFloat() for
+     * calculations.
      */
     unitPrice: string;
+    /**
+     * Live unit price resolved from the current product/variant. Differs from
+     * `unitPrice` if the merchant changed the price after the item was added.
+     * Display this if you want the customer to see the latest price.
+     */
+    currentUnitPrice: string;
+    /** True iff `currentUnitPrice !== unitPrice`. */
+    priceChanged: boolean;
+    /** `currentUnitPrice - unitPrice` as a Decimal string (negative = cheaper now). */
+    priceDelta: string;
+    priceDirection: 'increased' | 'decreased' | 'unchanged';
+    /** False if the item cannot be purchased right now. Block checkout / show banner. */
+    isAvailable: boolean;
+    /** Why the item is unavailable. `null` when `isAvailable === true`. */
+    unavailableReason: CartItemUnavailableReason | null;
     /**
      * Discount amount applied to this item as a string (from discount rules).
      * Use parseFloat() for calculations.
@@ -1446,6 +1569,27 @@ interface CartItem {
     notes?: string | null;
     /** Optional metadata for this line item */
     metadata?: Record<string, unknown> | null;
+    /**
+     * Per-line modifier breakdown — present when the line was added with
+     * modifier `selections`. Snapshot taken at add-time; immutable to catalog
+     * edits afterward (PRD §5.6.4).
+     */
+    modifiers?: CartItemModifierLine[];
+    /**
+     * Decimal-string total of the modifier deltas applied to this line
+     * (after free-allocation). Present when `modifiers` is non-empty.
+     */
+    modifiersTotal?: string;
+    /**
+     * PRD §15 Q5 — when this cart line is a child of a nested-combo parent
+     * (e.g. the burger inside a "Build Your Combo"), `parentCartItemId`
+     * points at the parent CartItem.id. Absent / null for top-level lines.
+     *
+     * Storefronts can group children visually under their parent in the
+     * cart drawer; the cart subtotal already includes every line in the
+     * tree, so children should NOT be summed twice.
+     */
+    parentCartItemId?: string | null;
     /**
      * Nested product information.
      * Access product details via this object (e.g., item.product.name).
@@ -1539,6 +1683,15 @@ interface Cart {
     items: CartItem[];
     /** Total number of items (sum of quantities) */
     itemCount: number;
+    /**
+     * True if any item has `priceChanged === true`. Use as a single signal to
+     * show a "prices have changed" banner without iterating items.
+     */
+    hasPriceChanges: boolean;
+    /** True if any item has `isAvailable === false`. */
+    hasUnavailableItems: boolean;
+    /** Convenience list of unavailable `CartItem.id`s. */
+    unavailableItemIds: string[];
     /** ISO timestamp when cart expires */
     expiresAt?: string | null;
     /** ISO timestamp when cart was created */
@@ -1558,6 +1711,19 @@ interface AddToCartDto {
     quantity: number;
     notes?: string;
     metadata?: Record<string, unknown>;
+    /**
+     * Modifier-group selections for restaurant / customizable products
+     * (e.g., toppings, sauces, sides). The server validates against effective
+     * group rules and rejects invalid payloads with a `MODIFIER_VALIDATION_FAILED`
+     * envelope (`BrainerceError.errorData`).
+     */
+    selections?: ModifierSelection[];
+    /**
+     * Nested-combo selections keyed by parent `modifierId` — only required when
+     * a picked modifier carries `referencedProductId` and that referenced product
+     * itself has modifier groups. Server enforces depth ≤ 3.
+     */
+    nestedByModifierId?: Record<string, ModifierSelection[]>;
     /**
      * Optional product info for local cart (guest mode).
      * If provided, SDK uses this directly without fetching from API.
@@ -1572,6 +1738,14 @@ interface AddToCartDto {
 }
 interface UpdateCartItemDto {
     quantity: number;
+    /**
+     * Replace the line's modifier selections. Idempotent: server deletes
+     * existing `CartItemModifier` rows and recreates them inside the same
+     * transaction (PRD §7.2.3).
+     */
+    selections?: ModifierSelection[];
+    /** Nested-combo selections (see `AddToCartDto.nestedByModifierId`). */
+    nestedByModifierId?: Record<string, ModifierSelection[]>;
 }
 interface ApplyCouponDto {
     code: string;
@@ -2848,6 +3022,33 @@ interface Category {
         name: string;
         sku?: string;
     }>;
+    /** Sales channels this category is explicitly published to (admin response only). */
+    channelPublishes?: Array<{
+        salesChannel: {
+            id: string;
+            name: string;
+            connectionId: string;
+        };
+        /** @deprecated alias of `salesChannel` — will be removed in SDK 2.0 */
+        connection?: {
+            id: string;
+            name: string;
+            connectionId: string;
+        };
+    }>;
+    /** @deprecated alias of `channelPublishes` — will be removed in SDK 2.0 */
+    vibeCodedPublishes?: Array<{
+        salesChannel: {
+            id: string;
+            name: string;
+            connectionId: string;
+        };
+        connection?: {
+            id: string;
+            name: string;
+            connectionId: string;
+        };
+    }>;
     createdAt: string;
     updatedAt: string;
 }
@@ -2893,6 +3094,33 @@ interface Brand {
         name: string;
         sku?: string;
     }>;
+    /** Sales channels this brand is explicitly published to (admin response only). */
+    channelPublishes?: Array<{
+        salesChannel: {
+            id: string;
+            name: string;
+            connectionId: string;
+        };
+        /** @deprecated alias of `salesChannel` — will be removed in SDK 2.0 */
+        connection?: {
+            id: string;
+            name: string;
+            connectionId: string;
+        };
+    }>;
+    /** @deprecated alias of `channelPublishes` — will be removed in SDK 2.0 */
+    vibeCodedPublishes?: Array<{
+        salesChannel: {
+            id: string;
+            name: string;
+            connectionId: string;
+        };
+        connection?: {
+            id: string;
+            name: string;
+            connectionId: string;
+        };
+    }>;
     createdAt: string;
     updatedAt: string;
 }
@@ -2922,6 +3150,8 @@ interface Tag {
     platformIds?: Record<string, string> | null;
     /** Platforms this tag is published on */
     publishedOn: string[];
+    /** Per-platform mapping config (parity with Category/Brand/MetafieldDefinition). */
+    platformMetadata?: Record<string, Record<string, unknown>> | null;
     isActive: boolean;
     productCount?: number;
     products?: Array<{
@@ -2929,6 +3159,33 @@ interface Tag {
         name: string;
         sku?: string;
     }>;
+    /** Sales channels this tag is explicitly published to (admin response only). */
+    channelPublishes?: Array<{
+        salesChannel: {
+            id: string;
+            name: string;
+            connectionId: string;
+        };
+        /** @deprecated alias of `salesChannel` — will be removed in SDK 2.0 */
+        connection?: {
+            id: string;
+            name: string;
+            connectionId: string;
+        };
+    }>;
+    /** @deprecated alias of `channelPublishes` — will be removed in SDK 2.0 */
+    vibeCodedPublishes?: Array<{
+        salesChannel: {
+            id: string;
+            name: string;
+            connectionId: string;
+        };
+        connection?: {
+            id: string;
+            name: string;
+            connectionId: string;
+        };
+    }>;
     createdAt: string;
     updatedAt: string;
 }
@@ -3193,11 +3450,21 @@ interface UpdateTaxRateDto {
  */
 type MetafieldType = 'TEXT' | 'TEXTAREA' | 'NUMBER' | 'BOOLEAN' | 'DATE' | 'DATETIME' | 'URL' | 'COLOR' | 'DIMENSION' | 'WEIGHT' | 'JSON' | 'IMAGE' | 'GALLERY' | 'SELECT' | 'MULTI_SELECT';
 /**
- * Metafield definition - schema for product metafields
+ * Metafield definition - schema for product metafields.
+ *
+ * Definitions are scoped either to a single store (`storeId` set) or to
+ * the entire account (`storeId === null`). Listing from a store route
+ * returns both — store-scoped first, then account-wide.
+ *
+ * Platform sync state is stored inline (`publishedOn`, `platformMetadata`,
+ * etc.) — same shape as Category / Tag / Brand. The `MetafieldPlatformMapping`
+ * junction was dropped on 2026-04-30.
  */
 interface MetafieldDefinition {
     id: string;
     accountId: string;
+    /** When null, the definition is shared across the account; otherwise it belongs to this store. */
+    storeId: string | null;
     name: string;
     key: string;
     description?: string | null;
@@ -3210,6 +3477,12 @@ interface MetafieldDefinition {
      * individual `ProductCustomizationField` rows when this is set.
      */
     appliesToAllProducts?: boolean;
+    /**
+     * When `true`, the field is exposed in storefront facet filters. Only
+     * meaningful for SELECT / MULTI_SELECT / BOOLEAN types — the backend
+     * rejects setting this on other types.
+     */
+    filterable?: boolean;
     minLength?: number | null;
     maxLength?: number | null;
     minValue?: number | null;
@@ -3218,15 +3491,64 @@ interface MetafieldDefinition {
     defaultValue?: string | null;
     position: number;
     isActive: boolean;
-    mappings?: MetafieldPlatformMapping[];
+    /** Sales channels / platforms where this field is published. */
+    publishedOn: string[];
+    /** External IDs of the metafield definition on each platform. */
+    platformIds?: Record<string, string> | null;
+    /** Per-platform mapping config required for sync. */
+    platformMetadata?: PlatformMetafieldMetadata | null;
+    /** Sync state per platform. */
+    syncStatus?: Record<string, string> | null;
+    /** Last sync timestamp per platform (ISO strings). */
+    lastSyncedAt?: Record<string, string> | null;
+    /** Origin of the definition (e.g. "LOCAL", "SHOPIFY"). */
+    source: string;
     /** Products this definition is explicitly attached to (customer-input only). */
     products?: Array<{
         id: string;
         name: string;
     }>;
+    /** Sales channels this definition is explicitly published to (admin response only). */
+    channelPublishes?: Array<{
+        salesChannel: {
+            id: string;
+            name: string;
+            connectionId: string;
+        };
+        /** @deprecated alias of `salesChannel` — will be removed in SDK 2.0 */
+        connection?: {
+            id: string;
+            name: string;
+            connectionId: string;
+        };
+    }>;
+    /** @deprecated alias of `channelPublishes` — will be removed in SDK 2.0 */
+    vibeCodedPublishes?: Array<{
+        salesChannel: {
+            id: string;
+            name: string;
+            connectionId: string;
+        };
+        connection?: {
+            id: string;
+            name: string;
+            connectionId: string;
+        };
+    }>;
     createdAt: string;
     updatedAt: string;
 }
+/**
+ * Per-platform mapping configuration. Required entry per platform listed in
+ * `publishedOn` for the platform to actually sync.
+ *
+ * Shape per platform:
+ * - `SHOPIFY`:     `{ namespace: string; key: string; type?: string }`
+ * - `WOOCOMMERCE`: `{ key: string }`
+ * - `TIKTOK`:      `{ attributeName: string }`
+ * - `META`:        `{ field: 'custom_label_0' | … | 'custom_label_4' }`
+ */
+type PlatformMetafieldMetadata = Record<string, Record<string, unknown>>;
 /**
  * Public subset of MetafieldDefinition for storefront/vibe-coded use.
  * Does not include admin-only validation fields.
@@ -3244,6 +3566,11 @@ interface PublicMetafieldDefinition {
      * including ones created after the flag was set.
      */
     appliesToAllProducts?: boolean;
+    /**
+     * When true, the storefront should expose this field as a facet filter.
+     * Pair with `getProducts({ metafields: { [key]: [...] } })`.
+     */
+    filterable?: boolean;
     enumValues?: string[];
     minLength?: number | null;
     maxLength?: number | null;
@@ -3271,19 +3598,6 @@ interface ProductCustomizationField {
     defaultValue?: string | null;
     position: number;
 }
-/**
- * Platform mapping for metafield syncing
- */
-interface MetafieldPlatformMapping {
-    id: string;
-    definitionId: string;
-    platform: ConnectorPlatform;
-    namespace: string;
-    key: string;
-    isEnabled: boolean;
-    createdAt: string;
-    updatedAt: string;
-}
 interface CreateMetafieldDefinitionDto {
     name: string;
     key: string;
@@ -3293,6 +3607,11 @@ interface CreateMetafieldDefinitionDto {
     isCustomerInput?: boolean;
     /** When true the field applies to every product in the account. */
     appliesToAllProducts?: boolean;
+    /**
+     * When true, the field is exposed as a storefront facet filter. Backend
+     * rejects this for types other than SELECT / MULTI_SELECT / BOOLEAN.
+     */
+    filterable?: boolean;
     /**
      * Assign the new (customer-input) definition to specific products atomically
      * in the same create call. Only valid when `isCustomerInput` is true.
@@ -3305,6 +3624,33 @@ interface CreateMetafieldDefinitionDto {
     enumValues?: string[];
     defaultValue?: string;
     position?: number;
+    /**
+     * When `true`, create the definition account-wide (`storeId = null`).
+     * Defaults to false — the definition belongs to the store named in the
+     * route's `:storeId` parameter.
+     */
+    accountWide?: boolean;
+    /** Sales channels / platforms where this field is published. */
+    publishedOn?: string[];
+    /**
+     * Per-platform sync configuration. Must contain a key for every platform
+     * listed in `publishedOn`.
+     */
+    platformMetadata?: PlatformMetafieldMetadata;
+    /** Origin of the definition (defaults to "LOCAL"). */
+    source?: string;
+}
+/**
+ * Replace the platform publishing configuration on a definition.
+ * Updates `publishedOn` + `platformMetadata` atomically.
+ */
+interface SetMetafieldPlatformsDto {
+    publishedOn: string[];
+    /**
+     * Per-platform mapping config keyed by platform. Must contain a key for
+     * every platform listed in `publishedOn`. Pass `null` to clear all metadata.
+     */
+    platformMetadata?: PlatformMetafieldMetadata | null;
 }
 interface UpdateMetafieldDefinitionDto {
     name?: string;
@@ -3313,6 +3659,8 @@ interface UpdateMetafieldDefinitionDto {
     required?: boolean;
     isCustomerInput?: boolean;
     appliesToAllProducts?: boolean;
+    /** Toggle storefront filter exposure. See CreateMetafieldDefinitionDto.filterable. */
+    filterable?: boolean;
     minLength?: number | null;
     maxLength?: number | null;
     minValue?: number | null;
@@ -3352,10 +3700,10 @@ interface UpsertProductMetafieldDto {
     variantId?: string;
 }
 /**
- * @deprecated Use StoreRole instead. Account-level team management is deprecated
- * in favor of store-level team management.
+ * @deprecated Use StoreRole instead. Account-level team management is reserved
+ * for billing/account-owner operations only.
  */
-type TeamRole = 'ACCOUNT_OWNER' | 'STORE_MANAGER' | 'ANALYST' | 'INTEGRATION_BOT';
+type TeamRole = 'ACCOUNT_OWNER';
 /**
  * @deprecated Use StoreMember instead.
  */
@@ -3413,7 +3761,7 @@ interface UpdateMemberRoleDto {
 /** Store-level team member role */
 type StoreRole = 'OWNER' | 'MANAGER' | 'STAFF' | 'VIEWER';
 /** Granular store permission */
-type StorePermission = 'VIEW_PRODUCTS' | 'CREATE_PRODUCTS' | 'EDIT_PRODUCTS' | 'DELETE_PRODUCTS' | 'MANAGE_PRODUCT_CATEGORIES' | 'VIEW_ORDERS' | 'UPDATE_ORDER_STATUS' | 'FULFILL_ORDERS' | 'CANCEL_ORDERS' | 'REFUND_ORDERS' | 'VIEW_INVENTORY' | 'UPDATE_INVENTORY' | 'VIEW_CUSTOMERS' | 'EDIT_CUSTOMERS' | 'DELETE_CUSTOMERS' | 'VIEW_ANALYTICS' | 'EXPORT_REPORTS' | 'MANAGE_STORE_SETTINGS' | 'MANAGE_INTEGRATIONS' | 'MANAGE_TEAM' | 'MANAGE_BILLING';
+type StorePermission = 'VIEW_PRODUCTS' | 'CREATE_PRODUCTS' | 'EDIT_PRODUCTS' | 'DELETE_PRODUCTS' | 'MANAGE_PRODUCT_CATEGORIES' | 'VIEW_ORDERS' | 'UPDATE_ORDER_STATUS' | 'FULFILL_ORDERS' | 'CANCEL_ORDERS' | 'REFUND_ORDERS' | 'VIEW_INVENTORY' | 'UPDATE_INVENTORY' | 'VIEW_CUSTOMERS' | 'EDIT_CUSTOMERS' | 'VIEW_ANALYTICS' | 'MANAGE_STORE_SETTINGS' | 'MANAGE_INTEGRATIONS' | 'MANAGE_TEAM' | 'MANAGE_BILLING';
 /** Store team member info */
 interface StoreMember {
     id: string;
@@ -3748,19 +4096,39 @@ interface LockedVariant {
     name?: string | null;
     attributes?: Record<string, string> | null;
 }
+interface CartBundleOfferOfferedProduct {
+    id: string;
+    name: string;
+    slug: string | null;
+    basePrice: string;
+    salePrice: string | null;
+    images: Array<{
+        url: string;
+    }>;
+    type: string;
+    originalPrice: string;
+    discountedPrice: string;
+}
 interface CartBundleOffer {
     id: string;
     name: string;
     description: string | null;
-    sourceProductId: string;
-    bundleProduct: ProductRecommendation;
-    bundleVariantId: string | null;
-    requiresVariantSelection: boolean;
-    lockedVariant?: LockedVariant | null;
+    /** First product in productIds — must be in cart for the bundle to surface. */
+    triggerProductId: string;
+    /**
+     * Full product list for the bundle. Index 0 is the trigger; indices 1..n
+     * are offered together at the discount.
+     */
+    productIds: string[];
+    /**
+     * Products being offered to the customer (productIds[1..] minus those
+     * already in cart). Each item carries the discounted price.
+     */
+    offeredProducts: CartBundleOfferOfferedProduct[];
     discountType: 'PERCENTAGE' | 'FIXED_AMOUNT';
     discountValue: string;
-    originalPrice: string;
-    discountedPrice: string;
+    totalOriginalPrice: string;
+    totalDiscountedPrice: string;
 }
 interface CartBundlesResponse {
     bundles: CartBundleOffer[];
@@ -3925,6 +4293,8 @@ interface ContactFormPublicField {
     }>;
     validation?: ContactFormFieldValidation;
     defaultValue?: string;
+    /** Layout width hint. Render in a CSS grid: FULL = full row, HALF = half row, THIRD = one-third. */
+    width?: 'FULL' | 'HALF' | 'THIRD';
 }
 interface ContactFormPublic {
     id: string;
@@ -3940,6 +4310,268 @@ interface ContactFormSummary {
     name: string;
     isDefault: boolean;
 }
+/**
+ * How many modifiers a customer can pick from a group.
+ *
+ * - `SINGLE`: radio behavior, max 1.
+ * - `MULTIPLE`: checkbox behavior, bounded by `min`/`max`.
+ */
+type ModifierSelectionType = 'SINGLE' | 'MULTIPLE';
+/**
+ * Tie-break rule for which selected modifiers consume the group's free quantity.
+ *
+ * - `EXPENSIVE_FREE`: the priciest picks become free (best for the customer).
+ * - `CHEAPEST_FREE`: the cheapest picks become free (best for the merchant).
+ * - `SELECTION_ORDER`: free is granted by click-order (first-N rule).
+ *
+ * Negative `priceDelta` modifiers never consume free slots regardless of policy.
+ */
+type FreeAllocationPolicy = 'EXPENSIVE_FREE' | 'CHEAPEST_FREE' | 'SELECTION_ORDER';
+/**
+ * A single picker option inside a `ModifierGroup` (e.g., "Olives", "Thick crust").
+ *
+ * **Money fields are strings**: `priceDelta` is a decimal string like `"5.00"`
+ * (negative values such as `"-2.00"` are valid for downsell modifiers, e.g.,
+ * "no bread −2₪"). Use `parseFloat()` for client-side arithmetic.
+ */
+interface Modifier {
+    id: string;
+    name: string;
+    description?: string;
+    /**
+     * Decimal string — `"5.00"`, `"-2.00"`. Never a JSON number.
+     * Per the platform's Decimal-on-the-wire contract (PRD §6.4.1).
+     */
+    priceDelta: string;
+    sku?: string;
+    image?: {
+        url: string;
+        thumbnailUrl?: string;
+        alt?: string;
+    };
+    position: number;
+    /** Pre-checked in the UI on first render. */
+    isDefault: boolean;
+    /** Sold-out toggle: `false` = out of stock, hidden as selectable in storefronts. */
+    available: boolean;
+    /**
+     * Nested-combo target. When present, picking this modifier opens the
+     * referenced product's own modifier groups (depth ≤ 3).
+     */
+    referencedProductId?: string;
+    translations?: Record<string, {
+        name?: string;
+        description?: string;
+    }>;
+    status?: 'active' | 'archived';
+    createdAt?: string;
+    updatedAt?: string;
+}
+/**
+ * A modifier group — the customer-facing block of related options
+ * (e.g., "Toppings", "Bread type"). Effective fields (`min`, `max`,
+ * `freeQuantity`, `required`, `freeAllocationPolicy`, `defaultModifierIds`)
+ * already reflect any per-attachment or per-variant overrides when fetched
+ * via a product context (`GET /products/:id`).
+ *
+ * `internalName` is admin-only and is stripped from public storefront responses
+ * (PRD §5.2 invariant). It surfaces only when fetched with a Clerk JWT or API key.
+ */
+interface ModifierGroup {
+    id: string;
+    /**
+     * Set when fetched in a product context — the `ProductModifierGroup` row id.
+     * Use this to update or detach the attachment without reattaching the group.
+     */
+    attachmentId?: string;
+    /** Customer-facing canonical name. */
+    name: string;
+    /** Admin-only disambiguator; never returned on public storefront responses. */
+    internalName?: string;
+    description?: string;
+    selectionType: ModifierSelectionType;
+    /** Effective minimum after any overrides. */
+    min: number;
+    /** Effective maximum after any overrides; `null` = unlimited. */
+    max?: number | null;
+    /** Effective free quantity. */
+    freeQuantity: number;
+    /** Effective required flag. */
+    required: boolean;
+    freeAllocationPolicy: FreeAllocationPolicy;
+    modifiers: Modifier[];
+    /** Effective default selections. */
+    defaultModifierIds: string[];
+    /**
+     * When fetched in a product context with admin scope: the per-variant overrides
+     * applied to this group on this product. Each entry shadows the group's default
+     * scalar fields when present.
+     */
+    variantOverrides?: Record<string, Partial<{
+        min: number;
+        max: number;
+        freeQuantity: number;
+        required: boolean;
+        defaultModifierIds: string[];
+        freeAllocationPolicy: FreeAllocationPolicy;
+    }>>;
+    translations?: Record<string, {
+        name?: string;
+        description?: string;
+    }>;
+    status?: 'active' | 'archived';
+    position?: number;
+    createdAt?: string;
+    updatedAt?: string;
+}
+/**
+ * Join row connecting a `ModifierGroup` to a `Product` (with optional per-variant overrides).
+ *
+ * Three patterns (PRD §5.4):
+ *  - `variantId` omitted → default attach (applies to all variants).
+ *  - `variantId` set + matching default attach exists → variant override row.
+ *  - `variantId` set + no default attach → variant-only group.
+ *
+ * `null` overrides inherit; any non-null value (including `0` or `false`) wins.
+ */
+interface ProductModifierGroupAttachment {
+    id: string;
+    productId: string;
+    modifierGroupId: string;
+    variantId?: string | null;
+    position: number;
+    minOverride?: number | null;
+    maxOverride?: number | null;
+    freeQuantityOverride?: number | null;
+    requiredOverride?: boolean | null;
+    freeAllocationPolicyOverride?: FreeAllocationPolicy | null;
+    /** Empty array = inherit (PRD rule E); non-empty = override. */
+    defaultModifierIds?: string[];
+    createdAt?: string;
+    updatedAt?: string;
+}
+/**
+ * Customer-side selection payload for cart add/update.
+ * `modifierIds` is in click-order — the resolver may use this for
+ * `SELECTION_ORDER` free-allocation policy.
+ */
+interface ModifierSelection {
+    modifierGroupId: string;
+    modifierIds: string[];
+}
+/**
+ * Per-line modifier breakdown surfaced on `CartItem` and `OrderItem`
+ * once the cart line includes selections.
+ */
+interface CartItemModifierLine {
+    modifierId: string;
+    /** Snapshot of the modifier name at the time the line was added. */
+    name: string;
+    /** Decimal string snapshot of the priceDelta at the time the line was added. */
+    priceDelta: string;
+    /** True if this modifier consumed one of the group's free slots. */
+    freeApplied: boolean;
+}
+/** Query parameters for `listModifierGroups`. */
+interface ListModifierGroupsParams {
+    [key: string]: string | number | undefined;
+    page?: number;
+    limit?: number;
+    /** Substring match against `name` and `internalName`. */
+    search?: string;
+    status?: 'active' | 'archived';
+}
+interface CreateModifierGroupInput {
+    name: string;
+    internalName?: string;
+    description?: string;
+    translations?: Record<string, {
+        name?: string;
+        description?: string;
+    }>;
+    selectionType?: ModifierSelectionType;
+    minSelections?: number;
+    /** `null` = unlimited. */
+    maxSelections?: number | null;
+    freeQuantity?: number;
+    required?: boolean;
+    freeAllocationPolicy?: FreeAllocationPolicy;
+    /** Default position hint for new product attachments. Per-attach value always wins. */
+    position?: number;
+}
+interface UpdateModifierGroupInput extends Partial<CreateModifierGroupInput> {
+    status?: 'active' | 'archived';
+}
+interface CreateModifierInput {
+    name: string;
+    description?: string;
+    translations?: Record<string, {
+        name?: string;
+        description?: string;
+    }>;
+    /**
+     * Decimal string. Negative values are accepted for downsell modifiers
+     * (e.g., `"-2.00"`); the server still enforces a `unitPrice >= 0` floor and
+     * rejects negative deltas combined with `referencedProductId`.
+     */
+    priceDelta: string;
+    sku?: string;
+    image?: {
+        url: string;
+        thumbnailUrl?: string;
+        alt?: string;
+    };
+    position?: number;
+    isDefault?: boolean;
+    available?: boolean;
+    referencedProductId?: string;
+}
+interface UpdateModifierInput extends Partial<CreateModifierInput> {
+    status?: 'active' | 'archived';
+}
+interface AttachModifierGroupInput {
+    modifierGroupId: string;
+    /** Specific variant for a per-variant override. Omit for a default attach. */
+    variantId?: string;
+    position?: number;
+    /** `null` = inherit; any value (incl. `0`) overrides. */
+    minOverride?: number | null;
+    maxOverride?: number | null;
+    freeQuantityOverride?: number | null;
+    /** `null` = inherit; any value (incl. `false`) overrides. */
+    requiredOverride?: boolean | null;
+    freeAllocationPolicyOverride?: FreeAllocationPolicy | null;
+    /** Empty array = inherit (PRD rule E); non-empty array = override. */
+    defaultModifierIds?: string[];
+}
+/**
+ * Update DTO for an existing attachment.
+ *
+ * `modifierGroupId` and `variantId` are immutable — they form the attachment's
+ * identity (PRD §5.4 partial unique index). To swap a group on a product, detach
+ * and re-attach.
+ */
+type UpdateAttachmentInput = Partial<Omit<AttachModifierGroupInput, 'modifierGroupId' | 'variantId'>>;
+/**
+ * Stable error codes returned in the structured `MODIFIER_VALIDATION_FAILED`
+ * envelope when a cart add/update payload fails server-side validation.
+ *
+ * `MODIFIER_PRICE_FLOOR_VIOLATED` is also wrapped in this envelope (Phase 1.5
+ * Slice C) — it fires when modifier downsells push the unit price below `0`.
+ */
+type ModifierValidationCode = 'REQUIRED_GROUP_MISSING' | 'MIN_SELECTIONS_NOT_MET' | 'MAX_SELECTIONS_EXCEEDED' | 'SINGLE_GROUP_MULTIPLE_PICKS' | 'UNKNOWN_MODIFIER' | 'UNKNOWN_GROUP' | 'MODIFIER_DISABLED_FOR_VARIANT' | 'MODIFIER_NOT_AVAILABLE' | 'NESTED_DEPTH_EXCEEDED' | 'NESTED_REQUIRES_PRODUCT_REF' | 'INVALID_PRICE_DELTA' | 'MODIFIER_PRICE_FLOOR_VIOLATED';
+/**
+ * Single validation issue inside the `MODIFIER_VALIDATION_FAILED` envelope.
+ */
+interface ModifierValidationError {
+    code: ModifierValidationCode;
+    /** Human-readable message — safe to show users. */
+    message: string;
+    /** Group the error belongs to (when applicable). */
+    modifierGroupId?: string;
+    /** Modifier the error belongs to (when applicable). */
+    modifierId?: string;
+}
 interface BrainerceApiError {
     statusCode: number;
     message: string;
@@ -4035,7 +4667,11 @@ declare class BrainerceClient {
      */
     private withPaginatedGuards;
     /**
-     * Check if client is in vibe-coded mode (using connectionId)
+     * Check if client is in sales-channel mode (using salesChannelId / legacy connectionId).
+     */
+    isSalesChannelMode(): boolean;
+    /**
+     * @deprecated Use `isSalesChannelMode()` instead. Kept as a backwards-compatible alias.
      */
     isVibeCodedMode(): boolean;
     /**
@@ -4770,6 +5406,50 @@ declare class BrainerceClient {
      * Get a customer by email
      */
     getCustomerByEmail(email: string): Promise<Customer | null>;
+    /**
+     * List a customer's saved payment methods (vaulted cards).
+     *
+     * Returns display-only metadata — last4, brand, expiry, default flag,
+     * status. The underlying provider token is encrypted at rest and
+     * NEVER returned through this API.
+     *
+     * Apps mode requires `customers:read` and `payments:read` scopes.
+     *
+     * @param storeId - The store this customer belongs to
+     * @param customerId - The customer's ID
+     * @returns Array of saved payment methods
+     *
+     * @example
+     * ```typescript
+     * const methods = await client.listSavedPaymentMethods(storeId, customerId);
+     * methods.forEach((m) => {
+     *   console.log(`${m.brand} ending in ${m.last4} (expires ${m.expMonth}/${m.expYear})`);
+     * });
+     * ```
+     */
+    listSavedPaymentMethods(storeId: string, customerId: string): Promise<SavedPaymentMethodSummary[]>;
+    /**
+     * Remove a customer's saved payment method.
+     *
+     * Hard-deletes the row. The provider may still hold the underlying
+     * token internally — we don't issue a delete-at-provider call because
+     * not every provider supports it. From the platform's perspective the
+     * token is gone; subsequent charges will fail.
+     *
+     * Apps mode requires `customers:write` scope.
+     *
+     * @param storeId - The store this customer belongs to
+     * @param customerId - The customer's ID
+     * @param paymentMethodId - The saved payment method ID to remove
+     *
+     * @example
+     * ```typescript
+     * await client.removeSavedPaymentMethod(storeId, customerId, methodId);
+     * ```
+     */
+    removeSavedPaymentMethod(storeId: string, customerId: string, paymentMethodId: string): Promise<{
+        success: true;
+    }>;
     /**
      * Login an existing customer (returns JWT token)
      * Works in vibe-coded, storefront, and admin mode
@@ -5249,6 +5929,42 @@ declare class BrainerceClient {
      * ```
      */
     removeCoupon(cartId: string): Promise<Cart>;
+    /**
+     * Recalculate cart totals against current product/variant prices and
+     * discount rules. Idempotent — does NOT mutate the per-item snapshot
+     * `unitPrice`. The returned cart's `hasPriceChanges` / `hasUnavailableItems`
+     * flags reflect the live state. Call this on cart load if you want to
+     * surface drift to the customer before they reach checkout.
+     *
+     * @example
+     * ```typescript
+     * const cart = await client.recalculateCart('cart_123');
+     * if (cart.hasPriceChanges) {
+     *   // show "prices have changed" banner
+     * }
+     * ```
+     */
+    recalculateCart(cartId: string): Promise<Cart>;
+    /**
+     * Refresh per-item `unitPrice` snapshots to current live prices. Use this
+     * after the customer accepts new prices in the drift-reconfirm flow. The
+     * subsequent `createCheckout` call will then succeed (it would otherwise
+     * throw `PRICE_DRIFT`).
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   await client.createCheckout(cartId);
+     * } catch (err) {
+     *   if (err.code === 'PRICE_DRIFT') {
+     *     // ask user to confirm new prices, then:
+     *     await client.refreshCartSnapshots(cartId);
+     *     await client.createCheckout(cartId);
+     *   }
+     * }
+     * ```
+     */
+    refreshCartSnapshots(cartId: string): Promise<Cart>;
     /**
      * Link a cart to the currently logged-in customer.
      * Use this after customer logs in to associate their guest cart with their account.
@@ -5383,7 +6099,8 @@ declare class BrainerceClient {
      * ```typescript
      * const { bundles } = await client.getCartBundles('cart_123');
      * bundles.forEach(b => {
-     *   console.log(`Add ${b.bundleProduct.name} and save! Was ${b.originalPrice}, now ${b.discountedPrice}`);
+     *   const names = b.offeredProducts.map(p => p.name).join(', ');
+     *   console.log(`Add ${names} and save! Was ${b.totalOriginalPrice}, now ${b.totalDiscountedPrice}`);
      * });
      * ```
      */
@@ -5413,23 +6130,27 @@ declare class BrainerceClient {
      */
     removeOrderBump(cartId: string, bumpConfigId: string): Promise<Cart>;
     /**
-     * Add a bundle offer product to the cart with its discount applied.
+     * Accept an N-product bundle offer: every offered product not yet in cart
+     * is added with the bundle discount applied.
      *
      * @param cartId - Cart ID
      * @param bundleOfferId - Bundle offer ID
-     * @param variantId - Optional variant ID (required when bundle product has variants and no admin-locked variant)
+     * @param variantSelections - Optional map of `productId → variantId` for offered products with variants
      * @returns Updated cart
      *
      * @example
      * ```typescript
      * const { bundles } = await client.getCartBundles('cart_123');
-     * // Simple product or locked variant:
-     * const cart = await client.addBundleToCart('cart_123', bundles[0].id);
-     * // Product with variants (customer selects):
-     * const cart = await client.addBundleToCart('cart_123', bundles[0].id, selectedVariantId);
+     * const bundle = bundles[0];
+     * // Simple products only:
+     * await client.addBundleToCart('cart_123', bundle.id);
+     * // Some offered products have variants:
+     * await client.addBundleToCart('cart_123', bundle.id, {
+     *   [variantProductId]: selectedVariantId,
+     * });
      * ```
      */
-    addBundleToCart(cartId: string, bundleOfferId: string, variantId?: string): Promise<Cart>;
+    addBundleToCart(cartId: string, bundleOfferId: string, variantSelections?: Record<string, string>): Promise<Cart>;
     /**
      * Remove a bundle offer product from the cart.
      *
@@ -5541,6 +6262,10 @@ declare class BrainerceClient {
         variantId?: string;
         quantity: number;
         metadata?: Record<string, unknown>;
+        /** Modifier-group selections (PRD §7.3 / §8.4). */
+        selections?: ModifierSelection[];
+        /** Nested-combo selections keyed by parent modifierId. */
+        nestedByModifierId?: Record<string, ModifierSelection[]>;
     }): Promise<Cart>;
     /**
      * Smart get cart - returns the current cart (server-side for both guests and logged-in users)
@@ -5963,6 +6688,21 @@ declare class BrainerceClient {
     createPaymentIntent(checkoutId: string, options?: {
         successUrl?: string;
         cancelUrl?: string;
+        /**
+         * Per-checkout opt-in to vault the card for off-session reuse.
+         * Set to `true` when the customer ticked a "save card for next
+         * time" checkbox. Only honored when the checkout has a known
+         * `customerId` (logged-in customers, not guests). The platform
+         * forwards this to the underlying payment provider; providers
+         * that don't support tokenization (e.g. Grow today) silently
+         * ignore it.
+         *
+         * After a successful charge with `saveCard: true`, the saved
+         * card appears in `customers.listSavedPaymentMethods()` and can
+         * be charged off-session via the dashboard / future
+         * subscription features.
+         */
+        saveCard?: boolean;
     }): Promise<PaymentIntent>;
     /**
      * Get payment status for a checkout.
@@ -6778,6 +7518,133 @@ declare class BrainerceClient {
      * Requires Admin mode (apiKey)
      */
     deleteAttributeOption(attributeId: string, optionId: string): Promise<void>;
+    /**
+     * List modifier groups in a store, paginated.
+     * Requires Admin mode (apiKey).
+     *
+     * @example
+     * ```typescript
+     * const groups = await client.listModifierGroups('store_123', {
+     *   page: 1,
+     *   limit: 20,
+     *   search: 'pizza',
+     *   status: 'active',
+     * });
+     * ```
+     */
+    listModifierGroups(storeId: string, params?: ListModifierGroupsParams): Promise<PaginatedResponse<ModifierGroup>>;
+    /**
+     * Fetch a single modifier group (with its modifiers).
+     * Requires Admin mode (apiKey).
+     *
+     * Admin fetches include `internalName`; storefront responses strip it
+     * (PRD §5.2 invariant).
+     */
+    getModifierGroup(storeId: string, groupId: string): Promise<ModifierGroup>;
+    /**
+     * Create a modifier group. Modifiers themselves are created separately via
+     * `createModifier(storeId, groupId, …)`.
+     * Requires Admin mode (apiKey).
+     *
+     * @example
+     * ```typescript
+     * const group = await client.createModifierGroup('store_123', {
+     *   name: 'Toppings',
+     *   internalName: 'Pizza toppings',
+     *   selectionType: 'MULTIPLE',
+     *   minSelections: 0,
+     *   maxSelections: 8,
+     *   freeQuantity: 3,
+     *   freeAllocationPolicy: 'EXPENSIVE_FREE',
+     * });
+     * ```
+     */
+    createModifierGroup(storeId: string, data: CreateModifierGroupInput): Promise<ModifierGroup>;
+    /**
+     * Update a modifier group's metadata or selection rules. Pass `status: 'archived'`
+     * to soft-delete (the group becomes hidden from product attachments).
+     * Requires Admin mode (apiKey).
+     */
+    updateModifierGroup(storeId: string, groupId: string, data: UpdateModifierGroupInput): Promise<ModifierGroup>;
+    /**
+     * Hard-delete a modifier group. Server rejects deletion when the group is
+     * still attached to any product (detach the attachments first, or use
+     * `updateModifierGroup(..., { status: 'archived' })` to keep the row).
+     * Requires Admin mode (apiKey).
+     */
+    deleteModifierGroup(storeId: string, groupId: string): Promise<void>;
+    /**
+     * Create a modifier inside a group (e.g., "Olives" inside the "Toppings" group).
+     * Requires Admin mode (apiKey).
+     *
+     * `priceDelta` is a decimal string. Negatives are accepted for downsell
+     * modifiers (e.g., `"-2.00"` for "no bread"); the server still enforces
+     * `unitPrice >= 0` at cart-line resolution and rejects negative deltas
+     * combined with a `referencedProductId`.
+     *
+     * @example
+     * ```typescript
+     * const olives = await client.createModifier('store_123', 'mg_toppings', {
+     *   name: 'Olives',
+     *   priceDelta: '5.00',
+     *   isDefault: false,
+     *   available: true,
+     * });
+     * ```
+     */
+    createModifier(storeId: string, groupId: string, data: CreateModifierInput): Promise<Modifier>;
+    /**
+     * Update a modifier. Pass `status: 'archived'` to soft-delete.
+     * Requires Admin mode (apiKey).
+     */
+    updateModifier(storeId: string, groupId: string, modifierId: string, data: UpdateModifierInput): Promise<Modifier>;
+    /**
+     * Hard-delete a modifier. Use `updateModifier(..., { status: 'archived' })`
+     * if existing line items / order snapshots reference it.
+     * Requires Admin mode (apiKey).
+     */
+    deleteModifier(storeId: string, groupId: string, modifierId: string): Promise<void>;
+    /**
+     * Flip the sold-out toggle on a modifier. Operational endpoint kept separate
+     * from `updateModifier` because the daily ops bar is intentionally lower
+     * (PRD §7.1 — STAFF role once the granular `TOGGLE_MODIFIER_AVAILABILITY`
+     * permission ships).
+     * Requires Admin mode (apiKey).
+     *
+     * @example
+     * ```typescript
+     * // Mark the egg modifier as out of stock during a busy lunch service
+     * await client.toggleModifierAvailability('store_123', 'mg_toppings', 'm_egg', false);
+     * ```
+     */
+    toggleModifierAvailability(storeId: string, groupId: string, modifierId: string, available: boolean): Promise<Modifier>;
+    /**
+     * Attach a modifier group to a product. Three patterns (PRD §5.4):
+     *
+     *   - `variantId` omitted → default attach (applies to all variants).
+     *   - `variantId` set + matching default attach already exists → variant override row.
+     *   - `variantId` set + no default attach → variant-only group.
+     *
+     * Override fields use `null` to mean inherit; any non-null value (including
+     * `0` or `false`) wins. The disable-for-variant convention is `maxOverride: 0` —
+     * the resolver returns the group with `effectiveMax=0` and the validator
+     * silently skips it on cart add.
+     *
+     * Requires Admin mode (apiKey).
+     */
+    attachModifierGroup(storeId: string, productId: string, data: AttachModifierGroupInput): Promise<ProductModifierGroupAttachment>;
+    /**
+     * Update an existing attachment's overrides or position. The `modifierGroupId`
+     * and `variantId` are immutable — to swap groups or move between default /
+     * per-variant rows, detach and re-attach.
+     * Requires Admin mode (apiKey).
+     */
+    updateAttachment(storeId: string, productId: string, attachmentId: string, data: UpdateAttachmentInput): Promise<ProductModifierGroupAttachment>;
+    /**
+     * Detach a modifier group from a product (or remove a per-variant override row).
+     * Requires Admin mode (apiKey).
+     */
+    detachModifierGroup(storeId: string, productId: string, attachmentId: string): Promise<void>;
     /**
      * List all shipping zones for the store with pagination
      * Requires Admin mode (apiKey)
@@ -6922,6 +7789,64 @@ declare class BrainerceClient {
      * Requires Admin mode (apiKey)
      */
     deleteMetafieldDefinition(definitionId: string): Promise<void>;
+    /**
+     * Replace the platform publishing configuration on a metafield definition.
+     * `publishedOn` is the source of truth for which sales channels the field
+     * appears on; `platformMetadata` carries the per-platform mapping config
+     * required for sync.
+     *
+     * Requires Admin mode (apiKey).
+     *
+     * @example
+     * ```typescript
+     * await client.setMetafieldPlatforms('def_123', {
+     *   publishedOn: ['SHOPIFY', 'WOOCOMMERCE'],
+     *   platformMetadata: {
+     *     SHOPIFY: { namespace: 'custom', key: 'warranty' },
+     *     WOOCOMMERCE: { key: '_warranty_info' },
+     *   },
+     * });
+     * ```
+     */
+    setMetafieldPlatforms(definitionId: string, data: SetMetafieldPlatformsDto): Promise<MetafieldDefinition>;
+    /**
+     * Publish a metafield definition to a vibe-coded site (admin mode).
+     * @example
+     * ```typescript
+     * await client.publishMetafieldDefinitionToVibeCodedSite('def_123', 'conn_456');
+     * ```
+     */
+    publishMetafieldDefinitionToVibeCodedSite(definitionId: string, vibeCodedConnectionId: string): Promise<{
+        success: boolean;
+    }>;
+    /** Unpublish a metafield definition from a vibe-coded site (admin mode). */
+    unpublishMetafieldDefinitionFromVibeCodedSite(definitionId: string, vibeCodedConnectionId: string): Promise<{
+        success: boolean;
+    }>;
+    /** Publish a category to a vibe-coded site (admin mode). */
+    publishCategoryToVibeCodedSite(categoryId: string, vibeCodedConnectionId: string): Promise<{
+        success: boolean;
+    }>;
+    /** Unpublish a category from a vibe-coded site (admin mode). */
+    unpublishCategoryFromVibeCodedSite(categoryId: string, vibeCodedConnectionId: string): Promise<{
+        success: boolean;
+    }>;
+    /** Publish a tag to a vibe-coded site (admin mode). */
+    publishTagToVibeCodedSite(tagId: string, vibeCodedConnectionId: string): Promise<{
+        success: boolean;
+    }>;
+    /** Unpublish a tag from a vibe-coded site (admin mode). */
+    unpublishTagFromVibeCodedSite(tagId: string, vibeCodedConnectionId: string): Promise<{
+        success: boolean;
+    }>;
+    /** Publish a brand to a vibe-coded site (admin mode). */
+    publishBrandToVibeCodedSite(brandId: string, vibeCodedConnectionId: string): Promise<{
+        success: boolean;
+    }>;
+    /** Unpublish a brand from a vibe-coded site (admin mode). */
+    unpublishBrandFromVibeCodedSite(brandId: string, vibeCodedConnectionId: string): Promise<{
+        success: boolean;
+    }>;
     /**
      * Replace the list of products a (customer-input) metafield definition is
      * attached to. Diff-scoped: only rows for this definition are touched, so
@@ -7331,4 +8256,33 @@ declare function enableDevGuards(options?: {
     force?: boolean;
 }): void;
 
-export { type AddToCartDto, type AppliedDiscount, type ApplyCouponDto, 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 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 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 CreateCouponDto, type CreateCustomApiDto, type CreateCustomerDto, type CreateEmailTemplateDto as CreateEmailTemplateInput, type CreateGuestOrderDto, type CreateInquiryInput, type CreateInquiryResponse, type CreateMetafieldDefinitionDto as CreateMetafieldDefinitionInput, 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 FormatPriceOptions, type FulfillOrderDto, type GuestCheckoutStartResponse, type GuestOrderResponse, type InsufficientStockError, type InventoryInfo, type InventoryReservationStrategy, type InventorySyncStatus, type InventoryTrackingMode, type InvitationStatus, type InviteMemberDto as InviteMemberInput, type InviteStoreMemberDto as InviteStoreMemberInput, type LocalCart, type LocalCartItem, type LockedVariant, type MergeCartsDto, type MetafieldConflict, type MetafieldConflictResolution, type MetafieldDefinition, type MetafieldPlatformMapping, type MetafieldType, 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 PaginatedResponse, type PaymentClientSdk, type PaymentConfig, type PaymentIntent, type PaymentProvider, type PaymentProviderConfig, type PaymentProvidersConfig, type PaymentStatus, type PickupLocation, type PlatformCouponCapabilities, type PreviewEmailTemplateDto as PreviewEmailTemplateInput, type Product, type ProductAttributeInput, type ProductAvailability, type ProductCustomizationField, type ProductDiscount, type ProductDiscountBadge, type ProductImage, type ProductMetafield, type ProductMetafieldValue, type ProductQueryParams, type ProductRecommendation, type ProductRecommendationsResponse, type ProductRelationType, type ProductSuggestion, type ProductVariant, type PublicMetafieldDefinition, type PublishProductResponse, type RecommendationVariant, type ReconcileInventoryResponse, type Refund, type RefundLineItem, type RefundLineItemResponse, type RefundType, type RegisterCustomerDto, type ReservationInfo, type ResolveMetafieldConflictDto as ResolveMetafieldConflictInput, type ResolveSyncConflictDto as ResolveSyncConflictInput, SDK_VERSION, type SearchSuggestions, type SelectPickupLocationDto, type SelectShippingMethodDto, type SendInvoiceDto, type SessionCartRef, type SetBillingAddressDto, type SetCheckoutCustomFieldsDto, type SetCheckoutCustomerDto, type SetDefinitionProductsDto as SetDefinitionProductsInput, 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 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 UpdateAttributeDto as UpdateAttributeInput, type UpdateAttributeOptionDto as UpdateAttributeOptionInput, type UpdateBrandDto as UpdateBrandInput, type UpdateCartItemDto, type UpdateCategoryDto as UpdateCategoryInput, 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 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, enableDevGuards, formatPrice, getCartItemImage, getCartItemName, getCartTotals, getDescriptionContent, formatPrice as getPriceDisplay, getProductCustomizationFields, getProductMetafield, getProductMetafieldValue, getProductMetafieldsByType, getProductPrice, getProductPriceInfo, getProductSwatches, getStockStatus, getVariantOptions, getVariantPrice, isCouponApplicableToProduct, isHtmlDescription, isWebhookEventType, parseWebhookEvent, verifyWebhook };
+interface PaymentUrlOptions {
+    /**
+     * Additional hostnames to allow (matches `host` exactly OR
+     * `*.host`). Use for custom self-hosted payment providers.
+     * Cannot remove entries from the platform default list.
+     */
+    extraHosts?: readonly string[];
+    /**
+     * Allow `http://localhost` and `http://127.0.0.1` so a local dev
+     * storefront can iframe a local backend embed proxy. Off by default —
+     * callers running in a known dev context should pass `true` explicitly.
+     */
+    allowLocalhost?: boolean;
+}
+/**
+ * Validate that a URL points to a known payment-provider host (or
+ * platform-hosted embed). Returns `false` for any malformed input,
+ * non-https URL (except localhost when explicitly allowed), or unknown host.
+ */
+declare function isAllowedPaymentUrl(url: string, options?: PaymentUrlOptions): boolean;
+/**
+ * Navigate the browser to a payment URL after validating it against the
+ * allowlist. Throws synchronously on a disallowed URL so the caller can
+ * surface a localized error instead of leaking the raw URL.
+ *
+ * No-op outside a browser environment.
+ */
+declare function safePaymentRedirect(url: string, options?: PaymentUrlOptions): void;
+
+export { type AddToCartDto, 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 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 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 FormatPriceOptions, type FreeAllocationPolicy, type FulfillOrderDto, type GuestCheckoutStartResponse, type GuestOrderResponse, 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 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, type RecommendationVariant, type ReconcileInventoryResponse, type Refund, type RefundLineItem, type RefundLineItemResponse, type RefundType, type RegisterCustomerDto, type ReservationInfo, type ResolveMetafieldConflictDto as ResolveMetafieldConflictInput, type ResolveSyncConflictDto as ResolveSyncConflictInput, 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 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 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, enableDevGuards, formatPrice, getCartItemImage, getCartItemName, getCartTotals, getDescriptionContent, formatPrice as getPriceDisplay, getProductCustomizationFields, getProductMetafield, getProductMetafieldValue, getProductMetafieldsByType, getProductPrice, getProductPriceInfo, getProductSwatches, getStockStatus, getVariantOptions, getVariantPrice, isAllowedPaymentUrl, isCouponApplicableToProduct, isHtmlDescription, isWebhookEventType, parseWebhookEvent, safePaymentRedirect, verifyWebhook };