brainerce 1.15.0 → 1.17.0

package/dist/index.js

@@ -41,6 +41,7 @@ __export(index_exports, {
   getCartTotals: () => getCartTotals,
   getDescriptionContent: () => getDescriptionContent,
   getPriceDisplay: () => formatPrice,
+  getProductCustomizationFields: () => getProductCustomizationFields,
   getProductMetafield: () => getProductMetafield,
   getProductMetafieldValue: () => getProductMetafieldValue,
   getProductMetafieldsByType: () => getProductMetafieldsByType,
@@ -241,6 +242,41 @@ var BrainerceClient = class {
     this.onAuthError = options.onAuthError;
     this.hydrateSessionCart();
   }
+  // -------------------- Locale --------------------
+  /**
+   * Set the active locale for content translation.
+   * When set, all content endpoints (products, categories, brands) will return
+   * translated content for this locale, falling back to the store's default language.
+   *
+   * @param locale - Locale code (e.g., "he", "es", "fr") or undefined to clear
+   */
+  setLocale(locale) {
+    this.locale = locale;
+  }
+  /**
+   * Get the currently active locale.
+   */
+  getLocale() {
+    return this.locale;
+  }
+  /**
+   * Get the supported locales for this store.
+   * Fetches store info and returns the i18n config.
+   * Returns `[storeLanguage]` if multi-language is not enabled.
+   *
+   * @example
+   * ```typescript
+   * const locales = await client.getSupportedLocales();
+   * // ["en", "he", "es"]
+   * ```
+   */
+  async getSupportedLocales() {
+    const info = await this.getStoreInfo();
+    if (info.i18n?.enabled && info.i18n.supportedLocales.length > 0) {
+      return info.i18n.supportedLocales;
+    }
+    return [info.language];
+  }
   withGuards(result, type) {
     if (!isDevGuardsEnabled()) return result;
     if (result && typeof result.then === "function") {
@@ -350,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,
@@ -385,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);
     }
@@ -408,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";
       }
@@ -456,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);
     }
@@ -479,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}`;
       }
@@ -610,12 +661,25 @@ var BrainerceClient = class {
    * Get a single product by ID
    * Works in vibe-coded, storefront (public), and admin mode
    */
-  async getProduct(productId) {
+  async getProduct(productId, options) {
+    const headerOverrides = options?.locale ? { "Accept-Language": options.locale } : void 0;
     if (this.isVibeCodedMode()) {
-      return this.vibeCodedRequest("GET", `/products/${productId}`);
+      return this.vibeCodedRequest(
+        "GET",
+        `/products/${productId}`,
+        void 0,
+        void 0,
+        headerOverrides
+      );
     }
     if (this.storeId && !this.apiKey) {
-      return this.storefrontRequest("GET", `/products/${productId}`);
+      return this.storefrontRequest(
+        "GET",
+        `/products/${productId}`,
+        void 0,
+        void 0,
+        headerOverrides
+      );
     }
     return this.adminRequest("GET", `/api/v1/products/${productId}`);
   }
@@ -629,12 +693,25 @@ var BrainerceClient = class {
    * const product = await client.getProductBySlug('awesome-product-name');
    * ```
    */
