@walkeros/web-destination-pinterest 3.3.0-next-1776098542393

package/dist/examples/index.d.mts

@@ -0,0 +1,206 @@
+import { DestinationWeb } from '@walkeros/web-core';
+import { Flow } from '@walkeros/core';
+
+/**
+ * Pinterest Tag global. The queue-based function created by the Pinterest
+ * snippet. Before core.js loads, calls are queued on `pintrk.queue`.
+ * After core.js resolves the queue, `pintrk` is replaced with the real
+ * implementation. Both shapes accept the same argument signatures.
+ */
+interface Pintrk {
+    (command: 'load', tagId: string, identify?: IdentifyFields): void;
+    (command: 'page'): void;
+    (command: 'track', eventName: string, eventData?: EventData, callback?: (didInit: boolean, error?: unknown) => void): void;
+    (command: 'set', userData: IdentifyFields): void;
+    queue?: unknown[][];
+    version?: string;
+}
+declare global {
+    interface Window {
+        pintrk?: Pintrk;
+    }
+}
+/**
+ * Enhanced matching fields. Web destination strictly limits to the two
+ * documented client-side Pinterest Tag fields. CAPI-only fields (ph, fn,
+ * ln, address, country, ip, ua) belong to a future server destination
+ * and are intentionally not accepted here.
+ *
+ * The Pinterest JS tag auto-hashes `em` with SHA-256 before transmission —
+ * the destination does NOT hash.
+ */
+interface IdentifyFields {
+    em?: string;
+    external_id?: string;
+}
+/**
+ * Event data payload for pintrk('track', ...). Pinterest has a prescribed
+ * set of parameter names. Common parameters across events plus an open
+ * `[key: string]: unknown` for event-specific fields (search_query,
+ * video_title, lead_type, opt_out_type, custom properties, etc.).
+ */
+interface EventData {
+    value?: number;
+    order_quantity?: number;
+    currency?: string;
+    event_id?: string;
+    order_id?: string;
+    promo_code?: string;
+    property?: string;
+    product_name?: string;
+    product_id?: string;
+    product_category?: string;
+    product_brand?: string;
+    product_price?: number;
+    product_quantity?: number;
+    product_variant_id?: string;
+    product_variant?: string;
+    line_items?: LineItem[];
+    search_query?: string;
+    video_title?: string;
+    lead_type?: string;
+    opt_out_type?: 'LDP';
+    [key: string]: unknown;
+}
+interface LineItem {
+    product_name?: string;
+    product_id?: string;
+    product_category?: string;
+    product_brand?: string;
+    product_price?: number;
+    product_quantity?: number;
+    product_variant_id?: string;
+    product_variant?: string;
+    [key: string]: unknown;
+}
+/**
+ * Env — mock surface for tests. Pinterest Tag uses window.pintrk, so
+ * the env extends DestinationWeb.Env (which already provides window
+ * and document).
+ */
+interface Env extends DestinationWeb.Env {
+    window: {
+        pintrk?: Pintrk;
+    };
+}
+
+/**
+ * Pre-init environment — pintrk is not yet on the window.
+ * Used to validate the init path that creates the queue function.
+ */
+declare const init: Env;
+/**
+ * Post-init environment — pintrk is available as a spy-able function.
+ * Tests clone this and replace `pintrk` with a jest.fn() to record calls.
+ */
+declare const push: Env;
+/** Simulation tracking paths for CLI --simulate. */
+declare const simulation: string[];
+
+declare const env_init: typeof init;
+declare const env_push: typeof push;
+declare const env_simulation: typeof simulation;
+declare namespace env {
+  export { env_init as init, env_push as push, env_simulation as simulation };
+}
+
+/**
+ * Output convention:
+ *   - Single SDK call: out = ['window.pintrk', 'track', 'checkout', { ... }]
+ *     (flat array: first element is the dot-path, remaining elements are args)
+ *   - Multiple SDK calls: out = [ [path, ...args], [path, ...args] ]
+ *   - Zero SDK calls: out = []
+ *
+ * The step-examples test runner normalizes both shapes via flatten().
+ */
+/**
+ * Default event forwarding — no rule. Without a mapping.name, the walkerOS
+ * event name is forwarded as-is. Pinterest accepts it but won't match a
+ * standard conversion event. event_id is auto-attached for deduplication.
+ */
+declare const defaultForward: Flow.StepExample;
+/**
+ * Wildcard ignore pattern — the standard walkerOS way to suppress noisy
+ * events. `mapping.ignore: true` at rule level produces zero SDK calls.
+ */
+declare const wildcardIgnored: Flow.StepExample;
+/**
+ * Standard Pinterest event rename via mapping.name. walkerOS "page view"
+ * → Pinterest "pagevisit". The ONLY way to get Pinterest to recognize
+ * a conversion event — the destination never auto-maps.
+ */
+declare const pageViewRename: Flow.StepExample;
+/**
+ * Search — walkerOS site search → Pinterest "search" with search_query.
+ * Illustrates single-field mapping.data resolution.
+ */
+declare const siteSearch: Flow.StepExample;
+/**
+ * Single-product viewcontent. Illustrates:
+ *   - currency fallback via { key, value: 'EUR' }
+ *   - flat product_* parameter names
+ */
+declare const productViewContent: Flow.StepExample;
+/**
+ * Add-to-cart with an inline line_items array.
+ *
+ * Pinterest sends a single track() call with line_items as an ARRAY
+ * INSIDE the event data — NOT a loop of N separate calls.
+ */
+declare const productAddToCart: Flow.StepExample;
+/**
+ * Multi-product checkout — the canonical Pinterest ecommerce pattern.
+ * `line_items.loop: ["nested", { condition, map }]` iterates event.nested
+ * and produces ONE array inside a SINGLE track() call.
+ *
+ * Default fixture has 3 nested entries: ers (420 black), cc (42, no color),
+ * gift (no price → filtered out by condition).
+ */
+declare const orderCompleteCheckout: Flow.StepExample;
+/**
+ * Lead conversion with per-event enhanced matching update.
+ *
+ * The rule-level settings.identify resolves to { em, external_id } and
+ * triggers pintrk('set', data) BEFORE the track() call — enhanced
+ * matching data is associated with the same event via event_id.
+ */
+declare const userLoginLead: Flow.StepExample;
+/**
+ * mapping.skip — processes side effects (identify set) but suppresses
+ * the default pintrk('track', ...) call. Useful when an upstream
+ * destination already fired the conversion and you only want to update
+ * enhanced matching.
+ */
+declare const identifyOnlySkip: Flow.StepExample;
+/**
+ * Consent revocation — walkerOS walker consent { marketing: false }.
+ * The destination's on('consent') handler flips the runtime state flag
+ * and stops calling pintrk('track', ...) for subsequent events. There
+ * is NO opt_out SDK call — Pinterest has no such API.
+ *
+ * Expected out: [] — no pintrk calls fire as a direct result of the
+ * consent dispatch.
+ */
+declare const consentRevoke: Flow.StepExample;
+/**
+ * Consent grant — explicit opt-in. Same behavior: the destination's
+ * on('consent') flips the flag. No SDK call fires.
+ */
+declare const consentGrant: Flow.StepExample;
+
+declare const step_consentGrant: typeof consentGrant;
+declare const step_consentRevoke: typeof consentRevoke;
+declare const step_defaultForward: typeof defaultForward;
+declare const step_identifyOnlySkip: typeof identifyOnlySkip;
+declare const step_orderCompleteCheckout: typeof orderCompleteCheckout;
+declare const step_pageViewRename: typeof pageViewRename;
+declare const step_productAddToCart: typeof productAddToCart;
+declare const step_productViewContent: typeof productViewContent;
+declare const step_siteSearch: typeof siteSearch;
+declare const step_userLoginLead: typeof userLoginLead;
+declare const step_wildcardIgnored: typeof wildcardIgnored;
+declare namespace step {
+  export { step_consentGrant as consentGrant, step_consentRevoke as consentRevoke, step_defaultForward as defaultForward, step_identifyOnlySkip as identifyOnlySkip, step_orderCompleteCheckout as orderCompleteCheckout, step_pageViewRename as pageViewRename, step_productAddToCart as productAddToCart, step_productViewContent as productViewContent, step_siteSearch as siteSearch, step_userLoginLead as userLoginLead, step_wildcardIgnored as wildcardIgnored };
+}
+
+export { env, step };

