brainerce 1.38.0 → 1.39.0

package/README.md

@@ -1526,10 +1526,19 @@ fields.forEach((field) => {
   // field.required: whether customer must fill this in
   // field.minLength, field.maxLength: validation for text fields
   // field.minValue, field.maxValue: validation for number fields
-  // field.enumValues: allowed options for dropdown fields
+  // field.enumValues: CustomizationFieldOption[] for SELECT/MULTI_SELECT
+  //   each option: { label: string, value: string, swatchColor?: string, swatchImageUrl?: string }
+  //   use option.value for metadata submission, option.label for display
   // field.defaultValue: default value to pre-fill
 });
 
+// Render SELECT options using label/value (not string[] anymore):
+for (const option of field.enumValues ?? []) {
+  // option.label → show to user (e.g. "Gold")
+  // option.value → submit in metadata (e.g. "gold")
+  // option.swatchColor → hex color for color swatch UI, if set
+}
+
 // Customer fills in values, then add to cart with metadata
 await client.addToCart(cartId, {
   productId: product.id,
@@ -1537,10 +1546,23 @@ await client.addToCart(cartId, {
   metadata: {
     cake_text: 'Happy Birthday!', // TEXT field
     font_color: '#FF0000', // COLOR field
+    frame_color: 'gold', // SELECT — use option.value
   },
 });
 ```
 
+**Display customizations in cart/checkout — no extra API call needed:**
+
+`CartItem` and `CheckoutLineItem` both include a `customizations` object with resolved labels. Use it directly — no need to call `getProduct()` per item.
+
+```typescript
+// Works for CartItem, CheckoutLineItem, and OrderItem — same shape
+const summary = Object.values(item.customizations ?? {})
+  .map(c => `${c.label}: ${Array.isArray(c.value) ? c.value.join(', ') : c.value}`)
+  .join(' | ');
+// e.g. "Frame color: Gold | Add-ons: Gift wrap, Engraving"
+```
+
 **For IMAGE/GALLERY fields**, upload the file first:
 
 ```typescript
@@ -3550,6 +3572,26 @@ await client.createZoneShippingRate('zone_id', {
 });
 ```
 
+### App Store Shipping (Shippo)
+
+Once a merchant installs the Shippo app from the Brainerce App Store and connects their own
+Shippo account, live carrier rates appear automatically at checkout. Billing goes directly
+to the merchant's Shippo account.
+
+```typescript
+// After an order is placed, purchase a shipping label:
+const label = await admin.createShippingLabel(orderId, {
+  shippoRateObjectId: 'rate_8f123456789abcdef', // Shippo rate.object_id from checkout rates
+});
+
+console.log(label.labelUrl);       // PDF label URL for printing
+console.log(label.trackingNumber); // Auto-populated on the order
+console.log(label.carrier);        // e.g. 'USPS', 'UPS', 'FedEx'
+```
+
+The `trackingNumber` is stored on the `Order` automatically — customers see it in their
+order history without any extra integration work.
+
 ### Tax Configuration
 
 `rate` is a **whole percentage** (`7.25` = 7.25%, not `0.0725`). A rate may target

package/dist/index.d.mts

@@ -1806,6 +1806,20 @@ interface CartItem {
     notes?: string | null;
     /** Optional metadata for this line item */
     metadata?: Record<string, unknown> | null;
+    /**
+     * Resolved customer input field values with merchant-defined labels.
+     * Mirrors `OrderItem.customizations` — same shape, live (not order-frozen).
+     * Present only when the item has at least one customization value set.
+     *
+     * @example
+     * // Display "Color: Silver / Size: 45" without an extra getProduct() call:
+     * Object.entries(item.customizations ?? {}).map(([, c]) => `${c.label}: ${c.value}`)
+     */
+    customizations?: Record<string, {
+        label: string;
+        value: string | string[];
+        type: string;
+    }>;
     /**
      * Per-line modifier breakdown — present when the line was added with
      * modifier `selections`. Snapshot taken at add-time; immutable to catalog
@@ -2326,6 +2340,20 @@ interface CheckoutLineItem {
     notes?: string | null;
     /** Custom metadata including customer input field values */
     metadata?: Record<string, unknown> | null;
+    /**
+     * Resolved customer input field values with merchant-defined labels.
+     * Mirrors `OrderItem.customizations` — same shape, live (not order-frozen).
+     * Present only when the item has at least one customization value set.
+     *
+     * @example
+     * // Render "Color: Silver / Ring size: 45" in your checkout summary:
+     * Object.entries(item.customizations ?? {}).map(([, c]) => `${c.label}: ${c.value}`)
+     */
+    customizations?: Record<string, {
+        label: string;
+        value: string | string[];
+        type: string;
+    }>;
 }
 /**
  * Represents an available shipping rate/method for checkout.
@@ -3983,7 +4011,8 @@ interface MetafieldDefinition {
     maxLength?: number | null;
     minValue?: number | null;
     maxValue?: number | null;
-    enumValues?: string[] | null;
+    /** Allowed values for SELECT / MULTI_SELECT fields, with optional swatch metadata. */
+    enumValues?: CustomizationFieldOption[] | null;
     defaultValue?: string | null;
     position: number;
     isActive: boolean;
@@ -4067,7 +4096,8 @@ interface PublicMetafieldDefinition {
      * Pair with `getProducts({ metafields: { [key]: [...] } })`.
      */
     filterable?: boolean;
-    enumValues?: string[];
+    /** Allowed values for SELECT / MULTI_SELECT fields, with optional swatch metadata. */
+    enumValues?: CustomizationFieldOption[];
     minLength?: number | null;
     maxLength?: number | null;
     minValue?: number | null;
@@ -4075,6 +4105,20 @@ interface PublicMetafieldDefinition {
     defaultValue?: string | null;
     position: number;
 }
+/**
+ * A single selectable option for a SELECT or MULTI_SELECT customization field.
+ * Legacy string-only `enumValues` arrays are automatically promoted to this shape.
+ */
+interface CustomizationFieldOption {
+    /** Human-readable label shown in the storefront UI (e.g., "Rose Gold"). */
+    label: string;
+    /** Value stored in `CartItem.metadata` and carried through to `OrderItem.customizations`. */
+    value: string;
+    /** Optional CSS hex color for rendering a color swatch (e.g., "#B76E79"). */
+    swatchColor?: string | null;
+    /** Optional image URL for rendering a texture/image swatch. */
+    swatchImageUrl?: string | null;
+}
 /**
  * Customer-facing input field definition assigned to a specific product.
  * Returned in product responses to tell the storefront which input fields to render.
@@ -4090,7 +4134,11 @@ interface ProductCustomizationField {
     maxLength?: number | null;
     minValue?: number | null;
     maxValue?: number | null;
-    enumValues?: string[];
+    /**
+     * Allowed values for SELECT / MULTI_SELECT fields.
+     * Each option includes a label, value, and optional swatch color/image.
+     */
+    enumValues?: CustomizationFieldOption[];
     defaultValue?: string | null;
     position: number;
 }
@@ -5972,6 +6020,29 @@ declare class BrainerceClient {
      * ```
      */
     updateOrderShipping(orderId: string, data: UpdateOrderShippingDto): Promise<Order>;
+    /**
+     * Create a shipping label for an order via the installed App Store shipping app.
+     * Pass the rate ID returned from checkout rate shopping. Billing goes directly
+     * to the merchant's carrier account — Brainerce is not a billing intermediary.
+     *
+     * @example
+     * ```typescript
+     * const label = await client.createShippingLabel('order_abc', {
+     *   rateId: 'rate_8f123456789abcdef',
+     * });
+     * console.log('Label URL:', label.labelUrl);
+     * console.log('Tracking:', label.trackingNumber);
+     * ```
+     */
+    createShippingLabel(orderId: string, data: {
+        rateId: string;
+        parcel?: Record<string, string>;
+    }): Promise<{
+        shipmentId: string;
+        labelUrl: string;
+        trackingNumber: string;
+        carrier: string;
+    }>;
     /**
      * Cancel an order
      * Works for Shopify and WooCommerce orders that haven't been fulfilled

package/dist/index.d.ts

@@ -1806,6 +1806,20 @@ interface CartItem {
     notes?: string | null;
     /** Optional metadata for this line item */
     metadata?: Record<string, unknown> | null;
+    /**
+     * Resolved customer input field values with merchant-defined labels.
+     * Mirrors `OrderItem.customizations` — same shape, live (not order-frozen).
+     * Present only when the item has at least one customization value set.
+     *
+     * @example
+     * // Display "Color: Silver / Size: 45" without an extra getProduct() call:
+     * Object.entries(item.customizations ?? {}).map(([, c]) => `${c.label}: ${c.value}`)
+     */
+    customizations?: Record<string, {
+        label: string;
+        value: string | string[];
+        type: string;
+    }>;
     /**
      * Per-line modifier breakdown — present when the line was added with
      * modifier `selections`. Snapshot taken at add-time; immutable to catalog
@@ -2326,6 +2340,20 @@ interface CheckoutLineItem {
     notes?: string | null;
     /** Custom metadata including customer input field values */
     metadata?: Record<string, unknown> | null;
+    /**
+     * Resolved customer input field values with merchant-defined labels.
+     * Mirrors `OrderItem.customizations` — same shape, live (not order-frozen).
+     * Present only when the item has at least one customization value set.
+     *
+     * @example
+     * // Render "Color: Silver / Ring size: 45" in your checkout summary:
+     * Object.entries(item.customizations ?? {}).map(([, c]) => `${c.label}: ${c.value}`)
+     */
+    customizations?: Record<string, {
+        label: string;
+        value: string | string[];
+        type: string;
+    }>;
 }
 /**
  * Represents an available shipping rate/method for checkout.
@@ -3983,7 +4011,8 @@ interface MetafieldDefinition {
     maxLength?: number | null;
     minValue?: number | null;
     maxValue?: number | null;
-    enumValues?: string[] | null;
+    /** Allowed values for SELECT / MULTI_SELECT fields, with optional swatch metadata. */
+    enumValues?: CustomizationFieldOption[] | null;
     defaultValue?: string | null;
     position: number;
     isActive: boolean;
@@ -4067,7 +4096,8 @@ interface PublicMetafieldDefinition {
      * Pair with `getProducts({ metafields: { [key]: [...] } })`.
      */
     filterable?: boolean;
-    enumValues?: string[];
+    /** Allowed values for SELECT / MULTI_SELECT fields, with optional swatch metadata. */
+    enumValues?: CustomizationFieldOption[];
     minLength?: number | null;
     maxLength?: number | null;
     minValue?: number | null;
@@ -4075,6 +4105,20 @@ interface PublicMetafieldDefinition {
     defaultValue?: string | null;
     position: number;
 }
+/**
+ * A single selectable option for a SELECT or MULTI_SELECT customization field.
+ * Legacy string-only `enumValues` arrays are automatically promoted to this shape.
+ */
+interface CustomizationFieldOption {
+    /** Human-readable label shown in the storefront UI (e.g., "Rose Gold"). */
+    label: string;
+    /** Value stored in `CartItem.metadata` and carried through to `OrderItem.customizations`. */
+    value: string;
+    /** Optional CSS hex color for rendering a color swatch (e.g., "#B76E79"). */
+    swatchColor?: string | null;
+    /** Optional image URL for rendering a texture/image swatch. */
+    swatchImageUrl?: string | null;
+}
 /**
  * Customer-facing input field definition assigned to a specific product.
  * Returned in product responses to tell the storefront which input fields to render.
@@ -4090,7 +4134,11 @@ interface ProductCustomizationField {
     maxLength?: number | null;
     minValue?: number | null;
     maxValue?: number | null;
-    enumValues?: string[];
+    /**
+     * Allowed values for SELECT / MULTI_SELECT fields.
+     * Each option includes a label, value, and optional swatch color/image.
+     */
+    enumValues?: CustomizationFieldOption[];
     defaultValue?: string | null;
     position: number;
 }
@@ -5972,6 +6020,29 @@ declare class BrainerceClient {
      * ```
      */
     updateOrderShipping(orderId: string, data: UpdateOrderShippingDto): Promise<Order>;
+    /**
+     * Create a shipping label for an order via the installed App Store shipping app.
+     * Pass the rate ID returned from checkout rate shopping. Billing goes directly
+     * to the merchant's carrier account — Brainerce is not a billing intermediary.
+     *
+     * @example
+     * ```typescript
+     * const label = await client.createShippingLabel('order_abc', {
+     *   rateId: 'rate_8f123456789abcdef',
+     * });
+     * console.log('Label URL:', label.labelUrl);
+     * console.log('Tracking:', label.trackingNumber);
+     * ```
+     */
+    createShippingLabel(orderId: string, data: {
+        rateId: string;
+        parcel?: Record<string, string>;
+    }): Promise<{
+        shipmentId: string;
+        labelUrl: string;
+        trackingNumber: string;
+        carrier: string;
+    }>;
     /**
      * Cancel an order
      * Works for Shopify and WooCommerce orders that haven't been fulfilled

package/dist/index.js

@@ -1805,6 +1805,27 @@ var BrainerceClient = class {
       data
     );
   }
+  /**
+   * Create a shipping label for an order via the installed App Store shipping app.
+   * Pass the rate ID returned from checkout rate shopping. Billing goes directly
+   * to the merchant's carrier account — Brainerce is not a billing intermediary.
+   *
+   * @example
+   * ```typescript
+   * const label = await client.createShippingLabel('order_abc', {
+   *   rateId: 'rate_8f123456789abcdef',
+   * });
+   * console.log('Label URL:', label.labelUrl);
+   * console.log('Tracking:', label.trackingNumber);
+   * ```
+   */
+  async createShippingLabel(orderId, data) {
+    return this.request(
+      "POST",
+      `/api/v1/orders/${encodePathSegment(orderId)}/shipments/app-label`,
+      data
+    );
+  }
   /**
    * Cancel an order
    * Works for Shopify and WooCommerce orders that haven't been fulfilled

package/dist/index.mjs

@@ -1735,6 +1735,27 @@ var BrainerceClient = class {
       data
     );
   }
+  /**
+   * Create a shipping label for an order via the installed App Store shipping app.
+   * Pass the rate ID returned from checkout rate shopping. Billing goes directly
+   * to the merchant's carrier account — Brainerce is not a billing intermediary.
+   *
+   * @example
+   * ```typescript
+   * const label = await client.createShippingLabel('order_abc', {
+   *   rateId: 'rate_8f123456789abcdef',
+   * });
+   * console.log('Label URL:', label.labelUrl);
+   * console.log('Tracking:', label.trackingNumber);
+   * ```
+   */
+  async createShippingLabel(orderId, data) {
+    return this.request(
+      "POST",
+      `/api/v1/orders/${encodePathSegment(orderId)}/shipments/app-label`,
+      data
+    );
+  }
   /**
    * Cancel an order
    * Works for Shopify and WooCommerce orders that haven't been fulfilled

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brainerce",
-  "version": "1.38.0",
+  "version": "1.39.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",