@c15t/scripts 2.0.1 → 2.2.0-canary-20260727202135

package/dist-types/vendors/analytics/hightouch.d.ts

@@ -0,0 +1,285 @@
+import type { Script } from 'c15t';
+export declare const HIGHTOUCH_QUEUE_METHODS: readonly ['trackSubmit', 'trackClick', 'trackLink', 'trackForm', 'pageview', 'identify', 'reset', 'group', 'track', 'ready', 'alias', 'debug', 'page', 'once', 'off', 'on', 'addSourceMiddleware', 'addIntegrationMiddleware', 'setAnonymousId', 'addDestinationMiddleware', 'load'];
+/**
+ * Public Hightouch Events browser API exposed on `window.htevents`.
+ *
+ * The official browser snippet starts as an array-backed queue and the loaded
+ * SDK replaces it with an initialized runtime object. Use this interface for
+ * calls made after consent has allowed the SDK to load.
+ *
+ * @example
+ * ```ts
+ * window.htevents?.track('Signup Completed', { plan: 'pro' });
+ * ```
+ */
+export interface HightouchApi {
+    /**
+     * Tracks a form submission.
+     *
+     * @param form - Form element, selector, or vendor-supported form target.
+     * @param event - Event name to record.
+     * @param properties - Optional event properties payload.
+     * @returns The Hightouch runtime or a promise-like value from the SDK.
+     */
+    trackSubmit: (form: unknown, event: string, properties?: Record<string, unknown>) => unknown;
+    /**
+     * Tracks a click interaction.
+     *
+     * @param element - Element, selector, or vendor-supported click target.
+     * @param event - Event name to record.
+     * @param properties - Optional event properties payload.
+     * @returns The Hightouch runtime or a promise-like value from the SDK.
+     */
+    trackClick: (element: unknown, event: string, properties?: Record<string, unknown>) => unknown;
+    /**
+     * Tracks link clicks before navigation.
+     *
+     * @param link - Link element, selector, or vendor-supported link target.
+     * @param event - Event name to record.
+     * @param properties - Optional event properties payload.
+     * @returns The Hightouch runtime or a promise-like value from the SDK.
+     */
+    trackLink: (link: unknown, event: string, properties?: Record<string, unknown>) => unknown;
+    /**
+     * Tracks form submissions with form-specific semantics.
+     *
+     * @param form - Form element, selector, or vendor-supported form target.
+     * @param event - Event name to record.
+     * @param properties - Optional event properties payload.
+     * @returns The Hightouch runtime or a promise-like value from the SDK.
+     */
+    trackForm: (form: unknown, event: string, properties?: Record<string, unknown>) => unknown;
+    /**
+     * Tracks a classic pageview event.
+     *
+     * @param url - Optional URL override.
+     * @returns The Hightouch runtime or a promise-like value from the SDK.
+     */
+    pageview: (url?: string) => unknown;
+    /**
+     * Identifies a user and associates traits with that identity.
+     *
+     * @param userId - Stable user identifier.
+     * @param traits - Optional trait map associated with the user.
+     * @param context - Optional event context overrides.
+     * @param callback - Optional callback after processing.
+     * @returns The Hightouch runtime or a promise-like value from the SDK.
+     */
+    identify: (userId: string, traits?: Record<string, unknown>, context?: Record<string, unknown>, callback?: () => void) => unknown;
+    /**
+     * Clears the current user identity state.
+     *
+     * @returns The Hightouch runtime or a promise-like value from the SDK.
+     */
+    reset: () => unknown;
+    /**
+     * Associates the current user with a group or account.
+     *
+     * @param groupId - Group or account identifier.
+     * @param traits - Optional group trait map.
+     * @param context - Optional event context overrides.
+     * @param callback - Optional callback after processing.
+     * @returns The Hightouch runtime or a promise-like value from the SDK.
+     */
+    group: (groupId: string, traits?: Record<string, unknown>, context?: Record<string, unknown>, callback?: () => void) => unknown;
+    /**
+     * Tracks a named event.
+     *
+     * @param event - Event name to record.
+     * @param properties - Optional event properties payload.
+     * @param context - Optional event context overrides.
+     * @param callback - Optional callback after processing.
+     * @returns The Hightouch runtime or a promise-like value from the SDK.
+     */
+    track: (event: string, properties?: Record<string, unknown>, context?: Record<string, unknown>, callback?: () => void) => unknown;
+    /**
+     * Registers a callback that fires when the SDK is ready.
+     *
+     * @param callback - Function to run once the SDK is ready.
+     * @returns The Hightouch runtime or a promise-like value from the SDK.
+     */
+    ready: (callback: () => void) => unknown;
+    /**
+     * Aliases one user identifier to another.
+     *
+     * @param userId - New canonical user identifier.
+     * @param previousId - Optional previous identifier.
+     * @param context - Optional event context overrides.
+     * @param callback - Optional callback after processing.
+     * @returns The Hightouch runtime or a promise-like value from the SDK.
+     */
+    alias: (userId: string, previousId?: string, context?: Record<string, unknown>, callback?: () => void) => unknown;
+    /**
+     * Enables or disables debug logging in the SDK.
+     *
+     * @param enabled - Whether debug logging should be enabled.
+     * @returns The Hightouch runtime or a promise-like value from the SDK.
+     */
+    debug: (enabled?: boolean) => unknown;
+    /**
+     * Tracks a page view with optional category, name, properties, and context.
+     *
+     * @param category - Optional page category or page name.
+     * @param name - Optional page name or properties payload.
+     * @param properties - Optional page metadata payload.
+     * @param context - Optional event context overrides.
+     * @param callback - Optional callback after processing.
+     * @returns The Hightouch runtime or a promise-like value from the SDK.
+     */
+    page: (category?: string, name?: string | Record<string, unknown>, properties?: Record<string, unknown>, context?: Record<string, unknown>, callback?: () => void) => unknown;
+    /**
+     * Registers a one-time event listener on the SDK emitter.
+     *
+     * @param event - Event name to listen for.
+     * @param callback - Listener callback.
+     * @returns The Hightouch runtime or a promise-like value from the SDK.
+     */
+    once: (event: string, callback: (...args: unknown[]) => void) => unknown;
+    /**
+     * Removes an SDK event listener.
+     *
+     * @param event - Event name to stop listening for.
+     * @param callback - Listener callback to remove.
+     * @returns The Hightouch runtime or a promise-like value from the SDK.
+     */
+    off: (event: string, callback?: (...args: unknown[]) => void) => unknown;
+    /**
+     * Registers an SDK event listener.
+     *
+     * @param event - Event name to listen for.
+     * @param callback - Listener callback.
+     * @returns The Hightouch runtime or a promise-like value from the SDK.
+     */
+    on: (event: string, callback: (...args: unknown[]) => void) => unknown;
+    /**
+     * Adds source middleware before events are dispatched.
+     *
+     * @param middleware - Middleware function or vendor-supported middleware.
+     * @returns The Hightouch runtime or a promise-like value from the SDK.
+     */
+    addSourceMiddleware: (middleware: unknown) => unknown;
+    /**
+     * Adds integration middleware for destination-specific event transforms.
+     *
+     * @param integration - Integration name.
+     * @param middleware - Middleware function or vendor-supported middleware.
+     * @returns The Hightouch runtime or a promise-like value from the SDK.
+     */
+    addIntegrationMiddleware: (integration: string, middleware: unknown) => unknown;
+    /**
+     * Sets the anonymous ID used for subsequent events.
+     *
+     * @param anonymousId - Anonymous identifier to assign.
+     * @returns The Hightouch runtime or a promise-like value from the SDK.
+     */
+    setAnonymousId: (anonymousId: string) => unknown;
+    /**
+     * Adds destination middleware for event delivery.
+     *
+     * @param destination - Destination name.
+     * @param middleware - Middleware function or vendor-supported middleware.
+     * @returns The Hightouch runtime or a promise-like value from the SDK.
+     */
+    addDestinationMiddleware: (destination: string, middleware: unknown) => unknown;
+}
+declare global {
+    interface Window {
+        htevents?: HightouchApi;
+    }
+}
+/**
+ * Hightouch Events vendor manifest.
+ *
+ * Creates Hightouch's analytics.js-style `window.htevents` queue, records the
+ * write key/load options expected by the standalone loader, queues the
+ * `load()` and optional `page()` calls, then lets c15t own the script element.
+ */
+export declare const hightouchManifest: {
+    readonly kind: "c15t.vendor-manifest";
+    readonly schemaVersion: 1;
+    readonly vendor: 'hightouch';
+    readonly category: 'measurement';
+    readonly bootstrap: [{
+        readonly type: 'setGlobal';
+        readonly name: 'htevents';
+        readonly value: readonly [];
+        readonly ifUndefined: true;
+    }, {
+        readonly type: 'defineQueueMethods';
+        readonly target: 'htevents';
+        readonly methods: ["trackSubmit", "trackClick", "trackLink", "trackForm", "pageview", "identify", "reset", "group", "track", "ready", "alias", "debug", "page", "once", "off", "on", "addSourceMiddleware", "addIntegrationMiddleware", "setAnonymousId", "addDestinationMiddleware", "load"];
+    }, {
+        readonly type: 'setGlobalPath';
+        readonly path: ["htevents", "_writeKey"];
+        readonly value: '{{writeKey}}';
+    }, {
+        readonly type: 'setGlobalPath';
+        readonly path: ["htevents", "_loadOptions"];
+        readonly value: '{{loadOptions}}';
+    }];
+    readonly install: [{
+        readonly type: 'callGlobal';
+        readonly global: 'htevents';
+        readonly method: 'load';
+        readonly args: ["{{writeKey}}", "{{loadOptions}}"];
+    }, {
+        readonly type: 'callGlobal';
+        readonly global: 'htevents';
+        readonly method: 'page';
+    }, {
+        readonly type: 'loadScript';
+        readonly src: '{{scriptUrl}}';
+        readonly async: true;
+    }];
+};
+export interface HightouchOptions {
+    /**
+     * Hightouch Events write key from your Event Source.
+     */
+    writeKey: string;
+    /**
+     * Optional Hightouch Events API host.
+     *
+     * Hightouch's browser SDK defaults to `us-east-1.hightouch-events.com`.
+     * Pass this only when your Event Source uses another region or a first-party
+     * tracking host.
+     */
+    apiHost?: string;
+    /**
+     * Queue the initial `htevents.page()` call during setup.
+     *
+     * @default true
+     */
+    trackPageView?: boolean;
+    /**
+     * Optional full loader URL override.
+     *
+     * @default 'https://cdn.hightouch-events.com/browser/release/v1-latest/events.min.js'
+     */
+    scriptUrl?: string;
+}
+/**
+ * Creates a Hightouch Events browser SDK script.
+ *
+ * @see https://hightouch.com/docs/events/sdks/browser
+ *
+ * @param options - The options for the Hightouch script.
+ * @returns The Hightouch script configuration.
+ * @throws {Error} When `writeKey` is missing or only whitespace.
+ *
+ * @remarks
+ * Hightouch Events collects customer behavior and sends it to the configured
+ * Event Source. c15t gates the browser SDK on `measurement` consent and does
+ * not allowlist collection endpoints in live probes beyond the CDN loader.
+ *
+ * @example
+ * ```ts
+ * import { hightouch } from '@c15t/scripts/hightouch';
+ *
+ * hightouch({
+ * 	writeKey: 'WRITE_KEY',
+ * 	apiHost: 'us-east-1.hightouch-events.com',
+ * });
+ * ```
+ */
+export declare function hightouch({ writeKey, apiHost, trackPageView, scriptUrl, }: HightouchOptions): Script;