package/dist/examples/index.d.ts

@@ -0,0 +1,206 @@
+import { DestinationWeb } from '@walkeros/web-core';
+import { Flow } from '@walkeros/core';
+
+/**
+ * Pinterest Tag global. The queue-based function created by the Pinterest
+ * snippet. Before core.js loads, calls are queued on `pintrk.queue`.
+ * After core.js resolves the queue, `pintrk` is replaced with the real
+ * implementation. Both shapes accept the same argument signatures.
+ */
+interface Pintrk {
+    (command: 'load', tagId: string, identify?: IdentifyFields): void;
+    (command: 'page'): void;
+    (command: 'track', eventName: string, eventData?: EventData, callback?: (didInit: boolean, error?: unknown) => void): void;
+    (command: 'set', userData: IdentifyFields): void;
+    queue?: unknown[][];
+    version?: string;
+}
+declare global {
+    interface Window {
+        pintrk?: Pintrk;
+    }
+}
+/**
+ * Enhanced matching fields. Web destination strictly limits to the two
+ * documented client-side Pinterest Tag fields. CAPI-only fields (ph, fn,
+ * ln, address, country, ip, ua) belong to a future server destination
+ * and are intentionally not accepted here.
+ *
+ * The Pinterest JS tag auto-hashes `em` with SHA-256 before transmission —
+ * the destination does NOT hash.
+ */
+interface IdentifyFields {
+    em?: string;
+    external_id?: string;
+}
+/**
+ * Event data payload for pintrk('track', ...). Pinterest has a prescribed
+ * set of parameter names. Common parameters across events plus an open
+ * `[key: string]: unknown` for event-specific fields (search_query,
+ * video_title, lead_type, opt_out_type, custom properties, etc.).
+ */
+interface EventData {
+    value?: number;
+    order_quantity?: number;
+    currency?: string;
+    event_id?: string;
+    order_id?: string;
+    promo_code?: string;
+    property?: string;
+    product_name?: string;
+    product_id?: string;
+    product_category?: string;
+    product_brand?: string;
+    product_price?: number;
+    product_quantity?: number;
+    product_variant_id?: string;
+    product_variant?: string;
+    line_items?: LineItem[];
+    search_query?: string;
+    video_title?: string;
+    lead_type?: string;
+    opt_out_type?: 'LDP';
+    [key: string]: unknown;
+}
+interface LineItem {
+    product_name?: string;
+    product_id?: string;
+    product_category?: string;
+    product_brand?: string;
+    product_price?: number;
+    product_quantity?: number;
+    product_variant_id?: string;
+    product_variant?: string;
+    [key: string]: unknown;
+}
+/**
+ * Env — mock surface for tests. Pinterest Tag uses window.pintrk, so
+ * the env extends DestinationWeb.Env (which already provides window
+ * and document).
+ */
+interface Env extends DestinationWeb.Env {
+    window: {
+        pintrk?: Pintrk;
+    };
+}
+
+/**
+ * Pre-init environment — pintrk is not yet on the window.
+ * Used to validate the init path that creates the queue function.
+ */
+declare const init: Env;
+/**
+ * Post-init environment — pintrk is available as a spy-able function.
+ * Tests clone this and replace `pintrk` with a jest.fn() to record calls.
+ */
+declare const push: Env;
+/** Simulation tracking paths for CLI --simulate. */
+declare const simulation: string[];
+
+declare const env_init: typeof init;
+declare const env_push: typeof push;
+declare const env_simulation: typeof simulation;
+declare namespace env {
+  export { env_init as init, env_push as push, env_simulation as simulation };
+}
+
+/**
+ * Output convention:
+ *   - Single SDK call: out = ['window.pintrk', 'track', 'checkout', { ... }]
+ *     (flat array: first element is the dot-path, remaining elements are args)
+ *   - Multiple SDK calls: out = [ [path, ...args], [path, ...args] ]
+ *   - Zero SDK calls: out = []
+ *
+ * The step-examples test runner normalizes both shapes via flatten().
+ */
+/**
+ * Default event forwarding — no rule. Without a mapping.name, the walkerOS
+ * event name is forwarded as-is. Pinterest accepts it but won't match a
+ * standard conversion event. event_id is auto-attached for deduplication.
+ */
+declare const defaultForward: Flow.StepExample;
+/**
+ * Wildcard ignore pattern — the standard walkerOS way to suppress noisy
+ * events. `mapping.ignore: true` at rule level produces zero SDK calls.
+ */
+declare const wildcardIgnored: Flow.StepExample;
+/**
+ * Standard Pinterest event rename via mapping.name. walkerOS "page view"
+ * → Pinterest "pagevisit". The ONLY way to get Pinterest to recognize
+ * a conversion event — the destination never auto-maps.
+ */
+declare const pageViewRename: Flow.StepExample;
+/**
+ * Search — walkerOS site search → Pinterest "search" with search_query.
+ * Illustrates single-field mapping.data resolution.
+ */
+declare const siteSearch: Flow.StepExample;
+/**
+ * Single-product viewcontent. Illustrates:
+ *   - currency fallback via { key, value: 'EUR' }
+ *   - flat product_* parameter names
+ */
+declare const productViewContent: Flow.StepExample;
+/**
+ * Add-to-cart with an inline line_items array.
+ *
+ * Pinterest sends a single track() call with line_items as an ARRAY
+ * INSIDE the event data — NOT a loop of N separate calls.
+ */
+declare const productAddToCart: Flow.StepExample;
+/**
+ * Multi-product checkout — the canonical Pinterest ecommerce pattern.
+ * `line_items.loop: ["nested", { condition, map }]` iterates event.nested
+ * and produces ONE array inside a SINGLE track() call.
+ *
+ * Default fixture has 3 nested entries: ers (420 black), cc (42, no color),
+ * gift (no price → filtered out by condition).
+ */
+declare const orderCompleteCheckout: Flow.StepExample;
+/**
+ * Lead conversion with per-event enhanced matching update.
+ *
+ * The rule-level settings.identify resolves to { em, external_id } and
+ * triggers pintrk('set', data) BEFORE the track() call — enhanced
+ * matching data is associated with the same event via event_id.
+ */
+declare const userLoginLead: Flow.StepExample;
+/**
+ * mapping.skip — processes side effects (identify set) but suppresses
+ * the default pintrk('track', ...) call. Useful when an upstream
+ * destination already fired the conversion and you only want to update
+ * enhanced matching.
+ */
+declare const identifyOnlySkip: Flow.StepExample;
+/**
+ * Consent revocation — walkerOS walker consent { marketing: false }.
+ * The destination's on('consent') handler flips the runtime state flag
+ * and stops calling pintrk('track', ...) for subsequent events. There
+ * is NO opt_out SDK call — Pinterest has no such API.
+ *
+ * Expected out: [] — no pintrk calls fire as a direct result of the
+ * consent dispatch.
+ */
+declare const consentRevoke: Flow.StepExample;
+/**
+ * Consent grant — explicit opt-in. Same behavior: the destination's
+ * on('consent') flips the flag. No SDK call fires.
+ */
+declare const consentGrant: Flow.StepExample;
+
+declare const step_consentGrant: typeof consentGrant;
+declare const step_consentRevoke: typeof consentRevoke;
+declare const step_defaultForward: typeof defaultForward;
+declare const step_identifyOnlySkip: typeof identifyOnlySkip;
+declare const step_orderCompleteCheckout: typeof orderCompleteCheckout;
+declare const step_pageViewRename: typeof pageViewRename;
+declare const step_productAddToCart: typeof productAddToCart;
+declare const step_productViewContent: typeof productViewContent;
+declare const step_siteSearch: typeof siteSearch;
+declare const step_userLoginLead: typeof userLoginLead;
+declare const step_wildcardIgnored: typeof wildcardIgnored;
+declare namespace step {
+  export { step_consentGrant as consentGrant, step_consentRevoke as consentRevoke, step_defaultForward as defaultForward, step_identifyOnlySkip as identifyOnlySkip, step_orderCompleteCheckout as orderCompleteCheckout, step_pageViewRename as pageViewRename, step_productAddToCart as productAddToCart, step_productViewContent as productViewContent, step_siteSearch as siteSearch, step_userLoginLead as userLoginLead, step_wildcardIgnored as wildcardIgnored };
+}
+
+export { env, step };