@c15t/scripts 1.0.1 → 1.1.0-rc.1

package/{dist → dist-types}/meta-pixel.d.ts

@@ -83,27 +83,75 @@ declare global {
         _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;
-    /**
-     * Override or extend the default script values.
-     *
-     * Default values:
-     * - `id`: 'meta-pixel'
-     * - `src`: `https://connect.facebook.net/en_US/fbevents.js`
-     * - `category`: 'marketing'
-     */
-    script?: Partial<Script>;
+    /** Meta Pixel loader URL. */
+    scriptSrc?: string;
 }
 /**
- * Creates a Meta Pixel script with inline JavaScript code.
+ * Creates a Meta Pixel script.
  *
- * This script uses textContent to inject the Meta Pixel tracking code directly
- * into the page, which is the recommended approach for Meta Pixel implementation.
+ * 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
@@ -117,7 +165,7 @@ export interface MetaPixelOptions {
  *
  * @see {@link https://developers.facebook.com/docs/meta-pixel/get-started} Meta Pixel documentation
  */
-export declare function metaPixel({ pixelId, script }: MetaPixelOptions): Script;
+export declare function metaPixel({ pixelId, scriptSrc }: MetaPixelOptions): Script;
 /**
  * Meta Pixel Event
  * This is a wrapper around the `fbq` function that the Meta Pixel script uses.
@@ -135,4 +183,3 @@ export declare function metaPixel({ pixelId, script }: MetaPixelOptions): Script
  */
 export declare const metaPixelEvent: <TEventName extends StandardEventName>(eventName: TEventName, params?: StandardEventParams[TEventName], eventId?: string) => void;
 export {};
-//# sourceMappingURL=meta-pixel.d.ts.map

package/dist-types/microsoft-uet.d.ts

@@ -0,0 +1,94 @@
+import type { Script } from 'c15t';
+declare global {
+    interface Window {
+        uetq: unknown[] | undefined;
+    }
+}
+/**
+ * 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' })`
+ */
+export declare const microsoftUetManifest: {
+    readonly vendor: "microsoft-uet";
+    readonly category: "marketing";
+    readonly persistAfterConsentRevoked: true;
+    readonly bootstrap: [{
+        readonly type: "setGlobal";
+        readonly name: "uetq";
+        readonly value: readonly [];
+        readonly ifUndefined: true;
+    }];
+    readonly install: [{
+        readonly type: "loadScript";
+        readonly src: "{{scriptSrc}}";
+        readonly async: true;
+    }];
+    readonly afterLoad: [{
+        readonly type: "constructGlobal";
+        readonly constructor: "UET";
+        readonly assignTo: "uetq";
+        readonly args: [{
+            readonly ti: "{{id}}";
+            readonly enableAutoSpaTracking: true;
+        }];
+        readonly copyAssignedValueToArgProperty: "q";
+    }, {
+        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 args: ["consent", "update", {
+            readonly ad_storage: "granted";
+        }];
+    }];
+    readonly onConsentDenied: [{
+        readonly type: "callGlobal";
+        readonly global: "uetq";
+        readonly method: "push";
+        readonly args: ["consent", "update", {
+            readonly ad_storage: "denied";
+        }];
+    }];
+    readonly kind: "c15t.vendor-manifest";
+    readonly schemaVersion: 1;
+};
+export interface MicrosoftUetOptions {
+    /**
+     * Your Microsoft UET ID
+     * @example `123456789012345`
+     */
+    id: string;
+    /** Microsoft UET loader URL. */
+    scriptSrc?: string;
+}
+/**
+ * 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.
+ *
+ * @param options - The options for the Microsoft UET script
+ * @returns The Microsoft UET script configuration
+ *
+ * @example
+ * ```ts
+ * const microsoftUetScript = microsoftUet({
+ *   id: '123456789012345',
+ * });
+ * ```
+ *
+ * @see https://learn.microsoft.com/en-us/advertising/guides/universal-event-tracking?view=bingads-13
+ */
+export declare function microsoftUet({ id, scriptSrc }: MicrosoftUetOptions): Script;

package/dist-types/posthog.d.ts

