brainerce 1.53.1 → 1.55.0

package/dist/index.mjs

@@ -12,7 +12,7 @@ var CART_GUARDS = [
 var CART_ITEM_GUARDS = [
   {
     property: "name",
-    message: 'CartItem has no "name" field. Use item.product.name or getCartItemName(item).\nImport: import { getCartItemName } from "brainerce";'
+    message: 'CartItem has no "name" field. Use getCartItemName(item) for the full\n"Product - Variant" label, or item.product.name for the product name alone.\nImport: import { getCartItemName } from "brainerce";'
   },
   {
     property: "price",
@@ -115,11 +115,29 @@ function isDevGuardsEnabled() {
 }
 
 // src/version.ts
-var SDK_VERSION = "1.53.1";
+var SDK_VERSION = "1.54.0";
 
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.brainerce.com";
 var DEFAULT_TIMEOUT = 3e4;
+var META_EVENT_NAMES = {
+  view_item: "ViewContent",
+  add_to_cart: "AddToCart",
+  begin_checkout: "InitiateCheckout",
+  add_payment_info: "AddPaymentInfo",
+  purchase: "Purchase",
+  search: "Search",
+  sign_up: "CompleteRegistration"
+};
+var TIKTOK_EVENT_NAMES = {
+  view_item: "ViewContent",
+  add_to_cart: "AddToCart",
+  begin_checkout: "InitiateCheckout",
+  add_payment_info: "AddPaymentInfo",
+  purchase: "CompletePayment",
+  search: "Search",
+  sign_up: "CompleteRegistration"
+};
 var RTL_LOCALES = /* @__PURE__ */ new Set(["ar", "he", "fa", "ur", "yi"]);
 function getDirectionForLocale(locale) {
   if (!locale) return "ltr";
@@ -174,6 +192,12 @@ var _BrainerceClient = class _BrainerceClient {
     // GA4 stitch state (see `loadGoogleAnalytics()` in the Analytics section).
     this._ga4MeasurementId = null;
     this._ga4StitchPromise = null;
+    // Marketing tags booted by `initTracking()`. Each holds the id already
+    // loaded, which is what makes a repeat call a no-op instead of a second
+    // pixel install (and a doubled PageView).
+    this._gtmContainerId = null;
+    this._metaPixelId = null;
+    this._tiktokPixelId = null;
     /** One warning per client, not per keystroke-driven address submit. */
     this._warnedResolvedOnlyAddressFields = false;
     /** localStorage key for session cart reference (sessionToken + cartId) */
@@ -1195,6 +1219,225 @@ var _BrainerceClient = class _BrainerceClient {
       }
     });
   }
+  /**
+   * Boot every marketing tag the merchant has configured — GA4, Google Tag
+   * Manager, the Meta pixel, the TikTok pixel — in one call.
+   *
+   * Pass `storeInfo.tracking` straight through. The ids in it are resolved
+   * server-side from the marketplace apps the merchant already connected, so
+   * for the common case nobody types an id anywhere and nobody redeploys the
+   * storefront: connect the Google app in the dashboard and this call starts
+   * loading GA4 on the next page render.
+   *
+   * Call it once, as early as possible (root layout / app entry). It is
+   * idempotent, a no-op during SSR, and never throws — a blocked or missing
+   * tag must never take a storefront down with it.
+   *
+   * GA4 goes through {@link loadGoogleAnalytics}, so the `client_id` /
+   * `session_id` stitch ids keep flowing onto cart and checkout calls and the
+   * server-side purchase conversion still lands in the right session.
+   *
+   * @example
+   * ```typescript
+   * const storeInfo = await client.getStoreInfo();
+   * client.initTracking(storeInfo.tracking);
+   * // …later, on the order confirmation page:
+   * client.trackMarketingEvent('purchase', {
+   *   transactionId: order.id,
+   *   currency: order.currency,
+   *   value: order.totalAmount,
+   *   items: order.items.map((i) => ({ itemId: i.sku, itemName: i.name, price: i.price, quantity: i.quantity })),
+   * });
+   * ```
+   */
+  initTracking(tracking) {
+    if (typeof window === "undefined" || !tracking) return;
+    if (tracking.ga4MeasurementId) {
+      this.loadGoogleAnalytics(tracking.ga4MeasurementId);
+    }
+    if (tracking.gtmContainerId) this.loadGtm(tracking.gtmContainerId);
+    if (tracking.metaPixelId) this.loadMetaPixel(tracking.metaPixelId);
+    if (tracking.tiktokPixelId) this.loadTikTokPixel(tracking.tiktokPixelId);
+  }
+  /**
+   * Report one e-commerce event to every marketing tag that
+   * {@link initTracking} loaded (GA4/GTM, Meta, TikTok).
+   *
+   * Distinct from {@link trackEvent}, which posts a cookieless pageview/beacon
+   * to Brainerce's own storefront analytics. This one is about ad platforms —
+   * call both; they answer different questions.
+   *
+   * You describe what happened once, in GA4's vocabulary, and the SDK
+   * translates: a `dataLayer` push for GA4/GTM, the matching Meta standard
+   * event via `fbq`, and the matching TikTok event via `ttq`. Tags that aren't
+   * loaded are skipped silently, so the same call is correct whether the
+   * merchant has connected none, one, or all of them.
+   *
+   * Why this matters for ad spend: a GTM container with no `dataLayer` events
+   * is an empty container, and Meta cannot optimize a campaign it never sees a
+   * `Purchase` for. The value/currency/item-id triple in {@link TrackingEventPayload}
+   * is the whole input to that optimization.
+   *
+   * `purchase` is de-duplicated by the vendors on `transactionId` (GA4
+   * `transaction_id`, Meta `eventID`, TikTok `event_id`), so a shopper
+   * refreshing the confirmation page cannot double-count the order — pass the
+   * order id and the safety is automatic.
+   *
+   * SSR-safe and never throws.
+   */
+  trackMarketingEvent(name, payload = {}) {
+    if (typeof window === "undefined") return;
+    try {
+      const items = payload.items ?? [];
+      window.dataLayer = window.dataLayer || [];
+      window.dataLayer.push({ ecommerce: null });
+      window.dataLayer.push({
+        event: name,
+        ecommerce: {
+          ...payload.currency ? { currency: payload.currency } : {},
+          ...payload.value !== void 0 ? { value: payload.value } : {},
+          ...payload.transactionId ? { transaction_id: payload.transactionId } : {},
+          ...payload.shipping !== void 0 ? { shipping: payload.shipping } : {},
+          ...payload.tax !== void 0 ? { tax: payload.tax } : {},
+          ...payload.coupon ? { coupon: payload.coupon } : {},
+          items: items.map((item) => ({
+            item_id: item.itemId,
+            ...item.itemName ? { item_name: item.itemName } : {},
+            ...item.price !== void 0 ? { price: item.price } : {},
+            ...item.quantity !== void 0 ? { quantity: item.quantity } : {},
+            ...item.itemVariant ? { item_variant: item.itemVariant } : {},
+            ...item.itemCategory ? { item_category: item.itemCategory } : {}
+          }))
+        }
+      });
+      if (window.gtag && this._ga4MeasurementId) {
+        window.gtag("event", name, {
+          ...payload.currency ? { currency: payload.currency } : {},
+          ...payload.value !== void 0 ? { value: payload.value } : {},
+          ...payload.transactionId ? { transaction_id: payload.transactionId } : {},
+          ...payload.shipping !== void 0 ? { shipping: payload.shipping } : {},
+          ...payload.tax !== void 0 ? { tax: payload.tax } : {},
+          ...payload.coupon ? { coupon: payload.coupon } : {},
+          items: items.map((item) => ({
+            item_id: item.itemId,
+            item_name: item.itemName,
+            price: item.price,
+            quantity: item.quantity
+          }))
+        });
+      }
+      const metaEvent = META_EVENT_NAMES[name];
+      if (window.fbq && metaEvent) {
+        const contents = items.map((item) => ({
+          id: item.itemId,
+          quantity: item.quantity ?? 1,
+          ...item.price !== void 0 ? { item_price: item.price } : {}
+        }));
+        window.fbq(
+          "track",
+          metaEvent,
+          {
+            ...payload.currency ? { currency: payload.currency } : {},
+            ...payload.value !== void 0 ? { value: payload.value } : {},
+            ...contents.length ? { contents, content_ids: contents.map((c) => c.id), content_type: "product" } : {}
+          },
+          // Meta de-dupes a browser event against a server (CAPI) event of the
+          // same eventID, and against a repeat send of the same page.
+          payload.transactionId ? { eventID: payload.transactionId } : void 0
+        );
+      }
+      const tiktokEvent = TIKTOK_EVENT_NAMES[name];
+      if (window.ttq?.track && tiktokEvent) {
+        window.ttq.track(
+          tiktokEvent,
+          {
+            ...payload.currency ? { currency: payload.currency } : {},
+            ...payload.value !== void 0 ? { value: payload.value } : {},
+            contents: items.map((item) => ({
+              content_id: item.itemId,
+              content_name: item.itemName,
+              quantity: item.quantity ?? 1,
+              price: item.price
+            }))
+          },
+          payload.transactionId ? { event_id: payload.transactionId } : void 0
+        );
+      }
+    } catch {
+    }
+  }
+  /** Install the GTM container loader. Idempotent; no-op if already present. */
+  loadGtm(containerId) {
+    if (this._gtmContainerId === containerId) return;
+    this._gtmContainerId = containerId;
+    try {
+      window.dataLayer = window.dataLayer || [];
+      window.dataLayer.push({ "gtm.start": Date.now(), event: "gtm.js" });
+      const script = document.createElement("script");
+      script.async = true;
+      script.src = `https://www.googletagmanager.com/gtm.js?id=${encodeURIComponent(containerId)}`;
+      document.head.appendChild(script);
+    } catch {
+    }
+  }
+  /** Install the Meta pixel and fire its initial PageView. Idempotent. */
+  loadMetaPixel(pixelId) {
+    if (this._metaPixelId === pixelId) return;
+    this._metaPixelId = pixelId;
+    try {
+      if (!window.fbq) {
+        const queue = [];
+        const fbq = ((...args) => {
+          if (fbq.callMethod) fbq.callMethod(...args);
+          else queue.push(args);
+        });
+        fbq.queue = queue;
+        fbq.loaded = true;
+        fbq.version = "2.0";
+        window.fbq = fbq;
+        window._fbq = fbq;
+        const script = document.createElement("script");
+        script.async = true;
+        script.src = "https://connect.facebook.net/en_US/fbevents.js";
+        document.head.appendChild(script);
+      }
+      window.fbq("init", pixelId);
+      window.fbq("track", "PageView");
+    } catch {
+    }
+  }
+  /** Install the TikTok pixel and fire its initial page view. Idempotent. */
+  loadTikTokPixel(pixelId) {
+    if (this._tiktokPixelId === pixelId) return;
+    this._tiktokPixelId = pixelId;
+    try {
+      const ttq = window.ttq ?? {};
+      ttq._i = ttq._i ?? {};
+      ttq._i[pixelId] = ttq._i[pixelId] ?? [];
+      ttq._t = ttq._t ?? {};
+      ttq._t[pixelId] = Date.now();
+      ttq._o = ttq._o ?? {};
+      ttq._o[pixelId] = {};
+      const methods = ["page", "track", "identify", "instances", "ready"];
+      ttq.methods = methods;
+      for (const method of methods) {
+        if (typeof ttq[method] !== "function") {
+          ttq[method] = (...args) => {
+            ttq._i?.[pixelId]?.push([method, ...args]);
+          };
+        }
+      }
+      window.ttq = ttq;
+      const script = document.createElement("script");
+      script.async = true;
+      script.src = `https://analytics.tiktok.com/i18n/pixel/events.js?sdkid=${encodeURIComponent(
+        pixelId
+      )}&lib=ttq`;
+      document.head.appendChild(script);
+      ttq.page?.();
+    } catch {
+    }
+  }
   /**
    * Merge the resolved GA4 stitch ids onto a request body — only for fields
    * the caller didn't already set explicitly (explicit values always win).
@@ -5115,9 +5358,7 @@ var _BrainerceClient = class _BrainerceClient {
    * ```
    */
   async setShippingAddress(checkoutId, address) {
-    const body = await this.withAnalyticsStitchIds(
-      this.stripResolvedOnlyAddressFields(address)
-    );
+    const body = await this.withAnalyticsStitchIds(this.stripResolvedOnlyAddressFields(address));
     if (this.isVibeCodedMode()) {
       return this.vibeCodedRequest(
         "PATCH",
@@ -8174,6 +8415,42 @@ var _BrainerceClient = class _BrainerceClient {
       `/api/v1/regions/${encodePathSegment(regionId)}/compatible-providers`
     );
   }
+  /**
+   * List a region's manual price overrides (regional pricing, admin). Prices
+   * are in the region's currency; `variantId: null` rows are product-level.
+   */
+  async getRegionPrices(regionId, params = {}) {
+    return this.adminRequest(
+      "GET",
+      `/api/v1/regions/${encodePathSegment(regionId)}/prices`,
+      void 0,
+      {
+        productId: params.productId,
+        page: params.page,
+        limit: params.limit
+      }
+    );
+  }
+  /**
+   * Bulk upsert/remove manual price overrides for a region (admin). Each
+   * entry: `price` = regular, `salePrice` = sale (must be lower), in the
+   * REGION's currency; `remove: true` deletes. A product/variant with no
+   * entry keeps automatic FX conversion.
+   */
+  async upsertRegionPrices(regionId, entries) {
+    return this.adminRequest(
+      "PUT",
+      `/api/v1/regions/${encodePathSegment(regionId)}/prices`,
+      { entries }
+    );
+  }
+  /** Delete one manual price override by id (admin). */
+  async deleteRegionPrice(regionId, priceId) {
+    await this.adminRequest(
+      "DELETE",
+      `/api/v1/regions/${encodePathSegment(regionId)}/prices/${encodePathSegment(priceId)}`
+    );
+  }
   // -------------------- Regions (Storefront + vibe-coded, public — no apiKey) --------------------
   // storeId- or connectionId-based, no auth. Call these from a storefront to
   // detect the buyer's region (story S1), then pair with detectRegion(). Then
@@ -10123,7 +10400,10 @@ function getCartTotals(cart, shippingPrice) {
   return { subtotal, discount, shipping, total };
 }
 function getCartItemName(item) {
-  return item.variant?.name || item.product.name;
+  const productName = item.product.name;
+  const variantName = item.variant?.name?.trim();
+  if (!variantName || variantName === productName) return productName;
+  return `${productName} - ${variantName}`;
 }
 function getCartItemImage(item) {
   if (item.variant?.image) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brainerce",
-  "version": "1.53.1",
+  "version": "1.55.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",
@@ -28,6 +28,7 @@
     "lint": "eslint \"src/**/*.ts\"",
     "test": "vitest run",
     "test:watch": "vitest",
+    "release": "pnpm build && node ../../scripts/publish-workspace-package.js .",
     "prepublishOnly": "pnpm build"
   },
   "keywords": [