brainerce 1.36.5 → 1.37.0

package/README.md

@@ -2076,8 +2076,11 @@ await client.getProduct('prod_tshirt', { regionId: 'region_eu' });
 
 > **Display-only** — like checkout, `regionId` here does not charge the region
 > price; it only changes what you render until currency-lock ships. **Mode note:**
-> region resolution applies on storefront (`storeId`) and admin (`apiKey`) reads;
-> it is currently ignored in vibe-coded (`vc_*`/`salesChannelId`) mode.
+> the additive FX display overlay (`displayPrice` / `displayCurrency`, see
+> [Regions](/docs/concepts/regions)) now applies in vibe-coded
+> (`vc_*`/`salesChannelId`) mode too — previously it was populated on storefront
+> (`storeId`) and admin (`apiKey`) reads only. Pass `regionId` and the response
+> gains `displayPrice` whenever a daily FX rate exists for the store→region pair.
 
 #### Partial Checkout (AliExpress-style)
 
@@ -3566,10 +3569,13 @@ await client.deleteTaxClass(food.id);
 ```
 
 **Storefront (public, no API key).** A storefront lists classes in `storeId`
-mode — storefront-safe fields only (for a "9% VAT" transparency badge):
+mode **or** vibe-coded mode (`salesChannelId: 'vc_*'`, gated on the
+`products:read` scope every connection already has) — storefront-safe fields
+only (for a "9% VAT" transparency badge):
 
 ```typescript
 const store = new BrainerceClient({ storeId: 'store_123' });
+// — or — new BrainerceClient({ salesChannelId: 'vc_abc123' });
 const { data: classes } = await store.getStoreTaxClasses();
 ```
 
@@ -3614,14 +3620,19 @@ await client.deleteRegion(eu.id);
 ```
 
 **Storefront (public, no API key).** A storefront fetches regions in `storeId`
-mode — only active regions, only storefront-safe fields:
+mode **or** vibe-coded mode (`salesChannelId: 'vc_*'`, gated on the
+`products:read` scope every connection already has) — only active regions, only
+storefront-safe fields. `getStoreRegions()`, `getStoreRegion()`, and
+`getAutoRegion()` all work in both modes:
 
 ```typescript
 const store = new BrainerceClient({ storeId: 'store_123' });
+// — or — new BrainerceClient({ salesChannelId: 'vc_abc123' });
 
 const { data: regions } = await store.getStoreRegions();
 const region = await store.getStoreRegion(regions[0].id); // + paymentProviders
 const dest = store.detectRegion('DE', regions); // pick by country, client-side
+const { region: resolved } = await store.getAutoRegion('DE'); // server-side, one round trip
 ```
 
 > **Multi-region checkout:** pass a `regionId` to `createCheckout` to associate the

package/dist/index.d.mts

@@ -4556,12 +4556,27 @@ interface ProductRecommendation {
     id: string;
     name: string;
     slug: string | null;
+    /**
+     * Effective price. For a VARIABLE target this is the pinned variant's price
+     * (when `targetVariantId` is set) or the "from {min variant}" range price —
+     * never a stale 0 parent price.
+     */
     basePrice: string;
     salePrice: string | null;
     images: ProductImage[];
     type: 'SIMPLE' | 'VARIABLE';
     inventory?: InventoryInfo | null;
     relationType: ProductRelationType;
+    /** Pinned variant of the target (VARIABLE only); null = customer chooses. */
+    targetVariantId?: string | null;
+    /**
+     * True when the target is VARIABLE with no pinned variant — the customer must
+     * pick a variation (use `variants`) before this can be added to the cart.
+     */
+    requiresVariantSelection?: boolean;
+    /** The pinned variation when `targetVariantId` is set. */
+    pinnedVariant?: LockedVariant | null;
+    /** Selectable variations, present when `requiresVariantSelection` is true. */
     variants?: RecommendationVariant[];
 }
 interface ProductRecommendationsResponse {
@@ -4596,6 +4611,15 @@ interface CartBundleOfferOfferedProduct {
         url: string;
     }>;
     type: string;
+    /** Pinned variant for this slot (VARIABLE only); null = customer chooses. */
+    variantId?: string | null;
+    /** True when the offered product is VARIABLE with no pinned variant. */
+    requiresVariantSelection?: boolean;
+    /** The pinned variation when `variantId` is set. */
+    pinnedVariant?: LockedVariant | null;
+    /** Selectable variations, present when `requiresVariantSelection` is true. */
+    variants?: RecommendationVariant[];
+    /** Effective pre-discount unit price (pinned/cheapest variant for VARIABLE). */
     originalPrice: string;
     discountedPrice: string;
 }
