@amboras-dev/snapchat-ads 2.0.0

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

@@ -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 };