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

package/dist/dev.d.ts

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