@amboras-dev/snapchat-ads 2.0.0

package/dist/index.js

@@ -0,0 +1,235 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  deriveMinuteBucket: () => deriveMinuteBucket,
+  getSnapchatAdsConfig: () => getSnapchatAdsConfig,
+  makeEventId: () => makeEventId,
+  minuteBucketNow: () => minuteBucketNow,
+  sendSnapchatCapiEvent: () => sendSnapchatCapiEvent,
+  trackAddCart: () => trackAddCart,
+  trackPageView: () => trackPageView,
+  trackPurchase: () => trackPurchase,
+  trackStartCheckout: () => trackStartCheckout,
+  trackViewContent: () => trackViewContent
+});
+module.exports = __toCommonJS(src_exports);
+
+// src/lib/snap-pixel-loader.ts
+function safeSnaptr(...args) {
+  if (typeof window === "undefined") return false;
+  const fn = window.snaptr;
+  if (typeof fn !== "function") return false;
+  try {
+    fn(...args);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// src/lib/dedup.ts
+var MS_PER_MINUTE = 60 * 1e3;
+function deriveMinuteBucket(nowMs) {
+  if (!Number.isFinite(nowMs)) return 0;
+  return Math.floor(nowMs / MS_PER_MINUTE);
+}
+function minuteBucketNow() {
+  return deriveMinuteBucket(Date.now());
+}
+function safeKey(primaryKey) {
+  if (!primaryKey) return "unknown";
+  return primaryKey.replace(/[^a-zA-Z0-9_-]/g, "_");
+}
+function makeEventId(eventName, primaryKey, minuteBucket = minuteBucketNow()) {
+  return `${eventName}_${safeKey(primaryKey)}_${minuteBucket}`;
+}
+function deriveOrderIdForPurchase(eventName, orderId) {
+  if (eventName !== "PURCHASE") return void 0;
+  if (typeof orderId !== "string") return void 0;
+  const trimmed = orderId.trim();
+  return trimmed ? trimmed : void 0;
+}
+
+// src/hooks/useSnapchatEvents.ts
+var CAPI_PROXY_ENDPOINT = "/api/snapchat-ads/events";
+function currentUrl() {
+  return typeof window !== "undefined" ? window.location.href : "";
+}
+async function sendSnapchatCapiEvent(payload) {
+  try {
+    await fetch(CAPI_PROXY_ENDPOINT, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(payload)
+    });
+  } catch {
+  }
+}
+function trackPageView(primaryKey, userData = {}, eventId) {
+  const eid = eventId ?? makeEventId("PAGE_VIEW", primaryKey, minuteBucketNow());
+  safeSnaptr("track", "PAGE_VIEW", { client_dedup_id: eid });
+  void sendSnapchatCapiEvent({
+    eventName: "PAGE_VIEW",
+    eventId: eid,
+    eventSourceUrl: currentUrl(),
+    userData
+  });
+}
+function trackViewContent(productId, options = {}) {
+  const eid = options.eventId ?? makeEventId("VIEW_CONTENT", productId, minuteBucketNow());
+  const contentIds = options.contentIds ?? [productId];
+  const customData = {
+    ...options.currency ? { currency: options.currency } : {},
+    ...options.value !== void 0 ? { value: options.value } : {},
+    ...contentIds.length ? { contentIds } : {},
+    ...options.contents?.length ? { contents: options.contents } : {},
+    ...typeof options.numItems === "number" ? { numItems: options.numItems } : {}
+  };
+  safeSnaptr("track", "VIEW_CONTENT", {
+    ...contentIds.length ? { item_ids: contentIds } : {},
+    ...options.currency ? { currency: options.currency } : {},
+    ...options.value !== void 0 ? { value: options.value } : {},
+    client_dedup_id: eid
+  });
+  void sendSnapchatCapiEvent({
+    eventName: "VIEW_CONTENT",
+    eventId: eid,
+    eventSourceUrl: currentUrl(),
+    userData: options.userData ?? {},
+    customData
+  });
+}
+function trackAddCart(cartId, options = {}) {
+  const eid = options.eventId ?? makeEventId("ADD_CART", cartId, minuteBucketNow());
+  const customData = {
+    ...options.currency ? { currency: options.currency } : {},
+    ...options.value !== void 0 ? { value: options.value } : {},
+    ...options.contentIds?.length ? { contentIds: options.contentIds } : {},
+    ...options.contents?.length ? { contents: options.contents } : {},
+    ...typeof options.numItems === "number" ? { numItems: options.numItems } : {}
+  };
+  safeSnaptr("track", "ADD_CART", {
+    ...options.contentIds?.length ? { item_ids: options.contentIds } : {},
+    ...options.currency ? { currency: options.currency } : {},
+    ...options.value !== void 0 ? { value: options.value } : {},
+    ...typeof options.numItems === "number" ? { number_items: options.numItems } : {},
+    client_dedup_id: eid
+  });
+  void sendSnapchatCapiEvent({
+    eventName: "ADD_CART",
+    eventId: eid,
+    eventSourceUrl: currentUrl(),
+    userData: options.userData ?? {},
+    customData
+  });
+}
+function trackStartCheckout(cartId, options = {}) {
+  const eid = options.eventId ?? makeEventId("START_CHECKOUT", cartId, minuteBucketNow());
+  const customData = {
+    ...options.currency ? { currency: options.currency } : {},
+    ...options.value !== void 0 ? { value: options.value } : {},
+    ...options.contentIds?.length ? { contentIds: options.contentIds } : {},
+    ...options.contents?.length ? { contents: options.contents } : {},
+    ...typeof options.numItems === "number" ? { numItems: options.numItems } : {}
+  };
+  safeSnaptr("track", "START_CHECKOUT", {
+    ...options.contentIds?.length ? { item_ids: options.contentIds } : {},
+    ...options.currency ? { currency: options.currency } : {},
+    ...options.value !== void 0 ? { value: options.value } : {},
+    ...typeof options.numItems === "number" ? { number_items: options.numItems } : {},
+    client_dedup_id: eid
+  });
+  void sendSnapchatCapiEvent({
+    eventName: "START_CHECKOUT",
+    eventId: eid,
+    eventSourceUrl: currentUrl(),
+    userData: options.userData ?? {},
+    customData
+  });
+}
+function trackPurchase(orderId, options = {}) {
+  const eid = options.eventId ?? makeEventId("PURCHASE", orderId, 0);
+  const derivedOrderId = deriveOrderIdForPurchase("PURCHASE", orderId);
+  const customData = {
+    ...options.currency ? { currency: options.currency } : {},
+    ...options.value !== void 0 ? { value: options.value } : {},
+    ...options.contentIds?.length ? { contentIds: options.contentIds } : {},
+    ...options.contents?.length ? { contents: options.contents } : {},
+    ...typeof options.numItems === "number" ? { numItems: options.numItems } : {},
+    ...derivedOrderId ? { orderId: derivedOrderId } : {}
+  };
+  safeSnaptr("track", "PURCHASE", {
+    ...options.contentIds?.length ? { item_ids: options.contentIds } : {},
+    ...options.currency ? { currency: options.currency } : {},
+    ...options.value !== void 0 ? { value: options.value } : {},
+    ...typeof options.numItems === "number" ? { number_items: options.numItems } : {},
+    ...derivedOrderId ? { transaction_id: derivedOrderId } : {},
+    client_dedup_id: eid
+  });
+  void sendSnapchatCapiEvent({
+    eventName: "PURCHASE",
+    eventId: eid,
+    eventSourceUrl: currentUrl(),
+    userData: options.userData ?? {},
+    customData
+  });
+}
+
+// src/get-config.ts
+function resolveEnv(key) {
+  if (key === "NEXT_PUBLIC_MEDUSA_BACKEND_URL") return process.env.NEXT_PUBLIC_MEDUSA_BACKEND_URL;
+  if (key === "NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY") return process.env.NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY;
+  if (key === "NEXT_PUBLIC_STORE_ID") return process.env.NEXT_PUBLIC_STORE_ID;
+  return void 0;
+}
+async function getSnapchatAdsConfig(options = {}) {
+  const baseUrl = options.baseUrl ?? resolveEnv("NEXT_PUBLIC_MEDUSA_BACKEND_URL") ?? "http://localhost:9000";
+  const publishableKey = options.publishableApiKey ?? resolveEnv("NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY");
+  const storeId = options.storeId ?? resolveEnv("NEXT_PUBLIC_STORE_ID");
+  try {
+    const res = await fetch(`${baseUrl}/store/snapchat-ads/config`, {
+      headers: {
+        ...storeId ? { "X-Store-Environment-ID": storeId } : {},
+        ...publishableKey ? { "x-publishable-api-key": publishableKey } : {}
+      },
+      next: { revalidate: 60 }
+    });
+    if (!res.ok) return null;
+    return await res.json();
+  } catch {
+    return null;
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  deriveMinuteBucket,
+  getSnapchatAdsConfig,
+  makeEventId,
+  minuteBucketNow,
+  sendSnapchatCapiEvent,
+  trackAddCart,
+  trackPageView,
+  trackPurchase,
+  trackStartCheckout,
+  trackViewContent
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/lib/snap-pixel-loader.ts","../src/lib/dedup.ts","../src/hooks/useSnapchatEvents.ts","../src/get-config.ts"],"sourcesContent":["export {\n  trackPageView,\n  trackViewContent,\n  trackAddCart,\n  trackStartCheckout,\n  trackPurchase,\n  sendSnapchatCapiEvent,\n} from './hooks/useSnapchatEvents'\n\nexport { getSnapchatAdsConfig } from './get-config'\n\nexport { makeEventId, deriveMinuteBucket, minuteBucketNow } from './lib/dedup'\n\n// `SnapchatAdsConfig` (the secret-bearing full shape with\n// `snap_conversion_api_token` / `snap_ad_account_id`) is intentionally NOT\n// exported: those fields never leave the Medusa side, and re-exporting the\n// type from a browser package invites callers to write handling that\n// assumes a secret is present. Storefront code consumes\n// `SnapchatAdsPublicConfig` only.\nexport type {\n  SnapchatAdsPublicConfig,\n  SnapEventName,\n  SnapUserData,\n  SnapCustomData,\n  SnapEventPayload,\n} from './types'\n","/**\n * Snap Pixel loader - installs the `snaptr` shim and injects\n * `https://sc-static.net/scevent.min.js`. Snap does NOT ship an\n * npm-installable browser SDK (research memo Section 10), so we inline\n * the same IIFE shape the official Snap install snippet emits. Once the\n * script loads, Snap reconciles the shim queue and subsequent calls\n * flow directly through.\n *\n * The shim mirrors Snap's canonical shape so their loaded pixel finds\n * the expected `handleRequest` / `queue` fields and picks up buffered\n * calls made before the network load completes.\n *\n * Idempotent: subsequent calls no-op if `window.snaptr` is already set,\n * so consent flips or SPA nav doesn't stack multiple scripts.\n */\n\ndeclare global {\n  interface Window {\n    snaptr?: SnaptrFunction\n  }\n}\n\nexport type SnaptrFunction = ((...args: unknown[]) => void) & {\n  handleRequest?: (...args: unknown[]) => void\n  push?: (...args: unknown[]) => void\n  queue?: unknown[][]\n  version?: string\n  loaded?: boolean\n}\n\nconst SCRIPT_SRC = 'https://sc-static.net/scevent.min.js'\n\n/**\n * Install the snaptr shim + inject `sc-static.net/scevent.min.js`.\n * Idempotent - safe to call multiple times.\n */\nexport function installSnapPixelShim(): void {\n  if (typeof window === 'undefined' || typeof document === 'undefined') return\n  if (window.snaptr) return\n\n  const queue: unknown[][] = []\n  const shim: SnaptrFunction = function (...args: unknown[]): void {\n    if (typeof shim.handleRequest === 'function') {\n      shim.handleRequest(...args)\n      return\n    }\n    queue.push(args)\n  } as SnaptrFunction\n  shim.push = function (...args: unknown[]): void {\n    queue.push(args)\n  }\n  shim.queue = queue\n  shim.version = '1.0'\n  shim.loaded = true\n  window.snaptr = shim\n\n  const script = document.createElement('script')\n  script.async = true\n  script.src = SCRIPT_SRC\n  document.head.appendChild(script)\n}\n\n/**\n * Best-effort synchronous call. Returns whether snaptr was ready. Slot\n * components use this so events queued before `scevent.min.js` finishes\n * loading still land - Snap's script drains the shim queue on load.\n */\nexport function safeSnaptr(...args: unknown[]): boolean {\n  if (typeof window === 'undefined') return false\n  const fn = window.snaptr\n  if (typeof fn !== 'function') return false\n  try {\n    fn(...args)\n    return true\n  } catch {\n    return false\n  }\n}\n\n/**\n * Poll `window.snaptr` on `requestAnimationFrame` up to `maxAttempts`\n * times, invoking the callback on the first tick where snaptr exists.\n * Escape hatch for callers that must run the moment snaptr becomes\n * ready. The standard slot components rely on the shim queue via\n * `safeSnaptr()`.\n */\nexport function whenSnaptrReady(cb: (fn: SnaptrFunction) => void, maxAttempts = 20): () => void {\n  if (typeof window === 'undefined') return () => {}\n  let cancelled = false\n  let attempts = 0\n\n  const tick = (): void => {\n    if (cancelled) return\n    attempts += 1\n    const fn = window.snaptr\n    if (typeof fn === 'function') {\n      cb(fn)\n      return\n    }\n    if (attempts >= maxAttempts) return\n    if (typeof requestAnimationFrame === 'function') {\n      requestAnimationFrame(tick)\n    } else {\n      setTimeout(tick, 50)\n    }\n  }\n\n  tick()\n  return () => {\n    cancelled = true\n  }\n}\n","import type { SnapEventName } from '../types'\n\n/**\n * Deterministic event-ID builder for Snap browser <-> CAPI dedup.\n *\n * Event ID contract (research memo Section 5, encoded verbatim):\n *\n * > For the 5 events (PAGE_VIEW, VIEW_CONTENT, ADD_CART, START_CHECKOUT,\n * > PURCHASE), the browser Pixel call and the CAPI server call MUST share a\n * > top-level `event_id` (Pixel side: `client_dedup_id`), matched by Snap\n * > within a 48-hour window. For PURCHASE ONLY, they MUST additionally share\n * > `custom_data.order_id` (CAPI) / `transaction_id` (Pixel), matched within\n * > a 30-day window. Reuse the Amboras cart/order id as both `order_id` and\n * > `transaction_id`; mint a deterministic UUID from `(event_name,\n * > cart_id_or_session_id, minute_bucket)` for `event_id`/`client_dedup_id`.\n * > Never let the Pixel SDK auto-mint `client_dedup_id` - it prefixes with\n * > `@-` and never matches CAPI (research memo Section 5).\n *\n * Determinism matters because the browser Pixel call and the CAPI relay\n * call happen in parallel from the same user action - if the IDs don't\n * match, Snap counts the event twice.\n *\n * Contract:\n *   - Same `(eventName, primaryKey, minuteBucket)` always produces the\n *     same ID.\n *   - Different event names with the same primary key produce different\n *     IDs (a `VIEW_CONTENT` and `ADD_CART` for the same product shouldn't\n *     collide).\n *   - The minute-bucket component keeps browser retries within the same\n *     minute stable (both sides land on the same ID), but rotates the ID\n *     for user actions in a subsequent minute so we don't accidentally\n *     collapse two genuine events.\n */\n\nconst MS_PER_MINUTE = 60 * 1000\n\n/** Bucket a Unix millisecond timestamp into whole minutes. */\nexport function deriveMinuteBucket(nowMs: number): number {\n  if (!Number.isFinite(nowMs)) return 0\n  return Math.floor(nowMs / MS_PER_MINUTE)\n}\n\n/** Convenience wrapper for `deriveMinuteBucket(Date.now())`. */\nexport function minuteBucketNow(): number {\n  return deriveMinuteBucket(Date.now())\n}\n\n/**\n * Sanitize a primary key for inclusion in an event id. Snap accepts\n * alphanumerics + `_` + `-`; anything else gets folded to `_` so a\n * merchant using URLs with query strings as page-view keys doesn't\n * produce malformed ids.\n */\nfunction safeKey(primaryKey: string): string {\n  if (!primaryKey) return 'unknown'\n  return primaryKey.replace(/[^a-zA-Z0-9_-]/g, '_')\n}\n\n/**\n * Mint a deterministic event id for `event_id` (CAPI) and\n * `client_dedup_id` (Pixel). See contract above.\n *\n * Callers that want a stable id across a longer window (e.g. tying two\n * page-view fires back to back to the same URL) can pin `minuteBucket` to\n * a well-known value; the default is `minuteBucketNow()`. For PURCHASE,\n * pin `minuteBucket` to a constant per order (recommend `0`) so a\n * failing browser fire that retries in a later minute still dedups\n * against the server event.\n */\nexport function makeEventId(\n  eventName: SnapEventName,\n  primaryKey: string,\n  minuteBucket: number = minuteBucketNow(),\n): string {\n  return `${eventName}_${safeKey(primaryKey)}_${minuteBucket}`\n}\n\n/**\n * Derivation helper for the PURCHASE event's 30-day dedup pair. Reuses\n * the Amboras order id as both `custom_data.order_id` (CAPI) and\n * `transaction_id` (Pixel) so Snap can dedup on the 30-day window even\n * if the 48h `event_id` window has expired.\n *\n * Returns `undefined` for non-PURCHASE events (encodes the \"PURCHASE\n * only\" leg of the dual-dedup scheme).\n */\nexport function deriveOrderIdForPurchase(\n  eventName: SnapEventName,\n  orderId: string | undefined,\n): string | undefined {\n  if (eventName !== 'PURCHASE') return undefined\n  if (typeof orderId !== 'string') return undefined\n  const trimmed = orderId.trim()\n  return trimmed ? trimmed : undefined\n}\n","import type { SnapEventName, SnapEventPayload, SnapUserData, SnapCustomData } from '../types'\nimport { safeSnaptr } from '../lib/snap-pixel-loader'\nimport { makeEventId, minuteBucketNow, deriveOrderIdForPurchase } from '../lib/dedup'\n\n/**\n * Client-side dual-fire hooks for Snap. Every event flows two ways from\n * the same user action:\n *\n *   1. Browser pixel: `snaptr('track', <EVENT_NAME>, { ..., client_dedup_id })`\n *      via the loaded `scevent.min.js`.\n *   2. Server-side CAPI: POST to the storefront proxy at\n *      `/api/snapchat-ads/events` which enriches with\n *      `client_ip_address` + `client_user_agent` and forwards to Medusa\n *      `/store/snapchat-ads/capi`.\n *\n * Both sides carry the SAME `event_id` / `client_dedup_id` so Snap can\n * dedup within 48h. For PURCHASE only, both sides also share\n * `custom_data.order_id` / `transaction_id` for the 30-day dedup window\n * (research memo Section 5).\n *\n * Snap v3 wire caveats encoded here:\n *   - Event names are UPPER_SNAKE_CASE (PAGE_VIEW / VIEW_CONTENT /\n *     ADD_CART / START_CHECKOUT / PURCHASE).\n *   - `value`, `item_price`, `quantity` are STRINGS in the CAPI payload.\n *     The browser pixel is more lenient but we mirror the same string\n *     serialization so the two sides stay symmetric and dedup diffs read\n *     cleanly in logs.\n *   - PII (`em`, `ph`, `madid`, `external_id`) is passed RAW from the\n *     browser and hashed on the Medusa side by `sendSnapchatCapiEvent`.\n *     The proxy strips raw PII before forwarding to Snap.\n *\n * All fires are non-throwing - a failed CAPI relay is logged, never\n * bubbled, so a merchant's storefront cannot break because Snap's edge\n * had a hiccup.\n */\n\nconst CAPI_PROXY_ENDPOINT = '/api/snapchat-ads/events'\n\nfunction currentUrl(): string {\n  return typeof window !== 'undefined' ? window.location.href : ''\n}\n\n/**\n * Send a server-side Snap CAPI event via the storefront's proxy. Fire-\n * and-forget from the caller's perspective; internal errors are swallowed\n * because analytics loss is preferable to storefront breakage.\n *\n * Intentionally NOT gated on analytics consent - Snap CAPI operates on a\n * different legal basis (order-tracking legitimate interest) than the\n * browser pixel. The `SnapPixelProvider` handles browser-side consent\n * gating separately.\n */\nexport async function sendSnapchatCapiEvent(payload: SnapEventPayload): Promise<void> {\n  try {\n    await fetch(CAPI_PROXY_ENDPOINT, {\n      method: 'POST',\n      headers: { 'Content-Type': 'application/json' },\n      body: JSON.stringify(payload),\n    })\n  } catch {\n    // non-fatal\n  }\n}\n\n/**\n * Fire PAGE_VIEW on both sides. The `SnapPixelProvider` already fires\n * this on mount + route change; this hook is exposed for callers that\n * want to trigger a page-view manually (e.g. modal opens counted as\n * page views).\n */\nexport function trackPageView(\n  primaryKey: string,\n  userData: SnapUserData = {},\n  eventId?: string,\n): void {\n  const eid = eventId ?? makeEventId('PAGE_VIEW', primaryKey, minuteBucketNow())\n  safeSnaptr('track', 'PAGE_VIEW', { client_dedup_id: eid })\n  void sendSnapchatCapiEvent({\n    eventName: 'PAGE_VIEW',\n    eventId: eid,\n    eventSourceUrl: currentUrl(),\n    userData,\n  })\n}\n\nexport interface TrackViewContentOptions {\n  currency?: string\n  /** Major-unit value STRING (e.g. `\"10.50\"`). */\n  value?: string\n  /** Product / variant id passed to Snap as `content_ids`. */\n  contentIds?: string[]\n  /** Optional per-line breakdown. `item_price` + `quantity` are STRINGS. */\n  contents?: Array<{ id: string; quantity: string; item_price?: string }>\n  numItems?: number\n  userData?: SnapUserData\n  eventId?: string\n}\n\nexport function trackViewContent(productId: string, options: TrackViewContentOptions = {}): void {\n  const eid = options.eventId ?? makeEventId('VIEW_CONTENT', productId, minuteBucketNow())\n  const contentIds = options.contentIds ?? [productId]\n  const customData: SnapCustomData = {\n    ...(options.currency ? { currency: options.currency } : {}),\n    ...(options.value !== undefined ? { value: options.value } : {}),\n    ...(contentIds.length ? { contentIds } : {}),\n    ...(options.contents?.length ? { contents: options.contents } : {}),\n    ...(typeof options.numItems === 'number' ? { numItems: options.numItems } : {}),\n  }\n  safeSnaptr('track', 'VIEW_CONTENT', {\n    ...(contentIds.length ? { item_ids: contentIds } : {}),\n    ...(options.currency ? { currency: options.currency } : {}),\n    ...(options.value !== undefined ? { value: options.value } : {}),\n    client_dedup_id: eid,\n  })\n  void sendSnapchatCapiEvent({\n    eventName: 'VIEW_CONTENT',\n    eventId: eid,\n    eventSourceUrl: currentUrl(),\n    userData: options.userData ?? {},\n    customData,\n  })\n}\n\nexport interface TrackAddCartOptions {\n  currency?: string\n  /** Major-unit value STRING. */\n  value?: string\n  /** Product / variant ids. */\n  contentIds?: string[]\n  contents?: Array<{ id: string; quantity: string; item_price?: string }>\n  /** Top-level `num_items` - number-typed per Snap docs. */\n  numItems?: number\n  userData?: SnapUserData\n  eventId?: string\n}\n\nexport function trackAddCart(cartId: string, options: TrackAddCartOptions = {}): void {\n  const eid = options.eventId ?? makeEventId('ADD_CART', cartId, minuteBucketNow())\n  const customData: SnapCustomData = {\n    ...(options.currency ? { currency: options.currency } : {}),\n    ...(options.value !== undefined ? { value: options.value } : {}),\n    ...(options.contentIds?.length ? { contentIds: options.contentIds } : {}),\n    ...(options.contents?.length ? { contents: options.contents } : {}),\n    ...(typeof options.numItems === 'number' ? { numItems: options.numItems } : {}),\n  }\n  safeSnaptr('track', 'ADD_CART', {\n    ...(options.contentIds?.length ? { item_ids: options.contentIds } : {}),\n    ...(options.currency ? { currency: options.currency } : {}),\n    ...(options.value !== undefined ? { value: options.value } : {}),\n    ...(typeof options.numItems === 'number' ? { number_items: options.numItems } : {}),\n    client_dedup_id: eid,\n  })\n  void sendSnapchatCapiEvent({\n    eventName: 'ADD_CART',\n    eventId: eid,\n    eventSourceUrl: currentUrl(),\n    userData: options.userData ?? {},\n    customData,\n  })\n}\n\nexport interface TrackStartCheckoutOptions {\n  currency?: string\n  value?: string\n  contentIds?: string[]\n  contents?: Array<{ id: string; quantity: string; item_price?: string }>\n  numItems?: number\n  userData?: SnapUserData\n  eventId?: string\n}\n\nexport function trackStartCheckout(cartId: string, options: TrackStartCheckoutOptions = {}): void {\n  const eid = options.eventId ?? makeEventId('START_CHECKOUT', cartId, minuteBucketNow())\n  const customData: SnapCustomData = {\n    ...(options.currency ? { currency: options.currency } : {}),\n    ...(options.value !== undefined ? { value: options.value } : {}),\n    ...(options.contentIds?.length ? { contentIds: options.contentIds } : {}),\n    ...(options.contents?.length ? { contents: options.contents } : {}),\n    ...(typeof options.numItems === 'number' ? { numItems: options.numItems } : {}),\n  }\n  safeSnaptr('track', 'START_CHECKOUT', {\n    ...(options.contentIds?.length ? { item_ids: options.contentIds } : {}),\n    ...(options.currency ? { currency: options.currency } : {}),\n    ...(options.value !== undefined ? { value: options.value } : {}),\n    ...(typeof options.numItems === 'number' ? { number_items: options.numItems } : {}),\n    client_dedup_id: eid,\n  })\n  void sendSnapchatCapiEvent({\n    eventName: 'START_CHECKOUT',\n    eventId: eid,\n    eventSourceUrl: currentUrl(),\n    userData: options.userData ?? {},\n    customData,\n  })\n}\n\nexport interface TrackPurchaseOptions {\n  currency?: string\n  value?: string\n  contentIds?: string[]\n  contents?: Array<{ id: string; quantity: string; item_price?: string }>\n  numItems?: number\n  userData?: SnapUserData\n  /**\n   * When present, pins `event_id` / `client_dedup_id` explicitly; otherwise\n   * a stable id is derived from `(PURCHASE, orderId, 0)` - minute-bucket 0\n   * so retries within a longer window still dedup against the server event.\n   */\n  eventId?: string\n}\n\n/**\n * PURCHASE gets the dual-dedup treatment:\n *   - Top-level `event_id` / Pixel `client_dedup_id` shared for 48h window.\n *   - `custom_data.order_id` / Pixel `transaction_id` shared for 30-day\n *     window. Reuses the Amboras order id as both.\n */\nexport function trackPurchase(orderId: string, options: TrackPurchaseOptions = {}): void {\n  // Pin minute-bucket to 0 for PURCHASE so a browser retry in a later\n  // minute still lands on the same event_id as the initial server fire.\n  const eid = options.eventId ?? makeEventId('PURCHASE', orderId, 0)\n  const derivedOrderId = deriveOrderIdForPurchase('PURCHASE', orderId)\n  const customData: SnapCustomData = {\n    ...(options.currency ? { currency: options.currency } : {}),\n    ...(options.value !== undefined ? { value: options.value } : {}),\n    ...(options.contentIds?.length ? { contentIds: options.contentIds } : {}),\n    ...(options.contents?.length ? { contents: options.contents } : {}),\n    ...(typeof options.numItems === 'number' ? { numItems: options.numItems } : {}),\n    ...(derivedOrderId ? { orderId: derivedOrderId } : {}),\n  }\n  safeSnaptr('track', 'PURCHASE', {\n    ...(options.contentIds?.length ? { item_ids: options.contentIds } : {}),\n    ...(options.currency ? { currency: options.currency } : {}),\n    ...(options.value !== undefined ? { value: options.value } : {}),\n    ...(typeof options.numItems === 'number' ? { number_items: options.numItems } : {}),\n    ...(derivedOrderId ? { transaction_id: derivedOrderId } : {}),\n    client_dedup_id: eid,\n  })\n  void sendSnapchatCapiEvent({\n    eventName: 'PURCHASE',\n    eventId: eid,\n    eventSourceUrl: currentUrl(),\n    userData: options.userData ?? {},\n    customData,\n  })\n}\n","import type { SnapchatAdsPublicConfig } from './types'\n\nfunction resolveEnv(key: string): string | undefined {\n  if (key === 'NEXT_PUBLIC_MEDUSA_BACKEND_URL') return process.env.NEXT_PUBLIC_MEDUSA_BACKEND_URL\n  if (key === 'NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY') return process.env.NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY\n  if (key === 'NEXT_PUBLIC_STORE_ID') return process.env.NEXT_PUBLIC_STORE_ID\n  return undefined\n}\n\ninterface GetSnapchatAdsConfigOptions {\n  baseUrl?: string\n  publishableApiKey?: string\n  storeId?: string\n}\n\n/**\n * Fetch the non-secret Snapchat Ads config from the Medusa Store API. Returns\n * `null` when the store isn't wired up, when the publishable key is missing,\n * or on any transport error - callers should treat `null` as \"plugin\n * off\" and skip event firing.\n *\n * NEVER surfaces `snap_conversion_api_token` or `snap_ad_account_id` -\n * those live only on the Medusa side and never leave the server.\n */\nexport async function getSnapchatAdsConfig(\n  options: GetSnapchatAdsConfigOptions = {},\n): Promise<SnapchatAdsPublicConfig | null> {\n  const baseUrl = options.baseUrl ?? resolveEnv('NEXT_PUBLIC_MEDUSA_BACKEND_URL') ?? 'http://localhost:9000'\n  const publishableKey = options.publishableApiKey ?? resolveEnv('NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY')\n  const storeId = options.storeId ?? resolveEnv('NEXT_PUBLIC_STORE_ID')\n\n  try {\n    // `next` is a Next.js fetch extension for cache revalidation - ignored outside Next.js\n    const res = await fetch(`${baseUrl}/store/snapchat-ads/config`, {\n      headers: {\n        ...(storeId ? { 'X-Store-Environment-ID': storeId } : {}),\n        ...(publishableKey ? { 'x-publishable-api-key': publishableKey } : {}),\n      },\n      next: { revalidate: 60 },\n    } as RequestInit)\n    if (!res.ok) return null\n    return (await res.json()) as SnapchatAdsPublicConfig\n  } catch {\n    return null\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/index.mjs

@@ -0,0 +1,177 @@
+import {
+  getSnapchatAdsConfig
+} from "./chunk-PK23QMZT.mjs";
+
+// src/lib/snap-pixel-loader.ts
+function safeSnaptr(...args) {
+  if (typeof window === "undefined") return false;
+  const fn = window.snaptr;
+  if (typeof fn !== "function") return false;
+  try {
+    fn(...args);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// src/lib/dedup.ts
+var MS_PER_MINUTE = 60 * 1e3;
+function deriveMinuteBucket(nowMs) {
+  if (!Number.isFinite(nowMs)) return 0;
+  return Math.floor(nowMs / MS_PER_MINUTE);
+}
+function minuteBucketNow() {
+  return deriveMinuteBucket(Date.now());
+}
+function safeKey(primaryKey) {
+  if (!primaryKey) return "unknown";
+  return primaryKey.replace(/[^a-zA-Z0-9_-]/g, "_");
+}
+function makeEventId(eventName, primaryKey, minuteBucket = minuteBucketNow()) {
+  return `${eventName}_${safeKey(primaryKey)}_${minuteBucket}`;
+}
+function deriveOrderIdForPurchase(eventName, orderId) {
+  if (eventName !== "PURCHASE") return void 0;
+  if (typeof orderId !== "string") return void 0;
+  const trimmed = orderId.trim();
+  return trimmed ? trimmed : void 0;
+}
+
+// src/hooks/useSnapchatEvents.ts
+var CAPI_PROXY_ENDPOINT = "/api/snapchat-ads/events";
+function currentUrl() {
+  return typeof window !== "undefined" ? window.location.href : "";
+}
+async function sendSnapchatCapiEvent(payload) {
+  try {
+    await fetch(CAPI_PROXY_ENDPOINT, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(payload)
+    });
+  } catch {
+  }
+}
+function trackPageView(primaryKey, userData = {}, eventId) {
+  const eid = eventId ?? makeEventId("PAGE_VIEW", primaryKey, minuteBucketNow());
+  safeSnaptr("track", "PAGE_VIEW", { client_dedup_id: eid });
+  void sendSnapchatCapiEvent({
+    eventName: "PAGE_VIEW",
+    eventId: eid,
+    eventSourceUrl: currentUrl(),
+    userData
+  });
+}
+function trackViewContent(productId, options = {}) {
+  const eid = options.eventId ?? makeEventId("VIEW_CONTENT", productId, minuteBucketNow());
+  const contentIds = options.contentIds ?? [productId];
+  const customData = {
+    ...options.currency ? { currency: options.currency } : {},
+    ...options.value !== void 0 ? { value: options.value } : {},
+    ...contentIds.length ? { contentIds } : {},
+    ...options.contents?.length ? { contents: options.contents } : {},
+    ...typeof options.numItems === "number" ? { numItems: options.numItems } : {}
+  };
+  safeSnaptr("track", "VIEW_CONTENT", {
+    ...contentIds.length ? { item_ids: contentIds } : {},
+    ...options.currency ? { currency: options.currency } : {},
+    ...options.value !== void 0 ? { value: options.value } : {},
+    client_dedup_id: eid
+  });
+  void sendSnapchatCapiEvent({
+    eventName: "VIEW_CONTENT",
+    eventId: eid,
+    eventSourceUrl: currentUrl(),
+    userData: options.userData ?? {},
+    customData
+  });
+}
+function trackAddCart(cartId, options = {}) {
+  const eid = options.eventId ?? makeEventId("ADD_CART", cartId, minuteBucketNow());
+  const customData = {
+    ...options.currency ? { currency: options.currency } : {},
+    ...options.value !== void 0 ? { value: options.value } : {},
+    ...options.contentIds?.length ? { contentIds: options.contentIds } : {},
+    ...options.contents?.length ? { contents: options.contents } : {},
+    ...typeof options.numItems === "number" ? { numItems: options.numItems } : {}
+  };
+  safeSnaptr("track", "ADD_CART", {
+    ...options.contentIds?.length ? { item_ids: options.contentIds } : {},
+    ...options.currency ? { currency: options.currency } : {},
+    ...options.value !== void 0 ? { value: options.value } : {},
+    ...typeof options.numItems === "number" ? { number_items: options.numItems } : {},
+    client_dedup_id: eid
+  });
+  void sendSnapchatCapiEvent({
+    eventName: "ADD_CART",
+    eventId: eid,
+    eventSourceUrl: currentUrl(),
+    userData: options.userData ?? {},
+    customData
+  });
+}
+function trackStartCheckout(cartId, options = {}) {
+  const eid = options.eventId ?? makeEventId("START_CHECKOUT", cartId, minuteBucketNow());
+  const customData = {
+    ...options.currency ? { currency: options.currency } : {},
+    ...options.value !== void 0 ? { value: options.value } : {},
+    ...options.contentIds?.length ? { contentIds: options.contentIds } : {},
+    ...options.contents?.length ? { contents: options.contents } : {},
+    ...typeof options.numItems === "number" ? { numItems: options.numItems } : {}
+  };
+  safeSnaptr("track", "START_CHECKOUT", {
+    ...options.contentIds?.length ? { item_ids: options.contentIds } : {},
+    ...options.currency ? { currency: options.currency } : {},
+    ...options.value !== void 0 ? { value: options.value } : {},
+    ...typeof options.numItems === "number" ? { number_items: options.numItems } : {},
+    client_dedup_id: eid
+  });
+  void sendSnapchatCapiEvent({
+    eventName: "START_CHECKOUT",
+    eventId: eid,
+    eventSourceUrl: currentUrl(),
+    userData: options.userData ?? {},
+    customData
+  });
+}
+function trackPurchase(orderId, options = {}) {
+  const eid = options.eventId ?? makeEventId("PURCHASE", orderId, 0);
+  const derivedOrderId = deriveOrderIdForPurchase("PURCHASE", orderId);
+  const customData = {
+    ...options.currency ? { currency: options.currency } : {},
+    ...options.value !== void 0 ? { value: options.value } : {},
+    ...options.contentIds?.length ? { contentIds: options.contentIds } : {},
+    ...options.contents?.length ? { contents: options.contents } : {},
+    ...typeof options.numItems === "number" ? { numItems: options.numItems } : {},
+    ...derivedOrderId ? { orderId: derivedOrderId } : {}
+  };
+  safeSnaptr("track", "PURCHASE", {
+    ...options.contentIds?.length ? { item_ids: options.contentIds } : {},
+    ...options.currency ? { currency: options.currency } : {},
+    ...options.value !== void 0 ? { value: options.value } : {},
+    ...typeof options.numItems === "number" ? { number_items: options.numItems } : {},
+    ...derivedOrderId ? { transaction_id: derivedOrderId } : {},
+    client_dedup_id: eid
+  });
+  void sendSnapchatCapiEvent({
+    eventName: "PURCHASE",
+    eventId: eid,
+    eventSourceUrl: currentUrl(),
+    userData: options.userData ?? {},
+    customData
+  });
+}
+export {
+  deriveMinuteBucket,
+  getSnapchatAdsConfig,
+  makeEventId,
+  minuteBucketNow,
+  sendSnapchatCapiEvent,
+  trackAddCart,
+  trackPageView,
+  trackPurchase,
+  trackStartCheckout,
+  trackViewContent
+};
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/lib/snap-pixel-loader.ts","../src/lib/dedup.ts","../src/hooks/useSnapchatEvents.ts"],"sourcesContent":["/**\n * Snap Pixel loader - installs the `snaptr` shim and injects\n * `https://sc-static.net/scevent.min.js`. Snap does NOT ship an\n * npm-installable browser SDK (research memo Section 10), so we inline\n * the same IIFE shape the official Snap install snippet emits. Once the\n * script loads, Snap reconciles the shim queue and subsequent calls\n * flow directly through.\n *\n * The shim mirrors Snap's canonical shape so their loaded pixel finds\n * the expected `handleRequest` / `queue` fields and picks up buffered\n * calls made before the network load completes.\n *\n * Idempotent: subsequent calls no-op if `window.snaptr` is already set,\n * so consent flips or SPA nav doesn't stack multiple scripts.\n */\n\ndeclare global {\n  interface Window {\n    snaptr?: SnaptrFunction\n  }\n}\n\nexport type SnaptrFunction = ((...args: unknown[]) => void) & {\n  handleRequest?: (...args: unknown[]) => void\n  push?: (...args: unknown[]) => void\n  queue?: unknown[][]\n  version?: string\n  loaded?: boolean\n}\n\nconst SCRIPT_SRC = 'https://sc-static.net/scevent.min.js'\n\n/**\n * Install the snaptr shim + inject `sc-static.net/scevent.min.js`.\n * Idempotent - safe to call multiple times.\n */\nexport function installSnapPixelShim(): void {\n  if (typeof window === 'undefined' || typeof document === 'undefined') return\n  if (window.snaptr) return\n\n  const queue: unknown[][] = []\n  const shim: SnaptrFunction = function (...args: unknown[]): void {\n    if (typeof shim.handleRequest === 'function') {\n      shim.handleRequest(...args)\n      return\n    }\n    queue.push(args)\n  } as SnaptrFunction\n  shim.push = function (...args: unknown[]): void {\n    queue.push(args)\n  }\n  shim.queue = queue\n  shim.version = '1.0'\n  shim.loaded = true\n  window.snaptr = shim\n\n  const script = document.createElement('script')\n  script.async = true\n  script.src = SCRIPT_SRC\n  document.head.appendChild(script)\n}\n\n/**\n * Best-effort synchronous call. Returns whether snaptr was ready. Slot\n * components use this so events queued before `scevent.min.js` finishes\n * loading still land - Snap's script drains the shim queue on load.\n */\nexport function safeSnaptr(...args: unknown[]): boolean {\n  if (typeof window === 'undefined') return false\n  const fn = window.snaptr\n  if (typeof fn !== 'function') return false\n  try {\n    fn(...args)\n    return true\n  } catch {\n    return false\n  }\n}\n\n/**\n * Poll `window.snaptr` on `requestAnimationFrame` up to `maxAttempts`\n * times, invoking the callback on the first tick where snaptr exists.\n * Escape hatch for callers that must run the moment snaptr becomes\n * ready. The standard slot components rely on the shim queue via\n * `safeSnaptr()`.\n */\nexport function whenSnaptrReady(cb: (fn: SnaptrFunction) => void, maxAttempts = 20): () => void {\n  if (typeof window === 'undefined') return () => {}\n  let cancelled = false\n  let attempts = 0\n\n  const tick = (): void => {\n    if (cancelled) return\n    attempts += 1\n    const fn = window.snaptr\n    if (typeof fn === 'function') {\n      cb(fn)\n      return\n    }\n    if (attempts >= maxAttempts) return\n    if (typeof requestAnimationFrame === 'function') {\n      requestAnimationFrame(tick)\n    } else {\n      setTimeout(tick, 50)\n    }\n  }\n\n  tick()\n  return () => {\n    cancelled = true\n  }\n}\n","import type { SnapEventName } from '../types'\n\n/**\n * Deterministic event-ID builder for Snap browser <-> CAPI dedup.\n *\n * Event ID contract (research memo Section 5, encoded verbatim):\n *\n * > For the 5 events (PAGE_VIEW, VIEW_CONTENT, ADD_CART, START_CHECKOUT,\n * > PURCHASE), the browser Pixel call and the CAPI server call MUST share a\n * > top-level `event_id` (Pixel side: `client_dedup_id`), matched by Snap\n * > within a 48-hour window. For PURCHASE ONLY, they MUST additionally share\n * > `custom_data.order_id` (CAPI) / `transaction_id` (Pixel), matched within\n * > a 30-day window. Reuse the Amboras cart/order id as both `order_id` and\n * > `transaction_id`; mint a deterministic UUID from `(event_name,\n * > cart_id_or_session_id, minute_bucket)` for `event_id`/`client_dedup_id`.\n * > Never let the Pixel SDK auto-mint `client_dedup_id` - it prefixes with\n * > `@-` and never matches CAPI (research memo Section 5).\n *\n * Determinism matters because the browser Pixel call and the CAPI relay\n * call happen in parallel from the same user action - if the IDs don't\n * match, Snap counts the event twice.\n *\n * Contract:\n *   - Same `(eventName, primaryKey, minuteBucket)` always produces the\n *     same ID.\n *   - Different event names with the same primary key produce different\n *     IDs (a `VIEW_CONTENT` and `ADD_CART` for the same product shouldn't\n *     collide).\n *   - The minute-bucket component keeps browser retries within the same\n *     minute stable (both sides land on the same ID), but rotates the ID\n *     for user actions in a subsequent minute so we don't accidentally\n *     collapse two genuine events.\n */\n\nconst MS_PER_MINUTE = 60 * 1000\n\n/** Bucket a Unix millisecond timestamp into whole minutes. */\nexport function deriveMinuteBucket(nowMs: number): number {\n  if (!Number.isFinite(nowMs)) return 0\n  return Math.floor(nowMs / MS_PER_MINUTE)\n}\n\n/** Convenience wrapper for `deriveMinuteBucket(Date.now())`. */\nexport function minuteBucketNow(): number {\n  return deriveMinuteBucket(Date.now())\n}\n\n/**\n * Sanitize a primary key for inclusion in an event id. Snap accepts\n * alphanumerics + `_` + `-`; anything else gets folded to `_` so a\n * merchant using URLs with query strings as page-view keys doesn't\n * produce malformed ids.\n */\nfunction safeKey(primaryKey: string): string {\n  if (!primaryKey) return 'unknown'\n  return primaryKey.replace(/[^a-zA-Z0-9_-]/g, '_')\n}\n\n/**\n * Mint a deterministic event id for `event_id` (CAPI) and\n * `client_dedup_id` (Pixel). See contract above.\n *\n * Callers that want a stable id across a longer window (e.g. tying two\n * page-view fires back to back to the same URL) can pin `minuteBucket` to\n * a well-known value; the default is `minuteBucketNow()`. For PURCHASE,\n * pin `minuteBucket` to a constant per order (recommend `0`) so a\n * failing browser fire that retries in a later minute still dedups\n * against the server event.\n */\nexport function makeEventId(\n  eventName: SnapEventName,\n  primaryKey: string,\n  minuteBucket: number = minuteBucketNow(),\n): string {\n  return `${eventName}_${safeKey(primaryKey)}_${minuteBucket}`\n}\n\n/**\n * Derivation helper for the PURCHASE event's 30-day dedup pair. Reuses\n * the Amboras order id as both `custom_data.order_id` (CAPI) and\n * `transaction_id` (Pixel) so Snap can dedup on the 30-day window even\n * if the 48h `event_id` window has expired.\n *\n * Returns `undefined` for non-PURCHASE events (encodes the \"PURCHASE\n * only\" leg of the dual-dedup scheme).\n */\nexport function deriveOrderIdForPurchase(\n  eventName: SnapEventName,\n  orderId: string | undefined,\n): string | undefined {\n  if (eventName !== 'PURCHASE') return undefined\n  if (typeof orderId !== 'string') return undefined\n  const trimmed = orderId.trim()\n  return trimmed ? trimmed : undefined\n}\n","import type { SnapEventName, SnapEventPayload, SnapUserData, SnapCustomData } from '../types'\nimport { safeSnaptr } from '../lib/snap-pixel-loader'\nimport { makeEventId, minuteBucketNow, deriveOrderIdForPurchase } from '../lib/dedup'\n\n/**\n * Client-side dual-fire hooks for Snap. Every event flows two ways from\n * the same user action:\n *\n *   1. Browser pixel: `snaptr('track', <EVENT_NAME>, { ..., client_dedup_id })`\n *      via the loaded `scevent.min.js`.\n *   2. Server-side CAPI: POST to the storefront proxy at\n *      `/api/snapchat-ads/events` which enriches with\n *      `client_ip_address` + `client_user_agent` and forwards to Medusa\n *      `/store/snapchat-ads/capi`.\n *\n * Both sides carry the SAME `event_id` / `client_dedup_id` so Snap can\n * dedup within 48h. For PURCHASE only, both sides also share\n * `custom_data.order_id` / `transaction_id` for the 30-day dedup window\n * (research memo Section 5).\n *\n * Snap v3 wire caveats encoded here:\n *   - Event names are UPPER_SNAKE_CASE (PAGE_VIEW / VIEW_CONTENT /\n *     ADD_CART / START_CHECKOUT / PURCHASE).\n *   - `value`, `item_price`, `quantity` are STRINGS in the CAPI payload.\n *     The browser pixel is more lenient but we mirror the same string\n *     serialization so the two sides stay symmetric and dedup diffs read\n *     cleanly in logs.\n *   - PII (`em`, `ph`, `madid`, `external_id`) is passed RAW from the\n *     browser and hashed on the Medusa side by `sendSnapchatCapiEvent`.\n *     The proxy strips raw PII before forwarding to Snap.\n *\n * All fires are non-throwing - a failed CAPI relay is logged, never\n * bubbled, so a merchant's storefront cannot break because Snap's edge\n * had a hiccup.\n */\n\nconst CAPI_PROXY_ENDPOINT = '/api/snapchat-ads/events'\n\nfunction currentUrl(): string {\n  return typeof window !== 'undefined' ? window.location.href : ''\n}\n\n/**\n * Send a server-side Snap CAPI event via the storefront's proxy. Fire-\n * and-forget from the caller's perspective; internal errors are swallowed\n * because analytics loss is preferable to storefront breakage.\n *\n * Intentionally NOT gated on analytics consent - Snap CAPI operates on a\n * different legal basis (order-tracking legitimate interest) than the\n * browser pixel. The `SnapPixelProvider` handles browser-side consent\n * gating separately.\n */\nexport async function sendSnapchatCapiEvent(payload: SnapEventPayload): Promise<void> {\n  try {\n    await fetch(CAPI_PROXY_ENDPOINT, {\n      method: 'POST',\n      headers: { 'Content-Type': 'application/json' },\n      body: JSON.stringify(payload),\n    })\n  } catch {\n    // non-fatal\n  }\n}\n\n/**\n * Fire PAGE_VIEW on both sides. The `SnapPixelProvider` already fires\n * this on mount + route change; this hook is exposed for callers that\n * want to trigger a page-view manually (e.g. modal opens counted as\n * page views).\n */\nexport function trackPageView(\n  primaryKey: string,\n  userData: SnapUserData = {},\n  eventId?: string,\n): void {\n  const eid = eventId ?? makeEventId('PAGE_VIEW', primaryKey, minuteBucketNow())\n  safeSnaptr('track', 'PAGE_VIEW', { client_dedup_id: eid })\n  void sendSnapchatCapiEvent({\n    eventName: 'PAGE_VIEW',\n    eventId: eid,\n    eventSourceUrl: currentUrl(),\n    userData,\n  })\n}\n\nexport interface TrackViewContentOptions {\n  currency?: string\n  /** Major-unit value STRING (e.g. `\"10.50\"`). */\n  value?: string\n  /** Product / variant id passed to Snap as `content_ids`. */\n  contentIds?: string[]\n  /** Optional per-line breakdown. `item_price` + `quantity` are STRINGS. */\n  contents?: Array<{ id: string; quantity: string; item_price?: string }>\n  numItems?: number\n  userData?: SnapUserData\n  eventId?: string\n}\n\nexport function trackViewContent(productId: string, options: TrackViewContentOptions = {}): void {\n  const eid = options.eventId ?? makeEventId('VIEW_CONTENT', productId, minuteBucketNow())\n  const contentIds = options.contentIds ?? [productId]\n  const customData: SnapCustomData = {\n    ...(options.currency ? { currency: options.currency } : {}),\n    ...(options.value !== undefined ? { value: options.value } : {}),\n    ...(contentIds.length ? { contentIds } : {}),\n    ...(options.contents?.length ? { contents: options.contents } : {}),\n    ...(typeof options.numItems === 'number' ? { numItems: options.numItems } : {}),\n  }\n  safeSnaptr('track', 'VIEW_CONTENT', {\n    ...(contentIds.length ? { item_ids: contentIds } : {}),\n    ...(options.currency ? { currency: options.currency } : {}),\n    ...(options.value !== undefined ? { value: options.value } : {}),\n    client_dedup_id: eid,\n  })\n  void sendSnapchatCapiEvent({\n    eventName: 'VIEW_CONTENT',\n    eventId: eid,\n    eventSourceUrl: currentUrl(),\n    userData: options.userData ?? {},\n    customData,\n  })\n}\n\nexport interface TrackAddCartOptions {\n  currency?: string\n  /** Major-unit value STRING. */\n  value?: string\n  /** Product / variant ids. */\n  contentIds?: string[]\n  contents?: Array<{ id: string; quantity: string; item_price?: string }>\n  /** Top-level `num_items` - number-typed per Snap docs. */\n  numItems?: number\n  userData?: SnapUserData\n  eventId?: string\n}\n\nexport function trackAddCart(cartId: string, options: TrackAddCartOptions = {}): void {\n  const eid = options.eventId ?? makeEventId('ADD_CART', cartId, minuteBucketNow())\n  const customData: SnapCustomData = {\n    ...(options.currency ? { currency: options.currency } : {}),\n    ...(options.value !== undefined ? { value: options.value } : {}),\n    ...(options.contentIds?.length ? { contentIds: options.contentIds } : {}),\n    ...(options.contents?.length ? { contents: options.contents } : {}),\n    ...(typeof options.numItems === 'number' ? { numItems: options.numItems } : {}),\n  }\n  safeSnaptr('track', 'ADD_CART', {\n    ...(options.contentIds?.length ? { item_ids: options.contentIds } : {}),\n    ...(options.currency ? { currency: options.currency } : {}),\n    ...(options.value !== undefined ? { value: options.value } : {}),\n    ...(typeof options.numItems === 'number' ? { number_items: options.numItems } : {}),\n    client_dedup_id: eid,\n  })\n  void sendSnapchatCapiEvent({\n    eventName: 'ADD_CART',\n    eventId: eid,\n    eventSourceUrl: currentUrl(),\n    userData: options.userData ?? {},\n    customData,\n  })\n}\n\nexport interface TrackStartCheckoutOptions {\n  currency?: string\n  value?: string\n  contentIds?: string[]\n  contents?: Array<{ id: string; quantity: string; item_price?: string }>\n  numItems?: number\n  userData?: SnapUserData\n  eventId?: string\n}\n\nexport function trackStartCheckout(cartId: string, options: TrackStartCheckoutOptions = {}): void {\n  const eid = options.eventId ?? makeEventId('START_CHECKOUT', cartId, minuteBucketNow())\n  const customData: SnapCustomData = {\n    ...(options.currency ? { currency: options.currency } : {}),\n    ...(options.value !== undefined ? { value: options.value } : {}),\n    ...(options.contentIds?.length ? { contentIds: options.contentIds } : {}),\n    ...(options.contents?.length ? { contents: options.contents } : {}),\n    ...(typeof options.numItems === 'number' ? { numItems: options.numItems } : {}),\n  }\n  safeSnaptr('track', 'START_CHECKOUT', {\n    ...(options.contentIds?.length ? { item_ids: options.contentIds } : {}),\n    ...(options.currency ? { currency: options.currency } : {}),\n    ...(options.value !== undefined ? { value: options.value } : {}),\n    ...(typeof options.numItems === 'number' ? { number_items: options.numItems } : {}),\n    client_dedup_id: eid,\n  })\n  void sendSnapchatCapiEvent({\n    eventName: 'START_CHECKOUT',\n    eventId: eid,\n    eventSourceUrl: currentUrl(),\n    userData: options.userData ?? {},\n    customData,\n  })\n}\n\nexport interface TrackPurchaseOptions {\n  currency?: string\n  value?: string\n  contentIds?: string[]\n  contents?: Array<{ id: string; quantity: string; item_price?: string }>\n  numItems?: number\n  userData?: SnapUserData\n  /**\n   * When present, pins `event_id` / `client_dedup_id` explicitly; otherwise\n   * a stable id is derived from `(PURCHASE, orderId, 0)` - minute-bucket 0\n   * so retries within a longer window still dedup against the server event.\n   */\n  eventId?: string\n}\n\n/**\n * PURCHASE gets the dual-dedup treatment:\n *   - Top-level `event_id` / Pixel `client_dedup_id` shared for 48h window.\n *   - `custom_data.order_id` / Pixel `transaction_id` shared for 30-day\n *     window. Reuses the Amboras order id as both.\n */\nexport function trackPurchase(orderId: string, options: TrackPurchaseOptions = {}): void {\n  // Pin minute-bucket to 0 for PURCHASE so a browser retry in a later\n  // minute still lands on the same event_id as the initial server fire.\n  const eid = options.eventId ?? makeEventId('PURCHASE', orderId, 0)\n  const derivedOrderId = deriveOrderIdForPurchase('PURCHASE', orderId)\n  const customData: SnapCustomData = {\n    ...(options.currency ? { currency: options.currency } : {}),\n    ...(options.value !== undefined ? { value: options.value } : {}),\n    ...(options.contentIds?.length ? { contentIds: options.contentIds } : {}),\n    ...(options.contents?.length ? { contents: options.contents } : {}),\n    ...(typeof options.numItems === 'number' ? { numItems: options.numItems } : {}),\n    ...(derivedOrderId ? { orderId: derivedOrderId } : {}),\n  }\n  safeSnaptr('track', 'PURCHASE', {\n    ...(options.contentIds?.length ? { item_ids: options.contentIds } : {}),\n    ...(options.currency ? { currency: options.currency } : {}),\n    ...(options.value !== undefined ? { value: options.value } : {}),\n    ...(typeof options.numItems === 'number' ? { number_items: options.numItems } : {}),\n    ...(derivedOrderId ? { transaction_id: derivedOrderId } : {}),\n    client_dedup_id: eid,\n  })\n  void sendSnapchatCapiEvent({\n    eventName: 'PURCHASE',\n    eventId: eid,\n    eventSourceUrl: currentUrl(),\n    userData: options.userData ?? {},\n    customData,\n  })\n}\n"],"mappings":"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","names":[]}

package/dist/slot-components/index.d.mts

@@ -0,0 +1,128 @@
+interface SnapPixelProviderProps {
+    /** Snap Pixel ID (`snap_pixel_id`). When absent, this component is a no-op. */
+    pixelId?: string;
+}
+/**
+ * Null-rendering side-effect component for the `rootProviders` plugin
+ * slot. Responsibilities:
+ *
+ *   1. Consent-gated install of the `snaptr` shim + injection of
+ *      `https://sc-static.net/scevent.min.js`. Snap does NOT ship an
+ *      npm-installable browser SDK (research memo Section 10) so we inline
+ *      the canonical IIFE via `installSnapPixelShim`.
+ *   2. Consent-gated `snaptr('init', pixelId)` - runs at most once per
+ *      pixel id even across SPA nav (guarded by `initedForPixelId`).
+ *   3. SPA PAGE_VIEW on every route change. `scevent.min.js` only fires
+ *      PAGE_VIEW automatically on full page loads; SPA navs need an
+ *      explicit `snaptr('track', 'PAGE_VIEW')`. Fires with an explicit
+ *      `client_dedup_id` derived from the pathname so a browser retry in
+ *      the same minute doesn't get counted twice.
+ *
+ * Everything is gated on `hasAnalyticsConsent()` and re-checked on the
+ * `amboras-consent-changed` event.
+ *
+ * Deliberately does NOT relay PAGE_VIEW to CAPI - the storefront has no
+ * server counterpart for a page view (no route handler dispatches it,
+ * unlike PURCHASE / ADD_CART which the checkout / cart flow triggers).
+ * Merchants who want server-side PAGE_VIEW attribution can call
+ * `trackPageView` from their app; the default here is browser-only for
+ * PAGE_VIEW parity with Snap's canonical install snippet.
+ */
+declare function SnapPixelProvider({ pixelId }: SnapPixelProviderProps): null;
+
+interface SnapViewContentProps {
+    productId?: string;
+    productName?: string;
+    sku?: string;
+    /** Major-unit numeric price (already converted from Medusa's minor units by the slot host). */
+    price?: number;
+    currency?: string;
+}
+/**
+ * Null-rendering component for the `pdpAnalytics` plugin slot.
+ * Fires Snap `VIEW_CONTENT` on both browser (Pixel) and server (CAPI)
+ * on PDP mount.
+ *
+ * Guarded by a productId ref so PDPs that swap variants without a full
+ * remount don't fire once per prop tick - Snap counts double fires as
+ * two events even when `client_dedup_id` matches (dedup is only across
+ * browser vs server, not within the same channel).
+ */
+declare function SnapViewContent({ productId, price, currency }: SnapViewContentProps): null;
+
+interface SnapAddCartProps {
+    cartId?: string;
+    itemCount?: number;
+    /** Kept for prop-shape compatibility with the plugin slot - not used directly. */
+    total?: number;
+    currency?: string;
+}
+/**
+ * Null-rendering component for the `cartUpdate` plugin slot.
+ * Fires Snap `ADD_CART` per newly-added variant, self-hydrating from
+ * Medusa's `/store/carts/:id` so `value`/`currency` are always
+ * authoritative. Per-variant sessionStorage baseline persists across
+ * cart-drawer mount cycles; a 1.5s window dedup absorbs TanStack Query
+ * refetch races.
+ *
+ * First-mount seed: on a fresh session with a hydrated cart (page
+ * refresh loads a cart with N items already in it), the baseline is
+ * seeded to the current cart state and NO events fire. Only subsequent
+ * quantity increases fire events.
+ *
+ * Values are serialised to STRINGS per Snap v3 wire spec (research memo
+ * caveat #3).
+ */
+declare function SnapAddCart({ cartId, itemCount: _itemCount }: SnapAddCartProps): null;
+
+interface SnapStartCheckoutProps {
+    cartId?: string;
+    itemCount?: number;
+    total?: number;
+    currency?: string;
+}
+/**
+ * Null-rendering component for the `checkoutStart` plugin slot.
+ * Fires Snap `START_CHECKOUT` exactly once per cartId. SessionStorage
+ * dedup so back-nav to the checkout page doesn't double-fire.
+ *
+ * Self-fetches the cart from Medusa so `value`/`currency` are correct
+ * even when the merchant slot context is thin. The ref is set only
+ * AFTER a successful dispatch so a StrictMode cleanup between effect-
+ * run and fetch-complete does NOT poison the ref.
+ */
+declare function SnapStartCheckout({ cartId, itemCount, total, currency }: SnapStartCheckoutProps): null;
+
+interface SnapPurchaseProps {
+    orderId?: string;
+    total?: number;
+    currency?: string;
+    itemCount?: number;
+}
+/**
+ * Null-rendering component for the `checkoutComplete` plugin slot.
+ * Fires Snap `PURCHASE` exactly once per orderId. Dual-dedup semantics
+ * per research memo Section 5:
+ *
+ *   - Top-level `event_id` / Pixel `client_dedup_id` shared for 48h.
+ *   - `custom_data.order_id` / Pixel `transaction_id` shared for 30d.
+ *
+ * Both derive from the orderId directly so browser retries in a later
+ * minute still line up with the server event.
+ *
+ * Primary path: self-fetch from `/store/orders/:id` and derive value +
+ * currency + contentIds from the authoritative Medusa response
+ * (currency-aware `toMajorUnits`, so JPY/KWD are correct).
+ *
+ * Fallback path (fetch failed): fire a MINIMAL browser PURCHASE using
+ * the incoming `total` + `currency` props, log a dev warning, and rely
+ * on Snap's dedup with the server-side `sendSnapchatCapiEvent` to
+ * reconcile.
+ *
+ * Two-layer dedup mirrors meta-ads: `useRef` guards StrictMode double-
+ * mount within the same instance; `sessionStorage` guards page refresh
+ * + remount. Both are set only AFTER successful dispatch.
+ */
+declare function SnapPurchase({ orderId, total, currency, itemCount: _itemCount }: SnapPurchaseProps): null;
+
+export { SnapAddCart, type SnapAddCartProps, SnapPixelProvider, type SnapPixelProviderProps, SnapPurchase, type SnapPurchaseProps, SnapStartCheckout, type SnapStartCheckoutProps, SnapViewContent, type SnapViewContentProps };