@@ -8851,15 +8875,17 @@ declare class BrainerceClient {
         name?: string | null;
     }>>;
     /**
-     * List the store's ACTIVE regions (public, no apiKey). Requires storeId mode.
-     * Returns only storefront-safe fields (no internal flags). Default region first.
+     * List the store's ACTIVE regions (public, no apiKey). Works in storeId and
+     * vibe-coded modes. Returns only storefront-safe fields (no internal flags).
+     * Default region first.
      */
     getStoreRegions(): Promise<{
         data: PublicRegion[];
     }>;
     /**
      * Get one active public region plus its enabled payment providers (public).
-     * Requires storeId mode. Throws 404 if the region is inactive or not found.
+     * Works in storeId and vibe-coded modes. Throws 404 if the region is inactive
+     * or not found.
      */
     getStoreRegion(regionId: string): Promise<PublicRegionDetail>;
     /**
@@ -8895,9 +8921,10 @@ declare class BrainerceClient {
         subtotal: number;
     }): Promise<TaxEstimateResponse>;
     /**
-     * List the store's tax classes (public, no apiKey — storeId mode). Storefront-
-     * safe fields only (id/name/slug/description/isDefault) for transparency UIs
-     * such as a "9% VAT" badge. Admin/api-key callers use getTaxClasses().
+     * List the store's tax classes (public, no apiKey — storeId or vibe-coded
+     * mode). Storefront-safe fields only (id/name/slug/description/isDefault) for
+     * transparency UIs such as a "9% VAT" badge. Admin/api-key callers use
+     * getTaxClasses().
      */
     getStoreTaxClasses(): Promise<{
         data: PublicTaxClass[];

package/dist/index.d.ts

@@ -4556,12 +4556,27 @@ interface ProductRecommendation {
     id: string;
     name: string;
     slug: string | null;
+    /**
+     * Effective price. For a VARIABLE target this is the pinned variant's price
+     * (when `targetVariantId` is set) or the "from {min variant}" range price —
+     * never a stale 0 parent price.
+     */
     basePrice: string;
     salePrice: string | null;
     images: ProductImage[];
     type: 'SIMPLE' | 'VARIABLE';
     inventory?: InventoryInfo | null;
     relationType: ProductRelationType;
+    /** Pinned variant of the target (VARIABLE only); null = customer chooses. */
+    targetVariantId?: string | null;
+    /**
+     * True when the target is VARIABLE with no pinned variant — the customer must
+     * pick a variation (use `variants`) before this can be added to the cart.
+     */
+    requiresVariantSelection?: boolean;
+    /** The pinned variation when `targetVariantId` is set. */
+    pinnedVariant?: LockedVariant | null;
+    /** Selectable variations, present when `requiresVariantSelection` is true. */
     variants?: RecommendationVariant[];
 }
 interface ProductRecommendationsResponse {
@@ -4596,6 +4611,15 @@ interface CartBundleOfferOfferedProduct {
         url: string;
     }>;
     type: string;
+    /** Pinned variant for this slot (VARIABLE only); null = customer chooses. */
+    variantId?: string | null;
+    /** True when the offered product is VARIABLE with no pinned variant. */
+    requiresVariantSelection?: boolean;
+    /** The pinned variation when `variantId` is set. */
+    pinnedVariant?: LockedVariant | null;
+    /** Selectable variations, present when `requiresVariantSelection` is true. */
+    variants?: RecommendationVariant[];
+    /** Effective pre-discount unit price (pinned/cheapest variant for VARIABLE). */
     originalPrice: string;
     discountedPrice: string;
 }
@@ -8851,15 +8875,17 @@ declare class BrainerceClient {
         name?: string | null;
     }>>;
     /**
-     * List the store's ACTIVE regions (public, no apiKey). Requires storeId mode.
-     * Returns only storefront-safe fields (no internal flags). Default region first.
+     * List the store's ACTIVE regions (public, no apiKey). Works in storeId and
+     * vibe-coded modes. Returns only storefront-safe fields (no internal flags).
+     * Default region first.
      */
     getStoreRegions(): Promise<{
         data: PublicRegion[];
     }>;
     /**
      * Get one active public region plus its enabled payment providers (public).
-     * Requires storeId mode. Throws 404 if the region is inactive or not found.
+     * Works in storeId and vibe-coded modes. Throws 404 if the region is inactive
+     * or not found.
      */
     getStoreRegion(regionId: string): Promise<PublicRegionDetail>;
     /**
@@ -8895,9 +8921,10 @@ declare class BrainerceClient {
         subtotal: number;
     }): Promise<TaxEstimateResponse>;
     /**
-     * List the store's tax classes (public, no apiKey — storeId mode). Storefront-
-     * safe fields only (id/name/slug/description/isDefault) for transparency UIs
-     * such as a "9% VAT" badge. Admin/api-key callers use getTaxClasses().
+     * List the store's tax classes (public, no apiKey — storeId or vibe-coded
+     * mode). Storefront-safe fields only (id/name/slug/description/isDefault) for
+     * transparency UIs such as a "9% VAT" badge. Admin/api-key callers use
+     * getTaxClasses().
      */
     getStoreTaxClasses(): Promise<{
         data: PublicTaxClass[];

package/dist/index.js

@@ -1130,7 +1130,7 @@ var BrainerceClient = class {
         "GET",
         "/products",
         void 0,
-        queryParams
+        queryParamsWithRegion
       );
     }
     if (this.storeId && !this.apiKey) {
@@ -1160,7 +1160,7 @@ var BrainerceClient = class {
         "GET",
         `/products/${encodePathSegment(productId)}`,
         void 0,
-        void 0,
+        queryParams,
         headerOverrides
       );
     }
@@ -7275,22 +7275,34 @@ var BrainerceClient = class {
       `/api/v1/regions/${encodePathSegment(regionId)}/compatible-providers`
     );
   }
