@c15t/scripts 2.0.1 → 2.1.0

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

@@ -0,0 +1,289 @@
+import type { Script } from 'c15t';
+/**
+ * Represents the `contents` array object property.
+ */
+export interface FbqContent {
+    id: string | number;
+    quantity: number;
+    [key: string]: unknown;
+}
+/**
+ * Base interface for all possible event parameters.
+ * All properties are optional here; specific event types will make them required.
+ */
+export interface FbqBaseEventParams {
+    content_category?: string;
+    content_ids?: (string | number)[];
+    content_name?: string;
+    content_type?: 'product' | 'product_group';
+    contents?: FbqContent[];
+    currency?: string;
+    delivery_category?: 'in_store' | 'curbside' | 'home_delivery';
+    num_items?: number;
+    predicted_ltv?: number;
+    search_string?: string;
+    status?: boolean;
+    value?: number;
+}
+export type FbqCustomParams = Record<string, unknown>;
+type WithCustomParams<TParams> = TParams & FbqCustomParams;
+type AddPaymentInfoParams = WithCustomParams<Pick<FbqBaseEventParams, 'content_ids' | 'contents' | 'currency' | 'value'>>;
+type AddToCartParams = WithCustomParams<Pick<FbqBaseEventParams, 'content_ids' | 'content_type' | 'contents' | 'currency' | 'value'>>;
+type AddToWishlistParams = WithCustomParams<Pick<FbqBaseEventParams, 'content_ids' | 'contents' | 'currency' | 'value'>>;
+type CompleteRegistrationParams = WithCustomParams<Pick<FbqBaseEventParams, 'currency' | 'value' | 'status'>>;
+type InitiateCheckoutParams = WithCustomParams<Pick<FbqBaseEventParams, 'content_ids' | 'contents' | 'currency' | 'num_items' | 'value'>>;
+type LeadParams = WithCustomParams<Pick<FbqBaseEventParams, 'currency' | 'value'>>;
+type PageViewParams = FbqCustomParams;
+type SearchParams = WithCustomParams<Pick<FbqBaseEventParams, 'content_ids' | 'content_type' | 'contents' | 'currency' | 'search_string' | 'value'>>;
+type StartTrialParams = WithCustomParams<Pick<FbqBaseEventParams, 'currency' | 'predicted_ltv' | 'value'>>;
+type SubscribeParams = WithCustomParams<Pick<FbqBaseEventParams, 'currency' | 'predicted_ltv' | 'value'>>;
+type ViewContentParams = WithCustomParams<Pick<FbqBaseEventParams, 'content_ids' | 'content_type' | 'contents' | 'currency' | 'value'>>;
+/**
+ * The 'Purchase' event has required properties.
+ * We use TypeScript's utility types to enforce this.
+ */
+type PurchaseParams = WithCustomParams<Pick<FbqBaseEventParams, 'content_ids' | 'content_type' | 'contents' | 'num_items'> & Required<Pick<FbqBaseEventParams, 'currency' | 'value'>>>;
+/**
+ * Events with no specific properties listed can accept any of the base parameters.
+ */
+type ContactParams = WithCustomParams<FbqBaseEventParams>;
+type CustomizeProductParams = WithCustomParams<FbqBaseEventParams>;
+type DonateParams = WithCustomParams<FbqBaseEventParams>;
+type FindLocationParams = WithCustomParams<FbqBaseEventParams>;
+type ScheduleParams = WithCustomParams<FbqBaseEventParams>;
+type SubmitApplicationParams = WithCustomParams<FbqBaseEventParams>;
+/**
+ * A mapping of Standard Event names to their corresponding parameter types.
+ * This is the core of our type-safety mechanism.
+ */
+export interface StandardEventParams {
+    AddPaymentInfo: AddPaymentInfoParams;
+    AddToCart: AddToCartParams;
+    AddToWishlist: AddToWishlistParams;
+    CompleteRegistration: CompleteRegistrationParams;
+    Contact: ContactParams;
+    CustomizeProduct: CustomizeProductParams;
+    Donate: DonateParams;
+    FindLocation: FindLocationParams;
+    InitiateCheckout: InitiateCheckoutParams;
+    Lead: LeadParams;
+    PageView: PageViewParams;
+    Purchase: PurchaseParams;
+    Schedule: ScheduleParams;
+    Search: SearchParams;
+    StartTrial: StartTrialParams;
+    SubmitApplication: SubmitApplicationParams;
+    Subscribe: SubscribeParams;
+    ViewContent: ViewContentParams;
+}
+export type StandardEventName = keyof StandardEventParams;
+export interface MetaPixelEventOptions {
+    /**
+     * Event ID used to deduplicate browser events against Conversions API events.
+     *
+     * @see https://developers.facebook.com/docs/marketing-api/conversions-api/deduplicate-pixel-and-server-events
+     */
+    eventID?: string;
+    [key: string]: unknown;
+}
+export interface MetaPixelDataProcessingOptions {
+    /**
+     * Data processing flags sent to Meta before `init`.
+     *
+     * Use `['LDU']` to enable Limited Data Use, or `[]` to explicitly disable it.
+     */
+    options: 'LDU'[] | [];
+    /**
+     * Meta country code. Use `0` to let Meta geolocate the event or `1` for USA.
+     */
+    country?: number;
+    /**
+     * Meta state code. Use `0` to let Meta geolocate the event.
+     *
+     * @example `1000` for California
+     */
+    state?: number;
+}
+declare global {
+    interface Window {
+        fbq: {
+            (command: 'dataProcessingOptions', options: MetaPixelDataProcessingOptions['options'], country?: number, state?: number): void;
+            (command: 'init', pixelId: string, options?: Record<string, unknown>): void;
+            (command: 'track', eventName: StandardEventName, params?: StandardEventParams[StandardEventName], options?: MetaPixelEventOptions): void;
+            (command: 'trackCustom', eventName: string, params?: FbqCustomParams, options?: MetaPixelEventOptions): void;
+            (command: 'trackSingle', pixelId: string, eventName: StandardEventName, params?: StandardEventParams[StandardEventName], options?: MetaPixelEventOptions): void;
+            (command: 'trackSingleCustom', pixelId: string, eventName: string, params?: FbqCustomParams, options?: MetaPixelEventOptions): void;
+            (command: 'consent', action: 'grant' | 'revoke'): void;
+            (...args: unknown[]): void;
+        };
+        _fbq: Window['fbq'];
+    }
+}
+/**
+ * Meta Pixel vendor manifest.
+ *
+ * The Meta Pixel uses structured bootstrap steps to define the standard `fbq`
+ * stub and provides a consent API via `fbq('consent', 'grant'|'revoke')`.
+ */
+export declare const metaPixelManifest: {
+    readonly vendor: "meta-pixel";
+    readonly category: "marketing";
+    readonly persistAfterConsentRevoked: true;
+    readonly bootstrap: [{
+        readonly type: "defineStubFunction";
+        readonly name: "fbq";
+        readonly queue: {
+            readonly property: "queue";
+        };
+        readonly dispatchProperty: "callMethod";
+        readonly selfReferences: ["push"];
+        readonly aliases: ["_fbq"];
+        readonly properties: {
+            readonly loaded: true;
+            readonly version: "2.0";
+        };
+        readonly ifUndefined: true;
+    }];
+    readonly install: [{
+        readonly type: "callGlobal";
+        readonly global: "fbq";
+        readonly args: ["consent", "grant"];
+    }, {
+        readonly type: "callGlobal";
+        readonly global: "fbq";
+        readonly args: ["init", "{{pixelId}}"];
+    }, {
+        readonly type: "callGlobal";
+        readonly global: "fbq";
+        readonly args: ["track", "PageView"];
+    }, {
+        readonly type: "loadScript";
+        readonly src: "{{scriptSrc}}";
+        readonly async: true;
+    }];
+    readonly onConsentGranted: [{
+        readonly type: "callGlobal";
+        readonly global: "fbq";
+        readonly args: ["consent", "grant"];
+    }];
+    readonly onConsentDenied: [{
+        readonly type: "callGlobal";
+        readonly global: "fbq";
+        readonly args: ["consent", "revoke"];
+    }];
+    readonly kind: "c15t.vendor-manifest";
+    readonly schemaVersion: 1;
+};
+export interface MetaPixelOptions {
+    /**
+     * Your Meta Pixel ID
+     * @example `123456789012345`
+     */
+    pixelId: string;
+    /** Optional payload passed as the third argument to `fbq('init', ...)`. */
+    initOptions?: Record<string, unknown>;
+    /**
+     * Queue the default `PageView` event during setup.
+     *
+     * @default true
+     */
+    trackPageView?: boolean;
+    /**
+     * Optional Meta data processing options, such as Limited Data Use.
+     *
+     * When provided, c15t queues `fbq('dataProcessingOptions', ...)` before
+     * `fbq('init', ...)`.
+     */
+    dataProcessingOptions?: MetaPixelDataProcessingOptions;
+    /** Meta Pixel loader URL. */
+    scriptSrc?: string;
+}
+/**
+ * Creates a Meta Pixel script.
+ *
+ * The manifest defines a structured `fbq` stub plus the external loader URL,
+ * avoiding raw inline vendor snippets in the manifest payload.
+ *
+ * @param options - The options for the Meta Pixel script
+ * @returns The Meta Pixel script configuration
+ *
+ * @example
+ * ```ts
+ * const metaPixelScript = metaPixel({
+ *   pixelId: '123456789012345',
+ * });
+ * ```
+ *
+ * @see {@link https://developers.facebook.com/docs/meta-pixel/get-started} Meta Pixel documentation
+ */
+export declare function metaPixel({ pixelId, initOptions, trackPageView, dataProcessingOptions, scriptSrc, }: MetaPixelOptions): Script;
+/**
+ * Tracks a Meta Pixel standard event.
+ *
+ * This is a wrapper around `fbq('track', ...)`.
+ *
+ * @template TEventName - The Meta `StandardEventName` being tracked.
+ * @param eventName - The `StandardEventName` to track.
+ * @param params - Optional `StandardEventParams[TEventName]` payload.
+ * @param eventOptions - Optional `MetaPixelEventOptions` or event ID string.
+ * @returns `void`; calls `window.fbq`.
+ *
+ * @example
+ * ```ts
+ * metaPixelEvent('Purchase', { value: 10.0, currency: 'USD' }, 'event-123');
+ * ```
+ *
+ * @see {@link https://developers.facebook.com/docs/meta-pixel/reference} Meta Pixel documentation
+ */
+export declare const metaPixelEvent: <TEventName extends StandardEventName>(eventName: TEventName, params?: StandardEventParams[TEventName], eventOptions?: MetaPixelEventOptions | string) => void;
+/**
+ * Tracks a Meta Pixel custom event with optional custom parameters.
+ *
+ * @param eventName - The custom event name to track
+ * @param params - Optional custom parameters to track
+ * @param eventOptions - Optional event options, including Conversions API eventID
+ */
+export declare const metaPixelCustomEvent: (eventName: string, params?: FbqCustomParams, eventOptions?: MetaPixelEventOptions | string) => void;
+/**
+ * Tracks a standard event for a single Meta Pixel ID.
+ *
+ * Use this when multiple Meta Pixels are initialized on the same page and the
+ * event should not fire for every initialized pixel.
+ *
+ * @template TEventName - The Meta `StandardEventName` being tracked.
+ * @param pixelId - Meta Pixel ID that should receive the event.
+ * @param eventName - The `StandardEventName` to track.
+ * @param params - Optional `StandardEventParams[TEventName]` payload.
+ * @param eventOptions - Optional `MetaPixelEventOptions` or event ID string.
+ * @returns `void`; calls `window.fbq`.
+ *
+ * @example
+ * ```ts
+ * metaPixelSingleEvent(
+ * 	'123456',
+ * 	'Purchase',
+ * 	{ value: 9.99, currency: 'USD' },
+ * 	'event-123'
+ * );
+ * ```
+ */
+export declare const metaPixelSingleEvent: <TEventName extends StandardEventName>(pixelId: string, eventName: TEventName, params?: StandardEventParams[TEventName], eventOptions?: MetaPixelEventOptions | string) => void;
+/**
+ * Tracks a custom event for a single Meta Pixel ID.
+ *
+ * Use this when multiple Meta Pixels are initialized on the same page and the
+ * custom event should not fire for every initialized pixel.
+ *
+ * @param pixelId - Meta Pixel ID that should receive the custom event.
+ * @param eventName - Custom event name to track.
+ * @param params - Optional `FbqCustomParams` payload.
+ * @param eventOptions - Optional `MetaPixelEventOptions` or event ID string.
+ * @returns `void`; calls `window.fbq`.
+ *
+ * @example
+ * ```ts
+ * metaPixelSingleCustomEvent('123456', 'MyCustomEvent', { foo: 'bar' });
+ * ```
+ */
+export declare const metaPixelSingleCustomEvent: (pixelId: string, eventName: string, params?: FbqCustomParams, eventOptions?: MetaPixelEventOptions | string) => void;
+export {};

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

@@ -7,12 +7,13 @@ 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 alwaysLoad: true;
     readonly persistAfterConsentRevoked: true;
     readonly bootstrap: [{
         readonly type: "setGlobal";
@@ -20,6 +21,22 @@ export declare const microsoftUetManifest: {
         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}}";
@@ -39,13 +56,6 @@ export declare const microsoftUetManifest: {
         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";
@@ -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 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"];
+    }];
+    readonly kind: "c15t.vendor-manifest";
+    readonly schemaVersion: 1;
+};
+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 {};