@amboras-dev/snapchat-ads 0.1.0

package/dist/chunk-IP2VTHD6.mjs

@@ -0,0 +1,27 @@
+// src/get-config.ts
+import { resolveBackendUrl, resolvePublishableKey, resolveStoreEnvironmentId } from "@amboras-dev/pixel-core";
+async function getSnapchatConfig(options = {}) {
+  const baseUrl = options.baseUrl ?? resolveBackendUrl();
+  if (!baseUrl) return null;
+  const publishableKey = options.publishableApiKey ?? resolvePublishableKey();
+  const storeId = options.storeId ?? resolveStoreEnvironmentId();
+  const doFetch = options.fetchImpl ?? fetch;
+  try {
+    const res = await doFetch(`${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;
+  }
+}
+
+export {
+  getSnapchatConfig
+};
+//# sourceMappingURL=chunk-IP2VTHD6.mjs.map

package/dist/chunk-IP2VTHD6.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/get-config.ts"],"sourcesContent":["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"],"mappings":";AAAA,SAAS,mBAAmB,uBAAuB,iCAAiC;AAiBpF,eAAsB,kBACpB,UAAoC,CAAC,GACC;AACtC,QAAM,UAAU,QAAQ,WAAW,kBAAkB;AACrD,MAAI,CAAC,QAAS,QAAO;AACrB,QAAM,iBAAiB,QAAQ,qBAAqB,sBAAsB;AAC1E,QAAM,UAAU,QAAQ,WAAW,0BAA0B;AAC7D,QAAM,UAAU,QAAQ,aAAa;AAErC,MAAI;AACF,UAAM,MAAM,MAAM,QAAQ,GAAG,OAAO,8BAA8B;AAAA,MAChE,SAAS;AAAA,QACP,GAAI,UAAU,EAAE,0BAA0B,QAAQ,IAAI,CAAC;AAAA,QACvD,GAAI,iBAAiB,EAAE,yBAAyB,eAAe,IAAI,CAAC;AAAA,MACtE;AAAA,MACA,MAAM,EAAE,YAAY,GAAG;AAAA,IACzB,CAAgB;AAChB,QAAI,CAAC,IAAI,GAAI,QAAO;AACpB,WAAQ,MAAM,IAAI,KAAK;AAAA,EACzB,QAAQ;AACN,WAAO;AAAA,EACT;AACF;","names":[]}

package/dist/get-config-Dr_GV8ip.d.mts

@@ -0,0 +1,93 @@
+/**
+ * Every fixed string the package puts on the wire or in browser storage.
+ * Wire names are a cross-repo contract: Medusa's strict Zod schema and the
+ * orchestrator's storefront relay template expect exactly these values.
+ */
+/**
+ * Snap standard event names. The pixel (`snaptr('track', <name>)`) and
+ * Conversions API v3 (`event_name`) use the SAME uppercase strings.
+ * https://developers.snap.com/api/marketing-api/Conversions-API/Parameters
+ */
+declare const SNAP_EVENTS: {
+    readonly PAGE_VIEW: "PAGE_VIEW";
+    readonly VIEW_CONTENT: "VIEW_CONTENT";
+    readonly ADD_CART: "ADD_CART";
+    readonly START_CHECKOUT: "START_CHECKOUT";
+    readonly PURCHASE: "PURCHASE";
+};
+/** Storefront relay route written by the orchestrator's template. */
+declare const CAPI_RELAY_ENDPOINT = "/api/snapchat/events";
+declare const COOKIE_NAMES: {
+    /** Plugin-owned raw PII for the relay; Medusa hashes it. */
+    readonly PII: "amboras_snap_pii";
+    /** Plugin-owned copy of `ScCid`. */
+    readonly CLICK_ID: "amboras_snap_clid";
+    /** Snap's own first-party cookie (forwarded as `sc_cookie1`). */
+    readonly SCID: "_scid";
+};
+
+/**
+ * Non-secret Snapchat configuration exposed to the browser via
+ * `/store/snapchat-ads/config`. Never contains the Conversions API token -
+ * that lives only on the Medusa side and never leaves the server.
+ */
+interface SnapchatPublicConfig {
+    pixel_id: string;
+    enabled: boolean;
+    track_page_view: boolean;
+    track_view_content: boolean;
+    track_add_cart: boolean;
+    track_start_checkout: boolean;
+    track_purchase: boolean;
+}
+/**
+ * Snap standard event names. The Snap Pixel (`snaptr('track', <name>)`) and
+ * Conversions API v3 (`event_name`) use the SAME uppercase strings, so the
+ * storefront sends the wire name end to end and Medusa forwards it as-is.
+ * https://developers.snap.com/api/marketing-api/Conversions-API/Parameters
+ */
+type SnapchatEventName = (typeof SNAP_EVENTS)[keyof typeof SNAP_EVENTS];
+/**
+ * Payload posted from the storefront to `/api/snapchat/events`. The proxy
+ * adds the PII cookie, client IP and User-Agent, then forwards to Medusa
+ * `/store/snapchat-ads/events` with the same `eventId`.
+ *
+ * Dedup contract with the browser pixel:
+ *   - `eventId` == pixel `client_dedup_id` (48h window, every event).
+ *   - `customData.orderId` == pixel `transaction_id` (30d window, PURCHASE).
+ */
+interface SnapchatCapiEventPayload {
+    eventName: SnapchatEventName;
+    eventId: string;
+    eventSourceUrl: string;
+    userData: {
+        /** `ScCid` URL param captured on ad landing. Sent raw, never hashed. */
+        clickId?: string;
+        /** Value of Snap's first-party `_scid` cookie. Sent raw, never hashed. */
+        cookie1?: string;
+    };
+    customData?: {
+        value?: number;
+        currency?: string;
+        orderId?: string;
+        contentIds?: string[];
+        numItems?: number;
+    };
+}
+
+interface GetSnapchatConfigOptions {
+    baseUrl?: string;
+    publishableApiKey?: string;
+    storeId?: string;
+    /** Injected `fetch` for testing. Defaults to global `fetch`. */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Fetches the non-secret Snapchat config from Medusa. Returns `null` when
+ * the backend URL is unknown or the endpoint is missing, unauthorized, or
+ * errors. The Conversions API token is never returned by the server route,
+ * so it never surfaces here.
+ */
+declare function getSnapchatConfig(options?: GetSnapchatConfigOptions): Promise<SnapchatPublicConfig | null>;
+
+export { CAPI_RELAY_ENDPOINT as C, type SnapchatCapiEventPayload as S, type SnapchatEventName as a, COOKIE_NAMES as b, SNAP_EVENTS as c, type SnapchatPublicConfig as d, getSnapchatConfig as g };

package/dist/get-config-Dr_GV8ip.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Every fixed string the package puts on the wire or in browser storage.
+ * Wire names are a cross-repo contract: Medusa's strict Zod schema and the
+ * orchestrator's storefront relay template expect exactly these values.
+ */
+/**
+ * Snap standard event names. The pixel (`snaptr('track', <name>)`) and
+ * Conversions API v3 (`event_name`) use the SAME uppercase strings.
+ * https://developers.snap.com/api/marketing-api/Conversions-API/Parameters
+ */
+declare const SNAP_EVENTS: {
+    readonly PAGE_VIEW: "PAGE_VIEW";
+    readonly VIEW_CONTENT: "VIEW_CONTENT";
+    readonly ADD_CART: "ADD_CART";
+    readonly START_CHECKOUT: "START_CHECKOUT";
+    readonly PURCHASE: "PURCHASE";
+};
+/** Storefront relay route written by the orchestrator's template. */
+declare const CAPI_RELAY_ENDPOINT = "/api/snapchat/events";
+declare const COOKIE_NAMES: {
+    /** Plugin-owned raw PII for the relay; Medusa hashes it. */
+    readonly PII: "amboras_snap_pii";
+    /** Plugin-owned copy of `ScCid`. */
+    readonly CLICK_ID: "amboras_snap_clid";
+    /** Snap's own first-party cookie (forwarded as `sc_cookie1`). */
+    readonly SCID: "_scid";
+};
+
+/**
+ * Non-secret Snapchat configuration exposed to the browser via
+ * `/store/snapchat-ads/config`. Never contains the Conversions API token -
+ * that lives only on the Medusa side and never leaves the server.
+ */
+interface SnapchatPublicConfig {
+    pixel_id: string;
+    enabled: boolean;
+    track_page_view: boolean;
+    track_view_content: boolean;
+    track_add_cart: boolean;
+    track_start_checkout: boolean;
+    track_purchase: boolean;
+}
+/**
+ * Snap standard event names. The Snap Pixel (`snaptr('track', <name>)`) and
+ * Conversions API v3 (`event_name`) use the SAME uppercase strings, so the
+ * storefront sends the wire name end to end and Medusa forwards it as-is.
+ * https://developers.snap.com/api/marketing-api/Conversions-API/Parameters
+ */
+type SnapchatEventName = (typeof SNAP_EVENTS)[keyof typeof SNAP_EVENTS];
+/**
+ * Payload posted from the storefront to `/api/snapchat/events`. The proxy
+ * adds the PII cookie, client IP and User-Agent, then forwards to Medusa
+ * `/store/snapchat-ads/events` with the same `eventId`.
+ *
+ * Dedup contract with the browser pixel:
+ *   - `eventId` == pixel `client_dedup_id` (48h window, every event).
+ *   - `customData.orderId` == pixel `transaction_id` (30d window, PURCHASE).
+ */
+interface SnapchatCapiEventPayload {
+    eventName: SnapchatEventName;
+    eventId: string;
+    eventSourceUrl: string;
+    userData: {
+        /** `ScCid` URL param captured on ad landing. Sent raw, never hashed. */
+        clickId?: string;
+        /** Value of Snap's first-party `_scid` cookie. Sent raw, never hashed. */
+        cookie1?: string;
+    };
+    customData?: {
+        value?: number;
+        currency?: string;
+        orderId?: string;
+        contentIds?: string[];
+        numItems?: number;
+    };
+}
+
+interface GetSnapchatConfigOptions {
+    baseUrl?: string;
+    publishableApiKey?: string;
+    storeId?: string;
+    /** Injected `fetch` for testing. Defaults to global `fetch`. */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Fetches the non-secret Snapchat config from Medusa. Returns `null` when
+ * the backend URL is unknown or the endpoint is missing, unauthorized, or
+ * errors. The Conversions API token is never returned by the server route,
+ * so it never surfaces here.
+ */
+declare function getSnapchatConfig(options?: GetSnapchatConfigOptions): Promise<SnapchatPublicConfig | null>;
+
+export { CAPI_RELAY_ENDPOINT as C, type SnapchatCapiEventPayload as S, type SnapchatEventName as a, COOKIE_NAMES as b, SNAP_EVENTS as c, type SnapchatPublicConfig as d, getSnapchatConfig as g };

package/dist/get-config.d.mts

@@ -0,0 +1 @@
+export { g as getSnapchatConfig } from './get-config-Dr_GV8ip.mjs';

package/dist/get-config.d.ts

@@ -0,0 +1 @@
+export { g as getSnapchatConfig } from './get-config-Dr_GV8ip.js';

package/dist/get-config.js

@@ -0,0 +1,51 @@
+"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/get-config.ts
+var get_config_exports = {};
+__export(get_config_exports, {
+  getSnapchatConfig: () => getSnapchatConfig
+});
+module.exports = __toCommonJS(get_config_exports);
+var import_pixel_core = require("@amboras-dev/pixel-core");
+async function getSnapchatConfig(options = {}) {
+  const baseUrl = options.baseUrl ?? (0, import_pixel_core.resolveBackendUrl)();
+  if (!baseUrl) return null;
+  const publishableKey = options.publishableApiKey ?? (0, import_pixel_core.resolvePublishableKey)();
+  const storeId = options.storeId ?? (0, import_pixel_core.resolveStoreEnvironmentId)();
+  const doFetch = options.fetchImpl ?? fetch;
+  try {
+    const res = await doFetch(`${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 = {
+  getSnapchatConfig
+});
+//# sourceMappingURL=get-config.js.map

package/dist/get-config.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/get-config.ts"],"sourcesContent":["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"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,wBAAoF;AAiBpF,eAAsB,kBACpB,UAAoC,CAAC,GACC;AACtC,QAAM,UAAU,QAAQ,eAAW,qCAAkB;AACrD,MAAI,CAAC,QAAS,QAAO;AACrB,QAAM,iBAAiB,QAAQ,yBAAqB,yCAAsB;AAC1E,QAAM,UAAU,QAAQ,eAAW,6CAA0B;AAC7D,QAAM,UAAU,QAAQ,aAAa;AAErC,MAAI;AACF,UAAM,MAAM,MAAM,QAAQ,GAAG,OAAO,8BAA8B;AAAA,MAChE,SAAS;AAAA,QACP,GAAI,UAAU,EAAE,0BAA0B,QAAQ,IAAI,CAAC;AAAA,QACvD,GAAI,iBAAiB,EAAE,yBAAyB,eAAe,IAAI,CAAC;AAAA,MACtE;AAAA,MACA,MAAM,EAAE,YAAY,GAAG;AAAA,IACzB,CAAgB;AAChB,QAAI,CAAC,IAAI,GAAI,QAAO;AACpB,WAAQ,MAAM,IAAI,KAAK;AAAA,EACzB,QAAQ;AACN,WAAO;AAAA,EACT;AACF;","names":[]}

package/dist/get-config.mjs

@@ -0,0 +1,7 @@
+import {
+  getSnapchatConfig
+} from "./chunk-IP2VTHD6.mjs";
+export {
+  getSnapchatConfig
+};
+//# sourceMappingURL=get-config.mjs.map

package/dist/get-config.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/index.d.mts

@@ -0,0 +1,48 @@
+import { S as SnapchatCapiEventPayload, a as SnapchatEventName } from './get-config-Dr_GV8ip.mjs';
+export { C as CAPI_RELAY_ENDPOINT, b as COOKIE_NAMES, c as SNAP_EVENTS, d as SnapchatPublicConfig, g as getSnapchatConfig } from './get-config-Dr_GV8ip.mjs';
+
+/**
+ * POST the event to the storefront's `/api/snapchat/events` proxy. The
+ * proxy enriches with the PII cookie + IP + User-Agent and forwards to
+ * Medusa's `/store/snapchat-ads/events` route, which queues it on the shared
+ * outbox. Intentionally UNGATED on analytics consent - CAPI operates on a
+ * different legal basis than the browser pixel. Merchant owns that call.
+ */
+declare function sendSnapchatCapiEvent(payload: SnapchatCapiEventPayload): Promise<void>;
+declare function trackPageView(): void;
+declare function trackViewContent(productId: string, value?: number, currency?: string): void;
+/**
+ * Fire `ADD_CART` for a single variant's quantity delta. `contentIds` is
+ * typically `[productId, variantId]`.
+ */
+declare function trackAddCart(variantId: string, quantity: number, value?: number, currency?: string, contentIds?: string[]): void;
+/** Deterministic per cart: a checkout refresh collapses into one event. */
+declare function trackStartCheckout(cartId: string, itemCount: number, value?: number, currency?: string, contentIds?: string[]): void;
+/**
+ * Order-complete tracker. Both channels use the SAME event name
+ * (`PURCHASE`) - unlike Pinterest there is no browser/server name split.
+ * Dedup is doubly anchored: `client_dedup_id` == `event_id` (48h) and pixel
+ * `transaction_id` == CAPI `order_id` (30d).
+ */
+declare function trackPurchase(orderId: string, value: number, currency: string, itemCount?: number, contentIds?: string[]): void;
+
+/**
+ * Event-ID builders for browser <-> CAPI dedup. Snap matches the pixel's
+ * `client_dedup_id` against the CAPI `event_id` within 48h, so the browser
+ * call and the CAPI relay for one user action must carry the same ID. Both
+ * are fired from the same function call, so the ID only has to be stable
+ * within that call - not across calls.
+ *
+ * Two flavours:
+ *   - `makeEventId`: deterministic. Used where a repeat fire of the SAME
+ *     action must collapse into one (START_CHECKOUT per cart, PURCHASE per
+ *     order), e.g. a refresh on the thank-you page.
+ *   - `makeUniqueEventId`: deterministic prefix + random suffix. Used for
+ *     actions a shopper legitimately repeats (viewing a product again,
+ *     adding the same variant twice, revisiting a page). A pure
+ *     deterministic ID would make Snap drop every repeat within 48h.
+ */
+declare function makeEventId(eventName: SnapchatEventName, primaryKey: string): string;
+declare function makeUniqueEventId(eventName: SnapchatEventName, primaryKey: string): string;
+
+export { SnapchatCapiEventPayload, SnapchatEventName, makeEventId, makeUniqueEventId, sendSnapchatCapiEvent, trackAddCart, trackPageView, trackPurchase, trackStartCheckout, trackViewContent };

package/dist/index.d.ts

@@ -0,0 +1,48 @@
+import { S as SnapchatCapiEventPayload, a as SnapchatEventName } from './get-config-Dr_GV8ip.js';
+export { C as CAPI_RELAY_ENDPOINT, b as COOKIE_NAMES, c as SNAP_EVENTS, d as SnapchatPublicConfig, g as getSnapchatConfig } from './get-config-Dr_GV8ip.js';
+
+/**
+ * POST the event to the storefront's `/api/snapchat/events` proxy. The
+ * proxy enriches with the PII cookie + IP + User-Agent and forwards to
+ * Medusa's `/store/snapchat-ads/events` route, which queues it on the shared
+ * outbox. Intentionally UNGATED on analytics consent - CAPI operates on a
+ * different legal basis than the browser pixel. Merchant owns that call.
+ */
+declare function sendSnapchatCapiEvent(payload: SnapchatCapiEventPayload): Promise<void>;
+declare function trackPageView(): void;
+declare function trackViewContent(productId: string, value?: number, currency?: string): void;
+/**
+ * Fire `ADD_CART` for a single variant's quantity delta. `contentIds` is
+ * typically `[productId, variantId]`.
+ */
+declare function trackAddCart(variantId: string, quantity: number, value?: number, currency?: string, contentIds?: string[]): void;
+/** Deterministic per cart: a checkout refresh collapses into one event. */
+declare function trackStartCheckout(cartId: string, itemCount: number, value?: number, currency?: string, contentIds?: string[]): void;
+/**
+ * Order-complete tracker. Both channels use the SAME event name
+ * (`PURCHASE`) - unlike Pinterest there is no browser/server name split.
+ * Dedup is doubly anchored: `client_dedup_id` == `event_id` (48h) and pixel
+ * `transaction_id` == CAPI `order_id` (30d).
+ */
+declare function trackPurchase(orderId: string, value: number, currency: string, itemCount?: number, contentIds?: string[]): void;
+
+/**
+ * Event-ID builders for browser <-> CAPI dedup. Snap matches the pixel's
+ * `client_dedup_id` against the CAPI `event_id` within 48h, so the browser
+ * call and the CAPI relay for one user action must carry the same ID. Both
+ * are fired from the same function call, so the ID only has to be stable
+ * within that call - not across calls.
+ *
+ * Two flavours:
+ *   - `makeEventId`: deterministic. Used where a repeat fire of the SAME
+ *     action must collapse into one (START_CHECKOUT per cart, PURCHASE per
+ *     order), e.g. a refresh on the thank-you page.
+ *   - `makeUniqueEventId`: deterministic prefix + random suffix. Used for
+ *     actions a shopper legitimately repeats (viewing a product again,
+ *     adding the same variant twice, revisiting a page). A pure
+ *     deterministic ID would make Snap drop every repeat within 48h.
+ */
+declare function makeEventId(eventName: SnapchatEventName, primaryKey: string): string;
+declare function makeUniqueEventId(eventName: SnapchatEventName, primaryKey: string): string;
+
+export { SnapchatCapiEventPayload, SnapchatEventName, makeEventId, makeUniqueEventId, sendSnapchatCapiEvent, trackAddCart, trackPageView, trackPurchase, trackStartCheckout, trackViewContent };

package/dist/index.js

@@ -0,0 +1,251 @@
+"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, {
+  CAPI_RELAY_ENDPOINT: () => CAPI_RELAY_ENDPOINT,
+  COOKIE_NAMES: () => COOKIE_NAMES,
+  SNAP_EVENTS: () => SNAP_EVENTS,
+  getSnapchatConfig: () => getSnapchatConfig,
+  makeEventId: () => makeEventId,
+  makeUniqueEventId: () => makeUniqueEventId,
+  sendSnapchatCapiEvent: () => sendSnapchatCapiEvent,
+  trackAddCart: () => trackAddCart,
+  trackPageView: () => trackPageView,
+  trackPurchase: () => trackPurchase,
+  trackStartCheckout: () => trackStartCheckout,
+  trackViewContent: () => trackViewContent
+});
+module.exports = __toCommonJS(src_exports);
+
+// 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
+var import_pixel_core = require("@amboras-dev/pixel-core");
+function readScid() {
+  return (0, import_pixel_core.readCookie)(COOKIE_NAMES.SCID);
+}
+function readClickId() {
+  return (0, import_pixel_core.readCookie)(COOKIE_NAMES.CLICK_ID);
+}
+
+// src/get-config.ts
+var import_pixel_core2 = require("@amboras-dev/pixel-core");
+async function getSnapchatConfig(options = {}) {
+  const baseUrl = options.baseUrl ?? (0, import_pixel_core2.resolveBackendUrl)();
+  if (!baseUrl) return null;
+  const publishableKey = options.publishableApiKey ?? (0, import_pixel_core2.resolvePublishableKey)();
+  const storeId = options.storeId ?? (0, import_pixel_core2.resolveStoreEnvironmentId)();
+  const doFetch = options.fetchImpl ?? fetch;
+  try {
+    const res = await doFetch(`${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;
+  }
+}
+
+// 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 }
+  );
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  CAPI_RELAY_ENDPOINT,
+  COOKIE_NAMES,
+  SNAP_EVENTS,
+  getSnapchatConfig,
+  makeEventId,
+  makeUniqueEventId,
+  sendSnapchatCapiEvent,
+  trackAddCart,
+  trackPageView,
+  trackPurchase,
+  trackStartCheckout,
+  trackViewContent
+});
+//# sourceMappingURL=index.js.map