-  async getProductBySlug(slug) {
+  async getProductBySlug(slug, options) {
+    const headerOverrides = options?.locale ? { "Accept-Language": options.locale } : void 0;
     if (this.isVibeCodedMode()) {
-      return this.vibeCodedRequest("GET", `/products/slug/${slug}`);
+      return this.vibeCodedRequest(
+        "GET",
+        `/products/slug/${slug}`,
+        void 0,
+        void 0,
+        headerOverrides
+      );
     }
     if (this.storeId && !this.apiKey) {
-      return this.storefrontRequest("GET", `/products/slug/${slug}`);
+      return this.storefrontRequest(
+        "GET",
+        `/products/slug/${slug}`,
+        void 0,
+        void 0,
+        headerOverrides
+      );
     }
     return this.adminRequest("GET", `/api/v1/products/by-slug/${slug}`);
   }
@@ -648,9 +725,10 @@ var BrainerceClient = class {
    * // categories is a tree structure with children
    * ```
    */
-  async getCategories() {
+  async getCategories(options) {
+    const headerOverrides = options?.locale ? { "Accept-Language": options.locale } : void 0;
     if (this.isVibeCodedMode()) {
-      return this.vibeCodedRequest("GET", "/categories");
+      return this.vibeCodedRequest("GET", "/categories", void 0, void 0, headerOverrides);
     }
     throw new BrainerceError("getCategories is only available in vibe-coded mode", 400);
   }
@@ -664,9 +742,10 @@ var BrainerceClient = class {
    * // Use brand IDs in getProducts({ brands: ['brand_id'] })
    * ```
    */
-  async getBrands() {
+  async getBrands(options) {
+    const headerOverrides = options?.locale ? { "Accept-Language": options.locale } : void 0;
     if (this.isVibeCodedMode()) {
-      return this.vibeCodedRequest("GET", "/brands");
+      return this.vibeCodedRequest("GET", "/brands", void 0, void 0, headerOverrides);
     }
     throw new BrainerceError("getBrands is only available in vibe-coded mode", 400);
   }
@@ -680,9 +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");
+      return this.vibeCodedRequest("GET", "/tags", void 0, void 0, headerOverrides);
     }
     throw new BrainerceError("getTags is only available in vibe-coded mode", 400);
   }
@@ -706,6 +786,22 @@ var BrainerceClient = class {
    * const suggestions = await client.getSearchSuggestions('dress', 3);
    * ```
    */
+  /**
+   * Get locale alternates for a product (for SEO hreflang tags).
+   * Returns the slug for each available locale.
+   *
+   * @example
+   * ```typescript
+   * const { alternates } = await client.getProductAlternates('product_id');
+   * // alternates = [{ locale: "en", slug: "running-shoes" }, { locale: "he", slug: "נעלי-ריצה" }]
+   * ```
+   */
+  async getProductAlternates(productId) {
+    if (this.storeId && !this.apiKey) {
+      return this.storefrontRequest("GET", `/products/${productId}/alternates`);
+    }
+    throw new BrainerceError("getProductAlternates is only available in storefront mode", 400);
+  }
   async getSearchSuggestions(query, limit) {
     if (!query || query.trim().length === 0) {
       return { products: [], categories: [] };
@@ -2372,17 +2468,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(
@@ -2406,17 +2506,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(
@@ -2492,14 +2596,16 @@ var BrainerceClient = class {
    *
    * @param cartId - Cart ID
    * @param bumpConfigId - Order bump config ID
+   * @param variantId - Optional variant ID (required when bump product has variants and no admin-locked variant)
    * @returns Updated cart
    */
-  async addOrderBump(cartId, bumpConfigId) {
+  async addOrderBump(cartId, bumpConfigId, variantId) {
+    const body = { bumpConfigId, ...variantId && { variantId } };
     if (this.isVibeCodedMode()) {
-      return this.vibeCodedRequest("POST", `/cart/${cartId}/bump`, { bumpConfigId });
+      return this.vibeCodedRequest("POST", `/cart/${cartId}/bump`, body);
     }
     if (this.storeId && !this.apiKey) {
-      return this.storefrontRequest("POST", `/cart/${cartId}/bump`, { bumpConfigId });
+      return this.storefrontRequest("POST", `/cart/${cartId}/bump`, body);
     }
     throw new BrainerceError("addOrderBump() requires vibe-coded or storefront mode", 400);
   }
@@ -2524,20 +2630,25 @@ var BrainerceClient = class {
    *
    * @param cartId - Cart ID
    * @param bundleOfferId - Bundle offer ID
+   * @param variantId - Optional variant ID (required when bundle product has variants and no admin-locked variant)
    * @returns Updated cart
    *
    * @example
    * ```typescript
    * const { bundles } = await client.getCartBundles('cart_123');
+   * // Simple product or locked variant:
    * const cart = await client.addBundleToCart('cart_123', bundles[0].id);
+   * // Product with variants (customer selects):
+   * const cart = await client.addBundleToCart('cart_123', bundles[0].id, selectedVariantId);
    * ```
    */
-  async addBundleToCart(cartId, bundleOfferId) {
+  async addBundleToCart(cartId, bundleOfferId, variantId) {
+    const body = { bundleOfferId, ...variantId && { variantId } };
     if (this.isVibeCodedMode()) {
-      return this.vibeCodedRequest("POST", `/cart/${cartId}/bundle`, { bundleOfferId });
+      return this.vibeCodedRequest("POST", `/cart/${cartId}/bundle`, body);
     }
     if (this.storeId && !this.apiKey) {
-      return this.storefrontRequest("POST", `/cart/${cartId}/bundle`, { bundleOfferId });
+      return this.storefrontRequest("POST", `/cart/${cartId}/bundle`, body);
     }
     throw new BrainerceError("addBundleToCart() requires vibe-coded or storefront mode", 400);
   }
@@ -3459,6 +3570,67 @@ var BrainerceClient = class {
     this.clearActiveCheckoutStorage();
     return result;
   }
+  // -------------------- Checkout Custom Fields --------------------
+  /**
+   * Get applicable custom field definitions for a checkout.
+   * Returns fields filtered by visibility conditions (delivery type, products in cart).
+   * Use these to render dynamic input fields in the checkout flow.
+   */
+  async getCheckoutCustomFields(checkoutId) {
+    if (this.isVibeCodedMode()) {
+      return this.vibeCodedRequest(
+        "GET",
+        `/checkout/${checkoutId}/custom-fields`
+      );
+    }
+    if (this.storeId && !this.apiKey) {
+      return this.storefrontRequest(
+        "GET",
+        `/checkout/${checkoutId}/custom-fields`
+      );
+    }
+    return this.adminRequest(
+      "GET",
+      `/api/v1/checkouts/${checkoutId}/custom-fields`
+    );
+  }
+  /**
+   * Set checkout custom field values and recalculate surcharges.
+   * The checkout total is automatically updated to include surcharges.
+   *
+   * @example
+   * ```typescript
+   * const checkout = await client.setCheckoutCustomFields(checkoutId, {
+   *   gift_wrapping: 'premium',  // SELECT field
+   *   floor_number: 5,           // NUMBER field
+   *   installation: true,        // BOOLEAN field
+   * });
+   * // checkout.surchargeAmount reflects the new surcharges
+   * // checkout.total is recalculated
+   * ```
+   */
+  async setCheckoutCustomFields(checkoutId, fields) {
+    const data = { fields };
+    if (this.isVibeCodedMode()) {
+      return this.vibeCodedRequest(
+        "PATCH",
+        `/checkout/${checkoutId}/custom-fields`,
+        data
+      );
+    }
+    if (this.storeId && !this.apiKey) {
+      return this.storefrontRequest(
+        "PATCH",
+        `/checkout/${checkoutId}/custom-fields`,
+        data
+      );
+    }
+    return this.adminRequest(
+      "PATCH",
+      `/api/v1/checkouts/${checkoutId}/custom-fields`,
+      data
+    );
+  }
   /**
    * Delete a checkout session. Releases inventory reservations and removes
    * payment records not yet linked to an order.
@@ -5502,6 +5674,53 @@ var BrainerceClient = class {
       `/api/v1/products/${productId}/metafields/${definitionId}`
     );
   }
+  // -------------------- Product Customization Fields (Admin) --------------------
+  /**
+   * Get customization fields assigned to a product.
+   * Requires Admin mode (apiKey).
+   */
+  async getProductCustomizationFields(productId) {
+    return this.adminRequest(
+      "GET",
+      `/api/v1/metafield-definitions/products/${productId}/customization-fields`
+    );
+  }
+  /**
+   * Set customization fields for a product (replaces all existing assignments).
+   * Only definitions marked as `isCustomerInput: true` can be assigned.
+   * Requires Admin mode (apiKey).
+   */
+  async setProductCustomizationFields(productId, definitionIds) {
+    return this.adminRequest(
+      "PATCH",
+      `/api/v1/metafield-definitions/products/${productId}/customization-fields`,
+      { definitionIds }
+    );
+  }
+  /**
+   * 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.
+   */
+  async uploadCustomizationFile(file) {
+    const formData = new FormData();
+    formData.append("file", file);
+    if (this.isVibeCodedMode()) {
+      return this.vibeCodedRequest(
+        "POST",
+        "/customization-upload",
+        formData
+      );
+    }
+    if (this.storeId && !this.apiKey) {
+      return this.storefrontRequest(
+        "POST",
+        "/customization-upload",
+        formData
+      );
+    }
+    throw new Error("uploadCustomizationFile requires storefront or vibe-coded mode");
+  }
   // -------------------- Team Management (Admin) - DEPRECATED --------------------
   // These account-level methods are deprecated. Use Store Team Management methods instead.
   /**
@@ -5696,7 +5915,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() {
@@ -6001,6 +6222,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;
@@ -6065,14 +6299,15 @@ function getVariantOptions(variant) {
   if (!variant?.attributes) return [];
   const internalKeys = /* @__PURE__ */ new Set([
     "id",
-    "shopifyVariantId",
-    "shopify_variant_id",
-    "shopifyInventoryItemId",
-    "woocommerceVariantId",
-    "metaVariantId",
-    "externalId"
+    "externalId",
+    "externalVariantId",
+    "externalInventoryItemId",
+    "platformVariantId"
   ]);
-  return Object.entries(variant.attributes).filter(([key, value]) => typeof value === "string" && !internalKeys.has(key)).map(([name, value]) => ({ name, value }));
+  const isPlatformKey = (key) => /^(shopify|woocommerce|tiktok|meta)[A-Z_]/.test(key) || key.includes("VariantId") || key.includes("InventoryItemId");
+  return Object.entries(variant.attributes).filter(
+    ([key, value]) => typeof value === "string" && !internalKeys.has(key) && !isPlatformKey(key)
+  ).map(([name, value]) => ({ name, value }));
 }
 function getProductSwatches(product) {
   if (!product?.productAttributeOptions) return [];
@@ -6122,6 +6357,9 @@ function getProductMetafieldValue(product, key) {
 function getProductMetafieldsByType(product, type) {
   return product.metafields?.filter((m) => m.type === type) || [];
 }
+function getProductCustomizationFields(product) {
+  return product.customizationFields ?? [];
+}
 function isCouponApplicableToProduct(coupon, productId) {
   const getIds = (refs) => refs?.map((ref) => ref.id) ?? [];
   const applicableProductIds = getIds(coupon.applicableProducts);
@@ -6143,6 +6381,7 @@ function isCouponApplicableToProduct(coupon, productId) {
   getCartTotals,
   getDescriptionContent,
   getPriceDisplay,
+  getProductCustomizationFields,
   getProductMetafield,
   getProductMetafieldValue,
   getProductMetafieldsByType,