package/dist-types/vendors/analytics/hotjar.d.ts

@@ -0,0 +1,73 @@
+import type { Script } from 'c15t';
+declare global {
+    interface Window {
+        hj?: ((...args: unknown[]) => void) & {
+            q?: unknown[][];
+        };
+        _hjSettings?: {
+            hjid: number | string;
+            hjsv: number;
+        };
+    }
+}
+/**
+ * Hotjar vendor manifest.
+ *
+ * Seeds the global Hotjar settings object and queue stub before loading
+ * the vendor bundle.
+ */
+export declare const hotjarManifest: {
+    readonly kind: "c15t.vendor-manifest";
+    readonly schemaVersion: 1;
+    readonly vendor: 'hotjar';
+    readonly category: 'measurement';
+    readonly install: [{
+        readonly type: 'setGlobal';
+        readonly name: '_hjSettings';
+        readonly value: {
+            readonly hjid: '{{siteId}}';
+            readonly hjsv: '{{version}}';
+        };
+        readonly ifUndefined: true;
+    }, {
+        readonly type: 'defineStubFunction';
+        readonly name: 'hj';
+        readonly queue: {
+            readonly property: 'q';
+        };
+        readonly queueFormat: 'array';
+        readonly ifUndefined: true;
+    }, {
+        readonly type: 'loadScript';
+        readonly src: '{{scriptUrl}}';
+        readonly async: true;
+    }];
+};
+export interface HotjarOptions {
+    /**
+     * Your Hotjar site ID.
+     * @example `1234567`
+     */
+    siteId: number | string;
+    /**
+     * Hotjar script version.
+     * @default 6
+     */
+    version?: number;
+    /** Hotjar loader URL. */
+    scriptUrl?: string;
+}
+/**
+ * Creates a Hotjar script.
+ *
+ * @param options - The options for the Hotjar script.
+ * @returns The Hotjar script configuration.
+ *
+ * @example
+ * ```ts
+ * import { hotjar } from '@c15t/scripts/hotjar';
+ *
+ * hotjar({ siteId: 1234567 });
+ * ```
+ */
+export declare function hotjar({ siteId, version, scriptUrl, }: HotjarOptions): Script;