@@ -0,0 +1,112 @@
+import type { Script } from 'c15t';
+declare global {
+    interface Window {
+        posthog: {
+            init: (token: string, options: {
+                api_host: string;
+                ui_host?: string;
+                autocapture?: boolean;
+                [key: string]: unknown;
+            }) => void;
+            opt_in_capturing: () => void;
+            opt_out_capturing: () => void;
+            get_explicit_consent_status: () => string;
+        };
+    }
+}
+/**
+ * PostHog vendor manifest.
+ *
+ * PostHog manages its own consent internally via opt_in/opt_out capturing.
+ * The script always loads, and consent is toggled via the PostHog API.
+ */
+export declare const posthogManifest: {
+    readonly vendor: "posthog";
+    readonly category: "measurement";
+    readonly alwaysLoad: true;
+    readonly bootstrap: [{
+        readonly type: "setGlobal";
+        readonly name: "posthog";
+        readonly value: {};
+        readonly ifUndefined: true;
+    }, {
+        readonly type: "defineGlobalMethods";
+        readonly target: "posthog";
+        readonly methods: [{
+            readonly name: "init";
+            readonly behavior: "noop";
+        }, {
+            readonly name: "opt_in_capturing";
+            readonly behavior: "noop";
+        }, {
+            readonly name: "opt_out_capturing";
+            readonly behavior: "noop";
+        }, {
+            readonly name: "get_explicit_consent_status";
+            readonly behavior: "return";
+            readonly value: "pending";
+        }];
+    }];
+    readonly install: [{
+        readonly type: "loadScript";
+        readonly src: "{{scriptUrl}}";
+        readonly async: true;
+        readonly attributes: {
+            readonly crossorigin: "anonymous";
+            readonly 'data-api-host': "{{apiHost}}";
+            readonly 'data-ui-host': "{{apiHost}}";
+        };
+    }];
+    readonly afterLoad: [{
+        readonly type: "callGlobal";
+        readonly global: "posthog";
+        readonly method: "init";
+        readonly args: ["{{id}}", "{{initOptions}}"];
+    }];
+    readonly onLoadGranted: [{
+        readonly type: "callGlobal";
+        readonly global: "posthog";
+        readonly method: "opt_in_capturing";
+    }];
+    readonly onLoadDenied: [{
+        readonly type: "callGlobal";
+        readonly global: "posthog";
+        readonly method: "opt_out_capturing";
+    }];
+    readonly onConsentGranted: [{
+        readonly type: "callGlobal";
+        readonly global: "posthog";
+        readonly method: "opt_in_capturing";
+    }];
+    readonly onConsentDenied: [{
+        readonly type: "callGlobal";
+        readonly global: "posthog";
+        readonly method: "opt_out_capturing";
+    }];
+    readonly kind: "c15t.vendor-manifest";
+    readonly schemaVersion: 1;
+};
+export interface PosthogConsentOptions {
+    /**
+     * Your posthog id, begins with 'phc_'.
+     */
+    id: string;
+    /**
+     * Your posthog api host.
+     * @default 'https://eu.i.posthog.com'
+     */
+    apiHost?: string;
+    /** The PostHog array loader URL. */
+    scriptUrl?: string;
+    /** PostHog init options passed to `posthog.init(...)`. */
+    initOptions?: Record<string, unknown>;
+}
+/**
+ * Loads the PostHog script and initializes it with the given options.
+ * This uses posthog.opt_in_capturing() to opt in to capturing. And posthog.opt_out_capturing() to opt out of capturing.
+ * @see https://posthog.com/docs/libraries/js#opt-in-capturing
+ *
+ * @param options - Optional configuration for the PostHog consent script
+ * @returns The Posthog script
+ */
+export declare function posthog(options: PosthogConsentOptions): Script;

package/dist-types/resolve.d.ts

@@ -0,0 +1,9 @@
+import type { Script } from 'c15t';
+import type { VendorManifest } from './types';
+/**
+ * Compiles a `VendorManifest` + config into a `Script` object.
+ *
+ * This compatibility wrapper preserves the existing public resolver API while
+ * delegating to the new compile and runtime conversion phases internally.
+ */
+export declare function resolveManifest(manifest: VendorManifest, config?: Record<string, unknown>): Script;

