brainerce 1.53.1 → 1.54.0

package/README.md

@@ -280,7 +280,7 @@ The SDK exports these utility functions for common UI tasks:
 | `getProductPriceInfo(product)`                 | Get price + sale info + discount % (falls back to `priceMin` when `basePrice=0` on VARIABLE) | `{ price, isOnSale, discountPercent }`                 |
 | `getVariantPrice(variant, basePrice)`          | Get variant price with fallback                                                              | `getVariantPrice(variant, '29.99')` → `34.99`          |
 | `getCartTotals(cart, shippingPrice?)`          | Calculate cart subtotal/discount/total                                                       | `{ subtotal, discount, shipping, total }`              |
-| `getCartItemName(item)`                        | Get name from nested cart item                                                               | `getCartItemName(item)` → `"Blue T-Shirt"`             |
+| `getCartItemName(item)`                        | Get name from nested cart item (product + variant)                                           | `getCartItemName(item)` → `"Blue T-Shirt - Large"`     |
 | `getCartItemImage(item)`                       | Get image URL from cart item                                                                 | `getCartItemImage(item)` → `"https://..."`             |
 | `getVariantOptions(variant)`                   | Get variant attributes as array                                                              | `[{ name: "Color", value: "Red" }]`                    |
 | `isCouponApplicableToProduct(coupon, product)` | Check if coupon applies                                                                      | `isCouponApplicableToProduct(coupon, product)`         |
