brainerce 1.15.0 → 1.17.0

package/dist/index.mjs

@@ -181,6 +181,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") {
@@ -290,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,
@@ -325,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);
     }
@@ -348,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";
       }
@@ -396,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);
     }
@@ -419,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}`;
       }
@@ -550,12 +600,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}`);
   }
@@ -569,12 +632,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}`);
   }
@@ -588,9 +664,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);
   }
@@ -604,9 +681,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);
   }
@@ -620,9 +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");
+      return this.vibeCodedRequest("GET", "/tags", void 0, void 0, headerOverrides);
     }
     throw new BrainerceError("getTags is only available in vibe-coded mode", 400);
   }
@@ -646,6 +725,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: [] };
@@ -2312,17 +2407,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(
@@ -2346,17 +2445,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(
@@ -2432,14 +2535,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);
   }
@@ -2464,20 +2569,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);
   }
@@ -3399,6 +3509,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.
@@ -5442,6 +5613,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.
   /**
@@ -5636,7 +5854,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() {
@@ -5941,6 +6161,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;
@@ -6005,14 +6238,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 [];
@@ -6062,6 +6296,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);
@@ -6082,6 +6319,7 @@ export {
   getCartTotals,
   getDescriptionContent,
   formatPrice as getPriceDisplay,
+  getProductCustomizationFields,
   getProductMetafield,
   getProductMetafieldValue,
   getProductMetafieldsByType,

package/package.json

@@ -1,76 +1,76 @@
-{
-  "name": "brainerce",
-  "version": "1.15.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.17.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
+    }
+  }
+}