brainerce 1.37.0 → 1.37.3

package/README.md

@@ -2050,37 +2050,41 @@ const checkout = await client.createCheckout({
 ```
 
 > The region is recorded on the checkout and used for payment-provider scoping.
-> Currency continues to follow the cart until FX price conversion lands, so
-> passing a `regionId` does not re-price the cart.
+> **FX-at-checkout:** when the region currency differs from the store base and its
+> provider can settle it (presentment-enabled — Stripe today), the buyer is charged
+> in the region currency and the checkout response carries a `presentment` overlay
+> (`presentment.total` / `presentment.currency` = what's charged). Otherwise the
+> checkout is charged in the store base currency.
 
 #### 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:**
-> 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.
+> 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)
 
@@ -3637,8 +3641,10 @@ const { region: resolved } = await store.getAutoRegion('DE'); // server-side, on
 
 > **Multi-region checkout:** pass a `regionId` to `createCheckout` to associate the
 > checkout with a region (for reporting + payment-provider scoping). The region
-> must belong to the store. Currency still follows the cart until FX price
-> conversion lands. See the Checkout section.
+> must belong to the store. **FX-at-checkout:** presentment-enabled regions
+> (Stripe today) charge in the region currency and return a `presentment` overlay;
+> otherwise the checkout is charged in the store base currency. See the Checkout
+> section.
 
 ### Price Lists (per-region pricing)
 

package/dist/index.d.mts

@@ -2507,8 +2507,11 @@ interface Checkout {
     currency: string;
     /**
      * Region this checkout is associated with (multi-region commerce), or null.
-     * Recorded for reporting + provider scoping; currency follows the cart until
-     * FX price conversion lands.
+     * Recorded for reporting + provider scoping. FX-at-checkout: when the region
+     * currency differs from the store base and its provider can settle it
+     * (presentment-enabled — Stripe today), the buyer is charged in the region
+     * currency and the `presentment` overlay below carries the charged amounts;
+     * otherwise the checkout is charged in the store base currency.
      */
     regionId?: string | null;
     /** Subtotal as string - use parseFloat() */
@@ -2560,6 +2563,41 @@ interface Checkout {
      * @see ReservationInfo
      */
     reservation?: ReservationInfo;
+    /**
+     * FX-at-checkout presentment overlay. Present ONLY when the checkout's region
+     * uses a different currency from the store base AND that region charges in its
+     * own currency (presentment). These are the amounts the buyer will actually be
+     * CHARGED, in `presentment.currency` — `presentment.total` equals the payment
+     * intent amount to the cent. Render these (not the base `total`/`currency`
+     * above) when present. Absent = the checkout is charged in the store base
+     * currency (the fields above are authoritative).
+     *
+     * @example
+     * const c = await client.getCheckout(id);
+     * const shown = c.presentment
+     *   ? formatPrice(c.presentment.total, { currency: c.presentment.currency })
+     *   : formatPrice(c.total, { currency: c.currency });
+     */
+    presentment?: {
+        /** ISO-4217 currency the buyer is charged in (e.g. "EUR"). */
+        currency: string;
+        /** Subtotal in the presentment currency as string - use parseFloat(). */
+        subtotal: string;
+        /** Discount amount in the presentment currency as string. */
+        discountAmount: string;
+        /** Shipping cost in the presentment currency as string. */
+        shippingAmount: string;
+        /** Tax amount in the presentment currency as string. */
+        taxAmount: string;
+        /** Surcharge amount in the presentment currency as string. */
+        surchargeAmount: string;
+        /** Grand total in the presentment currency — equals the charged amount. */
+        total: string;
+        /** Base→presentment rate applied (buffer included), as string. */
+        fxChargingRate: string;
+        /** FX buffer percent applied to the mid-market rate, as string (or null). */
+        fxBufferPercent: string | null;
+    };
 }
 /**
  * Options for creating a checkout from a cart.
@@ -5493,6 +5531,7 @@ declare class BrainerceClient {
      */
     getProductBySlug(slug: string, options?: {
         locale?: string;
+        regionId?: string;
     }): Promise<Product>;
     /**
      * Get available categories for filtering products

package/dist/index.d.ts

@@ -2507,8 +2507,11 @@ interface Checkout {
     currency: string;
     /**
      * Region this checkout is associated with (multi-region commerce), or null.
-     * Recorded for reporting + provider scoping; currency follows the cart until
-     * FX price conversion lands.
+     * Recorded for reporting + provider scoping. FX-at-checkout: when the region
+     * currency differs from the store base and its provider can settle it
+     * (presentment-enabled — Stripe today), the buyer is charged in the region
+     * currency and the `presentment` overlay below carries the charged amounts;
+     * otherwise the checkout is charged in the store base currency.
      */
     regionId?: string | null;
     /** Subtotal as string - use parseFloat() */
@@ -2560,6 +2563,41 @@ interface Checkout {
      * @see ReservationInfo
      */
     reservation?: ReservationInfo;
+    /**
+     * FX-at-checkout presentment overlay. Present ONLY when the checkout's region
+     * uses a different currency from the store base AND that region charges in its
+     * own currency (presentment). These are the amounts the buyer will actually be
+     * CHARGED, in `presentment.currency` — `presentment.total` equals the payment
+     * intent amount to the cent. Render these (not the base `total`/`currency`
+     * above) when present. Absent = the checkout is charged in the store base
+     * currency (the fields above are authoritative).
+     *
+     * @example
+     * const c = await client.getCheckout(id);
+     * const shown = c.presentment
+     *   ? formatPrice(c.presentment.total, { currency: c.presentment.currency })
+     *   : formatPrice(c.total, { currency: c.currency });
+     */
+    presentment?: {
+        /** ISO-4217 currency the buyer is charged in (e.g. "EUR"). */
+        currency: string;
+        /** Subtotal in the presentment currency as string - use parseFloat(). */
+        subtotal: string;
+        /** Discount amount in the presentment currency as string. */
+        discountAmount: string;
+        /** Shipping cost in the presentment currency as string. */
+        shippingAmount: string;
+        /** Tax amount in the presentment currency as string. */
+        taxAmount: string;
+        /** Surcharge amount in the presentment currency as string. */
+        surchargeAmount: string;
+        /** Grand total in the presentment currency — equals the charged amount. */
+        total: string;
+        /** Base→presentment rate applied (buffer included), as string. */
+        fxChargingRate: string;
+        /** FX buffer percent applied to the mid-market rate, as string (or null). */
+        fxBufferPercent: string | null;
+    };
 }
 /**
  * Options for creating a checkout from a cart.
@@ -5493,6 +5531,7 @@ declare class BrainerceClient {
      */
     getProductBySlug(slug: string, options?: {
         locale?: string;
+        regionId?: string;
     }): Promise<Product>;
     /**
      * Get available categories for filtering products

package/dist/index.js

@@ -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

package/dist/index.mjs

@@ -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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brainerce",
-  "version": "1.37.0",
+  "version": "1.37.3",
   "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",