package/dist-types/tiktok-pixel.d.ts

@@ -0,0 +1,91 @@
+import type { Script } from 'c15t';
+declare global {
+    interface Window {
+        ttq: {
+            grantConsent: () => void;
+            revokeConsent: () => void;
+            page: () => void;
+        };
+    }
+}
+/**
+ * TikTok Pixel vendor manifest.
+ *
+ * Uses structured bootstrap steps and provides a consent API
+ * via `ttq.grantConsent()` / `ttq.revokeConsent()`.
+ */
+export declare const tiktokPixelManifest: {
+    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: "ttq";
+        readonly value: readonly [];
+        readonly ifUndefined: true;
+    }, {
+        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: "page";
+    }, {
+        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 onConsentGranted: [{
+        readonly type: "callGlobal";
+        readonly global: "ttq";
+        readonly method: "grantConsent";
+    }];
+    readonly onConsentDenied: [{
+        readonly type: "callGlobal";
+        readonly global: "ttq";
+        readonly method: "revokeConsent";
+    }];
+    readonly kind: "c15t.vendor-manifest";
+    readonly schemaVersion: 1;
+};
+export interface TikTokPixelOptions {
+    /**
+     * Your TikTok Pixel ID
+     * @example `123456789012345`
+     */
+    pixelId: string;
+    /** TikTok Pixel loader base URL. */
+    scriptSrc?: string;
+}
+/**
+ * Creates a Tiktok Pixel 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.
+ *
+ * @param options - The options for the TikTok Pixel script
+ * @returns The TikTok Pixel script configuration
+ *
+ * @example
+ * ```ts
+ * const tiktokPixelScript = tiktokPixel({
+ *   pixelId: '123456789012345',
+ * });
+ * ```
+ *
+ * @see {@link https://ads.tiktok.com/help/article/tiktok-pixel} TikTok Pixel documentation
+ */
+export declare function tiktokPixel({ pixelId, scriptSrc, }: TikTokPixelOptions): Script;

package/dist-types/types.d.ts

