brainerce 1.17.0 → 1.18.0

package/dist/index.js

@@ -2112,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) {
@@ -2783,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;
     }
@@ -2920,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;
         }
@@ -2936,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 {
@@ -2987,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 {
@@ -2995,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;
@@ -3008,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);
     }
   }
   /**
@@ -5698,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();

package/dist/index.mjs

@@ -2051,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) {
@@ -2722,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;
     }
@@ -2859,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;
         }
@@ -2875,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 {
@@ -2926,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 {
@@ -2934,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;
@@ -2947,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);
     }
   }
   /**
@@ -5637,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();

package/package.json

@@ -1,76 +1,76 @@
-{
-  "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
-    }
-  }
-}
+{
+  "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
+    }
+  }
+}