@c15t/scripts 2.0.1 → 2.2.0-canary-20260727202135

package/dist-types/{microsoft-uet.d.ts → vendors/ads-and-pixels/microsoft-uet.d.ts}

@@ -7,64 +7,74 @@ declare global {
 /**
  * Microsoft UET vendor manifest.
  *
- * Uses structured startup steps and manages consent via the UET push API:
- * `window.uetq.push('consent', 'default'|'update', { ad_storage: 'granted'|'denied' })`
+ * Loads in consent mode and manages consent via the UET push API:
+ * `window.uetq.push('consent', 'default'|'update', consentState)`.
  */
 export declare const microsoftUetManifest: {
-    readonly vendor: "microsoft-uet";
-    readonly category: "marketing";
+    readonly kind: "c15t.vendor-manifest";
+    readonly schemaVersion: 1;
+    readonly vendor: 'microsoft-uet';
+    readonly category: 'marketing';
+    readonly alwaysLoad: true;
     readonly persistAfterConsentRevoked: true;
     readonly bootstrap: [{
-        readonly type: "setGlobal";
-        readonly name: "uetq";
+        readonly type: 'setGlobal';
+        readonly name: 'uetq';
         readonly value: readonly [];
         readonly ifUndefined: true;
     }];
+    readonly onBeforeLoadGranted: [{
+        readonly type: 'callGlobal';
+        readonly global: 'uetq';
+        readonly method: 'push';
+        readonly args: ["consent", "default", {
+            readonly ad_storage: 'granted';
+        }];
+    }];
+    readonly onBeforeLoadDenied: [{
+        readonly type: 'callGlobal';
+        readonly global: 'uetq';
+        readonly method: 'push';
+        readonly args: ["consent", "default", {
+            readonly ad_storage: 'denied';
+        }];
+    }];
     readonly install: [{
-        readonly type: "loadScript";
-        readonly src: "{{scriptSrc}}";
+        readonly type: 'loadScript';
+        readonly src: '{{scriptSrc}}';
         readonly async: true;
     }];
     readonly afterLoad: [{
-        readonly type: "constructGlobal";
-        readonly constructor: "UET";
-        readonly assignTo: "uetq";
+        readonly type: 'constructGlobal';
+        readonly constructor: 'UET';
+        readonly assignTo: 'uetq';
         readonly args: [{
-            readonly ti: "{{id}}";
+            readonly ti: '{{id}}';
             readonly enableAutoSpaTracking: true;
         }];
-        readonly copyAssignedValueToArgProperty: "q";
+        readonly copyAssignedValueToArgProperty: 'q';
     }, {
-        readonly type: "callGlobal";
-        readonly global: "uetq";
-        readonly method: "push";
+        readonly type: 'callGlobal';
+        readonly global: 'uetq';
+        readonly method: 'push';
         readonly args: ["pageLoad"];
-    }, {
-        readonly type: "callGlobal";
-        readonly global: "uetq";
-        readonly method: "push";
-        readonly args: ["consent", "default", {
-            readonly ad_storage: "granted";
-        }];
     }];
     readonly onConsentGranted: [{
-        readonly type: "callGlobal";
-        readonly global: "uetq";
-        readonly method: "push";
+        readonly type: 'callGlobal';
+        readonly global: 'uetq';
+        readonly method: 'push';
         readonly args: ["consent", "update", {
-            readonly ad_storage: "granted";
+            readonly ad_storage: 'granted';
         }];
     }];
     readonly onConsentDenied: [{
-        readonly type: "callGlobal";
-        readonly global: "uetq";
-        readonly method: "push";
+        readonly type: 'callGlobal';
+        readonly global: 'uetq';
+        readonly method: 'push';
         readonly args: ["consent", "update", {
-            readonly ad_storage: "denied";
+            readonly ad_storage: 'denied';
         }];
     }];
-    readonly kind: "c15t.vendor-manifest";
-    readonly schemaVersion: 1;
 };
 export interface MicrosoftUetOptions {
     /**
@@ -77,7 +87,8 @@ export interface MicrosoftUetOptions {
 }
 /**
  * Microsoft UET Script
- * This script is persistent after consent is revoked because it has built-in functionality to opt into and out of tracking based on consent, which allows us to not need to load the script again when consent is revoked.
+ * This script loads in consent mode and stays persistent because UET can opt
+ * into and out of tracking based on consent.
  *
  * @param options - The options for the Microsoft UET script
  * @returns The Microsoft UET script configuration

package/dist-types/vendors/ads-and-pixels/reddit-pixel.d.ts

@@ -0,0 +1,211 @@
+import type { Script } from 'c15t';
+/**
+ * Reddit Pixel standard conversion event names.
+ *
+ * @see {@link https://business.reddithelp.com/s/article/supported-conversion-events | Reddit supported conversion events}
+ */
+export type RedditPixelEventName = 'PageVisit' | 'ViewContent' | 'Search' | 'AddToCart' | 'AddToWishlist' | 'Purchase' | 'Lead' | 'SignUp';
+/**
+ * Controls Reddit Pixel automatic advanced matching signals.
+ *
+ * @see {@link https://business.reddithelp.com/s/article/reddit-pixel | Reddit Pixel setup}
+ */
+export interface RedditPixelAdvancedMatchingOptions {
+    /** Automatically scan page content for email addresses. */
+    email?: boolean;
+    /** Automatically scan page content for phone numbers. */
+    phone_number?: boolean;
+}
+/**
+ * Reddit Pixel initialization options.
+ *
+ * @see {@link https://business.reddithelp.com/s/article/reddit-pixel | Reddit Pixel setup}
+ * @see {@link https://business.reddithelp.com/s/article/Limited-Data-Use | Reddit Limited Data Use}
+ */
+export interface RedditPixelInitOptions {
+    /**
+     * Opt the user out of Reddit Pixel tracking.
+     *
+     * Reddit sends this as `opt_out=1` on pixel requests.
+     */
+    optOut?: boolean;
+    /**
+     * Disable Reddit first-party cookies during initialization.
+     */
+    disableFirstPartyCookies?: boolean;
+    /** Email address or SHA-256 email hash for attribution matching. */
+    email?: string;
+    /** Phone number or SHA-256 phone hash for attribution matching. */
+    phoneNumber?: string;
+    /** External user identifier or SHA-256 hash for attribution matching. */
+    externalId?: string;
+    /** Android Advertising ID or SHA-256 hash. */
+    aaid?: string;
+    /** iOS Identifier for Advertisers or SHA-256 hash. */
+    idfa?: string;
+    /** Automatic advanced matching controls. */
+    aam?: RedditPixelAdvancedMatchingOptions;
+    /**
+     * Data processing mode, including Reddit Limited Data Use values.
+     *
+     * @see {@link https://business.reddithelp.com/s/article/Limited-Data-Use | Reddit Limited Data Use}
+     */
+    dpm?: string | string[];
+    /**
+     * Data processing country code.
+     *
+     * @see {@link https://business.reddithelp.com/s/article/Limited-Data-Use | Reddit Limited Data Use}
+     */
+    dpcc?: string;
+    /**
+     * Data processing region code.
+     *
+     * @see {@link https://business.reddithelp.com/s/article/Limited-Data-Use | Reddit Limited Data Use}
+     */
+    dprc?: string;
+    /** Integration partner name. */
+    partner?: string;
+    /** Integration partner version. */
+    partner_version?: string;
+    /** Source integration name reported to Reddit. */
+    integration?: 'reddit' | 'gtm' | (string & {});
+    /** Enable Reddit Pixel debug logging. */
+    debug?: boolean;
+    /**
+     * Send monetary `value` metadata as `valueDecimal`.
+     *
+     * @default true
+     */
+    useDecimalCurrencyValues?: boolean;
+    [key: string]: unknown;
+}
+/**
+ * Metadata supported by Reddit Pixel conversion events.
+ *
+ * @see {@link https://business.reddithelp.com/s/article/about-event-metadata | Reddit event metadata}
+ * @see {@link https://business.reddithelp.com/s/article/manual-conversion-events-with-the-reddit-pixel | Reddit manual conversion events}
+ */
+export interface RedditPixelEventMetadata {
+    itemCount?: number | string;
+    value?: number | string;
+    valueDecimal?: number | string;
+    currency?: string;
+    transactionId?: string;
+    customEventName?: string;
+    products?: string | Array<{
+        id?: string | number;
+        name?: string;
+        category?: string;
+        quantity?: number | string;
+        itemPrice?: number | string;
+    }>;
+    /**
+     * Conversion ID used to deduplicate Pixel events against Conversions API
+     * events.
+     *
+     * @see {@link https://business.reddithelp.com/s/article/event-deduplication | Reddit event deduplication}
+     */
+    conversionId?: string;
+    [key: string]: unknown;
+}
+type RedditPixelFunction = {
+    (command: 'init', pixelId: string, options?: RedditPixelInitOptions): void;
+    (command: 'enableFirstPartyCookies'): void;
+    (command: 'disableFirstPartyCookies'): void;
+    (command: 'track', eventName: RedditPixelEventName | (string & {}), properties?: RedditPixelEventMetadata): void;
+    (command: string, ...args: unknown[]): void;
+};
+declare global {
+    interface Window {
+        rdt?: RedditPixelFunction & {
+            callQueue?: unknown[][];
+            sendEvent?: (...args: unknown[]) => void;
+        };
+    }
+}
+/**
+ * Reddit Pixel vendor manifest.
+ *
+ * Sets up Reddit's queue stub and optionally queues the standard page visit
+ * event before the external bundle loads.
+ */
+export declare const redditPixelManifest: {
+    readonly kind: "c15t.vendor-manifest";
+    readonly schemaVersion: 1;
+    readonly vendor: 'reddit-pixel';
+    readonly category: 'marketing';
+    readonly persistAfterConsentRevoked: true;
+    readonly bootstrap: [{
+        readonly type: 'defineStubFunction';
+        readonly name: 'rdt';
+        readonly queue: {
+            readonly property: 'callQueue';
+        };
+        readonly dispatchProperty: 'sendEvent';
+        readonly queueFormat: 'array';
+        readonly ifUndefined: true;
+    }];
+    readonly install: [{
+        readonly type: 'callGlobal';
+        readonly global: 'rdt';
+        readonly args: ["init", "{{pixelId}}"];
+    }, {
+        readonly type: 'callGlobal';
+        readonly global: 'rdt';
+        readonly args: ["track", "PageVisit"];
+    }, {
+        readonly type: 'loadScript';
+        readonly src: '{{scriptUrl}}';
+        readonly async: true;
+    }];
+    readonly onConsentGranted: [{
+        readonly type: 'callGlobal';
+        readonly global: 'rdt';
+        readonly args: ["enableFirstPartyCookies"];
+    }];
+    readonly onConsentDenied: [{
+        readonly type: 'callGlobal';
+        readonly global: 'rdt';
+        readonly args: ["disableFirstPartyCookies"];
+    }];
+};
+export interface RedditPixelOptions {
+    /**
+     * Your Reddit Pixel ID.
+     * @example `t2_abcdef`
+     */
+    pixelId: string;
+    /**
+     * Queue the standard `PageVisit` event during setup.
+     * @default true
+     */
+    trackPageVisit?: boolean;
+    /**
+     * Optional payload passed as the third argument to `rdt('init', ...)`.
+     */
+    initOptions?: RedditPixelInitOptions;
+    /**
+     * Disable Reddit first-party cookies during setup.
+     *
+     * This is merged into `initOptions.disableFirstPartyCookies`.
+     */
+    disableFirstPartyCookies?: boolean;
+    /** Reddit Pixel loader URL. */
+    scriptUrl?: string;
+}
+/**
+ * Creates a Reddit Pixel script.
+ *
+ * @param options - The options for the Reddit Pixel script.
+ * @returns The Reddit Pixel script configuration.
+ */
+export declare function redditPixel({ pixelId, trackPageVisit, initOptions, disableFirstPartyCookies, scriptUrl, }: RedditPixelOptions): Script;
+/**
+ * Tracks a Reddit Pixel event.
+ *
+ * @param eventName - Reddit standard event name or a custom event name.
+ * @param metadata - Optional event metadata, including `conversionId` for
+ * Pixel plus Conversions API deduplication.
+ */
+export declare const redditPixelEvent: (eventName: RedditPixelEventName | (string & {}), metadata?: RedditPixelEventMetadata) => void;
+export {};

package/dist-types/vendors/ads-and-pixels/snapchat-pixel.d.ts

@@ -0,0 +1,171 @@
+import type { Script } from 'c15t';
+export type SnapchatPixelEventName = 'PAGE_VIEW' | 'VIEW_CONTENT' | 'ADD_CART' | 'PURCHASE' | 'SIGN_UP' | 'SAVE' | 'START_CHECKOUT' | 'APP_OPEN' | 'ADD_BILLING' | 'SEARCH' | 'SUBSCRIBE' | 'AD_CLICK' | 'AD_VIEW' | 'COMPLETE_TUTORIAL' | 'LEVEL_COMPLETE' | 'INVITE' | 'LOGIN' | 'SHARE' | 'RESERVE' | 'ACHIEVEMENT_UNLOCKED' | 'ADD_TO_WISHLIST' | 'SPENT_CREDITS' | 'RATE' | 'START_TRIAL' | 'LIST_VIEW';
+export interface SnapchatPixelEventProperties {
+    /** Total monetary value for commerce events such as `PURCHASE`. */
+    price?: number;
+    /**
+     * Event identifier used to deduplicate browser Pixel events against
+     * server-side Conversions API events.
+     */
+    client_dedup_id?: string;
+    /** ISO 4217 currency code, for example `USD`. */
+    currency?: string;
+    /** Transaction/order identifier for purchase events. */
+    transaction_id?: string;
+    /** Product, SKU, or content identifiers associated with the event. */
+    item_ids?: string[];
+    /** Product or content category associated with the event. */
+    item_category?: string;
+    /** Free-form description for the event. */
+    description?: string;
+    /** Query text for `SEARCH` events. */
+    search_string?: string;
+    /** Number of items represented by the event. */
+    number_items?: number;
+    /** Whether payment information was available, represented as `0` or `1`. */
+    payment_info_available?: 0 | 1;
+    /** Signup method for `SIGN_UP` events. */
+    sign_up_method?: string;
+    /** Whether the action succeeded, represented as `0` or `1`. */
+    success?: 0 | 1;
+    /** Brand names associated with the event contents. */
+    brands?: string[];
+    /** Fulfillment method for commerce events. */
+    delivery_method?: 'in_store' | 'curbside' | 'delivery';
+    /** Customer lifecycle status associated with the event. */
+    customer_status?: 'new' | 'returning' | 'reactivated';
+    /** Optional custom tag for event segmentation in Snapchat. */
+    event_tag?: string;
+    [key: string]: unknown;
+}
+type SnapchatPixelFunction = {
+    (command: 'track', eventName: SnapchatPixelEventName | (string & {}), properties?: SnapchatPixelEventProperties): void;
+    (command: 'init', pixelId: string, config?: Record<string, unknown>): void;
+    (command: string, ...args: unknown[]): void;
+};
+declare global {
+    interface Window {
+        snaptr?: SnapchatPixelFunction & {
+            handleRequest?: (...args: unknown[]) => void;
+            loaded?: boolean;
+            push?: Window['snaptr'];
+            queue?: unknown[][];
+            version?: string;
+        };
+        _snaptr?: Window['snaptr'];
+    }
+}
+/**
+ * Snapchat Pixel vendor manifest.
+ *
+ * Uses a structured queue stub and queues `init` plus an optional
+ * `PAGE_VIEW` event before the vendor bundle loads.
+ */
+export declare const snapchatPixelManifest: {
+    readonly kind: "c15t.vendor-manifest";
+    readonly schemaVersion: 1;
+    readonly vendor: 'snapchat-pixel';
+    readonly category: 'marketing';
+    readonly bootstrap: [{
+        readonly type: 'defineStubFunction';
+        readonly name: 'snaptr';
+        readonly queue: {
+            readonly property: 'queue';
+        };
+        readonly dispatchProperty: 'handleRequest';
+        readonly queueFormat: 'array';
+        readonly aliases: ["_snaptr"];
+        readonly selfReferences: ["push"];
+        readonly properties: {
+            readonly loaded: true;
+            readonly version: '1.0';
+        };
+        readonly ifUndefined: true;
+    }];
+    readonly install: [{
+        readonly type: 'callGlobal';
+        readonly global: 'snaptr';
+        readonly args: ["init", "{{pixelId}}"];
+    }, {
+        readonly type: 'callGlobal';
+        readonly global: 'snaptr';
+        readonly args: ["track", "PAGE_VIEW"];
+    }, {
+        readonly type: 'loadScript';
+        readonly src: '{{scriptUrl}}';
+        readonly async: true;
+    }];
+};
+export interface SnapchatPixelOptions {
+    /**
+     * Your Snapchat Pixel ID.
+     * @example `123456789012345`
+     */
+    pixelId: string;
+    /** Optional init payload passed to `snaptr('init', ...)`. */
+    initOptions?: Record<string, unknown>;
+    /**
+     * Queue the default `PAGE_VIEW` event during setup.
+     * @default true
+     */
+    trackPageView?: boolean;
+    /** Snapchat Pixel loader URL. */
+    scriptUrl?: string;
+}
+/**
+ * Creates a Snapchat Pixel script.
+ *
+ * @param options.pixelId - Snapchat Pixel ID used in `snaptr('init', ...)`.
+ *   Expected format is a numeric string (commonly 15 digits), for example
+ *   `'123456789012345'`. This value is required and should come directly from
+ *   Snapchat Ads Manager.
+ * @param options.initOptions - Optional object passed as the third argument to
+ *   `snaptr('init', pixelId, initOptions)`, for advanced initialization values.
+ *   Example: `{ user_email: 'user@example.com', user_phone_number: '+15551234567' }`.
+ * @param options.trackPageView - Whether to queue the default
+ *   `snaptr('track', 'PAGE_VIEW')` call during setup. Defaults to `true`; set to
+ *   `false` when you want to control page-view tracking manually.
+ * @returns A resolved c15t `Script` configuration that defines the Snapchat
+ *   queue stub, runs `init` (and optionally `PAGE_VIEW`), and then loads the
+ *   Snapchat SDK script URL.
+ * @throws `resolveManifest` may throw when required placeholders cannot be
+ *   resolved (for example, when `pixelId` is missing/empty) or when provided
+ *   manifest values are invalid for interpolation.
+ *
+ * Edge cases:
+ * - Missing `pixelId` causes manifest resolution to fail.
+ * - Non-numeric or malformed `pixelId` values may initialize incorrectly in
+ *   Snapchat even if local script construction succeeds.
+ *
+ * @example
+ * ```ts
+ * const script = snapchatPixel({
+ * 	pixelId: '123456789012345',
+ * 	initOptions: {
+ * 		user_email: 'user@example.com',
+ * 		user_phone_number: '+15551234567',
+ * 	},
+ * 	trackPageView: false,
+ * });
+ * ```
+ */
+export declare function snapchatPixel({ pixelId, initOptions, trackPageView, scriptUrl, }: SnapchatPixelOptions): Script;
+/**
+ * Tracks a Snapchat Pixel event.
+ *
+ * @param eventName - Snapchat standard event name or a custom event name.
+ * @param properties - Optional event properties, including
+ *   `client_dedup_id` for Pixel plus Conversions API deduplication.
+ *
+ * @example
+ * ```ts
+ * snapchatPixelEvent('PURCHASE', {
+ * 	price: 99,
+ * 	currency: 'USD',
+ * 	transaction_id: 'order-123',
+ * 	client_dedup_id: 'event-123',
+ * });
+ * ```
+ */
+export declare const snapchatPixelEvent: (eventName: SnapchatPixelEventName | (string & {}), properties?: SnapchatPixelEventProperties) => void;
+export {};

package/dist-types/{tiktok-pixel.d.ts → vendors/ads-and-pixels/tiktok-pixel.d.ts}

@@ -1,11 +1,25 @@
 import type { Script } from 'c15t';
+interface TikTokPixelFunction {
+    grantConsent: () => void;
+    revokeConsent: () => void;
+    page: () => void;
+    track: (eventName: string, properties?: Record<string, unknown>) => void;
+    identify: (properties?: Record<string, unknown>) => void;
+    instances: (...args: unknown[]) => void;
+    debug: (...args: unknown[]) => void;
+    on: (...args: unknown[]) => void;
+    off: (...args: unknown[]) => void;
+    once: (...args: unknown[]) => void;
+    ready: (...args: unknown[]) => void;
+    alias: (...args: unknown[]) => void;
+    group: (...args: unknown[]) => void;
+    enableCookie: (...args: unknown[]) => void;
+    disableCookie: (...args: unknown[]) => void;
+    holdConsent: (...args: unknown[]) => void;
+}
 declare global {
     interface Window {
-        ttq: {
-            grantConsent: () => void;
-            revokeConsent: () => void;
-            page: () => void;
-        };
+        ttq: TikTokPixelFunction;
     }
 }
 /**
@@ -15,53 +29,53 @@ declare global {
  * via `ttq.grantConsent()` / `ttq.revokeConsent()`.
  */
 export declare const tiktokPixelManifest: {
-    readonly vendor: "tiktok-pixel";
-    readonly category: "marketing";
+    readonly kind: "c15t.vendor-manifest";
+    readonly schemaVersion: 1;
+    readonly vendor: 'tiktok-pixel';
+    readonly category: 'marketing';
     readonly persistAfterConsentRevoked: true;
     readonly bootstrap: [{
-        readonly type: "setGlobal";
-        readonly name: "TiktokAnalyticsObject";
-        readonly value: "ttq";
+        readonly type: 'setGlobal';
+        readonly name: 'TiktokAnalyticsObject';
+        readonly value: 'ttq';
     }, {
-        readonly type: "setGlobal";
-        readonly name: "ttq";
+        readonly type: 'setGlobal';
+        readonly name: 'ttq';
         readonly value: readonly [];
         readonly ifUndefined: true;
     }, {
-        readonly type: "defineQueueMethods";
-        readonly target: "ttq";
+        readonly type: 'defineQueueMethods';
+        readonly target: 'ttq';
         readonly methods: ["page", "track", "identify", "instances", "debug", "on", "off", "once", "ready", "alias", "group", "enableCookie", "disableCookie", "holdConsent", "revokeConsent", "grantConsent"];
     }];
     readonly install: [{
-        readonly type: "callGlobal";
-        readonly global: "ttq";
-        readonly method: "grantConsent";
+        readonly type: 'callGlobal';
+        readonly global: 'ttq';
+        readonly method: 'grantConsent';
     }, {
-        readonly type: "callGlobal";
-        readonly global: "ttq";
-        readonly method: "page";
+        readonly type: 'callGlobal';
+        readonly global: 'ttq';
+        readonly method: 'page';
     }, {
-        readonly type: "loadScript";
-        readonly src: "{{scriptSrc}}?sdkid={{pixelId}}&lib=ttq";
+        readonly type: 'loadScript';
+        readonly src: '{{scriptSrc}}?sdkid={{pixelId}}&lib=ttq';
         readonly async: true;
     }];
     readonly afterLoad: [{
-        readonly type: "callGlobal";
-        readonly global: "ttq";
-        readonly method: "grantConsent";
+        readonly type: 'callGlobal';
+        readonly global: 'ttq';
+        readonly method: 'grantConsent';
     }];
     readonly onConsentGranted: [{
-        readonly type: "callGlobal";
-        readonly global: "ttq";
-        readonly method: "grantConsent";
+        readonly type: 'callGlobal';
+        readonly global: 'ttq';
+        readonly method: 'grantConsent';
     }];
     readonly onConsentDenied: [{
-        readonly type: "callGlobal";
-        readonly global: "ttq";
-        readonly method: "revokeConsent";
+        readonly type: 'callGlobal';
+        readonly global: 'ttq';
+        readonly method: 'revokeConsent';
     }];
-    readonly kind: "c15t.vendor-manifest";
-    readonly schemaVersion: 1;
 };
 export interface TikTokPixelOptions {
     /**
@@ -89,3 +103,4 @@ export interface TikTokPixelOptions {
  * @see {@link https://ads.tiktok.com/help/article/tiktok-pixel} TikTok Pixel documentation
  */
 export declare function tiktokPixel({ pixelId, scriptSrc, }: TikTokPixelOptions): Script;
+export {};