npm - brainerce - Versions diffs - 1.37.3 → 1.39.0 - Mend

brainerce 1.37.3 → 1.39.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (6) hide show

package/README.md CHANGED Viewed

@@ -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
@@ -3361,6 +3383,51 @@ console.log(store.language); // 'en', 'he', etc.
 ---
+### Traffic Analytics (built-in, no GA4 needed)
+Brainerce has a **native cookieless analytics pipeline** — visits, visitors, countries, sources, devices, conversion funnel — visible in the merchant dashboard under **Dashboard → Traffic**. You don't need GA4, Meta Pixel, or any third-party script.
+**Option A — Script tag (recommended, zero JS):**
+Add one line to your root layout `<head>`:
+```html
+<!-- Vibe-coded (salesChannelId) mode -->
+<script defer src="https://api.brainerce.com/t.js" data-channel="vc_abc123"></script>
+<!-- storeId mode -->
+<script defer src="https://api.brainerce.com/t.js" data-store-id="your_store_id"></script>
+```
+The pixel auto-tracks pageviews on load and on every SPA route change, de-dupes consecutive identical paths, and measures active dwell time. Scaffolds from `create-brainerce-store ≥ 1.50` include it automatically.
+**Option B — SDK method (JS import, same endpoint):**
+```typescript
+// Basic pageview — call this on route changes if you're not using t.js
+client.trackEvent({ eventType: 'pageview', path: '/products/shoes' });
+// With UTM attribution (from URL params)
+const params = new URLSearchParams(window.location.search);
+client.trackEvent({
+  path: window.location.pathname,
+  utmSource:   params.get('utm_source')   ?? undefined,
+  utmMedium:   params.get('utm_medium')   ?? undefined,
+  utmCampaign: params.get('utm_campaign') ?? undefined,
+  screenWidth: window.innerWidth,
+  lang: navigator.language,
+});
+// Engagement dwell time (send on route change or pagehide)
+client.trackEvent({ eventType: 'engagement', path: '/products/shoes', engagedMs: 12000 });
+```
+> `trackEvent()` is fire-and-forget — errors are silently swallowed so a failed beacon never breaks your storefront. Available in `salesChannelId` and `storeId` modes.
+**Privacy:** cookieless, no PII stored. The visitor IP is resolved to a country server-side and then discarded. No cookie-consent banner required under GDPR/ePrivacy.
+---
 ## Admin API Reference
 > ⛔ **Server-side only.** The `apiKey` (`brainerce_*`) is a privileged secret — NEVER put it in browser code, client bundles, or any code that ships to the user's machine. It belongs in an environment variable on your server. For building the customer-facing storefront, use `salesChannelId` instead (see [Quick Start](#quick-start)).
@@ -3505,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 CHANGED Viewed

@@ -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;
 }
@@ -5306,6 +5354,30 @@ interface BlogPostListResponse {
         totalPages: number;
     };
 }