@@ -4542,6 +4542,20 @@ await client.updateRegionPaymentProviders(eu.id, ['app_inst_stripe', 'app_inst_p
 // Which installed providers can serve this region's countries?
 const compatible = await client.getRegionCompatibleProviders(eu.id);
 
+// Regional pricing — hand-set the price pair per product/variant in the
+// REGION's currency ($24.99 instead of the converted $24.63). A manual pair
+// replaces the whole converted pair; no entry = automatic FX conversion.
+// Applies only when the region actually charges its currency (presentment) —
+// then storefronts see it in displayPrice/displaySalePrice and checkout
+// charges pinned lines at it verbatim. salePrice must be lower than price.
+const { data: prices } = await client.getRegionPrices(eu.id, { page: 1 });
+await client.upsertRegionPrices(eu.id, [
+  { productId: 'prod_tshirt', price: 24.99, salePrice: 19.99 },
+  { productId: 'prod_tshirt', variantId: 'var_l', price: 26.99 },
+  { productId: 'prod_mug', remove: true }, // back to automatic conversion
+]);
+await client.deleteRegionPrice(eu.id, 'rp_123');
+
 // Pure client-side helper (no network) — pick a region for a country code
 const dest = client.detectRegion('DE', regions); // → the EU region, or the default, or null
 

package/dist/index.d.mts

@@ -1131,8 +1131,14 @@ declare function getCartTotals(cart: Pick<Cart, 'subtotal' | 'discountAmount'> |
 };
 /**
  * Get the display name for a cart item.
- * Handles the nested product/variant structure - uses variant name if available,
- * otherwise falls back to product name.
+ * Handles the nested product/variant structure - the product name identifies the
+ * line, with the variant name appended as a qualifier: `"Blue T-Shirt - Large"`.
+ *
+ * The suffix is omitted for products with no variant, and for variants whose name
+ * was copied from the product (so the name never renders twice).
+ *
+ * Need the two parts separately — e.g. to render the variant on its own line —
+ * read `item.product.name` and `item.variant?.name` directly.
  *
  * @param item - The cart item
  * @returns The display name for the item
@@ -1140,7 +1146,7 @@ declare function getCartTotals(cart: Pick<Cart, 'subtotal' | 'discountAmount'> |
  * @example
  * ```typescript
  * cart.items.forEach(item => {
- *   const name = getCartItemName(item);
+ *   const name = getCartItemName(item); // "Blue T-Shirt - Large"
  *   console.log(`${name} x ${item.quantity}`);
  * });
  * ```
@@ -4630,6 +4636,37 @@ interface AutoRegionResponse {
  * still runs at checkout against the full shipping address (state / postal /
  * per-class). Render with an "Estimate" affordance.
  */
+/**
+ * Manual per-region price override (regional pricing) — the merchant's
+ * hand-set price pair for one product or variant in one region, denominated
+ * in the REGION's currency. Replaces the automatic FX conversion for regions
+ * that actually charge their currency (presentment). Admin (api-key) surface.
+ */
+interface RegionPrice {
+    id: string;
+    productId: string;
+    /** null = the product-level price (covers every variant without its own row). */
+    variantId: string | null;
+    /** Regular price in the region currency (Decimal string). */
+    price: string;
+    /** Sale price in the region currency — always lower than price; null = no regional sale. */
+    salePrice: string | null;
+    updatedAt: string;
+}
+/** One bulk entry for `upsertRegionPrices`. `remove: true` deletes the row. */
+interface RegionPriceEntry {
+    productId: string;
+    variantId?: string;
+    /** Required unless `remove` — regular price in the region currency. */
+    price?: number;
+    /** Optional sale price — must be lower than `price`. */
+    salePrice?: number;
+    remove?: boolean;
+}
+interface UpsertRegionPricesResult {
+    upserted: number;
+    removed: number;
+}
 interface TaxEstimateResponse {
     appliesTax: boolean;
     /** Percent — e.g. 18 for 18%. `null` when no matching rule. */
@@ -10474,6 +10511,24 @@ declare class BrainerceClient {
         appId: string;
         name?: string | null;
     }>>;
+    /**
+     * List a region's manual price overrides (regional pricing, admin). Prices
+     * are in the region's currency; `variantId: null` rows are product-level.
+     */
+    getRegionPrices(regionId: string, params?: {
+        productId?: string;
+        page?: number;
+        limit?: number;
+    }): Promise<PaginatedResponse<RegionPrice>>;
+    /**
+     * Bulk upsert/remove manual price overrides for a region (admin). Each
+     * entry: `price` = regular, `salePrice` = sale (must be lower), in the
+     * REGION's currency; `remove: true` deletes. A product/variant with no
+     * entry keeps automatic FX conversion.
+     */
+    upsertRegionPrices(regionId: string, entries: RegionPriceEntry[]): Promise<UpsertRegionPricesResult>;
+    /** Delete one manual price override by id (admin). */
+    deleteRegionPrice(regionId: string, priceId: string): Promise<void>;
     /**
      * List the store's ACTIVE regions (public, no apiKey). Works in storeId and
      * vibe-coded modes. Returns only storefront-safe fields (no internal flags).
@@ -11126,7 +11181,7 @@ declare class BrainerceError extends Error {
     constructor(message: string, statusCode: number, details?: unknown);
 }
 
-declare const SDK_VERSION = "1.53.1";
+declare const SDK_VERSION = "1.54.0";
 
 /**
  * Verify a webhook signature from Brainerce

package/dist/index.d.ts

@@ -1131,8 +1131,14 @@ declare function getCartTotals(cart: Pick<Cart, 'subtotal' | 'discountAmount'> |
 };
 /**
  * Get the display name for a cart item.
- * Handles the nested product/variant structure - uses variant name if available,
- * otherwise falls back to product name.
+ * Handles the nested product/variant structure - the product name identifies the
+ * line, with the variant name appended as a qualifier: `"Blue T-Shirt - Large"`.
+ *
+ * The suffix is omitted for products with no variant, and for variants whose name
+ * was copied from the product (so the name never renders twice).
+ *
+ * Need the two parts separately — e.g. to render the variant on its own line —
+ * read `item.product.name` and `item.variant?.name` directly.
  *
  * @param item - The cart item
  * @returns The display name for the item
@@ -1140,7 +1146,7 @@ declare function getCartTotals(cart: Pick<Cart, 'subtotal' | 'discountAmount'> |
  * @example
  * ```typescript
  * cart.items.forEach(item => {
- *   const name = getCartItemName(item);
+ *   const name = getCartItemName(item); // "Blue T-Shirt - Large"
  *   console.log(`${name} x ${item.quantity}`);
  * });
  * ```
@@ -4630,6 +4636,37 @@ interface AutoRegionResponse {
  * still runs at checkout against the full shipping address (state / postal /
  * per-class). Render with an "Estimate" affordance.
  */
+/**
+ * Manual per-region price override (regional pricing) — the merchant's
+ * hand-set price pair for one product or variant in one region, denominated
+ * in the REGION's currency. Replaces the automatic FX conversion for regions
+ * that actually charge their currency (presentment). Admin (api-key) surface.
+ */
+interface RegionPrice {
+    id: string;
+    productId: string;
+    /** null = the product-level price (covers every variant without its own row). */
+    variantId: string | null;
+    /** Regular price in the region currency (Decimal string). */
+    price: string;
+    /** Sale price in the region currency — always lower than price; null = no regional sale. */
+    salePrice: string | null;
+    updatedAt: string;
+}
+/** One bulk entry for `upsertRegionPrices`. `remove: true` deletes the row. */
+interface RegionPriceEntry {
+    productId: string;
+    variantId?: string;
+    /** Required unless `remove` — regular price in the region currency. */
+    price?: number;
+    /** Optional sale price — must be lower than `price`. */
+    salePrice?: number;
+    remove?: boolean;
+}
+interface UpsertRegionPricesResult {
+    upserted: number;
+    removed: number;
+}
 interface TaxEstimateResponse {
     appliesTax: boolean;
     /** Percent — e.g. 18 for 18%. `null` when no matching rule. */
@@ -10474,6 +10511,24 @@ declare class BrainerceClient {
         appId: string;
         name?: string | null;
     }>>;
+    /**
+     * List a region's manual price overrides (regional pricing, admin). Prices
+     * are in the region's currency; `variantId: null` rows are product-level.
+     */
+    getRegionPrices(regionId: string, params?: {
+        productId?: string;
+        page?: number;
+        limit?: number;
+    }): Promise<PaginatedResponse<RegionPrice>>;
+    /**
+     * Bulk upsert/remove manual price overrides for a region (admin). Each
+     * entry: `price` = regular, `salePrice` = sale (must be lower), in the
+     * REGION's currency; `remove: true` deletes. A product/variant with no
+     * entry keeps automatic FX conversion.
+     */
+    upsertRegionPrices(regionId: string, entries: RegionPriceEntry[]): Promise<UpsertRegionPricesResult>;
+    /** Delete one manual price override by id (admin). */
+    deleteRegionPrice(regionId: string, priceId: string): Promise<void>;
     /**
      * List the store's ACTIVE regions (public, no apiKey). Works in storeId and
      * vibe-coded modes. Returns only storefront-safe fields (no internal flags).
@@ -11126,7 +11181,7 @@ declare class BrainerceError extends Error {
     constructor(message: string, statusCode: number, details?: unknown);
 }
 
-declare const SDK_VERSION = "1.53.1";
+declare const SDK_VERSION = "1.54.0";
 
 /**
  * Verify a webhook signature from Brainerce

package/dist/index.js

@@ -98,7 +98,7 @@ var CART_GUARDS = [
 var CART_ITEM_GUARDS = [
   {
     property: "name",
-    message: 'CartItem has no "name" field. Use item.product.name or getCartItemName(item).\nImport: import { getCartItemName } from "brainerce";'
+    message: 'CartItem has no "name" field. Use getCartItemName(item) for the full\n"Product - Variant" label, or item.product.name for the product name alone.\nImport: import { getCartItemName } from "brainerce";'
   },
   {
     property: "price",
@@ -201,7 +201,7 @@ function isDevGuardsEnabled() {
 }
 
 // src/version.ts
-var SDK_VERSION = "1.53.1";
+var SDK_VERSION = "1.54.0";
 
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.brainerce.com";
@@ -8260,6 +8260,42 @@ var _BrainerceClient = class _BrainerceClient {
       `/api/v1/regions/${encodePathSegment(regionId)}/compatible-providers`
     );
   }
+  /**
+   * List a region's manual price overrides (regional pricing, admin). Prices
+   * are in the region's currency; `variantId: null` rows are product-level.
+   */
+  async getRegionPrices(regionId, params = {}) {
+    return this.adminRequest(
+      "GET",
+      `/api/v1/regions/${encodePathSegment(regionId)}/prices`,
+      void 0,
+      {
+        productId: params.productId,
+        page: params.page,
+        limit: params.limit
+      }
+    );
+  }
+  /**
+   * Bulk upsert/remove manual price overrides for a region (admin). Each
+   * entry: `price` = regular, `salePrice` = sale (must be lower), in the
+   * REGION's currency; `remove: true` deletes. A product/variant with no
+   * entry keeps automatic FX conversion.
+   */
+  async upsertRegionPrices(regionId, entries) {
+    return this.adminRequest(
+      "PUT",
+      `/api/v1/regions/${encodePathSegment(regionId)}/prices`,
+      { entries }
+    );
+  }
+  /** Delete one manual price override by id (admin). */
+  async deleteRegionPrice(regionId, priceId) {
+    await this.adminRequest(
+      "DELETE",
+      `/api/v1/regions/${encodePathSegment(regionId)}/prices/${encodePathSegment(priceId)}`
+    );
+  }
   // -------------------- 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
@@ -10209,7 +10245,10 @@ function getCartTotals(cart, shippingPrice) {
   return { subtotal, discount, shipping, total };
 }
 function getCartItemName(item) {
-  return item.variant?.name || item.product.name;
+  const productName = item.product.name;
+  const variantName = item.variant?.name?.trim();
+  if (!variantName || variantName === productName) return productName;
+  return `${productName} - ${variantName}`;
 }
 function getCartItemImage(item) {
   if (item.variant?.image) {

package/dist/index.mjs

@@ -12,7 +12,7 @@ var CART_GUARDS = [
 var CART_ITEM_GUARDS = [
   {
     property: "name",
-    message: 'CartItem has no "name" field. Use item.product.name or getCartItemName(item).\nImport: import { getCartItemName } from "brainerce";'
+    message: 'CartItem has no "name" field. Use getCartItemName(item) for the full\n"Product - Variant" label, or item.product.name for the product name alone.\nImport: import { getCartItemName } from "brainerce";'
   },
   {
     property: "price",
@@ -115,7 +115,7 @@ function isDevGuardsEnabled() {
 }
 
 // src/version.ts
-var SDK_VERSION = "1.53.1";
+var SDK_VERSION = "1.54.0";
 
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.brainerce.com";
@@ -8174,6 +8174,42 @@ var _BrainerceClient = class _BrainerceClient {
       `/api/v1/regions/${encodePathSegment(regionId)}/compatible-providers`
     );
   }
+  /**
+   * List a region's manual price overrides (regional pricing, admin). Prices
+   * are in the region's currency; `variantId: null` rows are product-level.
+   */
+  async getRegionPrices(regionId, params = {}) {
+    return this.adminRequest(
+      "GET",
+      `/api/v1/regions/${encodePathSegment(regionId)}/prices`,
+      void 0,
+      {
+        productId: params.productId,
+        page: params.page,
+        limit: params.limit
+      }
+    );
+  }
+  /**
+   * Bulk upsert/remove manual price overrides for a region (admin). Each
+   * entry: `price` = regular, `salePrice` = sale (must be lower), in the
+   * REGION's currency; `remove: true` deletes. A product/variant with no
+   * entry keeps automatic FX conversion.
+   */
+  async upsertRegionPrices(regionId, entries) {
+    return this.adminRequest(
+      "PUT",
+      `/api/v1/regions/${encodePathSegment(regionId)}/prices`,
+      { entries }
+    );
+  }
+  /** Delete one manual price override by id (admin). */
+  async deleteRegionPrice(regionId, priceId) {
+    await this.adminRequest(
+      "DELETE",
+      `/api/v1/regions/${encodePathSegment(regionId)}/prices/${encodePathSegment(priceId)}`
+    );
+  }
   // -------------------- 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
@@ -10123,7 +10159,10 @@ function getCartTotals(cart, shippingPrice) {
   return { subtotal, discount, shipping, total };
 }
 function getCartItemName(item) {
-  return item.variant?.name || item.product.name;
+  const productName = item.product.name;
+  const variantName = item.variant?.name?.trim();
+  if (!variantName || variantName === productName) return productName;
+  return `${productName} - ${variantName}`;
 }
 function getCartItemImage(item) {
   if (item.variant?.image) {

package/package.json

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