@c15t/scripts 2.1.0 → 2.2.0-canary-20260804162155

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

@@ -0,0 +1,316 @@
+import type { Script } from 'c15t';
+/**
+ * Default Heap config-loader base URL.
+ *
+ * Heap's current web installation snippet loads account configuration from a
+ * per-environment `heap_config.js` URL. That configuration then chain-loads the
+ * versioned heap.js runtime selected for the environment.
+ */
+export declare const DEFAULT_HEAP_CONFIG_BASE_URL = "https://cdn.us.heap-api.com/config";
+/**
+ * Current heap.js v5 method stubs from Heap's official web snippet.
+ *
+ * These methods do not push `[method, args]` tuples into `window.heap`. They
+ * push `{ name, fn }` records into `window.heapReadyCb`; each callback replays
+ * the original call against the loaded `window.heap` runtime.
+ */
+export declare const HEAP_QUEUE_METHODS: readonly ['init', 'startTracking', 'stopTracking', 'track', 'resetIdentity', 'identify', 'identifyHashed', 'getSessionId', 'getUserId', 'getIdentity', 'addUserProperties', 'addEventProperties', 'removeEventProperty', 'clearEventProperties', 'addAccountProperties', 'addAdapter', 'addTransformer', 'addTransformerFn', 'onReady', 'addPageviewProperties', 'removePageviewProperty', 'clearPageviewProperties', 'trackPageview'];
+type JsonPrimitive = string | number | boolean | null;
+type JsonValue = JsonPrimitive | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+type JsonRecord = {
+    [key: string]: JsonValue;
+};
+export interface HeapReadyCallback {
+    /** Heap method name captured by the pre-load snippet stub. */
+    name: (typeof HEAP_QUEUE_METHODS)[number];
+    /** Callback invoked by heap.js after the runtime is ready. */
+    fn: () => void;
+}
+/**
+ * Minimal public heap.js API exposed on `window.heap`.
+ *
+ * Before the real SDK loads, c15t creates an array-backed stub with these
+ * methods. The config loader calls `heap.init(envId, clientConfig,
+ * serverConfig)`, and heap.js drains `window.heapReadyCb` by invoking each
+ * stored callback.
+ */
+export interface HeapApi {
+    /** Environment/app id selected for this Heap installation. */
+    envId?: string;
+    /** Legacy alias used by some Heap runtime paths. */
+    appid?: string;
+    /** Client configuration passed into `heap.load()`. */
+    clientConfig?: JsonRecord;
+    /** Server configuration assigned by `heap_config.js` before heap.js loads. */
+    serverConfig?: Record<string, unknown>;
+    /**
+     * Initializes the heap.js runtime.
+     *
+     * @param envId - Heap environment/app id.
+     * @param clientConfig - Client-side configuration options.
+     * @param serverConfig - Server-side configuration loaded by Heap.
+     * @returns Vendor-specific runtime result.
+     */
+    init: (envId: string, clientConfig?: JsonRecord, serverConfig?: Record<string, unknown>) => unknown;
+    /**
+     * Starts Heap autocapture and event delivery.
+     *
+     * @returns Vendor-specific runtime result.
+     */
+    startTracking: () => unknown;
+    /**
+     * Stops Heap tracking for the current runtime session.
+     *
+     * @returns Vendor-specific runtime result.
+     */
+    stopTracking: () => unknown;
+    /**
+     * Tracks a custom Heap event.
+     *
+     * @param event - Event name to record.
+     * @param properties - Optional event properties.
+     * @returns Vendor-specific runtime result.
+     */
+    track: (event: string, properties?: Record<string, unknown>) => unknown;
+    /**
+     * Clears the current Heap identity.
+     *
+     * @returns Vendor-specific runtime result.
+     */
+    resetIdentity: () => unknown;
+    /**
+     * Identifies the current user.
+     *
+     * @param identity - Stable user identity.
+     * @returns Vendor-specific runtime result.
+     */
+    identify: (identity: string) => unknown;
+    /**
+     * Identifies the current user with a hashed identity.
+     *
+     * @param identity - Hashed user identity.
+     * @returns Vendor-specific runtime result.
+     */
+    identifyHashed: (identity: string) => unknown;
+    /**
+     * Reads the current Heap session id.
+     *
+     * @returns Current session id when available.
+     */
+    getSessionId: () => unknown;
+    /**
+     * Reads the current Heap user id.
+     *
+     * @returns Current Heap user id when available.
+     */
+    getUserId: () => unknown;
+    /**
+     * Reads the current Heap identity.
+     *
+     * @returns Current identity when available.
+     */
+    getIdentity: () => unknown;
+    /**
+     * Adds properties to the current user.
+     *
+     * @param properties - User properties to merge.
+     * @returns Vendor-specific runtime result.
+     */
+    addUserProperties: (properties: Record<string, unknown>) => unknown;
+    /**
+     * Adds properties to every subsequent event.
+     *
+     * @param properties - Event properties to merge.
+     * @returns Vendor-specific runtime result.
+     */
+    addEventProperties: (properties: Record<string, unknown>) => unknown;
+    /**
+     * Removes a single persisted event property.
+     *
+     * @param property - Event property name to remove.
+     * @returns Vendor-specific runtime result.
+     */
+    removeEventProperty: (property: string) => unknown;
+    /**
+     * Clears persisted event properties.
+     *
+     * @returns Vendor-specific runtime result.
+     */
+    clearEventProperties: () => unknown;
+    /**
+     * Adds properties to the current account.
+     *
+     * @param properties - Account properties to merge.
+     * @returns Vendor-specific runtime result.
+     */
+    addAccountProperties: (properties: Record<string, unknown>) => unknown;
+    /**
+     * Adds a Heap adapter.
+     *
+     * @param adapter - Adapter implementation accepted by heap.js.
+     * @returns Vendor-specific runtime result.
+     */
+    addAdapter: (adapter: unknown) => unknown;
+    /**
+     * Adds a Heap event transformer.
+     *
+     * @param transformer - Transformer implementation accepted by heap.js.
+     * @returns Vendor-specific runtime result.
+     */
+    addTransformer: (transformer: unknown) => unknown;
+    /**
+     * Adds a Heap transformer function.
+     *
+     * @param transformer - Transformer callback accepted by heap.js.
+     * @returns Vendor-specific runtime result.
+     */
+    addTransformerFn: (transformer: (...args: unknown[]) => unknown) => unknown;
+    /**
+     * Registers a callback for Heap readiness.
+     *
+     * @param callback - Function to call once Heap is ready.
+     * @returns Vendor-specific runtime result.
+     */
+    onReady: (callback: () => void) => unknown;
+    /**
+     * Adds properties to subsequent pageview events.
+     *
+     * @param properties - Pageview properties to merge.
+     * @returns Vendor-specific runtime result.
+     */
+    addPageviewProperties: (properties: Record<string, unknown>) => unknown;
+    /**
+     * Removes a single persisted pageview property.
+     *
+     * @param property - Pageview property name to remove.
+     * @returns Vendor-specific runtime result.
+     */
+    removePageviewProperty: (property: string) => unknown;
+    /**
+     * Clears persisted pageview properties.
+     *
+     * @returns Vendor-specific runtime result.
+     */
+    clearPageviewProperties: () => unknown;
+    /**
+     * Tracks a pageview event.
+     *
+     * @param properties - Optional pageview properties.
+     * @returns Vendor-specific runtime result.
+     */
+    trackPageview: (properties?: Record<string, unknown>) => unknown;
+}
+declare global {
+    interface Window {
+        heap?: HeapApi;
+        heapReadyCb?: HeapReadyCallback[];
+    }
+}
+/**
+ * Heap vendor manifest.
+ *
+ * Reproduces the heap.js v5 snippet contract consumed by
+ * `heap_config.js`: `window.heapReadyCb` receives `{ name, fn }` callback
+ * records, `window.heap` stores `envId`/`appid` and `clientConfig`, and the
+ * Heap configuration script chain-loads the versioned heap.js runtime.
+ *
+ * Heap does not document a browser opt-out API that can make an already loaded
+ * runtime inert for c15t's purposes, so c15t gates the load on `measurement`
+ * consent and unloads the script when that consent is revoked.
+ */
+export declare const heapManifest: {
+    readonly kind: "c15t.vendor-manifest";
+    readonly schemaVersion: 1;
+    readonly vendor: 'heap';
+    readonly category: 'measurement';
+    readonly install: [{
+        readonly type: 'setGlobal';
+        readonly name: 'heapReadyCb';
+        readonly value: readonly [];
+        readonly ifUndefined: true;
+    }, {
+        readonly type: 'setGlobal';
+        readonly name: 'heap';
+        readonly value: readonly [];
+        readonly ifUndefined: true;
+    }, {
+        readonly type: 'setGlobalPath';
+        readonly path: ["heap", "envId"];
+        readonly value: '{{envId}}';
+    }, {
+        readonly type: 'setGlobalPath';
+        readonly path: ["heap", "appid"];
+        readonly value: '{{envId}}';
+    }, {
+        readonly type: 'setGlobalPath';
+        readonly path: ["heap", "clientConfig"];
+        readonly value: '{{clientConfig}}';
+    }, {
+        readonly type: 'defineQueueMethods';
+        readonly target: 'heap';
+        readonly queue: {
+            readonly global: 'heapReadyCb';
+        };
+        readonly queueFormat: 'callback';
+        readonly methods: ["init", "startTracking", "stopTracking", "track", "resetIdentity", "identify", "identifyHashed", "getSessionId", "getUserId", "getIdentity", "addUserProperties", "addEventProperties", "removeEventProperty", "clearEventProperties", "addAccountProperties", "addAdapter", "addTransformer", "addTransformerFn", "onReady", "addPageviewProperties", "removePageviewProperty", "clearPageviewProperties", "trackPageview"];
+    }, {
+        readonly type: 'loadScript';
+        readonly src: '{{scriptUrl}}';
+        readonly async: true;
+    }];
+};
+export interface HeapOptions {
+    /**
+     * Heap environment/app id.
+     *
+     * Heap's app UI commonly shows this as a numeric string. c15t validates only
+     * that the value is a non-empty string after trimming because Heap's public
+     * install docs describe it generically as `YOUR_APP_ID`.
+     */
+    envId: string;
+    /**
+     * Optional heap.js client configuration.
+     *
+     * Values must be JSON-serializable: plain objects, arrays, strings, finite
+     * numbers, booleans, and `null`. c15t adds `shouldFetchServerConfig: false`
+     * to match Heap's current web installation snippet.
+     */
+    clientConfig?: Record<string, unknown>;
+    /**
+     * Optional full Heap config-loader URL override.
+     *
+     * @default 'https://cdn.us.heap-api.com/config/{envId}/heap_config.js'
+     */
+    scriptUrl?: string;
+}
+/**
+ * Creates a Heap web analytics script.
+ *
+ * @see https://developers.heap.io/docs/web
+ *
+ * @param options - The options for the Heap script.
+ * @returns The Heap script configuration.
+ * @throws {Error} When `envId` is missing or only whitespace.
+ * @throws {TypeError} When `clientConfig` contains non-JSON values.
+ *
+ * @remarks
+ * Heap autocaptures interactions as soon as heap.js loads. c15t therefore
+ * gates the config loader on `measurement` consent and unloads the script when
+ * that consent is revoked.
+ *
+ * @example
+ * ```ts
+ * import { heap } from '@c15t/scripts/heap';
+ *
+ * const script = heap({
+ * 	envId: '123456789',
+ * 	clientConfig: {
+ * 		disableTextCapture: true,
+ * 	},
+ * });
+ * ```
+ */
+export declare function heap({ envId, clientConfig, scriptUrl }: HeapOptions): Script;
+export {};

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