-  // -------------------- Regions (Storefront mode, public — no apiKey) --------------------
-  // storeId-based, no auth. Call these from a storefront to detect the buyer's
-  // region (story S1), then pair with detectRegion(). Admin/api-key callers use
-  // getRegions()/getRegion() instead.
+  // -------------------- Regions (Storefront + vibe-coded, public — no apiKey) --------------------
+  // storeId- or connectionId-based, no auth. Call these from a storefront to
+  // detect the buyer's region (story S1), then pair with detectRegion(). Then
+  // pass the resolved regionId to getProducts({ regionId }) for display pricing.
+  // Admin/api-key callers use getRegions()/getRegion() instead.
   /**
-   * List the store's ACTIVE regions (public, no apiKey). Requires storeId mode.
-   * Returns only storefront-safe fields (no internal flags). Default region first.
+   * List the store's ACTIVE regions (public, no apiKey). Works in storeId and
+   * vibe-coded modes. Returns only storefront-safe fields (no internal flags).
+   * Default region first.
    */
   async getStoreRegions() {
+    if (this.isVibeCodedMode()) {
+      return this.vibeCodedRequest("GET", "/regions");
+    }
     return this.storefrontRequest("GET", "/regions");
   }
   /**
    * Get one active public region plus its enabled payment providers (public).
-   * Requires storeId mode. Throws 404 if the region is inactive or not found.
+   * Works in storeId and vibe-coded modes. Throws 404 if the region is inactive
+   * or not found.
    */
   async getStoreRegion(regionId) {
+    if (this.isVibeCodedMode()) {
+      return this.vibeCodedRequest(
+        "GET",
+        `/regions/${encodePathSegment(regionId)}`
+      );
+    }
     return this.storefrontRequest(
       "GET",
       `/regions/${encodePathSegment(regionId)}`
@@ -7318,6 +7330,14 @@ var BrainerceClient = class {
    * default region (or `region=null` if no default exists either).
    */
   async getAutoRegion(country) {
+    if (this.isVibeCodedMode()) {
+      return this.vibeCodedRequest(
+        "GET",
+        "/regions/auto",
+        void 0,
+        country ? { country } : void 0
+      );
+    }
     return this.storefrontRequest(
       "GET",
       "/regions/auto",
@@ -7335,20 +7355,23 @@ var BrainerceClient = class {
    * or no active rate covers it.
    */
   async estimateTax(params) {
-    return this.storefrontRequest(
-      "GET",
-      "/tax/estimate",
-      void 0,
-      params.country ? { country: params.country, subtotal: params.subtotal } : { subtotal: params.subtotal }
-    );
+    const query = params.country ? { country: params.country, subtotal: params.subtotal } : { subtotal: params.subtotal };
+    if (this.isVibeCodedMode()) {
+      return this.vibeCodedRequest("GET", "/tax/estimate", void 0, query);
+    }
+    return this.storefrontRequest("GET", "/tax/estimate", void 0, query);
   }
-  // -------------------- Tax Classes (Storefront mode, public — no apiKey) --------------------
+  // -------------------- Tax Classes (Storefront + vibe-coded, public — no apiKey) --------------------
   /**
-   * List the store's tax classes (public, no apiKey — storeId mode). Storefront-
-   * safe fields only (id/name/slug/description/isDefault) for transparency UIs
-   * such as a "9% VAT" badge. Admin/api-key callers use getTaxClasses().
+   * List the store's tax classes (public, no apiKey — storeId or vibe-coded
+   * mode). Storefront-safe fields only (id/name/slug/description/isDefault) for
+   * transparency UIs such as a "9% VAT" badge. Admin/api-key callers use
+   * getTaxClasses().
    */
   async getStoreTaxClasses() {
+    if (this.isVibeCodedMode()) {
+      return this.vibeCodedRequest("GET", "/tax-classes");
+    }
     return this.storefrontRequest("GET", "/tax-classes");
   }
   // -------------------- Tax Classes (Admin mode, apiKey) --------------------

package/dist/index.mjs

@@ -1060,7 +1060,7 @@ var BrainerceClient = class {
         "GET",
         "/products",
         void 0,
-        queryParams
+        queryParamsWithRegion
       );
     }
     if (this.storeId && !this.apiKey) {
@@ -1090,7 +1090,7 @@ var BrainerceClient = class {
         "GET",
         `/products/${encodePathSegment(productId)}`,
         void 0,
-        void 0,
+        queryParams,
         headerOverrides
       );
     }
@@ -7205,22 +7205,34 @@ var BrainerceClient = class {
       `/api/v1/regions/${encodePathSegment(regionId)}/compatible-providers`
     );
   }
-  // -------------------- Regions (Storefront mode, public — no apiKey) --------------------
-  // storeId-based, no auth. Call these from a storefront to detect the buyer's
-  // region (story S1), then pair with detectRegion(). Admin/api-key callers use
-  // getRegions()/getRegion() instead.
+  // -------------------- Regions (Storefront + vibe-coded, public — no apiKey) --------------------
+  // storeId- or connectionId-based, no auth. Call these from a storefront to
+  // detect the buyer's region (story S1), then pair with detectRegion(). Then
+  // pass the resolved regionId to getProducts({ regionId }) for display pricing.
+  // Admin/api-key callers use getRegions()/getRegion() instead.
   /**
-   * List the store's ACTIVE regions (public, no apiKey). Requires storeId mode.
-   * Returns only storefront-safe fields (no internal flags). Default region first.
+   * List the store's ACTIVE regions (public, no apiKey). Works in storeId and
+   * vibe-coded modes. Returns only storefront-safe fields (no internal flags).
+   * Default region first.
    */
   async getStoreRegions() {
+    if (this.isVibeCodedMode()) {
+      return this.vibeCodedRequest("GET", "/regions");
+    }
     return this.storefrontRequest("GET", "/regions");
   }
   /**
    * Get one active public region plus its enabled payment providers (public).
-   * Requires storeId mode. Throws 404 if the region is inactive or not found.
+   * Works in storeId and vibe-coded modes. Throws 404 if the region is inactive
+   * or not found.
    */
   async getStoreRegion(regionId) {
+    if (this.isVibeCodedMode()) {
+      return this.vibeCodedRequest(
+        "GET",
+        `/regions/${encodePathSegment(regionId)}`
+      );
+    }
     return this.storefrontRequest(
       "GET",
       `/regions/${encodePathSegment(regionId)}`
@@ -7248,6 +7260,14 @@ var BrainerceClient = class {
    * default region (or `region=null` if no default exists either).
    */
   async getAutoRegion(country) {
+    if (this.isVibeCodedMode()) {
+      return this.vibeCodedRequest(
+        "GET",
+        "/regions/auto",
+        void 0,
+        country ? { country } : void 0
+      );
+    }
     return this.storefrontRequest(
       "GET",
       "/regions/auto",
@@ -7265,20 +7285,23 @@ var BrainerceClient = class {
    * or no active rate covers it.
    */
   async estimateTax(params) {
-    return this.storefrontRequest(
-      "GET",
-      "/tax/estimate",
-      void 0,
-      params.country ? { country: params.country, subtotal: params.subtotal } : { subtotal: params.subtotal }
-    );
+    const query = params.country ? { country: params.country, subtotal: params.subtotal } : { subtotal: params.subtotal };
+    if (this.isVibeCodedMode()) {
+      return this.vibeCodedRequest("GET", "/tax/estimate", void 0, query);
+    }
+    return this.storefrontRequest("GET", "/tax/estimate", void 0, query);
   }
-  // -------------------- Tax Classes (Storefront mode, public — no apiKey) --------------------
+  // -------------------- Tax Classes (Storefront + vibe-coded, public — no apiKey) --------------------
   /**
-   * List the store's tax classes (public, no apiKey — storeId mode). Storefront-
-   * safe fields only (id/name/slug/description/isDefault) for transparency UIs
-   * such as a "9% VAT" badge. Admin/api-key callers use getTaxClasses().
+   * List the store's tax classes (public, no apiKey — storeId or vibe-coded
+   * mode). Storefront-safe fields only (id/name/slug/description/isDefault) for
+   * transparency UIs such as a "9% VAT" badge. Admin/api-key callers use
+   * getTaxClasses().
    */
   async getStoreTaxClasses() {
+    if (this.isVibeCodedMode()) {
+      return this.vibeCodedRequest("GET", "/tax-classes");
+    }
     return this.storefrontRequest("GET", "/tax-classes");
   }
   // -------------------- Tax Classes (Admin mode, apiKey) --------------------

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brainerce",
-  "version": "1.36.5",
+  "version": "1.37.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",