brainerce 1.39.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';
@@ -2375,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();
@@ -2391,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',
@@ -2400,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>;
@@ -3424,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.
 
 ---

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[];
 }
@@ -3098,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;
@@ -3113,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;
 }
@@ -5427,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;
@@ -5596,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
@@ -7930,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();
@@ -7939,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
+     *   }
      * }
      * ```
      */
@@ -9614,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[];
 }
@@ -3098,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;
@@ -3113,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;
 }
@@ -5427,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;
@@ -5596,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
@@ -7930,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();
@@ -7939,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
+     *   }
      * }
      * ```
      */
@@ -9614,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 {
     }
   }
@@ -5229,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();
@@ -5238,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
+   * // 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.
    * }
    *
-   * // Initialize PayPal if available
-   * if (paypalProvider) {
-   *   // Load PayPal SDK with paypalProvider.publicKey as client-id
-   *   // Show PayPal buttons
-   * }
-   *
-   * // 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 {
     }
   }
@@ -5159,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();
@@ -5168,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
+   * // 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.
    * }
    *
-   * // Initialize PayPal if available
-   * if (paypalProvider) {
-   *   // Load PayPal SDK with paypalProvider.publicKey as client-id
-   *   // Show PayPal buttons
-   * }
-   *
-   * // 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.39.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",