brainerce 1.16.0 → 1.18.0

package/dist/index.mjs

@@ -325,6 +325,9 @@ var BrainerceClient = class {
       if (this.origin) {
         headers["Origin"] = this.origin;
       }
+      if (this.locale) {
+        headers["Accept-Language"] = this.locale;
+      }
       const response = await fetch(url.toString(), {
         method,
         headers,
@@ -360,7 +363,7 @@ var BrainerceClient = class {
   /**
    * Make a request to the Vibe-Coded API (public, uses connectionId)
    */
-  async vibeCodedRequest(method, path, body, queryParams) {
+  async vibeCodedRequest(method, path, body, queryParams, headerOverrides) {
     if (!this.connectionId) {
       throw new BrainerceError("connectionId is required for vibe-coded requests", 400);
     }
@@ -383,6 +386,12 @@ var BrainerceClient = class {
       if (this.origin) {
         headers["Origin"] = this.origin;
       }
+      if (this.locale) {
+        headers["Accept-Language"] = this.locale;
+      }
+      if (headerOverrides) {
+        Object.assign(headers, headerOverrides);
+      }
       if (this.proxyMode && method !== "GET") {
         headers["X-Requested-With"] = "brainerce";
       }
@@ -431,7 +440,7 @@ var BrainerceClient = class {
   /**
    * Make a request to the Storefront API (public, uses storeId)
    */
-  async storefrontRequest(method, path, body, queryParams) {
+  async storefrontRequest(method, path, body, queryParams, headerOverrides) {
     if (!this.storeId) {
       throw new BrainerceError("storeId is required for storefront requests", 400);
     }
@@ -454,6 +463,12 @@ var BrainerceClient = class {
       if (this.origin) {
         headers["Origin"] = this.origin;
       }
+      if (this.locale) {
+        headers["Accept-Language"] = this.locale;
+      }
+      if (headerOverrides) {
+        Object.assign(headers, headerOverrides);
+      }
       if (this.customerToken) {
         headers["Authorization"] = `Bearer ${this.customerToken}`;
       }
@@ -555,7 +570,6 @@ var BrainerceClient = class {
       maxPrice: params?.maxPrice,
       sortBy: params?.sortBy,
       sortOrder: params?.sortOrder,
-      locale: params?.locale || this.locale,
       // Admin-only params
       type: params?.type
     };
@@ -587,13 +601,14 @@ var BrainerceClient = class {
    * Works in vibe-coded, storefront (public), and admin mode
    */
   async getProduct(productId, options) {
-    const localeParams = { locale: options?.locale || this.locale };
+    const headerOverrides = options?.locale ? { "Accept-Language": options.locale } : void 0;
     if (this.isVibeCodedMode()) {
       return this.vibeCodedRequest(
         "GET",
         `/products/${productId}`,
         void 0,
-        localeParams
+        void 0,
+        headerOverrides
       );
     }
     if (this.storeId && !this.apiKey) {
@@ -601,7 +616,8 @@ var BrainerceClient = class {
         "GET",
         `/products/${productId}`,
         void 0,
-        localeParams
+        void 0,
+        headerOverrides
       );
     }
     return this.adminRequest("GET", `/api/v1/products/${productId}`);
@@ -617,13 +633,14 @@ var BrainerceClient = class {
    * ```
    */
   async getProductBySlug(slug, options) {
-    const localeParams = { locale: options?.locale || this.locale };
+    const headerOverrides = options?.locale ? { "Accept-Language": options.locale } : void 0;
     if (this.isVibeCodedMode()) {
       return this.vibeCodedRequest(
         "GET",
         `/products/slug/${slug}`,
         void 0,
-        localeParams
+        void 0,
+        headerOverrides
       );
     }
     if (this.storeId && !this.apiKey) {
@@ -631,7 +648,8 @@ var BrainerceClient = class {
         "GET",
         `/products/slug/${slug}`,
         void 0,
-        localeParams
+        void 0,
+        headerOverrides
       );
     }
     return this.adminRequest("GET", `/api/v1/products/by-slug/${slug}`);
@@ -647,9 +665,9 @@ var BrainerceClient = class {
    * ```
    */
   async getCategories(options) {
-    const localeParams = { locale: options?.locale || this.locale };
+    const headerOverrides = options?.locale ? { "Accept-Language": options.locale } : void 0;
     if (this.isVibeCodedMode()) {
-      return this.vibeCodedRequest("GET", "/categories", void 0, localeParams);
+      return this.vibeCodedRequest("GET", "/categories", void 0, void 0, headerOverrides);
     }
     throw new BrainerceError("getCategories is only available in vibe-coded mode", 400);
   }
@@ -664,9 +682,9 @@ var BrainerceClient = class {
    * ```
    */
   async getBrands(options) {
-    const localeParams = { locale: options?.locale || this.locale };
+    const headerOverrides = options?.locale ? { "Accept-Language": options.locale } : void 0;
     if (this.isVibeCodedMode()) {
-      return this.vibeCodedRequest("GET", "/brands", void 0, localeParams);
+      return this.vibeCodedRequest("GET", "/brands", void 0, void 0, headerOverrides);
     }
     throw new BrainerceError("getBrands is only available in vibe-coded mode", 400);
   }
@@ -680,11 +698,10 @@ var BrainerceClient = class {
    * // Use tag IDs in getProducts({ tags: ['tag_id'] })
    * ```
    */
-  async getTags() {
+  async getTags(options) {
+    const headerOverrides = options?.locale ? { "Accept-Language": options.locale } : void 0;
     if (this.isVibeCodedMode()) {
-      return this.vibeCodedRequest("GET", "/tags", void 0, {
-        locale: this.locale
-      });
+      return this.vibeCodedRequest("GET", "/tags", void 0, void 0, headerOverrides);
     }
     throw new BrainerceError("getTags is only available in vibe-coded mode", 400);
   }
@@ -728,7 +745,7 @@ var BrainerceClient = class {
     if (!query || query.trim().length === 0) {
       return { products: [], categories: [] };
     }
-    const queryParams = { q: query, limit, locale: this.locale };
+    const queryParams = { q: query, limit };
     if (this.isVibeCodedMode()) {
       return this.vibeCodedRequest(
         "GET",
@@ -2034,30 +2051,82 @@ var BrainerceClient = class {
   }
   /**
    * Get a cart by ID
+   *
+   * @param cartId - The cart ID
+   * @param options - Optional settings. Use `include` to fetch related data in a single request.
+   *
+   * @example
+   * ```typescript
+   * // Basic cart fetch
+   * const cart = await client.getCart('cart_123');
+   *
+   * // Fetch cart with recommendations, upgrades, and bundles in one call
+   * const enriched = await client.getCart('cart_123', {
+   *   include: ['recommendations', 'upgrades', 'bundles'],
+   * });
+   * console.log(enriched.recommendations); // { recommendations: [...] }
+   * console.log(enriched.upgrades);        // { upgrades: { ... } }
+   * console.log(enriched.bundles);         // { bundles: [...] }
+   * ```
    */
-  async getCart(cartId) {
+  async getCart(cartId, options) {
     if (cartId === this.VIRTUAL_LOCAL_CART_ID) {
       console.warn('getCart("__local__") is deprecated. Use smartGetCart() instead.');
       return this.withGuards(this.localCartToCart(this.getLocalCart()), "cart");
     }
+    const queryParams = options?.include?.length ? { include: options.include.join(",") } : void 0;
     if (this.isVibeCodedMode()) {
-      return this.withGuards(this.vibeCodedRequest("GET", `/cart/${cartId}`), "cart");
+      return this.withGuards(
+        this.vibeCodedRequest("GET", `/cart/${cartId}`, void 0, queryParams),
+        "cart"
+      );
     }
     if (this.storeId && !this.apiKey) {
-      return this.withGuards(this.storefrontRequest("GET", `/cart/${cartId}`), "cart");
+      return this.withGuards(
+        this.storefrontRequest("GET", `/cart/${cartId}`, void 0, queryParams),
+        "cart"
+      );
     }
-    return this.withGuards(this.adminRequest("GET", `/api/v1/cart/${cartId}`), "cart");
+    return this.withGuards(
+      this.adminRequest("GET", `/api/v1/cart/${cartId}`, void 0, queryParams),
+      "cart"
+    );
   }
   /**
-   * Add an item to the cart
+   * Add an item to the cart.
+   *
+   * If the product has `customizationFields` (merchant-defined buyer input
+   * like engraving text, uploaded photos, select options), pass the buyer's
+   * values in `metadata`. Keys must match each field's `key`. For `IMAGE` /
+   * `GALLERY` types, upload the file first via `uploadCustomizationFile()`
+   * and pass the returned URL. The server validates every value against its
+   * `MetafieldDefinition` and rejects the request with HTTP 400 if anything
+   * fails (type mismatch, required missing, not in `enumValues`, etc.).
+   *
+   * Values are snapshotted onto the order line at checkout — later edits to
+   * the field definition do not retroactively change existing orders.
    *
    * @example
    * ```typescript
+   * // Product with no customization fields
    * const cart = await client.addToCart('cart_123', {
    *   productId: 'prod_abc',
    *   quantity: 2,
    *   notes: 'Gift wrap please',
    * });
+   *
+   * // Product WITH customization fields (engraving + photo + select + multi)
+   * const { url: photoUrl } = await client.uploadCustomizationFile(file);
+   * const cart = await client.addToCart('cart_123', {
+   *   productId: 'prod_mug',
+   *   quantity: 1,
+   *   metadata: {
+   *     engraving_text: 'Happy Birthday!',  // TEXT
+   *     frame_color: 'Gold',                // SELECT (must be in enumValues)
+   *     upload_photo: photoUrl,             // IMAGE
+   *     addons: ['Gift wrap'],              // MULTI_SELECT (always array)
+   *   },
+   * });
    * ```
    */
   async addToCart(cartId, item) {
@@ -2390,17 +2459,21 @@ var BrainerceClient = class {
    * ```
    */
   async getProductRecommendations(productId, type) {
-    const params = type ? `?type=${type}` : "";
+    const queryParams = type ? { type } : void 0;
     if (this.isVibeCodedMode()) {
       return this.vibeCodedRequest(
         "GET",
-        `/products/${productId}/recommendations${params}`
+        `/products/${productId}/recommendations`,
+        void 0,
+        queryParams
       );
     }
     if (this.storeId && !this.apiKey) {
       return this.storefrontRequest(
         "GET",
-        `/products/${productId}/recommendations${params}`
+        `/products/${productId}/recommendations`,
+        void 0,
+        queryParams
       );
     }
     throw new BrainerceError(
@@ -2424,17 +2497,21 @@ var BrainerceClient = class {
    * ```
    */
   async getCartRecommendations(cartId, limit) {
-    const params = limit ? `?limit=${limit}` : "";
+    const queryParams = limit ? { limit } : void 0;
     if (this.isVibeCodedMode()) {
       return this.vibeCodedRequest(
         "GET",
-        `/cart/${cartId}/recommendations${params}`
+        `/cart/${cartId}/recommendations`,
+        void 0,
+        queryParams
       );
     }
     if (this.storeId && !this.apiKey) {
       return this.storefrontRequest(
         "GET",
-        `/cart/${cartId}/recommendations${params}`
+        `/cart/${cartId}/recommendations`,
+        void 0,
+        queryParams
       );
     }
     throw new BrainerceError(
@@ -2697,11 +2774,21 @@ var BrainerceClient = class {
    * Uses promise dedup lock to prevent race conditions on parallel calls.
    * @internal
    */
-  async getOrCreateSessionCart() {
-    if (this._sessionCartPromise) return this._sessionCartPromise;
+  async getOrCreateSessionCart(options) {
+    if (this._sessionCartPromise) {
+      const base = await this._sessionCartPromise;
+      if (options?.include?.length && base.id) {
+        return this.getCart(base.id, options);
+      }
+      return base;
+    }
     this._sessionCartPromise = this._getOrCreateSessionCartImpl();
     try {
-      return await this._sessionCartPromise;
+      const base = await this._sessionCartPromise;
+      if (options?.include?.length && base.id) {
+        return this.getCart(base.id, options);
+      }
+      return base;
     } finally {
       this._sessionCartPromise = null;
     }
@@ -2834,10 +2921,10 @@ var BrainerceClient = class {
    * Caches the cart ID for subsequent calls
    * @internal
    */
-  async getOrCreateCustomerCart() {
+  async getOrCreateCustomerCart(options) {
     if (this.customerCartId) {
       try {
-        const existingCart = await this.getCart(this.customerCartId);
+        const existingCart = await this.getCart(this.customerCartId, options);
         if (existingCart.status === "ACTIVE") {
           return existingCart;
         }
@@ -2850,6 +2937,9 @@ var BrainerceClient = class {
       const cart2 = await this.fetchCustomerCart();
       if (cart2.status === "ACTIVE") {
         this.customerCartId = cart2.id;
+        if (options?.include?.length) {
+          return this.getCart(cart2.id, options);
+        }
         return cart2;
       }
     } catch {
@@ -2901,7 +2991,8 @@ var BrainerceClient = class {
       const updated = await this.addToCart(cart.id, {
         productId: item.productId,
         variantId: item.variantId,
-        quantity: item.quantity
+        quantity: item.quantity,
+        metadata: item.metadata
       });
       return updated;
     } else {
@@ -2909,7 +3000,8 @@ var BrainerceClient = class {
       const updated = await this.addToCart(cart.id, {
         productId: item.productId,
         variantId: item.variantId,
-        quantity: item.quantity
+        quantity: item.quantity,
+        metadata: item.metadata
       });
       this.updateSessionCartItemCount(updated.items?.length ?? 0);
       return updated;
@@ -2922,20 +3014,28 @@ var BrainerceClient = class {
    * - **Guest with session**: Returns server-side session cart
    * - **Guest without session**: Returns empty cart (no server call, cart created lazily on add)
    *
+   * @param options - Optional. Use `include` to fetch recommendations, upgrades, and bundles
+   *   in a single request instead of separate calls.
+   *
    * @example
    * ```typescript
    * const cart = await client.smartGetCart();
    * console.log('Items:', cart.items.length);
+   *
+   * // With includes — single request for cart + extras
+   * const enriched = await client.smartGetCart({
+   *   include: ['recommendations', 'upgrades', 'bundles'],
+   * });
    * ```
    */
-  async smartGetCart() {
+  async smartGetCart(options) {
     if (this.isCustomerLoggedIn()) {
-      return this.getOrCreateCustomerCart();
+      return this.getOrCreateCustomerCart(options);
     } else {
       if (!this.sessionToken) {
         return this.emptyCart();
       }
-      return this.getOrCreateSessionCart();
+      return this.getOrCreateSessionCart(options);
     }
   }
   /**
@@ -5612,9 +5712,35 @@ var BrainerceClient = class {
     );
   }
   /**
-   * Upload a file for product customization (e.g., customer logo for printing).
-   * Available in storefront and vibe-coded modes.
-   * Returns the uploaded file URL and key.
+   * Upload a buyer-submitted file (engraving photo, custom image, etc.) for a
+   * product customization field of type `IMAGE` or `GALLERY`. The returned `url`
+   * is what you pass back in the add-to-cart `metadata` payload.
+   *
+   * Available in storefront and vibe-coded modes — no customer login required.
+   *
+   * Server rules:
+   * - `image/*` MIME only. Other types → HTTP 400.
+   * - Max 5 MB per file.
+   * - Throttled to 10 uploads / minute per IP → HTTP 429.
+   * - Retention: at least 7 days. If the cart never becomes an order, the file
+   *   is reclaimed automatically. Once the order exists, the file is kept for
+   *   order-history purposes.
+   *
+   * @example
+   * ```ts
+   * // On a product page with IMAGE/GALLERY customization fields:
+   * const { url } = await client.uploadCustomizationFile(fileInput.files[0]);
+   *
+   * // Then include the URL in the add-to-cart metadata:
+   * await client.addToCart(cart.id, {
+   *   productId: product.id,
+   *   quantity: 1,
+   *   metadata: {
+   *     engraving_text: 'Happy Birthday!',
+   *     upload_photo: url,
+   *   },
+   * });
+   * ```
    */
   async uploadCustomizationFile(file) {
     const formData = new FormData();
@@ -5829,7 +5955,9 @@ var BrainerceClient = class {
     return this.adminRequest("PUT", "/api/v1/email/settings", data);
   }
   /**
-   * Get all email templates for the store
+   * Get all email templates for the store, grouped by (eventType, language).
+   * Response includes the store's primary language and supported languages so
+   * the caller can render a locale selector.
    * Requires Admin mode (apiKey)
    */
   async getEmailTemplates() {
@@ -6134,6 +6262,19 @@ function getProductPriceInfo(product) {
   if (!product) {
     return { price: 0, originalPrice: 0, isOnSale: false, discountAmount: 0, discountPercent: 0 };
   }
+  if (product.discount) {
+    const ruleOriginal = parseFloat(product.discount.originalPrice) || 0;
+    const ruleDiscounted = parseFloat(product.discount.discountedPrice) || 0;
+    const ruleAmount = Math.max(0, ruleOriginal - ruleDiscounted);
+    const rulePercent = ruleOriginal > 0 ? Math.round(ruleAmount / ruleOriginal * 100) : 0;
+    return {
+      price: ruleDiscounted,
+      originalPrice: ruleOriginal,
+      isOnSale: ruleDiscounted < ruleOriginal,
+      discountAmount: ruleAmount,
+      discountPercent: rulePercent
+    };
+  }
   const basePrice = parseFloat(product.basePrice) || 0;
   const salePrice = product.salePrice ? parseFloat(product.salePrice) : null;
   const isOnSale = salePrice !== null && salePrice < basePrice;

package/package.json

@@ -1,76 +1,76 @@
-{
-  "name": "brainerce",
-  "version": "1.16.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",
-  "types": "dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "require": "./dist/index.js",
-      "import": "./dist/index.mjs"
-    }
-  },
-  "files": [
-    "dist",
-    "README.md"
-  ],
-  "scripts": {
-    "build": "tsup src/index.ts --format cjs,esm --dts",
-    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
-    "lint": "eslint \"src/**/*.ts\"",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "prepublishOnly": "pnpm build"
-  },
-  "keywords": [
-    "brainerce",
-    "e-commerce",
-    "ecommerce",
-    "sdk",
-    "vibe-coding",
-    "vibe-coded",
-    "ai-commerce",
-    "storefront",
-    "headless-commerce",
-    "multi-platform",
-    "shopify",
-    "tiktok",
-    "cursor",
-    "lovable",
-    "v0",
-    "cart",
-    "checkout",
-    "products",
-    "sync"
-  ],
-  "author": "Brainerce",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/brainerce/brainerce.git",
-    "directory": "packages/sdk"
-  },
-  "homepage": "https://brainerce.com",
-  "bugs": {
-    "url": "https://github.com/brainerce/brainerce/issues"
-  },
-  "devDependencies": {
-    "@types/node": "^25.0.3",
-    "@typescript-eslint/eslint-plugin": "^8.50.1",
-    "@typescript-eslint/parser": "^8.50.1",
-    "eslint": "^9.39.2",
-    "tsup": "^8.0.0",
-    "typescript": "^5.3.0",
-    "vitest": "^1.0.0"
-  },
-  "peerDependencies": {
-    "typescript": ">=4.7.0"
-  },
-  "peerDependenciesMeta": {
-    "typescript": {
-      "optional": true
-    }
-  }
-}
+{
+  "name": "brainerce",
+  "version": "1.18.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",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "lint": "eslint \"src/**/*.ts\"",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "pnpm build"
+  },
+  "keywords": [
+    "brainerce",
+    "e-commerce",
+    "ecommerce",
+    "sdk",
+    "vibe-coding",
+    "vibe-coded",
+    "ai-commerce",
+    "storefront",
+    "headless-commerce",
+    "multi-platform",
+    "shopify",
+    "tiktok",
+    "cursor",
+    "lovable",
+    "v0",
+    "cart",
+    "checkout",
+    "products",
+    "sync"
+  ],
+  "author": "Brainerce",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/brainerce/brainerce.git",
+    "directory": "packages/sdk"
+  },
+  "homepage": "https://brainerce.com",
+  "bugs": {
+    "url": "https://github.com/brainerce/brainerce/issues"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.3",
+    "@typescript-eslint/eslint-plugin": "^8.50.1",
+    "@typescript-eslint/parser": "^8.50.1",
+    "eslint": "^9.39.2",
+    "tsup": "^8.0.0",
+    "typescript": "^5.3.0",
+    "vitest": "^1.0.0"
+  },
+  "peerDependencies": {
+    "typescript": ">=4.7.0"
+  },
+  "peerDependenciesMeta": {
+    "typescript": {
+      "optional": true
+    }
+  }
+}