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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 elbWalker GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,249 @@
+# Pinterest Tag Web Destination for walkerOS
+
+Forward walkerOS events to the Pinterest Tag (`window.pintrk`) for conversion
+tracking, enhanced matching, and dynamic retargeting.
+
+## Source Code
+
+[github.com/elbwalker/walkerOS/tree/main/packages/web/destinations/pinterest](https://github.com/elbwalker/walkerOS/tree/main/packages/web/destinations/pinterest)
+
+## NPM
+
+[`@walkeros/web-destination-pinterest`](https://www.npmjs.com/package/@walkeros/web-destination-pinterest)
+
+## Documentation
+
+[walkeros.io/docs/destinations/web/pinterest](https://www.walkeros.io/docs/destinations/web/pinterest)
+
+## Features
+
+- **Standard event taxonomy** — explicit `mapping.name` rename to Pinterest's
+  lowercase concatenated names (`pagevisit`, `addtocart`, `checkout`,
+  `viewcontent`, `lead`, `signup`, `search`, `custom`, ...).
+- **Inline `line_items` for multi-product** — single
+  `pintrk('track', 'checkout', { line_items: [...] })` call (NOT N separate
+  calls). Built via the standard walkerOS `loop` mapping syntax.
+- **Enhanced matching** — strict allow-list of `em` (email) and `external_id`.
+  The Pinterest JS tag auto-hashes `em` with SHA-256 — the destination passes
+  raw values through and never hashes.
+- **Auto `event_id` for dedup** — every `pintrk('track', ...)` call attaches the
+  walkerOS event `id` as `event_id`, ready for cross-channel deduplication with
+  a future server (Conversions API) destination.
+- **Consent-aware suppression** — `on('consent')` flips a runtime state flag.
+  After revocation, subsequent track calls are suppressed even though Pinterest
+  has no `opt_in`/`opt_out` SDK API.
+
+## Installation
+
+```bash
+npm install @walkeros/web-destination-pinterest
+```
+
+## Quick Start
+
+```json
+{
+  "destinations": {
+    "pinterest": {
+      "package": "@walkeros/web-destination-pinterest",
+      "config": {
+        "consent": { "marketing": true },
+        "loadScript": true,
+        "settings": {
+          "apiKey": "2612345678901"
+        },
+        "mapping": {
+          "page": {
+            "view": { "name": "pagevisit" }
+          },
+          "order": {
+            "complete": {
+              "name": "checkout",
+              "data": {
+                "map": {
+                  "value": "data.total",
+                  "order_id": "data.id",
+                  "currency": { "key": "data.currency", "value": "EUR" }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+## Configuration
+
+### Settings
+
+| Key          | Type                    | Required | Notes                                                                                                                                                                        |
+| ------------ | ----------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `apiKey`     | `string`                | yes      | Pinterest Tag ID (numeric string, e.g. `"2612345678901"`). Found in Pinterest Ads Manager under Conversions → Pinterest Tag. Passed to `pintrk('load', tagId)`.              |
+| `pageview`   | `boolean`               | no       | Fire `pintrk('page')` once in init after `core.js` loads. Default `true`. Set `false` when walkerOS sources already emit page view events to avoid a duplicate initial fire. |
+| `identify`   | `Mapping.Value`         | no       | Mapping value resolving to `{ em?, external_id? }`. Resolved on the first event and fired via `pintrk('set', data)` whenever the resolved identity changes.                  |
+| `include`    | `string[]`              | no       | Sections to forward as prefixed properties in track payloads. Pinterest expects specific parameter names — explicit `mapping.data` is usually preferred over `include`.      |
+| `loadScript` | `boolean` (on `config`) | no       | If `true`, the destination injects `https://s.pinimg.com/ct/core.js` on init. Set `false` when the host page already loads the Pinterest Tag snippet.                        |
+
+### Mapping (per-event)
+
+| Key                 | Resolved shape          | Notes                                                                                                                                           |
+| ------------------- | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `name`              | Pinterest event string  | One of `pagevisit`, `addtocart`, `checkout`, `viewcontent`, `lead`, `signup`, `search`, `custom`, ... Forwarded as the second arg to `track()`. |
+| `data` (top-level)  | `EventData`             | Standard walkerOS data resolution. The resolved object is sent verbatim as the third arg to `track()`.                                          |
+| `settings.identify` | `{ em?, external_id? }` | Per-event identity override. Fires `pintrk('set', data)` BEFORE the track call when the resolved identity differs from the current state.       |
+| `settings.include`  | `string[]`              | Overrides destination-level `include` for this rule.                                                                                            |
+| `skip`              | `boolean`               | Process side effects (identify) but suppress the default `pintrk('track', ...)` call.                                                           |
+
+## Event Mapping
+
+Pinterest expects lowercase concatenated event names. The destination never
+auto-maps — every conversion event needs an explicit `mapping.name`.
+
+| walkerOS event   | Pinterest event | Notes                                                                              |
+| ---------------- | --------------- | ---------------------------------------------------------------------------------- |
+| `page view`      | `pagevisit`     | Fired automatically by `pintrk('page')` on init unless `settings.pageview: false`. |
+| `product view`   | `viewcontent`   | Single product. Use `value`, `currency`, `product_id`, `product_name`.             |
+| `product add`    | `addtocart`     | Single product. Wrap in `line_items` array if you also want item-level data.       |
+| `order complete` | `checkout`      | Multi-product. Use `mapping.data.line_items.loop` to iterate `event.nested`.       |
+| `site search`    | `search`        | Use `search_query` field.                                                          |
+| `user login`     | `lead`          | Optional `lead_type`. Combine with `settings.identify` for enhanced matching.      |
+| `user signup`    | `signup`        | Same identify pattern as `lead`.                                                   |
+| (custom)         | `custom`        | Send Pinterest's `custom` event for non-standard conversions.                      |
+
+## Multi-product checkout
+
+Pinterest sends a SINGLE `pintrk('track', 'checkout', { line_items: [...] })`
+call. The walkerOS `loop` mapping resolves a nested array INTO the data, NOT
+into N separate SDK calls (different from Amplitude's per-item revenue pattern).
+
+```json
+"order": {
+  "complete": {
+    "name": "checkout",
+    "data": {
+      "map": {
+        "value": "data.total",
+        "order_id": "data.id",
+        "currency": { "key": "data.currency", "value": "EUR" },
+        "line_items": {
+          "loop": [
+            "nested",
+            {
+              "condition": "$code: (v) => typeof v?.data?.price === 'number'",
+              "map": {
+                "product_id": "data.id",
+                "product_name": "data.color",
+                "product_price": "data.price",
+                "product_quantity": { "value": 1 }
+              }
+            }
+          ]
+        }
+      }
+    }
+  }
+}
+```
+
+## Enhanced Matching
+
+Pinterest's web tag accepts two enhanced matching fields, both auto-hashed by
+the JS tag:
+
+| Field         | Source                             | Notes                                                    |
+| ------------- | ---------------------------------- | -------------------------------------------------------- |
+| `em`          | `data.email` / `user.email` / etc. | Pinterest auto-hashes — pass raw email, do NOT pre-hash. |
+| `external_id` | `data.id` / `user.id`              | Stable user identifier. Auto-hashed by Pinterest.        |
+
+The destination strictly limits to these two fields. CAPI-only fields (`ph`,
+`fn`, `ln`, `address`, `country`, `ip`, `ua`) belong to the future server
+destination and are intentionally not accepted here.
+
+```json
+"user": {
+  "login": {
+    "name": "lead",
+    "settings": {
+      "identify": {
+        "map": {
+          "em": "data.email",
+          "external_id": "data.id"
+        }
+      }
+    },
+    "data": {
+      "map": { "lead_type": { "value": "login" } }
+    }
+  }
+}
+```
+
+Identity is diffed against the destination's runtime state —
+`pintrk('set', ...)` only fires when the resolved identity actually changes.
+Destination-level `settings.identify` is resolved lazily on the first event
+(init has no event to bind to), so `pintrk('load', tagId)` is called without an
+identity object.
+
+## Consent
+
+Pinterest is an advertising platform — the Pinterest Tag falls under
+**marketing** consent:
+
+```json
+"config": {
+  "consent": { "marketing": true }
+}
+```
+
+walkerOS's collector blocks all events to this destination until `marketing` is
+granted. **Pinterest has no `opt_in`/`opt_out` SDK API**, so the destination
+implements consent revocation as a runtime suppression flag:
+
+1. `on('consent')` reads `config.consent` to determine which keys to check.
+2. If any required key resolves to `false`, the destination flips
+   `_state.consentGranted = false` and silently suppresses all subsequent
+   `pintrk('track', ...)` calls.
+3. If consent is later re-granted (all required keys `true`), the flag flips
+   back and tracking resumes.
+
+The Pinterest Tag itself stays loaded throughout — only the walkerOS bridge goes
+silent.
+
+### Skipping a fully configured rule
+
+```json
+"user": {
+  "update": {
+    "skip": true,
+    "settings": {
+      "identify": {
+        "map": { "em": "data.email", "external_id": "data.id" }
+      }
+    }
+  }
+}
+```
+
+`mapping.skip: true` processes side effects (the `pintrk('set', ...)` identity
+update) but suppresses the default `pintrk('track', ...)` call. Useful when you
+only want to refresh enhanced matching without firing a conversion.
+
+## Future: Conversions API
+
+A server-side Pinterest Conversions API destination is planned as a follow-up,
+matching the Meta / TikTok / LinkedIn web+server split. It will share the
+`event_id` field with this web destination for cross-channel deduplication.
+
+## Related
+
+- [Pinterest Tag documentation](https://help.pinterest.com/en/business/article/install-the-pinterest-tag)
+- [Enhanced match documentation](https://help.pinterest.com/en/business/article/enhanced-match)
+- walkerOS
+  [understanding-destinations skill](https://www.walkeros.io/docs/destinations)
+
+## License
+
+MIT

package/dist/dev.d.mts

@@ -0,0 +1,239 @@
+import * as _walkeros_core_dev from '@walkeros/core/dev';
+import { z } from '@walkeros/core/dev';
+import { DestinationWeb } from '@walkeros/web-core';
+import { Flow } from '@walkeros/core';
+
+declare const SettingsSchema: z.ZodObject<{
+    apiKey: z.ZodString;
+    pageview: z.ZodOptional<z.ZodBoolean>;
+    identify: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strip>;
+type Settings = z.infer<typeof SettingsSchema>;
+
+declare const MappingSchema: z.ZodObject<{
+    identify: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strip>;
+type Mapping = z.infer<typeof MappingSchema>;
+
+declare const settings: _walkeros_core_dev.JSONSchema;
+declare const mapping: _walkeros_core_dev.JSONSchema;
+
+type index$1_Mapping = Mapping;
+declare const index$1_MappingSchema: typeof MappingSchema;
+type index$1_Settings = Settings;
+declare const index$1_SettingsSchema: typeof SettingsSchema;
+declare const index$1_mapping: typeof mapping;
+declare const index$1_settings: typeof settings;
+declare namespace index$1 {
+  export { type index$1_Mapping as Mapping, index$1_MappingSchema as MappingSchema, type index$1_Settings as Settings, index$1_SettingsSchema as SettingsSchema, index$1_mapping as mapping, index$1_settings as settings };
+}
+
+/**
+ * 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 };
+}
+
+declare const index_env: typeof env;
+declare const index_step: typeof step;
+declare namespace index {
+  export { index_env as env, index_step as step };
+}
+
+export { index as examples, index$1 as schemas };