brainerce 1.16.0 → 1.18.0

package/dist/index.js

@@ -386,6 +386,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,
@@ -421,7 +424,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);
     }
@@ -444,6 +447,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";
       }
@@ -492,7 +501,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);
     }
@@ -515,6 +524,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}`;
       }
@@ -616,7 +631,6 @@ var BrainerceClient = class {
       maxPrice: params?.maxPrice,
       sortBy: params?.sortBy,
       sortOrder: params?.sortOrder,
-      locale: params?.locale || this.locale,
       // Admin-only params
       type: params?.type
     };
@@ -648,13 +662,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) {
@@ -662,7 +677,8 @@ var BrainerceClient = class {
         "GET",
         `/products/${productId}`,
         void 0,
-        localeParams
+        void 0,
+        headerOverrides
       );
     }
     return this.adminRequest("GET", `/api/v1/products/${productId}`);
@@ -678,13 +694,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) {
@@ -692,7 +709,8 @@ var BrainerceClient = class {
         "GET",
         `/products/slug/${slug}`,
         void 0,
-        localeParams
+        void 0,
+        headerOverrides
       );
     }
     return this.adminRequest("GET", `/api/v1/products/by-slug/${slug}`);
@@ -708,9 +726,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);
   }
@@ -725,9 +743,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);
   }
@@ -741,11 +759,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);
   }
@@ -789,7 +806,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",
@@ -2095,30 +2112,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) {
@@ -2451,17 +2520,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(
@@ -2485,17 +2558,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(
@@ -2758,11 +2835,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;
     }
@@ -2895,10 +2982,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;
         }
@@ -2911,6 +2998,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 {
@@ -2962,7 +3052,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 {
@@ -2970,7 +3061,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;
@@ -2983,20 +3075,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);
     }
   }
   /**
@@ -5673,9 +5773,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();
@@ -5890,7 +6016,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() {
@@ -6195,6 +6323,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;