brainerce 1.38.0 → 1.41.0

package/README.md

@@ -400,7 +400,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';
@@ -1526,10 +1526,19 @@ fields.forEach((field) => {
   // field.required: whether customer must fill this in
   // field.minLength, field.maxLength: validation for text fields
   // field.minValue, field.maxValue: validation for number fields
-  // field.enumValues: allowed options for dropdown fields
+  // field.enumValues: CustomizationFieldOption[] for SELECT/MULTI_SELECT
+  //   each option: { label: string, value: string, swatchColor?: string, swatchImageUrl?: string }
+  //   use option.value for metadata submission, option.label for display
   // field.defaultValue: default value to pre-fill
 });
 
+// Render SELECT options using label/value (not string[] anymore):
+for (const option of field.enumValues ?? []) {
+  // option.label → show to user (e.g. "Gold")
+  // option.value → submit in metadata (e.g. "gold")
+  // option.swatchColor → hex color for color swatch UI, if set
+}
+
 // Customer fills in values, then add to cart with metadata
 await client.addToCart(cartId, {
   productId: product.id,
@@ -1537,10 +1546,23 @@ await client.addToCart(cartId, {
   metadata: {
     cake_text: 'Happy Birthday!', // TEXT field
     font_color: '#FF0000', // COLOR field
+    frame_color: 'gold', // SELECT — use option.value
   },
 });
 ```
 
+**Display customizations in cart/checkout — no extra API call needed:**
+
+`CartItem` and `CheckoutLineItem` both include a `customizations` object with resolved labels. Use it directly — no need to call `getProduct()` per item.
+
+```typescript
+// Works for CartItem, CheckoutLineItem, and OrderItem — same shape
+const summary = Object.values(item.customizations ?? {})
+  .map(c => `${c.label}: ${Array.isArray(c.value) ? c.value.join(', ') : c.value}`)
+  .join(' | ');
+// e.g. "Frame color: Gold | Add-ons: Gift wrap, Engraving"
+```
+
 **For IMAGE/GALLERY fields**, upload the file first:
 
 ```typescript
@@ -2353,7 +2375,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();
@@ -2369,7 +2400,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',
@@ -2378,12 +2412,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>;
@@ -3402,6 +3444,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.
 
 ---
@@ -3550,6 +3594,26 @@ await client.createZoneShippingRate('zone_id', {
 });
 ```
 
+### App Store Shipping (Shippo)
+
+Once a merchant installs the Shippo app from the Brainerce App Store and connects their own
+Shippo account, live carrier rates appear automatically at checkout. Billing goes directly
+to the merchant's Shippo account.
+
+```typescript
+// After an order is placed, purchase a shipping label:
+const label = await admin.createShippingLabel(orderId, {
+  shippoRateObjectId: 'rate_8f123456789abcdef', // Shippo rate.object_id from checkout rates
+});
+
+console.log(label.labelUrl);       // PDF label URL for printing
+console.log(label.trackingNumber); // Auto-populated on the order
+console.log(label.carrier);        // e.g. 'USPS', 'UPS', 'FedEx'
+```
+
+The `trackingNumber` is stored on the `Order` automatically — customers see it in their
+order history without any extra integration work.
+
 ### Tax Configuration
 
 `rate` is a **whole percentage** (`7.25` = 7.25%, not `0.0725`). A rate may target

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;
@@ -256,13 +282,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;
@@ -1064,7 +1097,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 +1118,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[];
 }
@@ -1806,6 +1853,20 @@ interface CartItem {
     notes?: string | null;
     /** Optional metadata for this line item */
     metadata?: Record<string, unknown> | null;
+    /**
+     * Resolved customer input field values with merchant-defined labels.
+     * Mirrors `OrderItem.customizations` — same shape, live (not order-frozen).
+     * Present only when the item has at least one customization value set.
+     *
+     * @example
+     * // Display "Color: Silver / Size: 45" without an extra getProduct() call:
+     * Object.entries(item.customizations ?? {}).map(([, c]) => `${c.label}: ${c.value}`)
+     */
+    customizations?: Record<string, {
+        label: string;
+        value: string | string[];
+        type: string;
+    }>;
     /**
      * Per-line modifier breakdown — present when the line was added with
      * modifier `selections`. Snapshot taken at add-time; immutable to catalog
@@ -2326,6 +2387,20 @@ interface CheckoutLineItem {
     notes?: string | null;
     /** Custom metadata including customer input field values */
     metadata?: Record<string, unknown> | null;
+    /**
+     * Resolved customer input field values with merchant-defined labels.
+     * Mirrors `OrderItem.customizations` — same shape, live (not order-frozen).
+     * Present only when the item has at least one customization value set.
+     *
+     * @example
+     * // Render "Color: Silver / Ring size: 45" in your checkout summary:
+     * Object.entries(item.customizations ?? {}).map(([, c]) => `${c.label}: ${c.value}`)
+     */
+    customizations?: Record<string, {
+        label: string;
+        value: string | string[];
+        type: string;
+    }>;
 }
 /**
  * Represents an available shipping rate/method for checkout.
@@ -3070,6 +3145,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;
@@ -3085,8 +3172,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;
 }
@@ -3983,7 +4088,8 @@ interface MetafieldDefinition {
     maxLength?: number | null;
     minValue?: number | null;
     maxValue?: number | null;
-    enumValues?: string[] | null;
+    /** Allowed values for SELECT / MULTI_SELECT fields, with optional swatch metadata. */
+    enumValues?: CustomizationFieldOption[] | null;
     defaultValue?: string | null;
     position: number;
     isActive: boolean;
@@ -4067,7 +4173,8 @@ interface PublicMetafieldDefinition {
      * Pair with `getProducts({ metafields: { [key]: [...] } })`.
      */
     filterable?: boolean;
-    enumValues?: string[];
+    /** Allowed values for SELECT / MULTI_SELECT fields, with optional swatch metadata. */
+    enumValues?: CustomizationFieldOption[];
     minLength?: number | null;
     maxLength?: number | null;
     minValue?: number | null;
@@ -4075,6 +4182,20 @@ interface PublicMetafieldDefinition {
     defaultValue?: string | null;
     position: number;
 }
+/**
+ * A single selectable option for a SELECT or MULTI_SELECT customization field.
+ * Legacy string-only `enumValues` arrays are automatically promoted to this shape.
+ */
+interface CustomizationFieldOption {
+    /** Human-readable label shown in the storefront UI (e.g., "Rose Gold"). */
+    label: string;
+    /** Value stored in `CartItem.metadata` and carried through to `OrderItem.customizations`. */
+    value: string;
+    /** Optional CSS hex color for rendering a color swatch (e.g., "#B76E79"). */
+    swatchColor?: string | null;
+    /** Optional image URL for rendering a texture/image swatch. */
+    swatchImageUrl?: string | null;
+}
 /**
  * Customer-facing input field definition assigned to a specific product.
  * Returned in product responses to tell the storefront which input fields to render.
@@ -4090,7 +4211,11 @@ interface ProductCustomizationField {
     maxLength?: number | null;
     minValue?: number | null;
     maxValue?: number | null;
-    enumValues?: string[];
+    /**
+     * Allowed values for SELECT / MULTI_SELECT fields.
+     * Each option includes a label, value, and optional swatch color/image.
+     */
+    enumValues?: CustomizationFieldOption[];
     defaultValue?: string | null;
     position: number;
 }
@@ -5379,6 +5504,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;
@@ -5548,6 +5675,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
@@ -5972,6 +6113,29 @@ declare class BrainerceClient {
      * ```
      */
     updateOrderShipping(orderId: string, data: UpdateOrderShippingDto): Promise<Order>;
+    /**
+     * Create a shipping label for an order via the installed App Store shipping app.
+     * Pass the rate ID returned from checkout rate shopping. Billing goes directly
+     * to the merchant's carrier account — Brainerce is not a billing intermediary.
+     *
+     * @example
+     * ```typescript
+     * const label = await client.createShippingLabel('order_abc', {
+     *   rateId: 'rate_8f123456789abcdef',
+     * });
+     * console.log('Label URL:', label.labelUrl);
+     * console.log('Tracking:', label.trackingNumber);
+     * ```
+     */
+    createShippingLabel(orderId: string, data: {
+        rateId: string;
+        parcel?: Record<string, string>;
+    }): Promise<{
+        shipmentId: string;
+        labelUrl: string;
+        trackingNumber: string;
+        carrier: string;
+    }>;
     /**
      * Cancel an order
      * Works for Shopify and WooCommerce orders that haven't been fulfilled
@@ -7859,6 +8023,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();
@@ -7868,27 +8040,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
+     *   }
      * }
      * ```
      */
@@ -9543,7 +9709,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.41.0";
 
 /**
  * Verify a webhook signature from Brainerce

package/dist/index.d.ts

@@ -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;
@@ -256,13 +282,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;
@@ -1064,7 +1097,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 +1118,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[];
 }
@@ -1806,6 +1853,20 @@ interface CartItem {
     notes?: string | null;
     /** Optional metadata for this line item */
     metadata?: Record<string, unknown> | null;
+    /**
+     * Resolved customer input field values with merchant-defined labels.
+     * Mirrors `OrderItem.customizations` — same shape, live (not order-frozen).
+     * Present only when the item has at least one customization value set.
+     *
+     * @example
+     * // Display "Color: Silver / Size: 45" without an extra getProduct() call:
+     * Object.entries(item.customizations ?? {}).map(([, c]) => `${c.label}: ${c.value}`)
+     */
+    customizations?: Record<string, {
+        label: string;
+        value: string | string[];
+        type: string;
+    }>;
     /**
      * Per-line modifier breakdown — present when the line was added with
      * modifier `selections`. Snapshot taken at add-time; immutable to catalog
@@ -2326,6 +2387,20 @@ interface CheckoutLineItem {
     notes?: string | null;
     /** Custom metadata including customer input field values */
     metadata?: Record<string, unknown> | null;
+    /**
+     * Resolved customer input field values with merchant-defined labels.
+     * Mirrors `OrderItem.customizations` — same shape, live (not order-frozen).
+     * Present only when the item has at least one customization value set.
+     *
+     * @example
+     * // Render "Color: Silver / Ring size: 45" in your checkout summary:
+     * Object.entries(item.customizations ?? {}).map(([, c]) => `${c.label}: ${c.value}`)
+     */
+    customizations?: Record<string, {
+        label: string;
+        value: string | string[];
+        type: string;
+    }>;
 }
 /**
  * Represents an available shipping rate/method for checkout.
@@ -3070,6 +3145,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;
@@ -3085,8 +3172,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;
 }
@@ -3983,7 +4088,8 @@ interface MetafieldDefinition {
     maxLength?: number | null;
     minValue?: number | null;
     maxValue?: number | null;
-    enumValues?: string[] | null;
+    /** Allowed values for SELECT / MULTI_SELECT fields, with optional swatch metadata. */
+    enumValues?: CustomizationFieldOption[] | null;
     defaultValue?: string | null;
     position: number;
     isActive: boolean;
@@ -4067,7 +4173,8 @@ interface PublicMetafieldDefinition {
      * Pair with `getProducts({ metafields: { [key]: [...] } })`.
      */
     filterable?: boolean;
-    enumValues?: string[];
+    /** Allowed values for SELECT / MULTI_SELECT fields, with optional swatch metadata. */
+    enumValues?: CustomizationFieldOption[];
     minLength?: number | null;
     maxLength?: number | null;
     minValue?: number | null;
@@ -4075,6 +4182,20 @@ interface PublicMetafieldDefinition {
     defaultValue?: string | null;
     position: number;
 }
+/**
+ * A single selectable option for a SELECT or MULTI_SELECT customization field.
+ * Legacy string-only `enumValues` arrays are automatically promoted to this shape.
+ */
+interface CustomizationFieldOption {
+    /** Human-readable label shown in the storefront UI (e.g., "Rose Gold"). */
+    label: string;
+    /** Value stored in `CartItem.metadata` and carried through to `OrderItem.customizations`. */
+    value: string;
+    /** Optional CSS hex color for rendering a color swatch (e.g., "#B76E79"). */
+    swatchColor?: string | null;
+    /** Optional image URL for rendering a texture/image swatch. */
+    swatchImageUrl?: string | null;
+}
 /**
  * Customer-facing input field definition assigned to a specific product.
  * Returned in product responses to tell the storefront which input fields to render.
@@ -4090,7 +4211,11 @@ interface ProductCustomizationField {
     maxLength?: number | null;
     minValue?: number | null;
     maxValue?: number | null;
-    enumValues?: string[];
+    /**
+     * Allowed values for SELECT / MULTI_SELECT fields.
+     * Each option includes a label, value, and optional swatch color/image.
+     */
+    enumValues?: CustomizationFieldOption[];
     defaultValue?: string | null;
     position: number;
 }
@@ -5379,6 +5504,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;
@@ -5548,6 +5675,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
@@ -5972,6 +6113,29 @@ declare class BrainerceClient {
      * ```
      */
     updateOrderShipping(orderId: string, data: UpdateOrderShippingDto): Promise<Order>;
+    /**
+     * Create a shipping label for an order via the installed App Store shipping app.
+     * Pass the rate ID returned from checkout rate shopping. Billing goes directly
+     * to the merchant's carrier account — Brainerce is not a billing intermediary.
+     *
+     * @example
+     * ```typescript
+     * const label = await client.createShippingLabel('order_abc', {
+     *   rateId: 'rate_8f123456789abcdef',
+     * });
+     * console.log('Label URL:', label.labelUrl);
+     * console.log('Tracking:', label.trackingNumber);
+     * ```
+     */
+    createShippingLabel(orderId: string, data: {
+        rateId: string;
+        parcel?: Record<string, string>;
+    }): Promise<{
+        shipmentId: string;
+        labelUrl: string;
+        trackingNumber: string;
+        carrier: string;
+    }>;
     /**
      * Cancel an order
      * Works for Shopify and WooCommerce orders that haven't been fulfilled
@@ -7859,6 +8023,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();
@@ -7868,27 +8040,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
+     *   }
      * }
      * ```
      */
@@ -9543,7 +9709,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.41.0";
 
 /**
  * Verify a webhook signature from Brainerce

package/dist/index.js

@@ -185,7 +185,7 @@ function isDevGuardsEnabled() {
 }
 
 // src/version.ts
-var SDK_VERSION = "1.36.1";
+var SDK_VERSION = "1.41.0";
 
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.brainerce.com";
@@ -653,6 +653,7 @@ var BrainerceClient = class {
       }
     }
     this.proxyMode = options.proxyMode || false;
+    this.analyticsBaseUrl = this.resolveAnalyticsBaseUrl(options.analyticsBaseUrl, resolvedBase);
     this.onAuthError = options.onAuthError;
     this.hydrateSessionCart();
     this.detectRecoverCartFromUrl();
@@ -1106,12 +1107,46 @@ var BrainerceClient = class {
    * ```
    */
   async trackEvent(payload = {}) {
+    if (this.isVibeCodedMode() && this.connectionId) {
+      this.sendAnalyticsBeacon(`/api/vc/${encodePathSegment(this.connectionId)}/events`, payload);
+    } else if (this.isStorefrontMode() && this.storeId) {
+      this.sendAnalyticsBeacon(`/api/stores/${encodePathSegment(this.storeId)}/events`, payload);
+    }
+  }
+  /**
+   * 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).
+   */
+  resolveAnalyticsBaseUrl(explicit, resolvedBase) {
+    if (explicit) return explicit.replace(/\/$/, "");
+    const sameOriginProxy = this.proxyMode || typeof window !== "undefined" && !!window.location?.origin && resolvedBase.startsWith(window.location.origin);
+    return sameOriginProxy ? DEFAULT_BASE_URL : resolvedBase;
+  }
+  /**
+   * 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.
+   */
+  sendAnalyticsBeacon(eventsPath, payload) {
     try {
-      if (this.isVibeCodedMode()) {
-        await this.vibeCodedRequest("POST", "/events", payload);
-      } else if (this.isStorefrontMode()) {
-        await this.storefrontRequest("POST", "/events", payload);
-      }
+      const headers = {
+        "Content-Type": "application/json",
+        "X-SDK-Version": SDK_VERSION,
+        "ngrok-skip-browser-warning": "true"
+      };
+      if (this.origin) headers["Origin"] = this.origin;
+      void fetch(`${this.analyticsBaseUrl}${eventsPath}`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(payload),
+        keepalive: true,
+        credentials: "omit",
+        mode: "cors"
+      }).catch(() => {
+      });
     } catch {
     }
   }
@@ -1805,6 +1840,27 @@ var BrainerceClient = class {
       data
     );
   }
