@c15t/scripts 2.0.1 → 2.2.0-canary-20260727202135

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

@@ -0,0 +1,90 @@
+import type { Script } from 'c15t';
+declare global {
+    interface Window {
+        fathom?: {
+            blockTrackingForMe: () => void;
+            enableTrackingForMe: () => void;
+            trackEvent: (eventName: string, opts?: {
+                _value?: number;
+            }) => void;
+            trackGoal: (goalId: string, cents: number) => void;
+            trackPageview: (opts?: {
+                url: string;
+                referrer?: string;
+            }) => void;
+        };
+    }
+}
+/**
+ * Fathom Analytics vendor manifest.
+ *
+ * Configures Fathom via script `data-*` attributes. Fathom is a cookieless
+ * analytics product, so the script is consent-gated on `measurement` and
+ * unloaded when consent is revoked.
+ */
+export declare const fathomAnalyticsManifest: {
+    readonly kind: "c15t.vendor-manifest";
+    readonly schemaVersion: 1;
+    readonly vendor: 'fathom-analytics';
+    readonly category: 'measurement';
+    readonly install: [{
+        readonly type: 'loadScript';
+        readonly src: '{{scriptUrl}}';
+        readonly defer: true;
+        readonly attributes: {
+            readonly 'data-site': '{{site}}';
+            readonly 'data-spa': '{{spa}}';
+            readonly 'data-auto': '{{autoAttribute}}';
+            readonly 'data-canonical': '{{canonicalAttribute}}';
+            readonly 'data-honor-dnt': '{{honorDntAttribute}}';
+        };
+    }];
+};
+export interface FathomAnalyticsOptions {
+    /**
+     * Your Fathom Analytics site ID.
+     */
+    site: string;
+    /**
+     * The SPA tracking mode. When undefined, SPA auto-routing is disabled and
+     * the `data-spa` attribute is omitted.
+     */
+    spa?: 'auto' | 'history' | 'hash';
+    /**
+     * Automatically track page views.
+     */
+    auto?: boolean;
+    /**
+     * Enable canonical URL tracking.
+     */
+    canonical?: boolean;
+    /**
+     * Honor Do Not Track requests.
+     */
+    honorDnt?: boolean;
+    /**
+     * Custom loader URL.
+     * @default 'https://cdn.usefathom.com/script.js'
+     */
+    scriptUrl?: string;
+}
+/**
+ * Creates a Fathom Analytics script.
+ *
+ * @see https://usefathom.com/docs/script/script-settings
+ *
+ * @param options - The options for the Fathom Analytics script.
+ * @returns The Fathom Analytics script.
+ *
+ * @example
+ * ```ts
+ * import { fathomAnalytics } from '@c15t/scripts/fathom-analytics';
+ *
+ * fathomAnalytics({
+ *   site: 'SITE123',
+ *   spa: 'history',
+ *   canonical: true,
+ * });
+ * ```
+ */
+export declare function fathomAnalytics(options: FathomAnalyticsOptions): Script;

package/dist-types/{google-tag.d.ts → vendors/analytics/google-tag.d.ts}

@@ -12,44 +12,41 @@ declare global {
  * Uses the same Consent Mode v2 mapping.
  */
 export declare const gtagManifest: {
-    readonly vendor: "gtag";
-    readonly category: "{{category}}";
+    readonly kind: "c15t.vendor-manifest";
+    readonly schemaVersion: 1;
+    readonly vendor: 'gtag';
+    readonly category: '{{category}}';
     readonly alwaysLoad: true;
     readonly persistAfterConsentRevoked: true;
     readonly bootstrap: [{
-        readonly type: "setGlobal";
-        readonly name: "dataLayer";
+        readonly type: 'setGlobal';
+        readonly name: 'dataLayer';
         readonly value: readonly [];
         readonly ifUndefined: true;
     }, {
-        readonly type: "defineQueueFunction";
-        readonly name: "gtag";
-        readonly queue: "dataLayer";
+        readonly type: 'defineQueueFunction';
+        readonly name: 'gtag';
+        readonly queue: 'dataLayer';
         readonly ifUndefined: true;
     }];
     readonly install: [{
-        readonly type: "callGlobal";
-        readonly global: "gtag";
-        readonly args: ["js", "{{loadTime}}"];
+        readonly type: 'callGlobal';
+        readonly global: 'gtag';
+        readonly args: ["js", {
+            readonly kind: "c15t.runtime-value";
+            readonly value: 'date';
+        }];
     }, {
-        readonly type: "callGlobal";
-        readonly global: "gtag";
+        readonly type: 'callGlobal';
+        readonly global: 'gtag';
         readonly args: ["config", "{{id}}"];
     }, {
-        readonly type: "loadScript";
-        readonly src: "https://www.googletagmanager.com/gtag/js?id={{id}}";
+        readonly type: 'loadScript';
+        readonly src: 'https://www.googletagmanager.com/gtag/js?id={{id}}';
         readonly async: true;
     }];
-    readonly consentMapping: {
-        readonly necessary: ["security_storage"];
-        readonly functionality: ["functionality_storage"];
-        readonly measurement: ["analytics_storage"];
-        readonly marketing: ["ad_storage", "ad_user_data", "ad_personalization"];
-        readonly experience: ["personalization_storage"];
-    };
-    readonly consentSignal: "gtag";
-    readonly kind: "c15t.vendor-manifest";
-    readonly schemaVersion: 1;
+    readonly consentMapping: Record<string, string[]>;
+    readonly consentSignal: 'gtag';
 };
 export interface GtagOptions {
     /**

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 {};