@@ -0,0 +1,259 @@
+import type { AllConsentNames, HasCondition } from 'c15t';
+export declare const VENDOR_MANIFEST_KIND = "c15t.vendor-manifest";
+export declare const VENDOR_MANIFEST_SCHEMA_VERSION = 1;
+export declare const vendorManifestContract: {
+    readonly kind: "c15t.vendor-manifest";
+    readonly schemaVersion: 1;
+};
+export interface ManifestContract {
+    kind: typeof VENDOR_MANIFEST_KIND;
+    schemaVersion: typeof VENDOR_MANIFEST_SCHEMA_VERSION;
+}
+type ManifestInterpolationToken = `{{${string}}}`;
+export type ManifestCategoryCondition = HasCondition<AllConsentNames | ManifestInterpolationToken>;
+export interface LoadScriptStep {
+    type: 'loadScript';
+    src: string;
+    async?: boolean;
+    defer?: boolean;
+    attributes?: Record<string, string>;
+}
+export interface SetGlobalStep {
+    type: 'setGlobal';
+    /** Global variable name (e.g. 'dataLayer') */
+    name: string;
+    /** Value to assign. Arrays and objects are recursively cloned on execution. */
+    value: unknown;
+    /**
+     * Only set the global if it's not already defined.
+     * Mirrors the common `window.x = window.x || value` pattern.
+     * @default true
+     */
+    ifUndefined?: boolean;
+}
+export interface DefineQueueFunctionStep {
+    type: 'defineQueueFunction';
+    /** Global function name (e.g. 'gtag') */
+    name: string;
+    /** Global array name that receives queued calls (e.g. 'dataLayer') */
+    queue: string;
+    /**
+     * Only define the function if it is not already present.
+     * @default true
+     */
+    ifUndefined?: boolean;
+    /**
+     * Whether queued calls should store the `arguments` object or a copied array.
+     * @default 'arguments'
+     */
+    pushStyle?: 'arguments' | 'array';
+}
+export interface DefineStubFunctionStep {
+    type: 'defineStubFunction';
+    /** Global function name (e.g. 'fbq', 'twq', 'lintrk') */
+    name: string;
+    /**
+     * Queue storage location:
+     * - `global` pushes into another global array (e.g. `dataLayer`)
+     * - `property` pushes into a property on the stub function itself (e.g. `fbq.queue`)
+     */
+    queue: {
+        global: string;
+        property?: never;
+    } | {
+        global?: never;
+        property: string;
+    };
+    /**
+     * If present, calls `stub[dispatchProperty](...args)` when available instead of queueing.
+     * Mirrors vendor APIs like Meta Pixel's `callMethod`.
+     */
+    dispatchProperty?: string;
+    /**
+     * How queued values should be stored.
+     * - `'arguments'` => push the `arguments` object
+     * - `'array'` => push a copied array of arguments
+     */
+    queueFormat?: 'arguments' | 'array';
+    /** Additional globals that should reference the same stub */
+    aliases?: string[];
+    /** Properties on the stub that should reference the stub itself (e.g. `push`) */
+    selfReferences?: string[];
+    /** Additional scalar/object properties assigned to the stub */
+    properties?: Record<string, unknown>;
+    /** Only define the stub if not already present. */
+    ifUndefined?: boolean;
+}
+export interface CallGlobalStep {
+    type: 'callGlobal';
+    /** Global object name (e.g. 'posthog', 'fbq') */
+    global: string;
+    /** Method to call on the global. If omitted, the global itself is called as a function. */
+    method?: string;
+    /** Arguments to pass */
+    args?: unknown[];
+}
+export interface PushToQueueStep {
+    type: 'pushToQueue';
+    /** Global array name that receives queued values (e.g. 'dataLayer') */
+    queue: string;
+    /** Value to push onto the queue */
+    value: unknown;
+}
+export interface SetGlobalPathStep {
+    type: 'setGlobalPath';
+    /** Path segments under window (e.g. ['databuddy', 'options', 'disabled']) */
+    path: string[];
+    /** Value to assign at the target path */
+    value: unknown;
+}
+export interface DefineQueueMethodsStep {
+    type: 'defineQueueMethods';
+    /** Global array/object name that owns the queue methods */
+    target: string;
+    /** Method names to attach */
+    methods: string[];
+    /** Optional queue location. Defaults to the target itself. */
+    queue?: {
+        global: string;
+        property?: never;
+    } | {
+        global?: never;
+        property: string;
+    };
+}
+export type GlobalMethodBehavior = {
+    name: string;
+    behavior: 'noop';
+} | {
+    name: string;
+    behavior: 'return';
+    value: unknown;
+};
+export interface DefineGlobalMethodsStep {
+    type: 'defineGlobalMethods';
+    /** Global object name to receive the methods */
+    target: string;
+    methods: Array<GlobalMethodBehavior>;
+}
+export interface ConstructGlobalStep {
+    type: 'constructGlobal';
+    /** Global constructor name (e.g. `UET`) */
+    constructor: string;
+    /** Global name to assign the constructed instance to */
+    assignTo: string;
+    /** Constructor args */
+    args?: unknown[];
+    /**
+     * Copies the current `window[assignTo]` value into the first constructor arg object
+     * under this property before constructing.
+     */
+    copyAssignedValueToArgProperty?: string;
+}
+export type ManifestStep = LoadScriptStep | SetGlobalStep | DefineQueueFunctionStep | DefineStubFunctionStep | CallGlobalStep | PushToQueueStep | SetGlobalPathStep | DefineQueueMethodsStep | DefineGlobalMethodsStep | ConstructGlobalStep;
+/**
+ * Consent signal type determines how consent state is communicated to the vendor.
+ *
+ * - `'gtag'` — Google Consent Mode pattern: calls `gtag('consent', 'default'|'update', state)`
+ */
+export type ConsentSignalType = 'gtag';
+/**
+ * A declarative definition of a vendor integration.
+ *
+ * Manifests are the source definition that the scripts engine compiles into a
+ * serializable resolved manifest and then converts into a runtime `Script`.
+ */
+export interface VendorManifest extends ManifestContract {
+    /** Manifest contract identifier. */
+    kind: typeof VENDOR_MANIFEST_KIND;
+    /** Manifest schema version. */
+    schemaVersion: typeof VENDOR_MANIFEST_SCHEMA_VERSION;
+    /** Unique vendor identifier (used as Script.id) */
+    vendor: string;
+    /** Consent category or condition required to load this vendor */
+    category: ManifestCategoryCondition;
+    /** Load regardless of consent state (vendor manages its own consent internally) */
+    alwaysLoad?: boolean | string;
+    /** Keep script in DOM after consent revocation (vendor has a consent API) */
+    persistAfterConsentRevoked?: boolean | string;
+    /**
+     * Steps that must execute before default consent signaling.
+     *
+     * This is primarily used for integrations such as Google tags where a stub
+     * global must exist before calling the vendor's consent API.
+     */
+    bootstrap?: ManifestStep[];
+    /**
+     * Steps to execute when installing the vendor.
+     *
+     * The resolver extracts the script source from these steps:
+     * - If a `loadScript` step exists, its `src` becomes `Script.src`
+     * - All non-`loadScript` steps run as part of `onBeforeLoad`
+     */
+    install: ManifestStep[];
+    /** Steps to execute after the main script loads */
+    afterLoad?: ManifestStep[];
+    /** Steps to execute before load when the vendor has consent */
+    onBeforeLoadGranted?: ManifestStep[];
+    /** Steps to execute before load when the vendor does not have consent */
+    onBeforeLoadDenied?: ManifestStep[];
+    /** Steps to execute after load when the vendor has consent */
+    onLoadGranted?: ManifestStep[];
+    /** Steps to execute after load when the vendor does not have consent */
+    onLoadDenied?: ManifestStep[];
+    /** Steps to run on any consent state change */
+    onConsentChange?: ManifestStep[];
+    /** Steps to run when this vendor's category consent is granted */
+    onConsentGranted?: ManifestStep[];
+    /** Steps to run when this vendor's category consent is denied */
+    onConsentDenied?: ManifestStep[];
+    /**
+     * Maps c15t consent categories to vendor-specific consent type names.
+     *
+     * Used with `consentSignal` to translate c15t consent state into
+     * the vendor's consent API format.
+     *
+     * @example
+     * ```ts
+     * // Google Consent Mode v2 mapping
+     * consentMapping: {
+     *   marketing: ['ad_storage', 'ad_user_data', 'ad_personalization'],
+     *   measurement: ['analytics_storage'],
+     *   functionality: ['functionality_storage'],
+     *   necessary: ['security_storage'],
+     *   experience: ['personalization_storage'],
+     * }
+     * ```
+     */
+    consentMapping?: Record<string, string[]>;
+    /** How to signal consent state to the vendor */
+    consentSignal?: ConsentSignalType;
+    /** Target global for consent signaling (defaults based on signal type) */
+    consentSignalTarget?: string;
+}
+/**
+ * Internal transport-ready manifest shape produced by the compile phase.
+ *
+ * Contains only serializable data and no runtime callbacks.
+ */
+export interface ResolvedManifest extends ManifestContract {
+    vendor: string;
+    category: HasCondition<AllConsentNames>;
+    alwaysLoad?: boolean;
+    persistAfterConsentRevoked?: boolean;
+    bootstrapSteps: ManifestStep[];
+    setupSteps: ManifestStep[];
+    loadScript?: LoadScriptStep;
+    afterLoadSteps: ManifestStep[];
+    onBeforeLoadGrantedSteps: ManifestStep[];
+    onBeforeLoadDeniedSteps: ManifestStep[];
+    onLoadGrantedSteps: ManifestStep[];
+    onLoadDeniedSteps: ManifestStep[];
+    onConsentChangeSteps: ManifestStep[];
+    onConsentGrantedSteps: ManifestStep[];
+    onConsentDeniedSteps: ManifestStep[];
+    consentMapping?: Record<string, string[]>;
+    consentSignal?: ConsentSignalType;
+    consentSignalTarget?: string;
+}
+export {};