+  /**
+   * Create a shipping label for an order via the installed App Store shipping app.
+   * Pass the rate ID returned from checkout rate shopping. Billing goes directly
+   * to the merchant's carrier account — Brainerce is not a billing intermediary.
+   *
+   * @example
+   * ```typescript
+   * const label = await client.createShippingLabel('order_abc', {
+   *   rateId: 'rate_8f123456789abcdef',
+   * });
+   * console.log('Label URL:', label.labelUrl);
+   * console.log('Tracking:', label.trackingNumber);
+   * ```
+   */
+  async createShippingLabel(orderId, data) {
+    return this.request(
+      "POST",
+      `/api/v1/orders/${encodePathSegment(orderId)}/shipments/app-label`,
+      data
+    );
+  }
   /**
    * Cancel an order
    * Works for Shopify and WooCommerce orders that haven't been fulfilled
@@ -5208,6 +5264,14 @@ var BrainerceClient = class {
    *
    * @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();
@@ -5217,27 +5281,21 @@ var BrainerceClient = class {
    *   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
+   *   }
    * }
    * ```
    */

package/dist/index.mjs

@@ -115,7 +115,7 @@ function isDevGuardsEnabled() {
 }
 
 // src/version.ts
-var SDK_VERSION = "1.36.1";
+var SDK_VERSION = "1.41.0";
 
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.brainerce.com";
@@ -583,6 +583,7 @@ var BrainerceClient = class {
       }
     }
     this.proxyMode = options.proxyMode || false;