@@ -17,31 +17,31 @@ declare global {
  * the vendor bundle.
  */
 export declare const hotjarManifest: {
-    readonly vendor: "hotjar";
-    readonly category: "measurement";
+    readonly kind: "c15t.vendor-manifest";
+    readonly schemaVersion: 1;
+    readonly vendor: 'hotjar';
+    readonly category: 'measurement';
     readonly install: [{
-        readonly type: "setGlobal";
-        readonly name: "_hjSettings";
+        readonly type: 'setGlobal';
+        readonly name: '_hjSettings';
         readonly value: {
-            readonly hjid: "{{siteId}}";
-            readonly hjsv: "{{version}}";
+            readonly hjid: '{{siteId}}';
+            readonly hjsv: '{{version}}';
         };
         readonly ifUndefined: true;
     }, {
-        readonly type: "defineStubFunction";
-        readonly name: "hj";
+        readonly type: 'defineStubFunction';
+        readonly name: 'hj';
         readonly queue: {
-            readonly property: "q";
+            readonly property: 'q';
         };
-        readonly queueFormat: "array";
+        readonly queueFormat: 'array';
         readonly ifUndefined: true;
     }, {
-        readonly type: "loadScript";
-        readonly src: "{{scriptUrl}}";
+        readonly type: 'loadScript';
+        readonly src: '{{scriptUrl}}';
         readonly async: true;
     }];
-    readonly kind: "c15t.vendor-manifest";
-    readonly schemaVersion: 1;
 };
 export interface HotjarOptions {
     /**