brainerce 1.36.2 → 1.36.4

package/README.md

@@ -2206,7 +2206,8 @@ interface Checkout {
   subtotal: string;
   discountAmount: string;
   shippingAmount: string;
-  taxAmount: string;
+  taxAmount: string;          // "0" in inclusive (VAT) mode — see taxBreakdown.totalTax
+  taxBreakdown?: TaxBreakdown | null; // { totalTax, pricesIncludeTax, breakdown[] }
   total: string;
   couponCode?: string | null;
   items: CheckoutLineItem[];

package/dist/index.d.mts

@@ -1139,8 +1139,15 @@ interface Order {
     }> | null;
     /** Shipping cost */
     shippingAmount?: string | null;
-    /** Tax amount */
+    /** Tax amount. In inclusive (VAT) mode this is `"0"` — read the included VAT
+     *  from {@link Order.taxBreakdown}.totalTax instead. */
     taxAmount?: string | null;
+    /**
+     * Frozen tax breakdown snapshot. In inclusive (VAT) pricing `taxAmount` is 0
+     * and the real VAT lives here (`taxBreakdown.totalTax`, with
+     * `pricesIncludeTax: true`). Use it to display "incl. VAT" on receipts.
+     */
+    taxBreakdown?: TaxBreakdown | null;
     createdAt: string;
     /** Payment method used (e.g., "card", "paypal", "cash_on_delivery"). */
     paymentMethod?: string | null;
@@ -2204,6 +2211,12 @@ interface TaxBreakdown {
     total: number;
     /** Itemized tax breakdown */
     breakdown: TaxBreakdownItem[];
+    /**
+     * True when the store's prices already include tax (inclusive/VAT mode). In
+     * that mode `totalTax` is the VAT backed out of the displayed price — it is
+     * already part of `total`, not added on top. Display it as "incl. VAT".
+     */
+    pricesIncludeTax?: boolean;
     /** Currency code */
     currency?: string;
 }
@@ -5287,6 +5300,13 @@ declare class BrainerceClient {
     private sessionToken;
     private _sessionCartPromise;
     private _migrationDone;
+    /**
+     * Cart id to adopt from an abandoned-checkout recovery redirect. brainerce's
+     * recover endpoint 302s the shopper to `{storeDomain}/cart?brainerce_cart=<id>`;
+     * we pick it up on construction and adopt it as the active cart on first access,
+     * so the recovered cart shows up with zero per-store code.
+     */
+    private _pendingRecoverCartId;
     /** localStorage key for session cart reference (sessionToken + cartId) */
     private readonly SESSION_CART_KEY;
     /**
@@ -5582,8 +5602,12 @@ declare class BrainerceClient {
      */
     convertToVariable(productId: string): Promise<Product>;
     /**
-     * Convert a VARIABLE product to SIMPLE product
-     * Note: This will delete all variants
+     * Convert a VARIABLE product back to SIMPLE.
+     *
+     * The product must have **at most one variant**. That variant's price and
+     * inventory are merged back into the parent product, then the variant row is
+     * deleted. Throws `400` if more than one variant exists — delete the extras
+     * first. Throws `400` if the product is already SIMPLE.
      *
      * @example
      * ```typescript
@@ -5618,7 +5642,16 @@ declare class BrainerceClient {
      */
     createVariant(productId: string, data: CreateVariantDto): Promise<ProductVariant>;
     /**
-     * Bulk save variants (create, update, delete in one operation)
+     * Bulk save variants (create, update, delete in one atomic operation).
+     *
+     * **Auto-conversion:** if the product is currently `SIMPLE` and the payload
+     * includes new variants (entries without an `id`), the product is
+     * automatically converted to `VARIABLE` before the variants are created.
+     * You do **not** need to call `convertToVariable` first.
+     *
+     * To delete a variant include its `id` and set `isDeleted: true`.
+     * To update an existing variant supply its `id` with changed fields.
+     * Entries without an `id` (or with an `id` prefixed `new-`) are created.
      *
      * @example
      * ```typescript
@@ -7224,6 +7257,21 @@ declare class BrainerceClient {
      * @internal
      */
     private hydrateSessionCart;
+    /**
+     * Detect an abandoned-checkout recovery redirect. brainerce's recover endpoint
+     * sends the shopper to `{storeDomain}/cart?brainerce_cart=<cartId>`; we stash
+     * the id and adopt it (with its real session token) on the first cart access.
+     * @internal
+     */
+    private detectRecoverCartFromUrl;
+    /**
+     * Adopt a recovery-redirect cart if one is pending. Runs as the first step of
+     * session-cart resolution so the recovered cart wins over any stale local
+     * session. Returns the adopted cart, or null to fall through to normal
+     * resolution (no pending id, or the cart is no longer recoverable).
+     * @internal
+     */
+    private adoptPendingRecoverCart;
     /**
      * Persist session cart reference to localStorage.
      * @internal

package/dist/index.d.ts

@@ -1139,8 +1139,15 @@ interface Order {
     }> | null;
     /** Shipping cost */
     shippingAmount?: string | null;
-    /** Tax amount */
+    /** Tax amount. In inclusive (VAT) mode this is `"0"` — read the included VAT
+     *  from {@link Order.taxBreakdown}.totalTax instead. */
     taxAmount?: string | null;
+    /**
+     * Frozen tax breakdown snapshot. In inclusive (VAT) pricing `taxAmount` is 0
+     * and the real VAT lives here (`taxBreakdown.totalTax`, with
+     * `pricesIncludeTax: true`). Use it to display "incl. VAT" on receipts.
+     */
+    taxBreakdown?: TaxBreakdown | null;
     createdAt: string;
     /** Payment method used (e.g., "card", "paypal", "cash_on_delivery"). */
     paymentMethod?: string | null;
@@ -2204,6 +2211,12 @@ interface TaxBreakdown {
     total: number;
     /** Itemized tax breakdown */
     breakdown: TaxBreakdownItem[];
+    /**
+     * True when the store's prices already include tax (inclusive/VAT mode). In
+     * that mode `totalTax` is the VAT backed out of the displayed price — it is
+     * already part of `total`, not added on top. Display it as "incl. VAT".
+     */
+    pricesIncludeTax?: boolean;
     /** Currency code */
     currency?: string;
 }
@@ -5287,6 +5300,13 @@ declare class BrainerceClient {
     private sessionToken;
     private _sessionCartPromise;
     private _migrationDone;
+    /**
+     * Cart id to adopt from an abandoned-checkout recovery redirect. brainerce's
+     * recover endpoint 302s the shopper to `{storeDomain}/cart?brainerce_cart=<id>`;
+     * we pick it up on construction and adopt it as the active cart on first access,
+     * so the recovered cart shows up with zero per-store code.
+     */
+    private _pendingRecoverCartId;
     /** localStorage key for session cart reference (sessionToken + cartId) */
     private readonly SESSION_CART_KEY;
     /**
@@ -5582,8 +5602,12 @@ declare class BrainerceClient {
      */
     convertToVariable(productId: string): Promise<Product>;
     /**
-     * Convert a VARIABLE product to SIMPLE product
-     * Note: This will delete all variants
+     * Convert a VARIABLE product back to SIMPLE.
+     *
+     * The product must have **at most one variant**. That variant's price and
+     * inventory are merged back into the parent product, then the variant row is
+     * deleted. Throws `400` if more than one variant exists — delete the extras
+     * first. Throws `400` if the product is already SIMPLE.
      *
      * @example
      * ```typescript
@@ -5618,7 +5642,16 @@ declare class BrainerceClient {
      */
     createVariant(productId: string, data: CreateVariantDto): Promise<ProductVariant>;
     /**
-     * Bulk save variants (create, update, delete in one operation)
+     * Bulk save variants (create, update, delete in one atomic operation).
+     *
+     * **Auto-conversion:** if the product is currently `SIMPLE` and the payload
+     * includes new variants (entries without an `id`), the product is
+     * automatically converted to `VARIABLE` before the variants are created.
+     * You do **not** need to call `convertToVariable` first.
+     *
+     * To delete a variant include its `id` and set `isDeleted: true`.
+     * To update an existing variant supply its `id` with changed fields.
+     * Entries without an `id` (or with an `id` prefixed `new-`) are created.
      *
      * @example
      * ```typescript
@@ -7224,6 +7257,21 @@ declare class BrainerceClient {
      * @internal
      */
     private hydrateSessionCart;
+    /**
+     * Detect an abandoned-checkout recovery redirect. brainerce's recover endpoint
+     * sends the shopper to `{storeDomain}/cart?brainerce_cart=<cartId>`; we stash
+     * the id and adopt it (with its real session token) on the first cart access.
+     * @internal
+     */
+    private detectRecoverCartFromUrl;
+    /**
+     * Adopt a recovery-redirect cart if one is pending. Runs as the first step of
+     * session-cart resolution so the recovered cart wins over any stale local
+     * session. Returns the adopted cart, or null to fall through to normal
+     * resolution (no pending id, or the cart is no longer recoverable).
+     * @internal
+     */
+    private adoptPendingRecoverCart;
     /**
      * Persist session cart reference to localStorage.
      * @internal

package/dist/index.js

@@ -234,6 +234,13 @@ var BrainerceClient = class {
     this.sessionToken = null;
     this._sessionCartPromise = null;
     this._migrationDone = false;
+    /**
+     * Cart id to adopt from an abandoned-checkout recovery redirect. brainerce's
+     * recover endpoint 302s the shopper to `{storeDomain}/cart?brainerce_cart=<id>`;
+     * we pick it up on construction and adopt it as the active cart on first access,
+     * so the recovered cart shows up with zero per-store code.
+     */
+    this._pendingRecoverCartId = null;
     /** localStorage key for session cart reference (sessionToken + cartId) */
     this.SESSION_CART_KEY = "brainerce_session";
     /**
@@ -648,6 +655,7 @@ var BrainerceClient = class {
     this.proxyMode = options.proxyMode || false;
     this.onAuthError = options.onAuthError;
     this.hydrateSessionCart();
+    this.detectRecoverCartFromUrl();
   }
   // -------------------- Locale --------------------
   /**
@@ -1379,8 +1387,12 @@ var BrainerceClient = class {
     );
   }
   /**
-   * Convert a VARIABLE product to SIMPLE product
-   * Note: This will delete all variants
+   * Convert a VARIABLE product back to SIMPLE.
+   *
+   * The product must have **at most one variant**. That variant's price and
+   * inventory are merged back into the parent product, then the variant row is
+   * deleted. Throws `400` if more than one variant exists — delete the extras
+   * first. Throws `400` if the product is already SIMPLE.
    *
    * @example
    * ```typescript
@@ -1435,7 +1447,16 @@ var BrainerceClient = class {
     );
   }
   /**
-   * Bulk save variants (create, update, delete in one operation)
+   * Bulk save variants (create, update, delete in one atomic operation).
+   *
+   * **Auto-conversion:** if the product is currently `SIMPLE` and the payload
+   * includes new variants (entries without an `id`), the product is
+   * automatically converted to `VARIABLE` before the variants are created.
+   * You do **not** need to call `convertToVariable` first.
+   *
+   * To delete a variant include its `id` and set `isDeleted: true`.
+   * To update an existing variant supply its `id` with changed fields.
+   * Entries without an `id` (or with an `id` prefixed `new-`) are created.
    *
    * @example
    * ```typescript
@@ -3953,6 +3974,48 @@ var BrainerceClient = class {
     } catch {
     }
   }
+  /**
+   * Detect an abandoned-checkout recovery redirect. brainerce's recover endpoint
+   * sends the shopper to `{storeDomain}/cart?brainerce_cart=<cartId>`; we stash
+   * the id and adopt it (with its real session token) on the first cart access.
+   * @internal
+   */
+  detectRecoverCartFromUrl() {
+    if (typeof window === "undefined" || !window.location?.search) return;
+    try {
+      const recoverId = new URLSearchParams(window.location.search).get("brainerce_cart");
+      if (recoverId) this._pendingRecoverCartId = recoverId;
+    } catch {
+    }
+  }
+  /**
+   * Adopt a recovery-redirect cart if one is pending. Runs as the first step of
+   * session-cart resolution so the recovered cart wins over any stale local
+   * session. Returns the adopted cart, or null to fall through to normal
+   * resolution (no pending id, or the cart is no longer recoverable).
+   * @internal
+   */
+  async adoptPendingRecoverCart() {
+    const recoverId = this._pendingRecoverCartId;
+    if (!recoverId) return null;
+    this._pendingRecoverCartId = null;
+    try {
+      const cart = await this.getCart(recoverId);
+      if (cart.status !== "ACTIVE") return null;
+      if (cart.sessionToken) {
+        this.saveSessionCart({
+          sessionToken: cart.sessionToken,
+          cartId: cart.id,
+          itemCount: cart.itemCount
+        });
+      } else {
+        this.sessionCartId = cart.id;
+      }
+      return cart;
+    } catch {
+      return null;
+    }
+  }
   /**
    * Persist session cart reference to localStorage.
    * @internal
@@ -4052,6 +4115,8 @@ var BrainerceClient = class {
   }
   /** @internal */
   async _getOrCreateSessionCartImpl() {
+    const recovered = await this.adoptPendingRecoverCart();
+    if (recovered) return recovered;
     const migrated = await this.migrateLocalCartToSession();
     if (migrated) return migrated;
     if (this.sessionCartId && this.sessionToken) {
@@ -4285,9 +4350,13 @@ var BrainerceClient = class {
    */
   async smartGetCart(options) {
     if (this.isCustomerLoggedIn()) {
+      if (this._pendingRecoverCartId) {
+        const recovered = await this.adoptPendingRecoverCart();
+        if (recovered) return recovered;
+      }
       return this.getOrCreateCustomerCart(options);
     } else {
-      if (!this.sessionToken) {
+      if (!this.sessionToken && !this._pendingRecoverCartId) {
         return this.emptyCart();
       }
       return this.getOrCreateSessionCart(options);

package/dist/index.mjs

@@ -164,6 +164,13 @@ var BrainerceClient = class {
     this.sessionToken = null;
     this._sessionCartPromise = null;
     this._migrationDone = false;
+    /**
+     * Cart id to adopt from an abandoned-checkout recovery redirect. brainerce's
+     * recover endpoint 302s the shopper to `{storeDomain}/cart?brainerce_cart=<id>`;
+     * we pick it up on construction and adopt it as the active cart on first access,
+     * so the recovered cart shows up with zero per-store code.
+     */
+    this._pendingRecoverCartId = null;
     /** localStorage key for session cart reference (sessionToken + cartId) */
     this.SESSION_CART_KEY = "brainerce_session";
     /**
@@ -578,6 +585,7 @@ var BrainerceClient = class {
     this.proxyMode = options.proxyMode || false;
     this.onAuthError = options.onAuthError;
     this.hydrateSessionCart();
+    this.detectRecoverCartFromUrl();
   }
   // -------------------- Locale --------------------
   /**
@@ -1309,8 +1317,12 @@ var BrainerceClient = class {
     );
   }
   /**
-   * Convert a VARIABLE product to SIMPLE product
-   * Note: This will delete all variants
+   * Convert a VARIABLE product back to SIMPLE.
+   *
+   * The product must have **at most one variant**. That variant's price and
+   * inventory are merged back into the parent product, then the variant row is
+   * deleted. Throws `400` if more than one variant exists — delete the extras
+   * first. Throws `400` if the product is already SIMPLE.
    *
    * @example
    * ```typescript
@@ -1365,7 +1377,16 @@ var BrainerceClient = class {
     );
   }
   /**
-   * Bulk save variants (create, update, delete in one operation)
+   * Bulk save variants (create, update, delete in one atomic operation).
+   *
+   * **Auto-conversion:** if the product is currently `SIMPLE` and the payload
+   * includes new variants (entries without an `id`), the product is
+   * automatically converted to `VARIABLE` before the variants are created.
+   * You do **not** need to call `convertToVariable` first.
+   *
+   * To delete a variant include its `id` and set `isDeleted: true`.
+   * To update an existing variant supply its `id` with changed fields.
+   * Entries without an `id` (or with an `id` prefixed `new-`) are created.
    *
    * @example
    * ```typescript
@@ -3883,6 +3904,48 @@ var BrainerceClient = class {
     } catch {
     }
   }
+  /**
+   * Detect an abandoned-checkout recovery redirect. brainerce's recover endpoint
+   * sends the shopper to `{storeDomain}/cart?brainerce_cart=<cartId>`; we stash
+   * the id and adopt it (with its real session token) on the first cart access.
+   * @internal
+   */
+  detectRecoverCartFromUrl() {
+    if (typeof window === "undefined" || !window.location?.search) return;
+    try {
+      const recoverId = new URLSearchParams(window.location.search).get("brainerce_cart");
+      if (recoverId) this._pendingRecoverCartId = recoverId;
+    } catch {
+    }
+  }
+  /**
+   * Adopt a recovery-redirect cart if one is pending. Runs as the first step of
+   * session-cart resolution so the recovered cart wins over any stale local
+   * session. Returns the adopted cart, or null to fall through to normal
+   * resolution (no pending id, or the cart is no longer recoverable).
+   * @internal
+   */
+  async adoptPendingRecoverCart() {
+    const recoverId = this._pendingRecoverCartId;
+    if (!recoverId) return null;
+    this._pendingRecoverCartId = null;
+    try {
+      const cart = await this.getCart(recoverId);
+      if (cart.status !== "ACTIVE") return null;
+      if (cart.sessionToken) {
+        this.saveSessionCart({
+          sessionToken: cart.sessionToken,
+          cartId: cart.id,
+          itemCount: cart.itemCount
+        });
+      } else {
+        this.sessionCartId = cart.id;
+      }
+      return cart;
+    } catch {
+      return null;
+    }
+  }
   /**
    * Persist session cart reference to localStorage.
    * @internal
@@ -3982,6 +4045,8 @@ var BrainerceClient = class {
   }
   /** @internal */
   async _getOrCreateSessionCartImpl() {
+    const recovered = await this.adoptPendingRecoverCart();
+    if (recovered) return recovered;
     const migrated = await this.migrateLocalCartToSession();
     if (migrated) return migrated;
     if (this.sessionCartId && this.sessionToken) {
@@ -4215,9 +4280,13 @@ var BrainerceClient = class {
    */
   async smartGetCart(options) {
     if (this.isCustomerLoggedIn()) {
+      if (this._pendingRecoverCartId) {
+        const recovered = await this.adoptPendingRecoverCart();
+        if (recovered) return recovered;
+      }
       return this.getOrCreateCustomerCart(options);
     } else {
-      if (!this.sessionToken) {
+      if (!this.sessionToken && !this._pendingRecoverCartId) {
         return this.emptyCart();
       }
       return this.getOrCreateSessionCart(options);

package/package.json

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