brainerce 1.36.5 → 1.37.2

package/README.md

@@ -2055,29 +2055,33 @@ const checkout = await client.createCheckout({
 
 #### Region display pricing (`getProducts({ regionId })`)
 
-Product reads accept an optional `regionId`. When set, each product/variant that
-a region [price list](#price-lists) resolves gains additive fields —
-`resolvedPrice`, `resolvedCurrency`, `resolvedCompareAtPrice`, and `priceSource`
-(`'variant-entry'` | `'product-entry'`). Your existing `basePrice` / `salePrice`
-stay in the store currency; the fields appear **only** when a region entry
-actually applies, so an omitted/invalid region (or a catalog-price fallback)
-leaves the response byte-identical.
+All three product reads accept an optional `regionId` — `getProducts`,
+`getProduct(id)`, **and** `getProductBySlug(slug)` (the PDP path). When set and the
+region's currency differs from the store currency, each product/variant gains
+additive FX-display fields — `displayPrice`, `displaySalePrice`, and
+`displayCurrency` (plus `displayPriceMin` / `displayPriceMax` on storefront-mode
+list reads). Your `basePrice` / `salePrice` stay in the store currency; the
+display fields appear **only** when an FX rate applies, so an omitted/invalid
+region or a same-currency region leaves the response byte-identical.
 
 ```typescript
 const { data: products } = await client.getProducts({ regionId: 'region_eu' });
 const p = products[0];
-const display = p.resolvedPrice
-  ? `${p.resolvedPrice} ${p.resolvedCurrency}` // e.g. "27.00 EUR"
-  : p.basePrice; // store-currency catalog price
+const display = p.displayPrice
+  ? `${p.displayPrice} ${p.displayCurrency}` // e.g. "27.00 EUR"
+  : p.basePrice; // store-currency price (no FX rate / same currency)
 
-// Single product (id or slug) takes the same option:
+// Single product by id OR slug takes the same option:
 await client.getProduct('prod_tshirt', { regionId: 'region_eu' });
+await client.getProductBySlug('blue-shirt', { 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.
+> currency; it only changes what you render until currency-lock ships. Works in
+> **all three modes** — vibe-coded (`vc_*`/`salesChannelId`), storefront (`storeId`),
+> and admin (`apiKey`). The response gains `displayPrice` whenever a daily FX rate
+> exists for the store/region currency pair in **either** direction (the overlay
+> inverts the stored rate when needed). See [Regions](/docs/concepts/regions).
 
 #### Partial Checkout (AliExpress-style)
 
@@ -3566,10 +3570,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 +3621,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;
 }
@@ -5469,6 +5493,7 @@ declare class BrainerceClient {
      */
     getProductBySlug(slug: string, options?: {
         locale?: string;
+        regionId?: string;
     }): Promise<Product>;
     /**
      * Get available categories for filtering products
@@ -8851,15 +8876,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 +8922,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;
 }
@@ -5469,6 +5493,7 @@ declare class BrainerceClient {
      */
     getProductBySlug(slug: string, options?: {
         locale?: string;
+        regionId?: string;
     }): Promise<Product>;
     /**
      * Get available categories for filtering products
@@ -8851,15 +8876,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 +8922,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
       );
     }
@@ -1192,13 +1192,14 @@ var BrainerceClient = class {
    */
   async getProductBySlug(slug, options) {
     const headerOverrides = options?.locale ? { "Accept-Language": options.locale } : void 0;
+    const queryParams = options?.regionId ? { regionId: options.regionId } : void 0;
     const encodedSlug = encodePathSegment(slug);
     if (this.isVibeCodedMode()) {
       return this.vibeCodedRequest(
         "GET",
         `/products/slug/${encodedSlug}`,
         void 0,
-        void 0,
+        queryParams,
         headerOverrides
       );
     }
@@ -1207,11 +1208,16 @@ var BrainerceClient = class {
         "GET",
         `/products/slug/${encodedSlug}`,
         void 0,
-        void 0,
+        queryParams,
         headerOverrides
       );
     }
-    return this.adminRequest("GET", `/api/v1/products/by-slug/${encodedSlug}`);
+    return this.adminRequest(
+      "GET",
+      `/api/v1/products/by-slug/${encodedSlug}`,
+      void 0,
+      queryParams
+    );
   }
   /**
    * Get available categories for filtering products
@@ -7275,22 +7281,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 +7336,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 +7361,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
       );
     }
@@ -1122,13 +1122,14 @@ var BrainerceClient = class {
    */
   async getProductBySlug(slug, options) {
     const headerOverrides = options?.locale ? { "Accept-Language": options.locale } : void 0;
+    const queryParams = options?.regionId ? { regionId: options.regionId } : void 0;
     const encodedSlug = encodePathSegment(slug);
     if (this.isVibeCodedMode()) {
       return this.vibeCodedRequest(
         "GET",
         `/products/slug/${encodedSlug}`,
         void 0,
-        void 0,
+        queryParams,
         headerOverrides
       );
     }
@@ -1137,11 +1138,16 @@ var BrainerceClient = class {
         "GET",
         `/products/slug/${encodedSlug}`,
         void 0,
-        void 0,
+        queryParams,
         headerOverrides
       );
     }
-    return this.adminRequest("GET", `/api/v1/products/by-slug/${encodedSlug}`);
+    return this.adminRequest(
+      "GET",
+      `/api/v1/products/by-slug/${encodedSlug}`,
+      void 0,
+      queryParams
+    );
   }
   /**
    * Get available categories for filtering products
@@ -7205,22 +7211,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 +7266,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 +7291,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.2",
   "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",