+/**
+ * Payload for `client.trackEvent()` — the programmatic counterpart to the
+ * `t.js` script-tag pixel. Every field is optional; the server degrades
+ * gracefully on missing values. Deliberately collects no PII: `path` is
+ * pathname-only, `referrer` is reduced to a hostname server-side, and the
+ * visitor IP is resolved to a country then discarded.
+ */
+interface TrackEventPayload {
+    /** `'pageview'` (default) or `'engagement'` (active dwell-time report). */
+    eventType?: 'pageview' | 'engagement';
+    /** `window.location.pathname` — no query string (intentional, avoids PII). */
+    path?: string;
+    /** `document.referrer` — full URL, reduced to hostname server-side. */
+    referrer?: string;
+    utmSource?: string;
+    utmMedium?: string;
+    utmCampaign?: string;
+    /** Viewport width in px — used for mobile/tablet/desktop classification. */
+    screenWidth?: number;
+    /** `navigator.language` — coarse locale hint for future breakdowns. */
+    lang?: string;
+    /** Active dwell time in ms. Only meaningful for `eventType: 'engagement'`. Max 1 800 000 (30 min). */
+    engagedMs?: number;
+}
 interface BrainerceApiError {
     statusCode: number;
     message: string;
@@ -5491,6 +5563,39 @@ declare class BrainerceClient {
      *   `'ltr'` for everything else (including unknown locales).
      */
     getStoreDirection(locale?: string | null): 'ltr' | 'rtl';
+    /**
+     * Send a storefront analytics beacon (pageview or engagement).
+     *
+     * This is the programmatic counterpart to the `t.js` script-tag pixel —
+     * use it when you prefer a JS import over a `<script>` tag, or when you
+     * need to fire events the auto-tracker doesn't cover.
+     *
+     * **If you're already loading `t.js`, you do NOT need this** — the pixel
+     * handles pageviews and SPA route changes automatically.
+     *
+     * The call is fire-and-forget: errors are swallowed so a failed beacon
+     * never breaks your storefront. Available in `salesChannelId` and `storeId`
+     * modes; silently skipped in admin mode (server-to-server beacons are
+     * meaningless without a real browser session).
+     *
+     * @example
+     * ```typescript
+     * // Basic pageview (equivalent to what t.js sends automatically)
+     * client.trackEvent({ eventType: 'pageview', path: '/products/shoes' });
+     *
+     * // With UTM attribution
+     * client.trackEvent({
+     *   path: '/products/shoes',
+     *   utmSource: 'newsletter',
+     *   utmMedium: 'email',
+     *   utmCampaign: 'summer-sale',
+     * });
+     *
+     * // Engagement (active dwell time in ms — send on route change or pagehide)
+     * client.trackEvent({ eventType: 'engagement', path: '/products/shoes', engagedMs: 12000 });
+     * ```
+     */
+    trackEvent(payload?: TrackEventPayload): Promise<void>;
     /**
      * Get a list of products with pagination and filtering
      * Works in vibe-coded, storefront (public), and admin mode
@@ -5915,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 CHANGED Viewed

@@ -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;
 }
@@ -5306,6 +5354,30 @@ interface BlogPostListResponse {
         totalPages: number;
     };
 }
+/**
+ * Payload for `client.trackEvent()` — the programmatic counterpart to the
+ * `t.js` script-tag pixel. Every field is optional; the server degrades
+ * gracefully on missing values. Deliberately collects no PII: `path` is
+ * pathname-only, `referrer` is reduced to a hostname server-side, and the
+ * visitor IP is resolved to a country then discarded.
+ */
+interface TrackEventPayload {
+    /** `'pageview'` (default) or `'engagement'` (active dwell-time report). */
+    eventType?: 'pageview' | 'engagement';
+    /** `window.location.pathname` — no query string (intentional, avoids PII). */
+    path?: string;
+    /** `document.referrer` — full URL, reduced to hostname server-side. */
+    referrer?: string;
+    utmSource?: string;
+    utmMedium?: string;
+    utmCampaign?: string;
+    /** Viewport width in px — used for mobile/tablet/desktop classification. */
+    screenWidth?: number;
+    /** `navigator.language` — coarse locale hint for future breakdowns. */
+    lang?: string;
+    /** Active dwell time in ms. Only meaningful for `eventType: 'engagement'`. Max 1 800 000 (30 min). */
+    engagedMs?: number;
+}
 interface BrainerceApiError {
     statusCode: number;
     message: string;
@@ -5491,6 +5563,39 @@ declare class BrainerceClient {
      *   `'ltr'` for everything else (including unknown locales).
      */
     getStoreDirection(locale?: string | null): 'ltr' | 'rtl';
+    /**
+     * Send a storefront analytics beacon (pageview or engagement).
+     *
+     * This is the programmatic counterpart to the `t.js` script-tag pixel —
+     * use it when you prefer a JS import over a `<script>` tag, or when you
+     * need to fire events the auto-tracker doesn't cover.
+     *
+     * **If you're already loading `t.js`, you do NOT need this** — the pixel
+     * handles pageviews and SPA route changes automatically.
+     *
+     * The call is fire-and-forget: errors are swallowed so a failed beacon
+     * never breaks your storefront. Available in `salesChannelId` and `storeId`
+     * modes; silently skipped in admin mode (server-to-server beacons are
+     * meaningless without a real browser session).
+     *
+     * @example
+     * ```typescript
+     * // Basic pageview (equivalent to what t.js sends automatically)
+     * client.trackEvent({ eventType: 'pageview', path: '/products/shoes' });
+     *
+     * // With UTM attribution
+     * client.trackEvent({
+     *   path: '/products/shoes',
+     *   utmSource: 'newsletter',
+     *   utmMedium: 'email',
+     *   utmCampaign: 'summer-sale',
+     * });
+     *
+     * // Engagement (active dwell time in ms — send on route change or pagehide)
+     * client.trackEvent({ eventType: 'engagement', path: '/products/shoes', engagedMs: 12000 });
+     * ```
+     */
+    trackEvent(payload?: TrackEventPayload): Promise<void>;
     /**
      * Get a list of products with pagination and filtering
      * Works in vibe-coded, storefront (public), and admin mode
@@ -5915,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 CHANGED Viewed

@@ -1072,6 +1072,49 @@ var BrainerceClient = class {
   getStoreDirection(locale) {
     return getDirectionForLocale(locale ?? this.locale);
   }
+  // -------------------- Analytics --------------------
+  /**
+   * Send a storefront analytics beacon (pageview or engagement).
+   *
+   * This is the programmatic counterpart to the `t.js` script-tag pixel —
+   * use it when you prefer a JS import over a `<script>` tag, or when you
+   * need to fire events the auto-tracker doesn't cover.
+   *
+   * **If you're already loading `t.js`, you do NOT need this** — the pixel
+   * handles pageviews and SPA route changes automatically.
+   *
+   * The call is fire-and-forget: errors are swallowed so a failed beacon
+   * never breaks your storefront. Available in `salesChannelId` and `storeId`
+   * modes; silently skipped in admin mode (server-to-server beacons are
+   * meaningless without a real browser session).
+   *
+   * @example
+   * ```typescript
+   * // Basic pageview (equivalent to what t.js sends automatically)
+   * client.trackEvent({ eventType: 'pageview', path: '/products/shoes' });
+   *
+   * // With UTM attribution
+   * client.trackEvent({
+   *   path: '/products/shoes',
+   *   utmSource: 'newsletter',
+   *   utmMedium: 'email',
+   *   utmCampaign: 'summer-sale',
+   * });
+   *
+   * // Engagement (active dwell time in ms — send on route change or pagehide)
+   * client.trackEvent({ eventType: 'engagement', path: '/products/shoes', engagedMs: 12000 });
+   * ```
+   */
+  async trackEvent(payload = {}) {
+    try {
+      if (this.isVibeCodedMode()) {
+        await this.vibeCodedRequest("POST", "/events", payload);
+      } else if (this.isStorefrontMode()) {
+        await this.storefrontRequest("POST", "/events", payload);
+      }
+    } catch {
+    }
+  }
   // -------------------- Products --------------------
   /**
    * Get a list of products with pagination and filtering
@@ -1762,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 CHANGED Viewed

@@ -1002,6 +1002,49 @@ var BrainerceClient = class {
   getStoreDirection(locale) {
     return getDirectionForLocale(locale ?? this.locale);
   }
+  // -------------------- Analytics --------------------
+  /**
+   * Send a storefront analytics beacon (pageview or engagement).
+   *
+   * This is the programmatic counterpart to the `t.js` script-tag pixel —
+   * use it when you prefer a JS import over a `<script>` tag, or when you
+   * need to fire events the auto-tracker doesn't cover.
+   *
+   * **If you're already loading `t.js`, you do NOT need this** — the pixel
+   * handles pageviews and SPA route changes automatically.
+   *
+   * The call is fire-and-forget: errors are swallowed so a failed beacon
+   * never breaks your storefront. Available in `salesChannelId` and `storeId`
+   * modes; silently skipped in admin mode (server-to-server beacons are
+   * meaningless without a real browser session).
+   *
+   * @example
+   * ```typescript
+   * // Basic pageview (equivalent to what t.js sends automatically)
+   * client.trackEvent({ eventType: 'pageview', path: '/products/shoes' });
+   *
+   * // With UTM attribution
+   * client.trackEvent({
+   *   path: '/products/shoes',
+   *   utmSource: 'newsletter',
+   *   utmMedium: 'email',
+   *   utmCampaign: 'summer-sale',
+   * });
+   *
+   * // Engagement (active dwell time in ms — send on route change or pagehide)
+   * client.trackEvent({ eventType: 'engagement', path: '/products/shoes', engagedMs: 12000 });
+   * ```
+   */
+  async trackEvent(payload = {}) {
+    try {
+      if (this.isVibeCodedMode()) {
+        await this.vibeCodedRequest("POST", "/events", payload);
+      } else if (this.isStorefrontMode()) {
+        await this.storefrontRequest("POST", "/events", payload);
+      }
+    } catch {
+    }
+  }
   // -------------------- Products --------------------
   /**
    * Get a list of products with pagination and filtering
@@ -1692,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 CHANGED Viewed

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