@amboras-dev/snapchat-ads 0.1.0

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/constants/index.ts","../src/lib/snaptr.ts","../src/lib/event-id.ts","../src/lib/cookies.ts","../src/get-config.ts","../src/lib/runtime-config.ts","../src/hooks/useSnapchatEvents.ts"],"sourcesContent":["export {\n  trackPageView,\n  trackViewContent,\n  trackAddCart,\n  trackStartCheckout,\n  trackPurchase,\n  sendSnapchatCapiEvent,\n} from './hooks/useSnapchatEvents'\n\nexport { getSnapchatConfig } from './get-config'\n\nexport { makeEventId, makeUniqueEventId } from './lib/event-id'\n\nexport { SNAP_EVENTS, COOKIE_NAMES, CAPI_RELAY_ENDPOINT } from './constants'\n\n// The Conversions API token never leaves the Medusa side, so no\n// secret-bearing config type is exported. Storefront code consumes\n// `SnapchatPublicConfig` only.\nexport type {\n  SnapchatPublicConfig,\n  SnapchatCapiEventPayload,\n  SnapchatEventName,\n} from './types'\n","/**\n * Every fixed string the package puts on the wire or in browser storage.\n * Wire names are a cross-repo contract: Medusa's strict Zod schema and the\n * orchestrator's storefront relay template expect exactly these values.\n */\n\n/**\n * Snap standard event names. The pixel (`snaptr('track', <name>)`) and\n * Conversions API v3 (`event_name`) use the SAME uppercase strings.\n * https://developers.snap.com/api/marketing-api/Conversions-API/Parameters\n */\nexport const SNAP_EVENTS = {\n  PAGE_VIEW: 'PAGE_VIEW',\n  VIEW_CONTENT: 'VIEW_CONTENT',\n  ADD_CART: 'ADD_CART',\n  START_CHECKOUT: 'START_CHECKOUT',\n  PURCHASE: 'PURCHASE',\n} as const\n\n/**\n * Merchant setting (from `/store/snapchat-ads/config`) that switches each\n * event off. Medusa enforces the same map server-side before enqueueing.\n */\nexport const EVENT_TOGGLES = {\n  PAGE_VIEW: 'track_page_view',\n  VIEW_CONTENT: 'track_view_content',\n  ADD_CART: 'track_add_cart',\n  START_CHECKOUT: 'track_start_checkout',\n  PURCHASE: 'track_purchase',\n} as const satisfies Record<keyof typeof SNAP_EVENTS, string>\n\n/** How long the browser reuses the merchant config before re-reading it. */\nexport const CONFIG_REFRESH_MS = 60_000\n\n/** Storefront relay route written by the orchestrator's template. */\nexport const CAPI_RELAY_ENDPOINT = '/api/snapchat/events'\n\n/** Snap's official pixel script. */\nexport const SNAP_SCRIPT_SRC = 'https://sc-static.net/scevent.min.js'\n\n/** URL param Snap appends to ad landing URLs (forwarded as `sc_click_id`). */\nexport const CLICK_ID_QUERY_PARAM = 'ScCid'\n\nexport const COOKIE_NAMES = {\n  /** Plugin-owned raw PII for the relay; Medusa hashes it. */\n  PII: 'amboras_snap_pii',\n  /** Plugin-owned copy of `ScCid`. */\n  CLICK_ID: 'amboras_snap_clid',\n  /** Snap's own first-party cookie (forwarded as `sc_cookie1`). */\n  SCID: '_scid',\n} as const\n\nexport const COOKIE_MAX_AGE_SECONDS = {\n  PII: 30 * 24 * 60 * 60,\n  // Matches Snap's default 28-day click attribution window.\n  CLICK_ID: 28 * 24 * 60 * 60,\n} as const\n\n/** sessionStorage / globalThis keys the slot components use for dedup. */\nexport const STORAGE_KEYS = {\n  CART_STATE: 'amboras_snap_cart_state_v1',\n  CART_RECENT_FIRES: '__amboras_snap_recent_fires__',\n  CHECKOUT_SEEN: 'amboras_snap_checkout_seen',\n  PURCHASE_PREFIX: 'amboras_snap_purchase_',\n} as const\n\n/** Storefront window events the provider listens to. */\nexport const WINDOW_EVENTS = {\n  CONSENT_CHANGED: 'amboras-consent-changed',\n  AUTH_CHANGED: 'amboras-auth-changed',\n} as const\n","/**\n * Typed wrapper around Snap's global `snaptr`. The shim is installed by\n * `SnapPixelProvider` behind consent - every other slot component calls\n * `safeSnaptr()`, which is a no-op when snaptr is absent (consent denied,\n * plugin uninstalled, or SSR).\n */\n\nimport { SNAP_SCRIPT_SRC } from '../constants'\n\ndeclare global {\n  interface Window {\n    snaptr?: SnaptrFunction\n  }\n}\n\nexport type SnaptrFunction = (...args: unknown[]) => void\n\n/** Best-effort synchronous call. Returns whether snaptr was present. */\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 * Install the snaptr queue shim + inject `scevent.min.js`. Idempotent.\n * Mirrors the shape of Snap's official install snippet\n * (https://developers.snap.com/api/marketing-api/Ads-API/snap-pixel) so the\n * loaded script drains the queue via `handleRequest`.\n */\nexport function installSnaptrShim(): void {\n  if (typeof window === 'undefined' || typeof document === 'undefined') return\n  if (window.snaptr) return\n\n  const shim = function (...args: unknown[]): void {\n    const self = shim as unknown as { handleRequest?: (...a: unknown[]) => void; queue: unknown[] }\n    if (self.handleRequest) self.handleRequest(...args)\n    else self.queue.push(args)\n  } as SnaptrFunction\n  ;(shim as unknown as { queue: unknown[] }).queue = []\n  window.snaptr = shim\n\n  const script = document.createElement('script')\n  script.async = true\n  script.src = SNAP_SCRIPT_SRC\n  document.head.appendChild(script)\n}\n","import type { SnapchatEventName } from '../types'\n\n/**\n * Event-ID builders for browser <-> CAPI dedup. Snap matches the pixel's\n * `client_dedup_id` against the CAPI `event_id` within 48h, so the browser\n * call and the CAPI relay for one user action must carry the same ID. Both\n * are fired from the same function call, so the ID only has to be stable\n * within that call - not across calls.\n *\n * Two flavours:\n *   - `makeEventId`: deterministic. Used where a repeat fire of the SAME\n *     action must collapse into one (START_CHECKOUT per cart, PURCHASE per\n *     order), e.g. a refresh on the thank-you page.\n *   - `makeUniqueEventId`: deterministic prefix + random suffix. Used for\n *     actions a shopper legitimately repeats (viewing a product again,\n *     adding the same variant twice, revisiting a page). A pure\n *     deterministic ID would make Snap drop every repeat within 48h.\n */\nexport function makeEventId(eventName: SnapchatEventName, primaryKey: string): string {\n  const safeKey = primaryKey.replace(/[^a-zA-Z0-9_-]/g, '_')\n  return `${eventName.toLowerCase()}_${safeKey}`\n}\n\nfunction randomSuffix(): string {\n  const c = (globalThis as { crypto?: { randomUUID?: () => string } }).crypto\n  if (c?.randomUUID) return c.randomUUID().replace(/-/g, '').slice(0, 16)\n  return Math.random().toString(36).slice(2, 12) + Date.now().toString(36)\n}\n\nexport function makeUniqueEventId(eventName: SnapchatEventName, primaryKey: string): string {\n  return `${makeEventId(eventName, primaryKey)}_${randomSuffix()}`\n}\n","/**\n * Snap-specific cookies, on top of `@amboras-dev/pixel-core`'s cookie helpers:\n *   - `_scid`: Snap's first-party cookie set by the pixel. Forwarded raw to\n *     CAPI as `sc_cookie1`.\n *   - `amboras_snap_clid`: plugin-owned copy of the `ScCid` URL param Snap\n *     appends to ad landing URLs. Forwarded raw to CAPI as `sc_click_id`.\n *     Captured on landing because a later SPA navigation drops the param.\n *   - `amboras_snap_pii`: plugin-owned raw (unhashed) customer PII for the\n *     storefront's `/api/snapchat/events` relay; Medusa normalizes + hashes\n *     it before shipping to Snap. Separate from the meta/pinterest PII\n *     cookies so the plugins stay decoupled.\n */\n\nimport { deleteCookie, readCookie, writeCookie, writePiiCookie, type PiiPayload } from '@amboras-dev/pixel-core'\nimport { CLICK_ID_QUERY_PARAM, COOKIE_MAX_AGE_SECONDS, COOKIE_NAMES } from '../constants'\n\nexport function readScid(): string | undefined {\n  return readCookie(COOKIE_NAMES.SCID)\n}\n\nexport function readClickId(): string | undefined {\n  return readCookie(COOKIE_NAMES.CLICK_ID)\n}\n\n/**\n * Store `?ScCid=` from the landing URL. A newer click id replaces an older\n * one so the most recent ad click wins attribution.\n */\nexport function captureClickIdFromQuery(): void {\n  if (typeof window === 'undefined' || typeof document === 'undefined') return\n  let clickId: string | null = null\n  try {\n    clickId = new URL(window.location.href).searchParams.get(CLICK_ID_QUERY_PARAM)\n  } catch {\n    return\n  }\n  if (!clickId || clickId === readClickId()) return\n  writeCookie(COOKIE_NAMES.CLICK_ID, clickId, COOKIE_MAX_AGE_SECONDS.CLICK_ID)\n}\n\nexport function writeSnapchatPiiCookie(payload: PiiPayload): void {\n  writePiiCookie(COOKIE_NAMES.PII, payload, COOKIE_MAX_AGE_SECONDS.PII)\n}\n\nexport function clearSnapchatPiiCookie(): void {\n  deleteCookie(COOKIE_NAMES.PII)\n}\n","import { resolveBackendUrl, resolvePublishableKey, resolveStoreEnvironmentId } from '@amboras-dev/pixel-core'\nimport type { SnapchatPublicConfig } from './types'\n\ninterface GetSnapchatConfigOptions {\n  baseUrl?: string\n  publishableApiKey?: string\n  storeId?: string\n  /** Injected `fetch` for testing. Defaults to global `fetch`. */\n  fetchImpl?: typeof fetch\n}\n\n/**\n * Fetches the non-secret Snapchat config from Medusa. Returns `null` when\n * the backend URL is unknown or the endpoint is missing, unauthorized, or\n * errors. The Conversions API token is never returned by the server route,\n * so it never surfaces here.\n */\nexport async function getSnapchatConfig(\n  options: GetSnapchatConfigOptions = {},\n): Promise<SnapchatPublicConfig | null> {\n  const baseUrl = options.baseUrl ?? resolveBackendUrl()\n  if (!baseUrl) return null\n  const publishableKey = options.publishableApiKey ?? resolvePublishableKey()\n  const storeId = options.storeId ?? resolveStoreEnvironmentId()\n  const doFetch = options.fetchImpl ?? fetch\n\n  try {\n    const res = await doFetch(`${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 SnapchatPublicConfig\n  } catch {\n    return null\n  }\n}\n","/**\n * The merchant's live Snapchat settings, read once per page (refreshed\n * every CONFIG_REFRESH_MS) and shared by the provider and every event.\n *\n * Fail-closed: no config (network error, plugin disconnected, Medusa answers\n * `{ enabled: false }`) means no pixel and no events. The browser then\n * honours \"Plugin enabled\" and each \"Track ...\" toggle the same way Medusa's\n * events route does, and a Pixel ID change applies without a redeploy.\n */\n\nimport { getSnapchatConfig } from '../get-config'\nimport { CONFIG_REFRESH_MS, EVENT_TOGGLES } from '../constants'\nimport type { SnapchatEventName, SnapchatPublicConfig } from '../types'\n\nlet cached: { at: number; read: Promise<SnapchatPublicConfig | null> } | null = null\n\nexport function loadSnapchatConfig(): Promise<SnapchatPublicConfig | null> {\n  const now = Date.now()\n  if (cached && now - cached.at < CONFIG_REFRESH_MS) return cached.read\n  const read = getSnapchatConfig().then((config) => {\n    // A failed read is not reused, so the next event tries again.\n    if (!config) cached = null\n    return config\n  })\n  cached = { at: now, read }\n  return read\n}\n\n/** The pixel ID to load, or null when the plugin is off / not configured. */\nexport function activePixelId(config: SnapchatPublicConfig | null): string | null {\n  if (!config || config.enabled !== true) return null\n  return config.pixel_id || null\n}\n\nexport function isEventEnabled(config: SnapchatPublicConfig | null, eventName: SnapchatEventName): boolean {\n  if (!activePixelId(config)) return false\n  // A toggle the config omits counts as on, matching Medusa's default.\n  return config![EVENT_TOGGLES[eventName]] !== false\n}\n\n/** Test-only: forget the cached config. */\nexport function resetSnapchatConfigCache(): void {\n  cached = null\n}\n","import { safeSnaptr } from '../lib/snaptr'\nimport { makeEventId, makeUniqueEventId } from '../lib/event-id'\nimport { readClickId, readScid } from '../lib/cookies'\nimport { CAPI_RELAY_ENDPOINT, SNAP_EVENTS } from '../constants'\nimport { isEventEnabled, loadSnapchatConfig } from '../lib/runtime-config'\nimport type { SnapchatCapiEventPayload, SnapchatEventName } from '../types'\n\nfunction currentUrl(): string {\n  return typeof window !== 'undefined' ? window.location.href : ''\n}\n\n/**\n * Match keys shared by every CAPI event: the `ScCid` click id captured on\n * ad landing and Snap's `_scid` cookie. Both are sent RAW - Snap matches\n * them against its own tables, they must never be hashed.\n */\nfunction baseUserData(): SnapchatCapiEventPayload['userData'] {\n  const out: SnapchatCapiEventPayload['userData'] = {}\n  const clickId = readClickId()\n  const cookie1 = readScid()\n  if (clickId) out.clickId = clickId\n  if (cookie1) out.cookie1 = cookie1\n  return out\n}\n\n/** Drop undefined keys so the pixel never receives `price: undefined`. */\nfunction compact(input: Record<string, unknown>): Record<string, unknown> {\n  const out: Record<string, unknown> = {}\n  for (const [k, v] of Object.entries(input)) {\n    if (v !== undefined) out[k] = v\n  }\n  return out\n}\n\n/**\n * POST the event to the storefront's `/api/snapchat/events` proxy. The\n * proxy enriches with the PII cookie + IP + User-Agent and forwards to\n * Medusa's `/store/snapchat-ads/events` route, which queues it on the shared\n * outbox. Intentionally UNGATED on analytics consent - CAPI operates on a\n * different legal basis than the browser pixel. Merchant owns that call.\n */\nexport async function sendSnapchatCapiEvent(payload: SnapchatCapiEventPayload): Promise<void> {\n  try {\n    await fetch(CAPI_RELAY_ENDPOINT, {\n      method: 'POST',\n      headers: { 'Content-Type': 'application/json' },\n      body: JSON.stringify(payload),\n      keepalive: true,\n    })\n  } catch {\n    // non-fatal - CAPI is best-effort from the browser's perspective\n  }\n}\n\n/**\n * Fire one event on both channels with a shared ID. The pixel gets\n * `client_dedup_id` (Snap's browser-side dedup key); the relay gets the\n * same value as `eventId`, which Medusa sends as CAPI `event_id`.\n *\n * Gated on the merchant's live settings first: with the plugin off or this\n * event's \"Track ...\" toggle off, nothing leaves the browser on either\n * channel. URL and match keys are read before the (cached) config lookup,\n * so an SPA navigation during it cannot attribute the event to the next page.\n */\nfunction fire(\n  eventName: SnapchatEventName,\n  eventId: string,\n  pixelParams: Record<string, unknown>,\n  customData?: SnapchatCapiEventPayload['customData'],\n): void {\n  const payload: SnapchatCapiEventPayload = {\n    eventName,\n    eventId,\n    eventSourceUrl: currentUrl(),\n    userData: baseUserData(),\n    ...(customData ? { customData } : {}),\n  }\n  const params = compact({ ...pixelParams, client_dedup_id: eventId })\n  void loadSnapchatConfig().then((config) => {\n    if (!isEventEnabled(config, eventName)) return\n    safeSnaptr('track', eventName, params)\n    void sendSnapchatCapiEvent(payload)\n  })\n}\n\nexport function trackPageView(): void {\n  fire(SNAP_EVENTS.PAGE_VIEW, makeUniqueEventId(SNAP_EVENTS.PAGE_VIEW, 'page'), {})\n}\n\nexport function trackViewContent(\n  productId: string,\n  value?: number,\n  currency?: string,\n): void {\n  fire(\n    SNAP_EVENTS.VIEW_CONTENT,\n    makeUniqueEventId(SNAP_EVENTS.VIEW_CONTENT, productId),\n    { price: value, currency, item_ids: [productId] },\n    { value, currency, contentIds: [productId] },\n  )\n}\n\n/**\n * Fire `ADD_CART` for a single variant's quantity delta. `contentIds` is\n * typically `[productId, variantId]`.\n */\nexport function trackAddCart(\n  variantId: string,\n  quantity: number,\n  value?: number,\n  currency?: string,\n  contentIds?: string[],\n): void {\n  const ids = contentIds?.length ? contentIds : [variantId]\n  fire(\n    SNAP_EVENTS.ADD_CART,\n    makeUniqueEventId(SNAP_EVENTS.ADD_CART, variantId),\n    { price: value, currency, item_ids: ids, number_items: quantity },\n    { value, currency, contentIds: ids, numItems: quantity },\n  )\n}\n\n/** Deterministic per cart: a checkout refresh collapses into one event. */\nexport function trackStartCheckout(\n  cartId: string,\n  itemCount: number,\n  value?: number,\n  currency?: string,\n  contentIds?: string[],\n): void {\n  fire(\n    SNAP_EVENTS.START_CHECKOUT,\n    makeEventId(SNAP_EVENTS.START_CHECKOUT, cartId),\n    { price: value, currency, item_ids: contentIds?.length ? contentIds : undefined, number_items: itemCount },\n    { value, currency, contentIds, numItems: itemCount },\n  )\n}\n\n/**\n * Order-complete tracker. Both channels use the SAME event name\n * (`PURCHASE`) - unlike Pinterest there is no browser/server name split.\n * Dedup is doubly anchored: `client_dedup_id` == `event_id` (48h) and pixel\n * `transaction_id` == CAPI `order_id` (30d).\n */\nexport function trackPurchase(\n  orderId: string,\n  value: number,\n  currency: string,\n  itemCount?: number,\n  contentIds?: string[],\n): void {\n  fire(\n    SNAP_EVENTS.PURCHASE,\n    makeEventId(SNAP_EVENTS.PURCHASE, orderId),\n    {\n      price: value,\n      currency,\n      transaction_id: orderId,\n      item_ids: contentIds?.length ? contentIds : undefined,\n      number_items: itemCount,\n    },\n    { value, currency, orderId, contentIds, numItems: itemCount },\n  )\n}\n"],"mappings":"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","names":["import_pixel_core"]}

