npm - brainerce - Versions diffs - 1.36.4 → 1.37.0 - Mend

brainerce 1.36.4 → 1.37.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (6) hide show

package/README.md CHANGED Viewed

@@ -100,6 +100,8 @@ Violating any of these causes production incidents or broken orders. Read them b
 - NEVER hardcode currency, locale, or language strings — read them from `getStoreInfo()`.
 - NEVER format prices with `toFixed(2)` — use `formatPrice()` from the SDK.
 - When i18n is enabled, call `client.setLocale(locale)` at app init and include a language switcher. For RTL locales (`he`, `ar`), set `<html dir="rtl">` — do NOT add `flex-row-reverse` on top.
+- Call `setLocale()` **before `createCheckout()`** — the order captures the active locale (`order.locale`), which drives the confirmation-email language AND the product names shown in order history. Without it, orders and their emails fall back to the store default language. Search also needs the locale active to match translated names.
+- Built-in order emails are localized for English and Hebrew; for other languages the merchant must add a custom email template per language (otherwise the email falls back to English).
 ### Type safety
@@ -2074,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)
@@ -3564,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();
 ```
@@ -3612,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 CHANGED Viewed

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

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

@@ -955,7 +955,7 @@ var BrainerceClient = class {
     if (!this.storeId) {
       throw new BrainerceError("storeId is required for storefront requests", 400);
     }
-    const url = new URL(`${this.baseUrl}/stores/${encodePathSegment(this.storeId)}${path}`);
+    const url = new URL(`${this.baseUrl}/api/stores/${encodePathSegment(this.storeId)}${path}`);
     if (queryParams) {
       Object.entries(queryParams).forEach(([key, value]) => {
         if (value !== void 0) {
@@ -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 CHANGED Viewed

@@ -885,7 +885,7 @@ var BrainerceClient = class {
     if (!this.storeId) {
       throw new BrainerceError("storeId is required for storefront requests", 400);
     }
-    const url = new URL(`${this.baseUrl}/stores/${encodePathSegment(this.storeId)}${path}`);
+    const url = new URL(`${this.baseUrl}/api/stores/${encodePathSegment(this.storeId)}${path}`);
     if (queryParams) {
       Object.entries(queryParams).forEach(([key, value]) => {
         if (value !== void 0) {
@@ -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 CHANGED Viewed

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