brainerce 1.15.0 → 1.16.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") {
@@ -580,6 +616,7 @@ var BrainerceClient = class {
       maxPrice: params?.maxPrice,
       sortBy: params?.sortBy,
       sortOrder: params?.sortOrder,
+      locale: params?.locale || this.locale,
       // Admin-only params
       type: params?.type
     };
@@ -610,12 +647,23 @@ 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 localeParams = { locale: options?.locale || this.locale };
     if (this.isVibeCodedMode()) {
-      return this.vibeCodedRequest("GET", `/products/${productId}`);
+      return this.vibeCodedRequest(
+        "GET",
+        `/products/${productId}`,
+        void 0,
+        localeParams
+      );
     }
     if (this.storeId && !this.apiKey) {
-      return this.storefrontRequest("GET", `/products/${productId}`);
+      return this.storefrontRequest(
+        "GET",
+        `/products/${productId}`,
+        void 0,
+        localeParams
+      );
     }
     return this.adminRequest("GET", `/api/v1/products/${productId}`);
   }
@@ -629,12 +677,23 @@ var BrainerceClient = class {
    * const product = await client.getProductBySlug('awesome-product-name');
    * ```
    */
-  async getProductBySlug(slug) {
+  async getProductBySlug(slug, options) {
+    const localeParams = { locale: options?.locale || this.locale };
     if (this.isVibeCodedMode()) {
-      return this.vibeCodedRequest("GET", `/products/slug/${slug}`);
+      return this.vibeCodedRequest(
+        "GET",
+        `/products/slug/${slug}`,
+        void 0,
+        localeParams
+      );
     }
     if (this.storeId && !this.apiKey) {
-      return this.storefrontRequest("GET", `/products/slug/${slug}`);
+      return this.storefrontRequest(
+        "GET",
+        `/products/slug/${slug}`,
+        void 0,
+        localeParams
+      );
     }
     return this.adminRequest("GET", `/api/v1/products/by-slug/${slug}`);
   }
@@ -648,9 +707,10 @@ var BrainerceClient = class {
    * // categories is a tree structure with children
    * ```
    */
-  async getCategories() {
+  async getCategories(options) {
+    const localeParams = { locale: options?.locale || this.locale };
     if (this.isVibeCodedMode()) {
-      return this.vibeCodedRequest("GET", "/categories");
+      return this.vibeCodedRequest("GET", "/categories", void 0, localeParams);
     }
     throw new BrainerceError("getCategories is only available in vibe-coded mode", 400);
   }
@@ -664,9 +724,10 @@ var BrainerceClient = class {
    * // Use brand IDs in getProducts({ brands: ['brand_id'] })
    * ```
    */
-  async getBrands() {
+  async getBrands(options) {
+    const localeParams = { locale: options?.locale || this.locale };
     if (this.isVibeCodedMode()) {
-      return this.vibeCodedRequest("GET", "/brands");
+      return this.vibeCodedRequest("GET", "/brands", void 0, localeParams);
     }
     throw new BrainerceError("getBrands is only available in vibe-coded mode", 400);
   }
@@ -682,7 +743,9 @@ var BrainerceClient = class {
    */
   async getTags() {
     if (this.isVibeCodedMode()) {
-      return this.vibeCodedRequest("GET", "/tags");
+      return this.vibeCodedRequest("GET", "/tags", void 0, {
+        locale: this.locale
+      });
     }
     throw new BrainerceError("getTags is only available in vibe-coded mode", 400);
   }
@@ -706,11 +769,27 @@ 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: [] };
     }
-    const queryParams = { q: query, limit };
+    const queryParams = { q: query, limit, locale: this.locale };
     if (this.isVibeCodedMode()) {
       return this.vibeCodedRequest(
         "GET",
@@ -2492,14 +2571,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 +2605,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 +3545,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 +5649,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.
   /**
@@ -6065,14 +6259,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 +6317,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 +6341,7 @@ function isCouponApplicableToProduct(coupon, productId) {
   getCartTotals,
   getDescriptionContent,
   getPriceDisplay,
+  getProductCustomizationFields,
   getProductMetafield,
   getProductMetafieldValue,
   getProductMetafieldsByType,