brainerce 1.54.0 → 1.56.0

package/dist/index.mjs

@@ -120,6 +120,24 @@ 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).
@@ -1324,6 +1567,50 @@ var _BrainerceClient = class _BrainerceClient {
       queryParamsWithRegion
     );
   }
+  /**
+   * Lightweight product rows for sitemap generation: `slug`, `updatedAt`, and
+   * per-locale `localeSlugs` only — up to `limit` (max 5000) in ONE request,
+   * with none of the 100-per-page clamp the full listing applies.
+   *
+   * Sales-channel (`salesChannelId`) mode only; other modes throw so
+   * {@link getProductSitemapEntries} (sitemap.ts) can catch and fall back to
+   * paginating `getProducts`. Prefer that helper over calling this directly.
+   */
+  async getSitemapProducts(limit = 5e3) {
+    if (!this.isVibeCodedMode()) {
+      throw new Error("getSitemapProducts is available in salesChannelId mode only");
+    }
+    const res = await this.vibeCodedRequest("GET", "/sitemap-products", void 0, { limit: Math.min(limit, 5e3) });
+    return res.data;
+  }
+  /**
+   * Resolve an old (renamed) slug to the entity's CURRENT slug, so the
+   * storefront can issue a permanent (301/308) redirect instead of a 404.
+   *
+   * Call this in the catch/not-found path of a product or blog page:
+   * the platform records every slug rename, so a URL that stopped matching
+   * usually has a redirect. Returns `null` when there is no redirect (real
+   * 404) or outside sales-channel mode — always fall through to notFound().
+   *
+   * @example
+   * ```typescript
+   * // app/products/[slug]/page.tsx — in the catch path:
+   * const redirect = await client.resolveSlugRedirect('product', slug);
+   * if (redirect) permanentRedirect(`/products/${redirect.currentSlug}`);
+   * notFound();
+   * ```
+   */
+  async resolveSlugRedirect(entityType, slug) {
+    if (!this.isVibeCodedMode()) return null;
+    try {
+      return await this.vibeCodedRequest(
+        "GET",
+        `/slug-redirects/${entityType}/${encodePathSegment(slug)}`
+      );
+    } catch {
+      return null;
+    }
+  }
   /**
    * Get a single product by ID
    * Works in vibe-coded, storefront (public), and admin mode
@@ -5115,9 +5402,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",
@@ -8618,6 +8903,41 @@ var _BrainerceClient = class _BrainerceClient {
       { salesChannelId }
     );
   }
+  /**
+   * Attach a customer to a sales channel (admin mode) — marks them as active in
+   * that storefront. Accepts the sales-channel record ID or its public `vc_*`
+   * connection ID.
+   *
+   * Rarely needed: the platform records a channel by itself whenever the
+   * customer registers, signs in or checks out on it. Use this for migrations
+   * from another system and for fixing up records you created yourself. A
+   * customer belongs to one store but can be active in any number of its
+   * channels, so calling this for several channels is normal and expected.
+   *
+   * This does not change where the customer CAME FROM — for that, pass
+   * `acquisitionSalesChannelId` to {@link updateCustomer}.
+   */
+  async publishCustomerToSalesChannel(customerId, salesChannelId) {
+    return this.adminRequest(
+      "POST",
+      `/api/v1/customers/${encodePathSegment(customerId)}/publish-sales-channel`,
+      { salesChannelId }
+    );
+  }
+  /**
+   * Detach a customer from a sales channel (admin mode).
+   *
+   * A correction, NOT a block — it does not stop that person from buying on
+   * that storefront, and the channel is recorded again the next time they sign
+   * in or order there. There is no way to bar a customer from a channel.
+   */
+  async unpublishCustomerFromSalesChannel(customerId, salesChannelId) {
+    return this.adminRequest(
+      "POST",
+      `/api/v1/customers/${encodePathSegment(customerId)}/unpublish-sales-channel`,
+      { salesChannelId }
+    );
+  }
   /**
    * Publish a coupon to a sales channel (admin mode) — makes it redeemable on
    * that vibe-coded storefront. Accepts the sales-channel record ID or its
@@ -9809,7 +10129,8 @@ function buildProductJsonLd(product, opts) {
   const brand = opts.brandName ?? product.brands?.[0]?.name;
   const description = stripHtml(product.description).slice(0, 5e3);
   const effectivePrice = product.salePrice ?? product.basePrice;
-  const inStock = product.inventory ? (product.inventory.available ?? 0) > 0 : true;
+  const inv = product.inventory;
+  const availability = !inv ? "https://schema.org/InStock" : inv.inStock ?? (inv.available ?? 0) > 0 ? "https://schema.org/InStock" : inv.canPurchase ? "https://schema.org/BackOrder" : "https://schema.org/OutOfStock";
   const isVariable = product.type === "VARIABLE" && product.priceMin && product.priceMax;
   const itemCondition = "https://schema.org/NewCondition";
   const shippingDetails = (opts.shipping ?? []).filter((z) => z.amount !== null).map((z) => ({
@@ -9840,8 +10161,9 @@ function buildProductJsonLd(product, opts) {
     "@type": "AggregateOffer",
     lowPrice: product.priceMin,
     highPrice: product.priceMax,
+    ...product.variants?.length ? { offerCount: product.variants.length } : {},
     priceCurrency: opts.currency,
-    availability: inStock ? "https://schema.org/InStock" : "https://schema.org/OutOfStock",
+    availability,
     itemCondition,
     ...shippingDetails.length > 0 ? { shippingDetails } : {},
     ...url ? { url } : {}
@@ -9849,7 +10171,7 @@ function buildProductJsonLd(product, opts) {
     "@type": "Offer",
     price: effectivePrice,
     priceCurrency: opts.currency,
-    availability: inStock ? "https://schema.org/InStock" : "https://schema.org/OutOfStock",
+    availability,
     itemCondition,
     // Only meaningful for an active sale price with a known end date —
     // a regular (non-sale) price has no expiry to declare.
@@ -9864,19 +10186,25 @@ function buildProductJsonLd(product, opts) {
     ...description ? { description } : {},
     ...images.length > 0 ? { image: images } : {},
     ...url ? { url } : {},
-    sku: product.sku,
+    // Fall back to the product id so the offer always carries a stable SKU —
+    // Merchant Center matching and review aggregation both key on it.
+    sku: product.sku || product.id,
     // Identifiers Google uses to match a product to its catalog — key for
     // free merchant-listing eligibility without a Merchant Center feed.
     ...product.gtin ? { gtin: product.gtin } : {},
     ...product.mpn ? { mpn: product.mpn } : {},
     ...brand ? { brand: { "@type": "Brand", name: brand } } : {},
     offers: offer,
-    // Google policy: never emit an empty/zero rating block.
+    // Google policy: never emit an empty/zero rating block. bestRating /
+    // worstRating make the 1-5 scale explicit so aggregators can't misread
+    // a 4.8 on an assumed 0-10 scale.
     ...product.reviewCount && product.reviewCount > 0 && product.avgRating ? {
       aggregateRating: {
         "@type": "AggregateRating",
         ratingValue: product.avgRating,
-        reviewCount: product.reviewCount
+        reviewCount: product.reviewCount,
+        bestRating: 5,
+        worstRating: 1
       }
     } : {}
   };
@@ -9987,6 +10315,54 @@ async function getBlogSitemapEntries(client, opts) {
   }
   return entries;
 }
+async function getProductSitemapEntries(client, opts) {
+  const base = opts.siteUrl.replace(/\/+$/, "");
+  const basePath = opts.basePath ?? "/products";
+  const pageSize = Math.min(opts.pageSize ?? 100, 100);
+  const maxEntries = opts.maxEntries ?? 5e3;
+  let rows = [];
+  try {
+    rows = await client.getSitemapProducts(maxEntries);
+  } catch {
+    let page = 1;
+    for (; ; ) {
+      const res = await client.getProducts({ page, limit: pageSize });
+      rows.push(
+        ...res.data.map((p) => ({
+          slug: p.slug ?? null,
+          id: p.id,
+          updatedAt: p.updatedAt,
+          localeSlugs: p.localeSlugs ?? null
+        }))
+      );
+      if (page >= res.meta.totalPages || rows.length >= maxEntries) break;
+      page += 1;
+    }
+  }
+  const nonDefaultLocales = opts.locales?.filter((locale) => locale !== opts.defaultLocale) ?? [];
+  const entries = [];
+  for (const row of rows.slice(0, maxEntries)) {
+    const baseSlug = row.slug || row.id;
+    if (!baseSlug) continue;
+    const lastModified = row.updatedAt ? new Date(row.updatedAt) : void 0;
+    const localeSlugs = row.localeSlugs ?? {};
+    entries.push({
+      url: `${base}${basePath}/${baseSlug}`,
+      ...lastModified ? { lastModified } : {},
+      changeFrequency: "daily",
+      priority: 0.8
+    });
+    for (const locale of nonDefaultLocales) {
+      entries.push({
+        url: `${base}/${locale}${basePath}/${localeSlugs[locale] || baseSlug}`,
+        ...lastModified ? { lastModified } : {},
+        changeFrequency: "daily",
+        priority: 0.7
+      });
+    }
+  }
+  return entries;
+}
 async function getCategorySitemapEntries(client, opts) {
   const base = opts.siteUrl.replace(/\/+$/, "");
   const basePath = opts.basePath ?? "/category";
@@ -10291,6 +10667,7 @@ export {
   getProductMetafieldsByType,
   getProductPrice,
   getProductPriceInfo,
+  getProductSitemapEntries,
   getProductSwatches,
   getStockStatus,
   getVariantOptions,

package/package.json

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