@walkeros/web-destination-tiktok 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,280 @@
+<p align="left">
+  <a href="https://www.walkeros.io">
+    <img alt="walkerOS" title="walkerOS" src="https://www.walkeros.io/img/walkerOS_logo.svg" width="256px"/>
+  </a>
+</p>
+
+# TikTok Pixel Destination for walkerOS
+
+[Source Code](https://github.com/elbwalker/walkerOS/tree/main/packages/web/destinations/tiktok)
+&bull;
+[NPM Package](https://www.npmjs.com/package/@walkeros/web-destination-tiktok)
+&bull; [Documentation](https://www.walkeros.io/docs/destinations/web/tiktok)
+
+This package forwards walkerOS events to the
+[TikTok Pixel](https://business-api.tiktok.com/portal/docs?id=1739585702922241)
+— conversion tracking and audience building for TikTok Ads. The destination
+wraps the standard TikTok Pixel snippet (loaded from
+`https://analytics.tiktok.com/i18n/pixel/events.js`); there is no npm SDK for
+the browser pixel.
+
+walkerOS follows a **source → collector → destination** architecture. This
+TikTok destination receives processed events from the walkerOS collector and
+forwards them as `ttq.track`, `ttq.identify`, and consent toggles via
+`ttq.enableCookie` / `ttq.disableCookie`.
+
+## Features
+
+- **Default event forwarding** — every walkerOS event becomes
+  `ttq.track(name, params, { event_id })`. The `event_id` is the walkerOS event
+  id, ready for deduplication with a server-side Events API destination.
+- **Standard event renaming** — `mapping.name` flips walkerOS event names
+  (`"product view"`) into TikTok's rigid 14-event taxonomy (`"ViewContent"`). An
+  exported `StandardEventNames` TypeScript union lights up IDE autocomplete;
+  arbitrary strings are still allowed for custom events.
+- **Advanced Matching** — destination-level + per-event `settings.identify`
+  resolving to `{ email, phone_number, external_id }`. Runtime state diffing
+  skips redundant `ttq.identify()` calls on unchanged values. The TikTok SDK
+  auto-hashes all values with SHA256 before sending.
+- **Custom event properties** — `settings.include` flattens walkerOS event
+  sections (`data`, `globals`, `user`, …) with prefixes (`data_id`, `user_id`,
+  …) onto the params object. Useful for custom events where TikTok won't
+  optimize anyway.
+- **Consent cookie toggling** — the `on('consent')` handler reads
+  `config.consent` and calls `ttq.enableCookie()` when all required consent keys
+  are granted, `ttq.disableCookie()` otherwise.
+- **No npm dependency** — TikTok ships only the script-tag snippet. The
+  destination injects the CDN tag via `addScript()` exactly like the Meta Pixel
+  destination.
+
+## Installation
+
+```sh
+npm install @walkeros/web-destination-tiktok
+```
+
+## Quick Start
+
+```typescript
+import { startFlow } from '@walkeros/collector';
+import { destinationTikTok } from '@walkeros/web-destination-tiktok';
+
+await startFlow({
+  consent: { marketing: false },
+  destinations: {
+    tiktok: {
+      code: destinationTikTok,
+      config: {
+        consent: { marketing: true },
+        settings: {
+          apiKey: 'C4XXXXXXXXXXXXXXXXXXX', // your TikTok Pixel ID
+        },
+      },
+    },
+  },
+});
+```
+
+## Configuration
+
+### Settings (destination-level)
+
+| Name               | Type            | Description                                                                                           | Required |
+| ------------------ | --------------- | ----------------------------------------------------------------------------------------------------- | -------- |
+| `apiKey`           | `string`        | TikTok Pixel ID — first argument to `ttq.load(...)`                                                   | Yes      |
+| `identify`         | `Mapping.Value` | Resolves to an Advanced Matching object (`email`, `phone_number`, `external_id`). SHA256 auto-hashed. | No       |
+| `include`          | `string[]`      | walkerOS event sections to flatten with prefix (`data` → `data_*`, `globals` → `globals_*`, …)        | No       |
+| `auto_config`      | `boolean`       | TikTok default `true`. Enable automatic form field detection for Advanced Matching                    | No       |
+| `limited_data_use` | `boolean`       | TikTok default `false`. Restrict data use under U.S. state privacy laws                               | No       |
+
+Any additional snake_case TikTok Pixel init option (passthrough) is forwarded to
+`ttq.load(apiKey, options)` unchanged.
+
+### Mapping (`rule.settings`)
+
+| Name       | Type            | Description                                                              |
+| ---------- | --------------- | ------------------------------------------------------------------------ |
+| `identify` | `Mapping.Value` | Per-event Advanced Matching override. Same shape as `settings.identify`. |
+| `include`  | `string[]`      | Replaces destination-level `include` for this rule.                      |
+
+`mapping.name` (the walkerOS-standard event-rename mechanism) flips the walkerOS
+event name into TikTok's standard event taxonomy.
+
+## Standard Events
+
+TikTok recognizes 14 standard events for ad optimization. Use `mapping.name` to
+flip walkerOS event names into the rigid taxonomy:
+
+| TikTok name            | When to use                                    |
+| ---------------------- | ---------------------------------------------- |
+| `ViewContent`          | Product / content detail view                  |
+| `ClickButton`          | Generic CTA click                              |
+| `Search`               | Site search                                    |
+| `AddToWishlist`        | Item added to a wishlist                       |
+| `AddToCart`            | Item added to cart                             |
+| `InitiateCheckout`     | User started checkout                          |
+| `AddPaymentInfo`       | Payment details entered                        |
+| `CompletePayment`      | Order successfully placed (primary conversion) |
+| `PlaceAnOrder`         | Order placed (alternative)                     |
+| `Contact`              | Lead / contact form                            |
+| `Download`             | Asset download                                 |
+| `SubmitForm`           | Generic form submission                        |
+| `CompleteRegistration` | User signup                                    |
+| `Subscribe`            | Subscription start                             |
+
+Custom event names (any string not in the list) are still tracked but receive no
+optimization signal.
+
+## Custom Event Properties
+
+Two ways to attach custom params to a `ttq.track()` call:
+
+```typescript
+// 1. Flatten walkerOS sections with settings.include
+config: {
+  settings: {
+    apiKey: 'C4XXXXXXXXXXXXXXXXXXX',
+    include: ['data', 'user'], // → data_*, user_* params on every event
+  },
+}
+
+// 2. Explicit per-event params via mapping.data (the canonical pattern)
+mapping: {
+  product: {
+    view: {
+      name: 'ViewContent',
+      data: {
+        map: {
+          content_type: { value: 'product' },
+          content_id: 'data.id',
+          content_name: 'data.name',
+          value: 'data.price',
+          currency: { key: 'data.currency', value: 'EUR' },
+        },
+      },
+    },
+  },
+}
+```
+
+When a rule sets `mapping.data`, the resolved object is the params object —
+`settings.include` is bypassed for that call. Set
+`mapping.settings.include = []` to ensure no prefixed properties leak in.
+
+## Advanced Matching
+
+TikTok matches conversions back to TikTok users via three optional parameters:
+`email`, `phone_number`, `external_id`. The SDK hashes them with SHA256 before
+sending, so it's safe to pass raw values.
+
+```typescript
+// Destination-level — fires on first push, then re-fires only when the
+// resolved value changes (runtime state diffing)
+config: {
+  settings: {
+    apiKey: 'C4XXXXXXXXXXXXXXXXXXX',
+    identify: {
+      map: {
+        email: 'user.email',
+        phone_number: 'user.phone',
+        external_id: 'user.id',
+      },
+    },
+  },
+}
+
+// Per-event — overrides destination-level for one push (e.g. signup form)
+mapping: {
+  user: {
+    register: {
+      name: 'CompleteRegistration',
+      settings: {
+        identify: {
+          map: {
+            email: 'data.email',
+            phone_number: 'data.phone',
+            external_id: 'data.user_id',
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+`ttq.identify()` always fires **before** `ttq.track()` so Advanced Matching is
+set for the conversion event.
+
+## Ecommerce — `CompletePayment`
+
+The hero example. `mapping.data` builds the TikTok-native shape; `loop` walks
+`event.nested` to produce the `contents` array; `{ key, value: 'EUR' }` provides
+a fallback currency.
+
+```typescript
+mapping: {
+  order: {
+    complete: {
+      name: 'CompletePayment',
+      data: {
+        map: {
+          content_type: { value: 'product' },
+          value: 'data.total',
+          currency: { key: 'data.currency', value: 'EUR' },
+          order_id: 'data.id',
+          contents: {
+            loop: [
+              'nested',
+              {
+                map: {
+                  content_id: 'data.id',
+                  content_name: 'data.name',
+                  quantity: { key: 'data.quantity', value: 1 },
+                  price: 'data.price',
+                },
+              },
+            ],
+          },
+        },
+      },
+      settings: { include: [] },
+    },
+  },
+}
+```
+
+## Consent
+
+TikTok is an advertising platform — the typical walkerOS consent key is
+`marketing` (whatever name your CMP reports). The walkerOS `config.consent` gate
+blocks unconsented events from reaching the destination in the first place; the
+destination's `on('consent')` handler then toggles TikTok's own cookie state for
+attribution.
+
+```typescript
+config: {
+  consent: { marketing: true },
+  settings: { apiKey: 'C4XXXXXXXXXXXXXXXXXXX' },
+}
+```
+
+The handler iterates every key in `config.consent` and calls
+`ttq.enableCookie()` only when **all** required keys are granted. Otherwise it
+calls `ttq.disableCookie()`. This is the conservative semantic that matches
+walkerOS's gating model.
+
+> TikTok's SDK auto-fires `ttq.page()` once on load. The destination has no knob
+> to suppress it — letting the auto page view fire is the expected behavior. If
+> you need fine-grained page-view control, gate the destination behind a
+> transformer.
+
+## Contribute
+
+Feel free to contribute by submitting an
+[issue](https://github.com/elbwalker/walkerOS/issues), starting a
+[discussion](https://github.com/elbwalker/walkerOS/discussions), or getting in
+[contact](https://calendly.com/elb-alexander/30min).
+
+## License
+
+This project is licensed under the MIT License.

package/dist/dev.d.mts

@@ -0,0 +1,266 @@
+import * as _walkeros_core_dev from '@walkeros/core/dev';
+import { z } from '@walkeros/core/dev';
+import { Mapping as Mapping$1, Flow } from '@walkeros/core';
+import { DestinationWeb } from '@walkeros/web-core';
+
+declare const SettingsSchema: z.ZodObject<{
+    apiKey: z.ZodString;
+    auto_config: z.ZodOptional<z.ZodBoolean>;
+    limited_data_use: z.ZodOptional<z.ZodBoolean>;
+    identify: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strip>;
+type Settings$1 = 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;
+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 Settings$1 as Settings, index$1_SettingsSchema as SettingsSchema, index$1_mapping as mapping, index$1_settings as settings };
+}
+
+/**
+ * Settings (destination-level).
+ *
+ * apiKey is the TikTok Pixel ID. `identify` resolves to Advanced Matching
+ * parameters (email, phone_number, external_id) — TikTok auto-hashes these
+ * before sending, so raw values are safe. `include` names walkerOS event
+ * sections to flatten into prefixed TikTok event parameters. All other
+ * TikTok-native snake_case options (e.g., `auto_config`, `limited_data_use`)
+ * are passed through to `ttq.load(apiKey, options)`.
+ */
+interface Settings {
+    /** TikTok Pixel ID — first argument to ttq.load(...). Required. */
+    apiKey: string;
+    /**
+     * walkerOS mapping value resolving to an Advanced Matching object with any
+     * of: `email`, `phone_number`, `external_id`. Applied on first push and
+     * re-fired only on change (runtime state in _state.lastIdentity).
+     */
+    identify?: Mapping$1.Value;
+    /** TikTok default: true. Enable auto-detection of form fields for Advanced Matching. */
+    auto_config?: boolean;
+    /** TikTok default: false. Restrict data use under U.S. state privacy laws. */
+    limited_data_use?: boolean;
+    /**
+     * Runtime state — populated by init() and mutated by push(). Not
+     * user-facing. Stores last-resolved identity so subsequent pushes with
+     * unchanged values skip redundant ttq.identify() calls.
+     */
+    _state?: RuntimeState;
+    /**
+     * Pass-through bucket: any additional TikTok Pixel init config (snake_case
+     * keys per TikTok's docs). Merged into ttq.load()'s second argument.
+     */
+    [key: string]: unknown;
+}
+interface RuntimeState {
+    lastIdentity?: {
+        email?: string;
+        phone_number?: string;
+        external_id?: string;
+    };
+}
+/**
+ * Advanced Matching parameter shape — what settings.identify must resolve to.
+ * All fields are optional; if the resolved object has no non-empty values,
+ * the destination skips the ttq.identify() call entirely.
+ */
+interface IdentifyParams {
+    email?: string;
+    phone_number?: string;
+    external_id?: string;
+}
+/**
+ * Minimal surface of TikTok's window.ttq this destination uses. Tests mock
+ * this by attaching a plain object to env.window.ttq; production uses the
+ * real SDK created by the snippet setup() call.
+ */
+interface TTQ {
+    (...args: unknown[]): void;
+    load: (pixelId: string, config?: Record<string, unknown>) => void;
+    page: () => void;
+    track: (event: string, params?: Record<string, unknown>, options?: {
+        event_id?: string;
+    }) => void;
+    identify: (params: IdentifyParams) => void;
+    enableCookie: () => void;
+    disableCookie: () => void;
+    /** Queue-based pattern — snippet sets this; destination does not read it. */
+    methods?: string[];
+    /** Internal queue populated before the CDN SDK loads. */
+    _i?: Record<string, unknown>;
+    /** Flag the snippet sets after the real SDK loads. */
+    loaded?: boolean;
+}
+/**
+ * Env — the destination reads `window.ttq` via getEnv(env). Tests attach
+ * a mock ttq to env.window; production reads window.ttq created by the
+ * SDK snippet.
+ */
+interface Env extends DestinationWeb.Env {
+    window: {
+        ttq: TTQ;
+    };
+    document: {
+        createElement: (tagName: string) => Element;
+        head: {
+            appendChild: (node: unknown) => void;
+        };
+    };
+}
+
+/**
+ * Pre-init env — destination init() call will set up ttq and load the
+ * script. Tests receive this as a starting point.
+ */
+declare const init: Env;
+/**
+ * Post-init env — same shape; the test runner clones this and replaces
+ * individual ttq methods with jest.fn() so it can assert on 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 };
+}
+
+/**
+ * Examples may optionally carry destination-level settings. The test
+ * runner reads `settings` from the example and merges it into the base
+ * destination settings on top of the fixed apiKey.
+ */
+type TikTokStepExample = Flow.StepExample & {
+    settings?: Partial<Settings>;
+    configInclude?: string[];
+};
+/**
+ * Default event forwarding — every walkerOS event becomes a ttq.track()
+ * call. With no mapping and no destination-level include, the params
+ * object is empty. event_id is always passed as the 3rd argument (TikTok
+ * dedup between pixel and Events API).
+ *
+ * NOTE: The raw walkerOS event name "product view" (with space) is NOT a
+ * TikTok standard event. Without a mapping.name override, TikTok treats
+ * it as a custom event — functional for audience building, no
+ * optimization. The next example shows the recommended override.
+ */
+declare const defaultEventForwarding: TikTokStepExample;
+/**
+ * Wildcard ignore — walkerOS's standard way to drop events. The rule
+ * matches but does nothing. The destination fires zero SDK calls.
+ */
+declare const wildcardIgnored: TikTokStepExample;
+/**
+ * The canonical TikTok pattern: walkerOS "product view" → TikTok
+ * "ViewContent" via mapping.name. mapping.data builds the TikTok-native
+ * parameter shape (content_type, content_id, content_name, value,
+ * currency). include is explicitly set to [] so prefixed walkerOS
+ * properties don't leak onto the call and confuse TikTok's matcher.
+ */
+declare const productViewContent: TikTokStepExample;
+/**
+ * Destination-level settings.include flattens the walkerOS `data` section
+ * into prefixed TikTok event parameters on every push. This is the
+ * "dump everything" mode — useful for custom events where TikTok won't
+ * do optimization anyway, and no mapping.data is needed.
+ */
+declare const destinationLevelInclude: TikTokStepExample;
+/**
+ * Per-rule settings.include REPLACES destination-level include for the
+ * matched rule (design doc §6: mapping-level include replaces, not
+ * merges with, destination-level include).
+ */
+declare const ruleIncludeReplaces: TikTokStepExample;
+/**
+ * Destination-level settings.identify fires on the first push (once the
+ * state cache is empty). Advanced Matching parameters (email,
+ * phone_number, external_id) are passed to ttq.identify() which
+ * auto-hashes them SHA256 before sending. Subsequent pushes with
+ * unchanged values do NOT re-fire ttq.identify() — runtime state tracks
+ * the last-resolved identity.
+ *
+ * walkerOS's default user fixture has user.id='us3r' and no email/phone,
+ * so the example injects data and maps from there.
+ */
+declare const destinationLevelIdentify: TikTokStepExample;
+/**
+ * User registration → CompleteRegistration standard event with per-event
+ * identify. The user just provided their email + phone, so this is the
+ * moment to fire Advanced Matching for this session. The per-event
+ * identify overrides any destination-level identify for this one push.
+ */
+declare const userRegisterCompleteRegistration: TikTokStepExample;
+/**
+ * Multi-product order → CompletePayment standard event. The canonical
+ * TikTok ecommerce pattern:
+ *  - mapping.name flips the walkerOS event to TikTok's rigid taxonomy
+ *  - mapping.data builds the TikTok-native parameter shape
+ *  - loop iterates event.nested to produce the `contents` array, one
+ *    entry per product
+ *  - { key, value: 'EUR' } provides a currency fallback if data.currency
+ *    is absent (here data.currency is 'EUR' so the key wins)
+ *
+ * The default "order complete" fixture has 3 nested entries: two
+ * products (ers, cc) and one gift (Surprise — no id, no price).
+ */
+declare const orderCompleteCompletePayment: TikTokStepExample;
+/**
+ * Search → TikTok Search standard event. Minimal example that shows how
+ * a walkerOS search event flips through mapping.name with a single
+ * mapping.data field (the query string).
+ */
+declare const searchSubmitSearch: TikTokStepExample;
+/**
+ * Consent granted → ttq.enableCookie(). The destination checks the
+ * consent keys declared in config.consent (here "marketing" — TikTok is
+ * an ad platform, not analytics) and toggles cookie behavior.
+ *
+ * Uses the canonical StepExample.command='consent' pattern: the test
+ * runner dispatches via elb('walker consent', in) instead of pushing
+ * an event.
+ */
+declare const consentGrantEnableCookie: TikTokStepExample;
+/**
+ * Consent revoked → ttq.disableCookie(). TikTok stops setting and
+ * reading its first-party cookie (_ttp) for attribution.
+ */
+declare const consentRevokeDisableCookie: TikTokStepExample;
+
+type step_TikTokStepExample = TikTokStepExample;
+declare const step_consentGrantEnableCookie: typeof consentGrantEnableCookie;
+declare const step_consentRevokeDisableCookie: typeof consentRevokeDisableCookie;
+declare const step_defaultEventForwarding: typeof defaultEventForwarding;
+declare const step_destinationLevelIdentify: typeof destinationLevelIdentify;
+declare const step_destinationLevelInclude: typeof destinationLevelInclude;
+declare const step_orderCompleteCompletePayment: typeof orderCompleteCompletePayment;
+declare const step_productViewContent: typeof productViewContent;
+declare const step_ruleIncludeReplaces: typeof ruleIncludeReplaces;
+declare const step_searchSubmitSearch: typeof searchSubmitSearch;
+declare const step_userRegisterCompleteRegistration: typeof userRegisterCompleteRegistration;
+declare const step_wildcardIgnored: typeof wildcardIgnored;
+declare namespace step {
+  export { type step_TikTokStepExample as TikTokStepExample, step_consentGrantEnableCookie as consentGrantEnableCookie, step_consentRevokeDisableCookie as consentRevokeDisableCookie, step_defaultEventForwarding as defaultEventForwarding, step_destinationLevelIdentify as destinationLevelIdentify, step_destinationLevelInclude as destinationLevelInclude, step_orderCompleteCompletePayment as orderCompleteCompletePayment, step_productViewContent as productViewContent, step_ruleIncludeReplaces as ruleIncludeReplaces, step_searchSubmitSearch as searchSubmitSearch, step_userRegisterCompleteRegistration as userRegisterCompleteRegistration, 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 };