package/dist-types/vendors/analytics/logrocket.d.ts

@@ -0,0 +1,101 @@
+import type { Script } from 'c15t';
+declare global {
+    interface Window {
+        LogRocket?: {
+            init: (appId: string, options?: Record<string, unknown>) => void;
+            identify?: (id: string, traits?: Record<string, unknown>) => void;
+            track?: (event: string, properties?: Record<string, unknown>) => void;
+            getSessionURL?: (callback: (sessionUrl: string) => void) => void;
+            start?: () => void;
+            startNewSession?: () => void;
+            uninstall?: () => void;
+        };
+    }
+}
+/**
+ * LogRocket vendor manifest.
+ *
+ * Loads the browser SDK and initializes it after the loader fires its `load`
+ * event. LogRocket does not document a consent opt-out or stop-recording API
+ * for the web SDK, so c15t gates the loader on measurement consent and unloads
+ * the script element when that consent is revoked.
+ */
+export declare const logRocketManifest: {
+    readonly kind: "c15t.vendor-manifest";
+    readonly schemaVersion: 1;
+    readonly vendor: 'logrocket';
+    readonly category: 'measurement';
+    readonly install: [{
+        readonly type: 'loadScript';
+        readonly src: '{{scriptUrl}}';
+        readonly attributes: {
+            readonly crossorigin: 'anonymous';
+        };
+    }];
+    readonly afterLoad: [{
+        readonly type: 'callGlobal';
+        readonly global: 'LogRocket';
+        readonly method: 'init';
+        readonly args: ["{{appId}}", "{{initOptions}}"];
+    }];
+};
+export interface LogRocketOptions {
+    /**
+     * Your LogRocket app ID in `org-slug/app-slug` format.
+     */
+    appId: string;
+    /**
+     * LogRocket init options passed as the second `LogRocket.init()` argument.
+     *
+     * The manifest engine serializes this object as a template variable, so use
+     * JSON-serializable values only (no functions, class instances, prototypes,
+     * `Map`, `Set`, or other non-JSON types).
+     */
+    initOptions?: Record<string, unknown>;
+    /**
+     * Custom LogRocket loader URL.
+     * @default 'https://cdn.logrocket.io/LogRocket.min.js'
+     */
+    scriptUrl?: string;
+    /**
+     * Proxied URL for LogRocket's asynchronously loaded logger bundle.
+     *
+     * LogRocket's proxy setup requires `window._lrAsyncScript` in addition to
+     * the main `scriptUrl`, because the SDK chain-loads its logger bundle from
+     * this location. Only needed when proxying traffic through your own
+     * domain.
+     *
+     * @see https://docs.logrocket.com/docs/proxying-traffic-through-your-own-domain
+     */
+    asyncScriptUrl?: string;
+}
+/**
+ * Creates a LogRocket script.
+ *
+ * @see https://docs.logrocket.com/reference/init
+ *
+ * @param options - The options for the LogRocket script.
+ * @returns The LogRocket script.
+ * @throws {Error} When `appId` is missing, empty, or not in `org/app` format.
+ * Provide the app ID from LogRocket Project Setup to prevent this error.
+ *
+ * @remarks
+ * LogRocket records session replay and monitoring data. Configure LogRocket's
+ * privacy and sanitization options before deployment so sensitive DOM, input,
+ * network, or application state data is excluded from recordings.
+ *
+ * @example
+ * ```ts
+ * import { logRocket } from '@c15t/scripts/logrocket';
+ *
+ * logRocket({
+ * 	appId: 'org-slug/app-slug',
+ * 	initOptions: {
+ * 		dom: {
+ * 			inputSanitizer: true,
+ * 		},
+ * 	},
+ * });
+ * ```
+ */
+export declare function logRocket(options: LogRocketOptions): Script;