+    this.analyticsBaseUrl = this.resolveAnalyticsBaseUrl(options.analyticsBaseUrl, resolvedBase);
     this.onAuthError = options.onAuthError;
     this.hydrateSessionCart();
     this.detectRecoverCartFromUrl();
@@ -1036,12 +1037,46 @@ var BrainerceClient = class {
    * ```
    */
   async trackEvent(payload = {}) {
+    if (this.isVibeCodedMode() && this.connectionId) {
+      this.sendAnalyticsBeacon(`/api/vc/${encodePathSegment(this.connectionId)}/events`, payload);
+    } else if (this.isStorefrontMode() && this.storeId) {
+      this.sendAnalyticsBeacon(`/api/stores/${encodePathSegment(this.storeId)}/events`, payload);
+    }
+  }
+  /**
+   * 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).
+   */
+  resolveAnalyticsBaseUrl(explicit, resolvedBase) {
+    if (explicit) return explicit.replace(/\/$/, "");
+    const sameOriginProxy = this.proxyMode || typeof window !== "undefined" && !!window.location?.origin && resolvedBase.startsWith(window.location.origin);
+    return sameOriginProxy ? DEFAULT_BASE_URL : resolvedBase;
+  }
+  /**
+   * 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.
+   */
+  sendAnalyticsBeacon(eventsPath, payload) {
     try {
-      if (this.isVibeCodedMode()) {
-        await this.vibeCodedRequest("POST", "/events", payload);
-      } else if (this.isStorefrontMode()) {
-        await this.storefrontRequest("POST", "/events", payload);
-      }
+      const headers = {
+        "Content-Type": "application/json",
+        "X-SDK-Version": SDK_VERSION,
+        "ngrok-skip-browser-warning": "true"
+      };
+      if (this.origin) headers["Origin"] = this.origin;
+      void fetch(`${this.analyticsBaseUrl}${eventsPath}`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(payload),
+        keepalive: true,
+        credentials: "omit",
+        mode: "cors"
+      }).catch(() => {
+      });
     } catch {
     }
   }
@@ -1735,6 +1770,27 @@ var BrainerceClient = class {
       data
     );
   }
+  /**
+   * Create a shipping label for an order via the installed App Store shipping app.
+   * Pass the rate ID returned from checkout rate shopping. Billing goes directly
+   * to the merchant's carrier account — Brainerce is not a billing intermediary.
+   *
+   * @example
+   * ```typescript
+   * const label = await client.createShippingLabel('order_abc', {
+   *   rateId: 'rate_8f123456789abcdef',
+   * });
+   * console.log('Label URL:', label.labelUrl);
+   * console.log('Tracking:', label.trackingNumber);
+   * ```
+   */
+  async createShippingLabel(orderId, data) {
+    return this.request(
+      "POST",
+      `/api/v1/orders/${encodePathSegment(orderId)}/shipments/app-label`,
+      data
+    );
+  }
   /**
    * Cancel an order
    * Works for Shopify and WooCommerce orders that haven't been fulfilled
@@ -5138,6 +5194,14 @@ var BrainerceClient = class {
    *
    * @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();
@@ -5147,27 +5211,21 @@ var BrainerceClient = class {
    *   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
+   *   }
    * }
    * ```
    */

package/package.json

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