brainerce 1.55.0 → 1.57.0

package/dist/index.mjs

@@ -212,6 +212,14 @@ var _BrainerceClient = class _BrainerceClient {
      * This is needed because Stripe redirects lose in-memory state.
      */
     this.ACTIVE_CHECKOUT_KEY = "brainerce_active_checkout";
+    /**
+     * Merge the resolved GA4 stitch ids onto a request body — only for fields
+     * the caller didn't already set explicitly (explicit values always win).
+     * No-op (returns `dto` unchanged) if `loadGoogleAnalytics()` was never
+     * called, or if it hasn't resolved any ids by the time this is awaited.
+     */
+    /** localStorage key holding the last non-direct-touch attribution blob. */
+    this.TRAFFIC_ATTR_KEY = "brainerce_attr";
     // -------------------- Contact Forms (schema) --------------------
     /**
      * List active contact forms configured for the store.
@@ -617,6 +625,7 @@ var _BrainerceClient = class _BrainerceClient {
     this.onCartReset = options.onCartReset;
     this.hydrateSessionCart();
     this.detectRecoverCartFromUrl();
+    this.captureTrafficAttribution();
   }
   // -------------------- Locale --------------------
   /**
@@ -1439,11 +1448,82 @@ var _BrainerceClient = class _BrainerceClient {
     }
   }
   /**
-   * Merge the resolved GA4 stitch ids onto a request body — only for fields
-   * the caller didn't already set explicitly (explicit values always win).
-   * No-op (returns `dto` unchanged) if `loadGoogleAnalytics()` was never
-   * called, or if it hasn't resolved any ids by the time this is awaited.
+   * Record the visit's traffic origin — LAST NON-DIRECT TOUCH semantics: an
+   * external referrer or any utm_source overwrites the stored blob; a direct
+   * or internal navigation keeps the previous touch. Runs once per client
+   * construction (i.e. per page load in browser storefronts) and must never
+   * throw — attribution is telemetry, the storefront always wins.
+   */
+  captureTrafficAttribution() {
+    try {
+      if (typeof window === "undefined" || !window.localStorage) return;
+      const params = new URLSearchParams(window.location.search);
+      const utmSource = params.get("utm_source") || void 0;
+      const utmMedium = params.get("utm_medium") || void 0;
+      const utmCampaign = params.get("utm_campaign") || void 0;
+      let referrerHost;
+      if (document.referrer) {
+        try {
+          const ref = new URL(document.referrer);
+          if (ref.hostname && ref.hostname !== window.location.hostname) {
+            referrerHost = ref.hostname.toLowerCase().replace(/^www\./, "");
+          }
+        } catch {
+        }
+      }
+      if (!referrerHost && !utmSource) return;
+      window.localStorage.setItem(
+        this.TRAFFIC_ATTR_KEY,
+        JSON.stringify({ referrerHost, utmSource, utmMedium, utmCampaign, at: Date.now() })
+      );
+    } catch {
+    }
+  }
+  /** The stored attribution as request-body fields, or null when absent/stale. */
+  getTrafficAttribution() {
+    try {
+      if (typeof window === "undefined" || !window.localStorage) return null;
+      const raw = window.localStorage.getItem(this.TRAFFIC_ATTR_KEY);
+      if (!raw) return null;
+      const blob = JSON.parse(raw);
+      if (!blob || typeof blob !== "object") return null;
+      if (typeof blob.at !== "number" || Date.now() - blob.at > _BrainerceClient.TRAFFIC_ATTR_MAX_AGE_MS) {
+        return null;
+      }
+      const out = {};
+      if (typeof blob.referrerHost === "string" && blob.referrerHost) {
+        out.trafficReferrerHost = blob.referrerHost.slice(0, 253);
+      }
+      if (typeof blob.utmSource === "string" && blob.utmSource) {
+        out.trafficUtmSource = blob.utmSource.slice(0, 150);
+      }
+      if (typeof blob.utmMedium === "string" && blob.utmMedium) {
+        out.trafficUtmMedium = blob.utmMedium.slice(0, 150);
+      }
+      if (typeof blob.utmCampaign === "string" && blob.utmCampaign) {
+        out.trafficUtmCampaign = blob.utmCampaign.slice(0, 150);
+      }
+      return Object.keys(out).length > 0 ? out : null;
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Merge the stored traffic attribution onto a request body — only for
+   * fields the caller didn't set explicitly (explicit values always win),
+   * mirroring `withAnalyticsStitchIds`. No-op outside the browser.
    */
+  withTrafficAttribution(dto) {
+    const attr = this.getTrafficAttribution();
+    if (!attr) return dto;
+    return {
+      ...dto ?? {},
+      trafficReferrerHost: dto?.trafficReferrerHost ?? attr.trafficReferrerHost,
+      trafficUtmSource: dto?.trafficUtmSource ?? attr.trafficUtmSource,
+      trafficUtmMedium: dto?.trafficUtmMedium ?? attr.trafficUtmMedium,
+      trafficUtmCampaign: dto?.trafficUtmCampaign ?? attr.trafficUtmCampaign
+    };
+  }
   async withAnalyticsStitchIds(dto) {
     if (!this._ga4StitchPromise) return dto;
     try {
@@ -1567,6 +1647,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
@@ -5256,7 +5380,7 @@ var _BrainerceClient = class _BrainerceClient {
    * ```
    */
   async setCheckoutCustomer(checkoutId, data) {
-    const body = await this.withAnalyticsStitchIds(data);
+    const body = this.withTrafficAttribution(await this.withAnalyticsStitchIds(data));
     if (this.isVibeCodedMode()) {
       return this.vibeCodedRequest(
         "PATCH",
@@ -5358,7 +5482,9 @@ var _BrainerceClient = class _BrainerceClient {
    * ```
    */
   async setShippingAddress(checkoutId, address) {
-    const body = await this.withAnalyticsStitchIds(this.stripResolvedOnlyAddressFields(address));
+    const body = this.withTrafficAttribution(
+      await this.withAnalyticsStitchIds(this.stripResolvedOnlyAddressFields(address))
+    );
     if (this.isVibeCodedMode()) {
       return this.vibeCodedRequest(
         "PATCH",
@@ -8859,6 +8985,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
@@ -9550,6 +9711,8 @@ _BrainerceClient.RESOLVED_ONLY_ADDRESS_FIELDS = [
   "lng",
   "formattedAddress"
 ];
+/** Attribution older than this is stale and never forwarded (classic 30-day window). */
+_BrainerceClient.TRAFFIC_ATTR_MAX_AGE_MS = 30 * 24 * 3600 * 1e3;
 var BrainerceClient = _BrainerceClient;
 var BrainerceError = class extends Error {
   constructor(message, statusCode, details) {
@@ -10050,7 +10213,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) => ({
@@ -10081,8 +10245,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 } : {}
@@ -10090,7 +10255,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.
@@ -10105,19 +10270,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
       }
     } : {}
   };
@@ -10228,6 +10399,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";
@@ -10532,6 +10751,7 @@ export {
   getProductMetafieldsByType,
   getProductPrice,
   getProductPriceInfo,
+  getProductSitemapEntries,
   getProductSwatches,
   getStockStatus,
   getVariantOptions,

package/package.json

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