package/dist-types/vendors/analytics/matomo-analytics.d.ts

@@ -0,0 +1,41 @@
+import type { Script } from 'c15t';
+import { type VendorManifest } from '../../types';
+declare global {
+    interface Window {
+        _paq?: unknown[];
+    }
+}
+export declare const matomoAnalyticsManifest: VendorManifest;
+export interface MatomoAnalyticsOptions {
+    /** Your Matomo site ID. */
+    siteId?: string | number;
+    /** Your Matomo base URL, for example `https://analytics.example.com`. */
+    matomoUrl?: string;
+    /** Your Matomo Cloud identifier, for example `my-site.matomo.cloud`. */
+    cloudId?: string;
+    /** Optional explicit tracker endpoint override. */
+    trackerUrl?: string;
+    /** Optional explicit script URL override. */
+    scriptUrl?: string;
+    /** Queue `enableLinkTracking`. */
+    enableLinkTracking?: boolean;
+    /** Queue `disableCookies`. */
+    disableCookies?: boolean;
+    /** Queue an initial `trackPageView`. */
+    trackPageView?: boolean;
+    /** Default Matomo consent state (`required` blocks, `given` starts enabled). */
+    defaultConsent?: 'required' | 'given';
+}
+/**
+ * Creates a Matomo Analytics script.
+ *
+ * @param options - The options for the Matomo Analytics script.
+ * @returns The Matomo Analytics script configuration.
+ * @throws {Error} Throws
+ * `'matomoAnalytics requires \`matomoUrl\`, \`cloudId\`, or explicit \`trackerUrl\` and \`scriptUrl\` values.'`
+ * when either resolved `trackerUrl` or `scriptUrl` is missing (for example,
+ * when neither `matomoUrl` nor `cloudId` is provided and explicit
+ * `trackerUrl`/`scriptUrl` values are not supplied). Provide `matomoUrl`, or
+ * provide both explicit `trackerUrl` and `scriptUrl`.
+ */
+export declare function matomoAnalytics(options?: MatomoAnalyticsOptions): Script;