package/dist/index.mjs

@@ -0,0 +1,194 @@
+import {
+  getSnapchatConfig
+} from "./chunk-IP2VTHD6.mjs";
+
+// src/constants/index.ts
+var SNAP_EVENTS = {
+  PAGE_VIEW: "PAGE_VIEW",
+  VIEW_CONTENT: "VIEW_CONTENT",
+  ADD_CART: "ADD_CART",
+  START_CHECKOUT: "START_CHECKOUT",
+  PURCHASE: "PURCHASE"
+};
+var EVENT_TOGGLES = {
+  PAGE_VIEW: "track_page_view",
+  VIEW_CONTENT: "track_view_content",
+  ADD_CART: "track_add_cart",
+  START_CHECKOUT: "track_start_checkout",
+  PURCHASE: "track_purchase"
+};
+var CONFIG_REFRESH_MS = 6e4;
+var CAPI_RELAY_ENDPOINT = "/api/snapchat/events";
+var COOKIE_NAMES = {
+  /** Plugin-owned raw PII for the relay; Medusa hashes it. */
+  PII: "amboras_snap_pii",
+  /** Plugin-owned copy of `ScCid`. */
+  CLICK_ID: "amboras_snap_clid",
+  /** Snap's own first-party cookie (forwarded as `sc_cookie1`). */
+  SCID: "_scid"
+};
+var COOKIE_MAX_AGE_SECONDS = {
+  PII: 30 * 24 * 60 * 60,
+  // Matches Snap's default 28-day click attribution window.
+  CLICK_ID: 28 * 24 * 60 * 60
+};
+
+// src/lib/snaptr.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/event-id.ts
+function makeEventId(eventName, primaryKey) {
+  const safeKey = primaryKey.replace(/[^a-zA-Z0-9_-]/g, "_");
+  return `${eventName.toLowerCase()}_${safeKey}`;
+}
+function randomSuffix() {
+  const c = globalThis.crypto;
+  if (c?.randomUUID) return c.randomUUID().replace(/-/g, "").slice(0, 16);
+  return Math.random().toString(36).slice(2, 12) + Date.now().toString(36);
+}
+function makeUniqueEventId(eventName, primaryKey) {
+  return `${makeEventId(eventName, primaryKey)}_${randomSuffix()}`;
+}
+
+// src/lib/cookies.ts
+import { deleteCookie, readCookie, writeCookie, writePiiCookie } from "@amboras-dev/pixel-core";
+function readScid() {
+  return readCookie(COOKIE_NAMES.SCID);
+}
+function readClickId() {
+  return readCookie(COOKIE_NAMES.CLICK_ID);
+}
+
+// src/lib/runtime-config.ts
+var cached = null;
+function loadSnapchatConfig() {
+  const now = Date.now();
+  if (cached && now - cached.at < CONFIG_REFRESH_MS) return cached.read;
+  const read = getSnapchatConfig().then((config) => {
+    if (!config) cached = null;
+    return config;
+  });
+  cached = { at: now, read };
+  return read;
+}
+function activePixelId(config) {
+  if (!config || config.enabled !== true) return null;
+  return config.pixel_id || null;
+}
+function isEventEnabled(config, eventName) {
+  if (!activePixelId(config)) return false;
+  return config[EVENT_TOGGLES[eventName]] !== false;
+}
+
+// src/hooks/useSnapchatEvents.ts
+function currentUrl() {
+  return typeof window !== "undefined" ? window.location.href : "";
+}
+function baseUserData() {
+  const out = {};
+  const clickId = readClickId();
+  const cookie1 = readScid();
+  if (clickId) out.clickId = clickId;
+  if (cookie1) out.cookie1 = cookie1;
+  return out;
+}
+function compact(input) {
+  const out = {};
+  for (const [k, v] of Object.entries(input)) {
+    if (v !== void 0) out[k] = v;
+  }
+  return out;
+}
+async function sendSnapchatCapiEvent(payload) {
+  try {
+    await fetch(CAPI_RELAY_ENDPOINT, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(payload),
+      keepalive: true
+    });
+  } catch {
+  }
+}
+function fire(eventName, eventId, pixelParams, customData) {
+  const payload = {
+    eventName,
+    eventId,
+    eventSourceUrl: currentUrl(),
+    userData: baseUserData(),
+    ...customData ? { customData } : {}
+  };
+  const params = compact({ ...pixelParams, client_dedup_id: eventId });
+  void loadSnapchatConfig().then((config) => {
+    if (!isEventEnabled(config, eventName)) return;
+    safeSnaptr("track", eventName, params);
+    void sendSnapchatCapiEvent(payload);
+  });
+}
+function trackPageView() {
+  fire(SNAP_EVENTS.PAGE_VIEW, makeUniqueEventId(SNAP_EVENTS.PAGE_VIEW, "page"), {});
+}
+function trackViewContent(productId, value, currency) {
+  fire(
+    SNAP_EVENTS.VIEW_CONTENT,
+    makeUniqueEventId(SNAP_EVENTS.VIEW_CONTENT, productId),
+    { price: value, currency, item_ids: [productId] },
+    { value, currency, contentIds: [productId] }
+  );
+}
+function trackAddCart(variantId, quantity, value, currency, contentIds) {
+  const ids = contentIds?.length ? contentIds : [variantId];
+  fire(
+    SNAP_EVENTS.ADD_CART,
+    makeUniqueEventId(SNAP_EVENTS.ADD_CART, variantId),
+    { price: value, currency, item_ids: ids, number_items: quantity },
+    { value, currency, contentIds: ids, numItems: quantity }
+  );
+}
+function trackStartCheckout(cartId, itemCount, value, currency, contentIds) {
+  fire(
+    SNAP_EVENTS.START_CHECKOUT,
+    makeEventId(SNAP_EVENTS.START_CHECKOUT, cartId),
+    { price: value, currency, item_ids: contentIds?.length ? contentIds : void 0, number_items: itemCount },
+    { value, currency, contentIds, numItems: itemCount }
+  );
+}
+function trackPurchase(orderId, value, currency, itemCount, contentIds) {
+  fire(
+    SNAP_EVENTS.PURCHASE,
+    makeEventId(SNAP_EVENTS.PURCHASE, orderId),
+    {
+      price: value,
+      currency,
+      transaction_id: orderId,
+      item_ids: contentIds?.length ? contentIds : void 0,
+      number_items: itemCount
+    },
+    { value, currency, orderId, contentIds, numItems: itemCount }
+  );
+}
+export {
+  CAPI_RELAY_ENDPOINT,
+  COOKIE_NAMES,
+  SNAP_EVENTS,
+  getSnapchatConfig,
+  makeEventId,
+  makeUniqueEventId,
+  sendSnapchatCapiEvent,
+  trackAddCart,
+  trackPageView,
+  trackPurchase,
+  trackStartCheckout,
+  trackViewContent
+};
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/constants/index.ts","../src/lib/snaptr.ts","../src/lib/event-id.ts","../src/lib/cookies.ts","../src/lib/runtime-config.ts","../src/hooks/useSnapchatEvents.ts"],"sourcesContent":["/**\n * Every fixed string the package puts on the wire or in browser storage.\n * Wire names are a cross-repo contract: Medusa's strict Zod schema and the\n * orchestrator's storefront relay template expect exactly these values.\n */\n\n/**\n * Snap standard event names. The pixel (`snaptr('track', <name>)`) and\n * Conversions API v3 (`event_name`) use the SAME uppercase strings.\n * https://developers.snap.com/api/marketing-api/Conversions-API/Parameters\n */\nexport const SNAP_EVENTS = {\n  PAGE_VIEW: 'PAGE_VIEW',\n  VIEW_CONTENT: 'VIEW_CONTENT',\n  ADD_CART: 'ADD_CART',\n  START_CHECKOUT: 'START_CHECKOUT',\n  PURCHASE: 'PURCHASE',\n} as const\n\n/**\n * Merchant setting (from `/store/snapchat-ads/config`) that switches each\n * event off. Medusa enforces the same map server-side before enqueueing.\n */\nexport const EVENT_TOGGLES = {\n  PAGE_VIEW: 'track_page_view',\n  VIEW_CONTENT: 'track_view_content',\n  ADD_CART: 'track_add_cart',\n  START_CHECKOUT: 'track_start_checkout',\n  PURCHASE: 'track_purchase',\n} as const satisfies Record<keyof typeof SNAP_EVENTS, string>\n\n/** How long the browser reuses the merchant config before re-reading it. */\nexport const CONFIG_REFRESH_MS = 60_000\n\n/** Storefront relay route written by the orchestrator's template. */\nexport const CAPI_RELAY_ENDPOINT = '/api/snapchat/events'\n\n/** Snap's official pixel script. */\nexport const SNAP_SCRIPT_SRC = 'https://sc-static.net/scevent.min.js'\n\n/** URL param Snap appends to ad landing URLs (forwarded as `sc_click_id`). */\nexport const CLICK_ID_QUERY_PARAM = 'ScCid'\n\nexport const COOKIE_NAMES = {\n  /** Plugin-owned raw PII for the relay; Medusa hashes it. */\n  PII: 'amboras_snap_pii',\n  /** Plugin-owned copy of `ScCid`. */\n  CLICK_ID: 'amboras_snap_clid',\n  /** Snap's own first-party cookie (forwarded as `sc_cookie1`). */\n  SCID: '_scid',\n} as const\n\nexport const COOKIE_MAX_AGE_SECONDS = {\n  PII: 30 * 24 * 60 * 60,\n  // Matches Snap's default 28-day click attribution window.\n  CLICK_ID: 28 * 24 * 60 * 60,\n} as const\n\n/** sessionStorage / globalThis keys the slot components use for dedup. */\nexport const STORAGE_KEYS = {\n  CART_STATE: 'amboras_snap_cart_state_v1',\n  CART_RECENT_FIRES: '__amboras_snap_recent_fires__',\n  CHECKOUT_SEEN: 'amboras_snap_checkout_seen',\n  PURCHASE_PREFIX: 'amboras_snap_purchase_',\n} as const\n\n/** Storefront window events the provider listens to. */\nexport const WINDOW_EVENTS = {\n  CONSENT_CHANGED: 'amboras-consent-changed',\n  AUTH_CHANGED: 'amboras-auth-changed',\n} as const\n","/**\n * Typed wrapper around Snap's global `snaptr`. The shim is installed by\n * `SnapPixelProvider` behind consent - every other slot component calls\n * `safeSnaptr()`, which is a no-op when snaptr is absent (consent denied,\n * plugin uninstalled, or SSR).\n */\n\nimport { SNAP_SCRIPT_SRC } from '../constants'\n\ndeclare global {\n  interface Window {\n    snaptr?: SnaptrFunction\n  }\n}\n\nexport type SnaptrFunction = (...args: unknown[]) => void\n\n/** Best-effort synchronous call. Returns whether snaptr was present. */\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 * Install the snaptr queue shim + inject `scevent.min.js`. Idempotent.\n * Mirrors the shape of Snap's official install snippet\n * (https://developers.snap.com/api/marketing-api/Ads-API/snap-pixel) so the\n * loaded script drains the queue via `handleRequest`.\n */\nexport function installSnaptrShim(): void {\n  if (typeof window === 'undefined' || typeof document === 'undefined') return\n  if (window.snaptr) return\n\n  const shim = function (...args: unknown[]): void {\n    const self = shim as unknown as { handleRequest?: (...a: unknown[]) => void; queue: unknown[] }\n    if (self.handleRequest) self.handleRequest(...args)\n    else self.queue.push(args)\n  } as SnaptrFunction\n  ;(shim as unknown as { queue: unknown[] }).queue = []\n  window.snaptr = shim\n\n  const script = document.createElement('script')\n  script.async = true\n  script.src = SNAP_SCRIPT_SRC\n  document.head.appendChild(script)\n}\n","import type { SnapchatEventName } from '../types'\n\n/**\n * Event-ID builders for browser <-> CAPI dedup. Snap matches the pixel's\n * `client_dedup_id` against the CAPI `event_id` within 48h, so the browser\n * call and the CAPI relay for one user action must carry the same ID. Both\n * are fired from the same function call, so the ID only has to be stable\n * within that call - not across calls.\n *\n * Two flavours:\n *   - `makeEventId`: deterministic. Used where a repeat fire of the SAME\n *     action must collapse into one (START_CHECKOUT per cart, PURCHASE per\n *     order), e.g. a refresh on the thank-you page.\n *   - `makeUniqueEventId`: deterministic prefix + random suffix. Used for\n *     actions a shopper legitimately repeats (viewing a product again,\n *     adding the same variant twice, revisiting a page). A pure\n *     deterministic ID would make Snap drop every repeat within 48h.\n */\nexport function makeEventId(eventName: SnapchatEventName, primaryKey: string): string {\n  const safeKey = primaryKey.replace(/[^a-zA-Z0-9_-]/g, '_')\n  return `${eventName.toLowerCase()}_${safeKey}`\n}\n\nfunction randomSuffix(): string {\n  const c = (globalThis as { crypto?: { randomUUID?: () => string } }).crypto\n  if (c?.randomUUID) return c.randomUUID().replace(/-/g, '').slice(0, 16)\n  return Math.random().toString(36).slice(2, 12) + Date.now().toString(36)\n}\n\nexport function makeUniqueEventId(eventName: SnapchatEventName, primaryKey: string): string {\n  return `${makeEventId(eventName, primaryKey)}_${randomSuffix()}`\n}\n","/**\n * Snap-specific cookies, on top of `@amboras-dev/pixel-core`'s cookie helpers:\n *   - `_scid`: Snap's first-party cookie set by the pixel. Forwarded raw to\n *     CAPI as `sc_cookie1`.\n *   - `amboras_snap_clid`: plugin-owned copy of the `ScCid` URL param Snap\n *     appends to ad landing URLs. Forwarded raw to CAPI as `sc_click_id`.\n *     Captured on landing because a later SPA navigation drops the param.\n *   - `amboras_snap_pii`: plugin-owned raw (unhashed) customer PII for the\n *     storefront's `/api/snapchat/events` relay; Medusa normalizes + hashes\n *     it before shipping to Snap. Separate from the meta/pinterest PII\n *     cookies so the plugins stay decoupled.\n */\n\nimport { deleteCookie, readCookie, writeCookie, writePiiCookie, type PiiPayload } from '@amboras-dev/pixel-core'\nimport { CLICK_ID_QUERY_PARAM, COOKIE_MAX_AGE_SECONDS, COOKIE_NAMES } from '../constants'\n\nexport function readScid(): string | undefined {\n  return readCookie(COOKIE_NAMES.SCID)\n}\n\nexport function readClickId(): string | undefined {\n  return readCookie(COOKIE_NAMES.CLICK_ID)\n}\n\n/**\n * Store `?ScCid=` from the landing URL. A newer click id replaces an older\n * one so the most recent ad click wins attribution.\n */\nexport function captureClickIdFromQuery(): void {\n  if (typeof window === 'undefined' || typeof document === 'undefined') return\n  let clickId: string | null = null\n  try {\n    clickId = new URL(window.location.href).searchParams.get(CLICK_ID_QUERY_PARAM)\n  } catch {\n    return\n  }\n  if (!clickId || clickId === readClickId()) return\n  writeCookie(COOKIE_NAMES.CLICK_ID, clickId, COOKIE_MAX_AGE_SECONDS.CLICK_ID)\n}\n\nexport function writeSnapchatPiiCookie(payload: PiiPayload): void {\n  writePiiCookie(COOKIE_NAMES.PII, payload, COOKIE_MAX_AGE_SECONDS.PII)\n}\n\nexport function clearSnapchatPiiCookie(): void {\n  deleteCookie(COOKIE_NAMES.PII)\n}\n","/**\n * The merchant's live Snapchat settings, read once per page (refreshed\n * every CONFIG_REFRESH_MS) and shared by the provider and every event.\n *\n * Fail-closed: no config (network error, plugin disconnected, Medusa answers\n * `{ enabled: false }`) means no pixel and no events. The browser then\n * honours \"Plugin enabled\" and each \"Track ...\" toggle the same way Medusa's\n * events route does, and a Pixel ID change applies without a redeploy.\n */\n\nimport { getSnapchatConfig } from '../get-config'\nimport { CONFIG_REFRESH_MS, EVENT_TOGGLES } from '../constants'\nimport type { SnapchatEventName, SnapchatPublicConfig } from '../types'\n\nlet cached: { at: number; read: Promise<SnapchatPublicConfig | null> } | null = null\n\nexport function loadSnapchatConfig(): Promise<SnapchatPublicConfig | null> {\n  const now = Date.now()\n  if (cached && now - cached.at < CONFIG_REFRESH_MS) return cached.read\n  const read = getSnapchatConfig().then((config) => {\n    // A failed read is not reused, so the next event tries again.\n    if (!config) cached = null\n    return config\n  })\n  cached = { at: now, read }\n  return read\n}\n\n/** The pixel ID to load, or null when the plugin is off / not configured. */\nexport function activePixelId(config: SnapchatPublicConfig | null): string | null {\n  if (!config || config.enabled !== true) return null\n  return config.pixel_id || null\n}\n\nexport function isEventEnabled(config: SnapchatPublicConfig | null, eventName: SnapchatEventName): boolean {\n  if (!activePixelId(config)) return false\n  // A toggle the config omits counts as on, matching Medusa's default.\n  return config![EVENT_TOGGLES[eventName]] !== false\n}\n\n/** Test-only: forget the cached config. */\nexport function resetSnapchatConfigCache(): void {\n  cached = null\n}\n","import { safeSnaptr } from '../lib/snaptr'\nimport { makeEventId, makeUniqueEventId } from '../lib/event-id'\nimport { readClickId, readScid } from '../lib/cookies'\nimport { CAPI_RELAY_ENDPOINT, SNAP_EVENTS } from '../constants'\nimport { isEventEnabled, loadSnapchatConfig } from '../lib/runtime-config'\nimport type { SnapchatCapiEventPayload, SnapchatEventName } from '../types'\n\nfunction currentUrl(): string {\n  return typeof window !== 'undefined' ? window.location.href : ''\n}\n\n/**\n * Match keys shared by every CAPI event: the `ScCid` click id captured on\n * ad landing and Snap's `_scid` cookie. Both are sent RAW - Snap matches\n * them against its own tables, they must never be hashed.\n */\nfunction baseUserData(): SnapchatCapiEventPayload['userData'] {\n  const out: SnapchatCapiEventPayload['userData'] = {}\n  const clickId = readClickId()\n  const cookie1 = readScid()\n  if (clickId) out.clickId = clickId\n  if (cookie1) out.cookie1 = cookie1\n  return out\n}\n\n/** Drop undefined keys so the pixel never receives `price: undefined`. */\nfunction compact(input: Record<string, unknown>): Record<string, unknown> {\n  const out: Record<string, unknown> = {}\n  for (const [k, v] of Object.entries(input)) {\n    if (v !== undefined) out[k] = v\n  }\n  return out\n}\n\n/**\n * POST the event to the storefront's `/api/snapchat/events` proxy. The\n * proxy enriches with the PII cookie + IP + User-Agent and forwards to\n * Medusa's `/store/snapchat-ads/events` route, which queues it on the shared\n * outbox. Intentionally UNGATED on analytics consent - CAPI operates on a\n * different legal basis than the browser pixel. Merchant owns that call.\n */\nexport async function sendSnapchatCapiEvent(payload: SnapchatCapiEventPayload): Promise<void> {\n  try {\n    await fetch(CAPI_RELAY_ENDPOINT, {\n      method: 'POST',\n      headers: { 'Content-Type': 'application/json' },\n      body: JSON.stringify(payload),\n      keepalive: true,\n    })\n  } catch {\n    // non-fatal - CAPI is best-effort from the browser's perspective\n  }\n}\n\n/**\n * Fire one event on both channels with a shared ID. The pixel gets\n * `client_dedup_id` (Snap's browser-side dedup key); the relay gets the\n * same value as `eventId`, which Medusa sends as CAPI `event_id`.\n *\n * Gated on the merchant's live settings first: with the plugin off or this\n * event's \"Track ...\" toggle off, nothing leaves the browser on either\n * channel. URL and match keys are read before the (cached) config lookup,\n * so an SPA navigation during it cannot attribute the event to the next page.\n */\nfunction fire(\n  eventName: SnapchatEventName,\n  eventId: string,\n  pixelParams: Record<string, unknown>,\n  customData?: SnapchatCapiEventPayload['customData'],\n): void {\n  const payload: SnapchatCapiEventPayload = {\n    eventName,\n    eventId,\n    eventSourceUrl: currentUrl(),\n    userData: baseUserData(),\n    ...(customData ? { customData } : {}),\n  }\n  const params = compact({ ...pixelParams, client_dedup_id: eventId })\n  void loadSnapchatConfig().then((config) => {\n    if (!isEventEnabled(config, eventName)) return\n    safeSnaptr('track', eventName, params)\n    void sendSnapchatCapiEvent(payload)\n  })\n}\n\nexport function trackPageView(): void {\n  fire(SNAP_EVENTS.PAGE_VIEW, makeUniqueEventId(SNAP_EVENTS.PAGE_VIEW, 'page'), {})\n}\n\nexport function trackViewContent(\n  productId: string,\n  value?: number,\n  currency?: string,\n): void {\n  fire(\n    SNAP_EVENTS.VIEW_CONTENT,\n    makeUniqueEventId(SNAP_EVENTS.VIEW_CONTENT, productId),\n    { price: value, currency, item_ids: [productId] },\n    { value, currency, contentIds: [productId] },\n  )\n}\n\n/**\n * Fire `ADD_CART` for a single variant's quantity delta. `contentIds` is\n * typically `[productId, variantId]`.\n */\nexport function trackAddCart(\n  variantId: string,\n  quantity: number,\n  value?: number,\n  currency?: string,\n  contentIds?: string[],\n): void {\n  const ids = contentIds?.length ? contentIds : [variantId]\n  fire(\n    SNAP_EVENTS.ADD_CART,\n    makeUniqueEventId(SNAP_EVENTS.ADD_CART, variantId),\n    { price: value, currency, item_ids: ids, number_items: quantity },\n    { value, currency, contentIds: ids, numItems: quantity },\n  )\n}\n\n/** Deterministic per cart: a checkout refresh collapses into one event. */\nexport function trackStartCheckout(\n  cartId: string,\n  itemCount: number,\n  value?: number,\n  currency?: string,\n  contentIds?: string[],\n): void {\n  fire(\n    SNAP_EVENTS.START_CHECKOUT,\n    makeEventId(SNAP_EVENTS.START_CHECKOUT, cartId),\n    { price: value, currency, item_ids: contentIds?.length ? contentIds : undefined, number_items: itemCount },\n    { value, currency, contentIds, numItems: itemCount },\n  )\n}\n\n/**\n * Order-complete tracker. Both channels use the SAME event name\n * (`PURCHASE`) - unlike Pinterest there is no browser/server name split.\n * Dedup is doubly anchored: `client_dedup_id` == `event_id` (48h) and pixel\n * `transaction_id` == CAPI `order_id` (30d).\n */\nexport function trackPurchase(\n  orderId: string,\n  value: number,\n  currency: string,\n  itemCount?: number,\n  contentIds?: string[],\n): void {\n  fire(\n    SNAP_EVENTS.PURCHASE,\n    makeEventId(SNAP_EVENTS.PURCHASE, orderId),\n    {\n      price: value,\n      currency,\n      transaction_id: orderId,\n      item_ids: contentIds?.length ? contentIds : undefined,\n      number_items: itemCount,\n    },\n    { value, currency, orderId, contentIds, numItems: itemCount },\n  )\n}\n"],"mappings":"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","names":[]}

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

@@ -0,0 +1,117 @@
+interface SnapPixelProviderProps {
+    /**
+     * Bound by the manifest's `propsFromConfig` (migration 475) and kept for
+     * that contract. The pixel actually loaded is the live config's
+     * `pixel_id`, so a Pixel ID change in the admin applies without a
+     * storefront redeploy.
+     */
+    pixelId?: string;
+}
+/**
+ * Root providers slot component for Snapchat. Three effects, one job each:
+ *   1. Consent: read `amboras_consent` and follow `amboras-consent-changed`
+ *      so a banner can enable the pixel mid-session. Nothing below runs
+ *      without consent.
+ *   2. Identity: fetch the logged-in customer on mount and on
+ *      `amboras-auth-changed` (not per route - identity almost never changes
+ *      mid-session) and write or clear the `amboras_snap_pii` cookie the CAPI
+ *      relay reads.
+ *   3. Navigation: on every route change capture `?ScCid=`, read the
+ *      merchant's live config, install the pixel the first time
+ *      (`snaptr('init', pixelId)`), then fire the single `PAGE_VIEW`
+ *      (browser + CAPI, shared event id). The click id is captured first so
+ *      the landing page's PAGE_VIEW already carries it. With the plugin
+ *      switched off (or no config) the pixel is never loaded.
+ */
+declare function SnapPixelProvider(_props: SnapPixelProviderProps): null;
+
+interface SnapViewContentProps {
+    productId?: string;
+    productName?: string;
+    sku?: string;
+    /**
+     * Product price in Medusa's storage unit (×100 for every currency, see
+     * `toMajorUnits` in @amboras-dev/pixel-core). Converted to major units
+     * before it reaches Snap.
+     */
+    price?: number;
+    currency?: string;
+}
+/**
+ * Null-rendering component for the `pdpAnalytics` plugin slot. Fires Snap
+ * `VIEW_CONTENT` (pixel + CAPI relay) on PDP mount and once per productId
+ * change during SPA navigation.
+ */
+declare function SnapViewContent({ productId, price, currency }: SnapViewContentProps): null;
+
+interface SnapAddCartProps {
+    cartId?: string;
+    itemCount?: number;
+    total?: number;
+    currency?: string;
+}
+/**
+ * Null-rendering component for the `cartUpdate` plugin slot. Fires Snap
+ * `ADD_CART` once per newly added variant, with the positive quantity delta
+ * and its value in major units.
+ *
+ * The diff (first-hydration seed, per-cart sessionStorage snapshot, removals
+ * ignored, per-variant dedup window, failed-read handling) lives in
+ * `@amboras-dev/pixel-core`'s cart-add tracker; this component only maps an
+ * add to the Snap event. The cart is self-fetched there, so the event never
+ * depends on merchant-passed `total` / `currency`.
+ */
+declare function SnapAddCart({ cartId, 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. Two-layer dedup:
+ *   - `useRef` guards StrictMode double-mount.
+ *   - `sessionStorage` guards page-refresh + back-navigation within the
+ *     same session.
+ *
+ * Self-fetches the cart from Medusa so `value` and `currency` are correct
+ * even when the merchant slot context is thin or wrong. Snap treats
+ * `value` as major units, so `toMajorUnits` runs at this boundary (Medusa
+ * stores everything in minor units).
+ *
+ * The dedup ref is set only AFTER a successful dispatch - a StrictMode
+ * cleanup between effect-run and fetch-complete does NOT poison the ref,
+ * so the event still fires on the second mount.
+ */
+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` (with `transaction_id` = order id) exactly once per
+ * orderId.
+ *
+ * Primary path: self-fetch from `/store/orders/:id` and derive value +
+ * currency + contentIds from the authoritative Medusa response, then convert
+ * to major units via currency-aware `toMajorUnits` (correct for JPY/KWD).
+ *
+ * Fallback path (fetch failed - guest order with expired session, network
+ * error): fire using the incoming `total` + `currency` props with the same
+ * conversion. Snap dedups against the CAPI relay by `client_dedup_id` /
+ * `event_id` (48h) and `transaction_id` / `order_id` (30d).
+ *
+ * Two-layer dedup (useRef + sessionStorage) so a StrictMode double-mount,
+ * a page refresh on the thank-you page, or a back-nav never double-fires.
+ * The ref is set AFTER dispatch so a StrictMode cleanup between mount and
+ * effect body doesn't poison it.
+ */
+declare function SnapPurchase({ orderId, total, currency, itemCount, }: SnapPurchaseProps): null;
+
+export { SnapAddCart, type SnapAddCartProps, SnapPixelProvider, type SnapPixelProviderProps, SnapPurchase, type SnapPurchaseProps, SnapStartCheckout, type SnapStartCheckoutProps, SnapViewContent, type SnapViewContentProps };

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

@@ -0,0 +1,117 @@
+interface SnapPixelProviderProps {
+    /**
+     * Bound by the manifest's `propsFromConfig` (migration 475) and kept for
+     * that contract. The pixel actually loaded is the live config's
+     * `pixel_id`, so a Pixel ID change in the admin applies without a
+     * storefront redeploy.
+     */
+    pixelId?: string;
+}
+/**
+ * Root providers slot component for Snapchat. Three effects, one job each:
+ *   1. Consent: read `amboras_consent` and follow `amboras-consent-changed`
+ *      so a banner can enable the pixel mid-session. Nothing below runs
+ *      without consent.
+ *   2. Identity: fetch the logged-in customer on mount and on
+ *      `amboras-auth-changed` (not per route - identity almost never changes
+ *      mid-session) and write or clear the `amboras_snap_pii` cookie the CAPI
+ *      relay reads.
+ *   3. Navigation: on every route change capture `?ScCid=`, read the
+ *      merchant's live config, install the pixel the first time
+ *      (`snaptr('init', pixelId)`), then fire the single `PAGE_VIEW`
+ *      (browser + CAPI, shared event id). The click id is captured first so
+ *      the landing page's PAGE_VIEW already carries it. With the plugin
+ *      switched off (or no config) the pixel is never loaded.
+ */
+declare function SnapPixelProvider(_props: SnapPixelProviderProps): null;
+
+interface SnapViewContentProps {
+    productId?: string;
+    productName?: string;
+    sku?: string;
+    /**
+     * Product price in Medusa's storage unit (×100 for every currency, see
+     * `toMajorUnits` in @amboras-dev/pixel-core). Converted to major units
+     * before it reaches Snap.
+     */
+    price?: number;
+    currency?: string;
+}
+/**
+ * Null-rendering component for the `pdpAnalytics` plugin slot. Fires Snap
+ * `VIEW_CONTENT` (pixel + CAPI relay) on PDP mount and once per productId
+ * change during SPA navigation.
+ */
+declare function SnapViewContent({ productId, price, currency }: SnapViewContentProps): null;
+
+interface SnapAddCartProps {
+    cartId?: string;
+    itemCount?: number;
+    total?: number;
+    currency?: string;
+}
+/**
+ * Null-rendering component for the `cartUpdate` plugin slot. Fires Snap
+ * `ADD_CART` once per newly added variant, with the positive quantity delta
+ * and its value in major units.
+ *
+ * The diff (first-hydration seed, per-cart sessionStorage snapshot, removals
+ * ignored, per-variant dedup window, failed-read handling) lives in
+ * `@amboras-dev/pixel-core`'s cart-add tracker; this component only maps an
+ * add to the Snap event. The cart is self-fetched there, so the event never
+ * depends on merchant-passed `total` / `currency`.
+ */
+declare function SnapAddCart({ cartId, 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. Two-layer dedup:
+ *   - `useRef` guards StrictMode double-mount.
+ *   - `sessionStorage` guards page-refresh + back-navigation within the
+ *     same session.
+ *
+ * Self-fetches the cart from Medusa so `value` and `currency` are correct
+ * even when the merchant slot context is thin or wrong. Snap treats
+ * `value` as major units, so `toMajorUnits` runs at this boundary (Medusa
+ * stores everything in minor units).
+ *
+ * The dedup ref is set only AFTER a successful dispatch - a StrictMode
+ * cleanup between effect-run and fetch-complete does NOT poison the ref,
+ * so the event still fires on the second mount.
+ */
+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` (with `transaction_id` = order id) exactly once per
+ * orderId.
+ *
+ * Primary path: self-fetch from `/store/orders/:id` and derive value +
+ * currency + contentIds from the authoritative Medusa response, then convert
+ * to major units via currency-aware `toMajorUnits` (correct for JPY/KWD).
+ *
+ * Fallback path (fetch failed - guest order with expired session, network
+ * error): fire using the incoming `total` + `currency` props with the same
+ * conversion. Snap dedups against the CAPI relay by `client_dedup_id` /
+ * `event_id` (48h) and `transaction_id` / `order_id` (30d).
+ *
+ * Two-layer dedup (useRef + sessionStorage) so a StrictMode double-mount,
+ * a page refresh on the thank-you page, or a back-nav never double-fires.
+ * The ref is set AFTER dispatch so a StrictMode cleanup between mount and
+ * effect body doesn't poison it.
+ */
+declare function SnapPurchase({ orderId, total, currency, itemCount, }: SnapPurchaseProps): null;
+
+export { SnapAddCart, type SnapAddCartProps, SnapPixelProvider, type SnapPixelProviderProps, SnapPurchase, type SnapPurchaseProps, SnapStartCheckout, type SnapStartCheckoutProps, SnapViewContent, type SnapViewContentProps };