package/dist-types/vendors/analytics/microsoft-clarity.d.ts

@@ -0,0 +1,98 @@
+import type { Script } from 'c15t';
+/**
+ * Microsoft Clarity Consent V2 storage state.
+ *
+ * Clarity accepts string consent values instead of booleans for its granular
+ * `ad_Storage` and `analytics_Storage` channels.
+ */
+export type ClarityConsentState = 'granted' | 'denied';
+/**
+ * Consent V2 payload sent to Microsoft Clarity.
+ *
+ * c15t maps `marketing` consent to `ad_Storage` and `measurement` consent to
+ * `analytics_Storage`.
+ */
+export interface ClarityConsentV2Payload {
+    ad_Storage: ClarityConsentState;
+    analytics_Storage: ClarityConsentState;
+}
+/**
+ * Optional boot-time consent override accepted by the Clarity helper.
+ *
+ * Booleans apply the same value to both Clarity Consent V2 channels. Object
+ * values may use Clarity keys or c15t category aliases and are merged over the
+ * current c15t consent state.
+ */
+export type ClarityConsentValue = boolean | Partial<Record<keyof ClarityConsentV2Payload | 'ad_storage' | 'analytics_storage' | 'marketing' | 'measurement' | 'analytics', ClarityConsentState | boolean>>;
+type ClarityFunction = {
+    (command: 'consent', value?: boolean): void;
+    (command: 'consentv2', value: ClarityConsentV2Payload): void;
+    (command: 'event', value: string): void;
+    (command: 'identify', id: string, session?: string, page?: string): unknown;
+    (command: 'set', key: string, value: string | string[]): void;
+    (command: 'start', options?: Record<string, unknown>): void;
+    (command: 'upgrade', reason: string): void;
+    (command: string, ...args: unknown[]): unknown;
+};
+declare global {
+    interface Window {
+        clarity?: ClarityFunction & {
+            q?: unknown[][];
+        };
+    }
+}
+/**
+ * Microsoft Clarity vendor manifest.
+ *
+ * Seeds the global queue stub before loading the vendor bundle and uses
+ * Clarity's Consent V2 API for granular analytics and ad storage transitions.
+ */
+export declare const clarityManifest: {
+    readonly kind: "c15t.vendor-manifest";
+    readonly schemaVersion: 1;
+    readonly vendor: 'microsoft-clarity';
+    readonly category: 'measurement';
+    readonly persistAfterConsentRevoked: true;
+    readonly bootstrap: [{
+        readonly type: 'defineStubFunction';
+        readonly name: 'clarity';
+        readonly queue: {
+            readonly property: 'q';
+        };
+        readonly queueFormat: 'array';
+        readonly ifUndefined: true;
+    }];
+    readonly install: [{
+        readonly type: 'loadScript';
+        readonly src: '{{scriptUrl}}';
+        readonly async: true;
+    }];
+};
+export interface ClarityOptions {
+    /**
+     * Your Microsoft Clarity project ID.
+     * @example `abcdef1234`
+     */
+    id: string;
+    /**
+     * Optional initial Consent V2 value queued before the script loads.
+     *
+     * By default, c15t maps `measurement` to `analytics_Storage` and `marketing`
+     * to `ad_Storage`. Pass this only when boot-time consent must override the
+     * current c15t consent state.
+     */
+    defaultConsent?: ClarityConsentValue;
+    /** Clarity loader URL. */
+    scriptUrl?: string;
+}
+/**
+ * Creates a Microsoft Clarity script.
+ *
+ * @param options - The options for the Clarity script.
+ * @returns The Clarity script configuration.
+ * @throws {Error} When `options.id` is missing or invalid and no `scriptUrl`
+ * override is provided. Provide a valid Clarity project id string to prevent
+ * this error.
+ */
+export declare function clarity({ id, defaultConsent, scriptUrl, }: ClarityOptions): Script;
+export {};