@c15t/scripts 2.0.1 → 2.2.0-canary-20260727202135

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

@@ -0,0 +1,113 @@
+import type { Script } from 'c15t';
+declare global {
+    interface Window {
+        mixpanel?: {
+            init: (token: string, config?: Record<string, unknown>) => void;
+            track: (event: string, properties?: Record<string, unknown>) => void;
+            identify: (distinctId: string) => void;
+            reset: () => void;
+            register: (properties: Record<string, unknown>) => void;
+            opt_in_tracking: () => void;
+            opt_out_tracking: () => void;
+            /** Snippet version marker consumed by `init_from_snippet`. */
+            __SV?: number;
+            /** Pending `[token, config, instanceName]` init tuples consumed at SDK load. */
+            _i?: unknown[][];
+        };
+    }
+}
+/**
+ * Mixpanel vendor manifest.
+ *
+ * Implements the official snippet contract: the stub array carries the
+ * snippet version marker (`__SV`) and the pending `[token, config, 'mixpanel']`
+ * init tuple in `_i`, which `mixpanel-2-latest.min.js` consumes at load time via
+ * `init_from_snippet`. Without `__SV` the SDK logs "Mixpanel error: Version
+ * mismatch" and never initializes, silently dropping queued calls.
+ *
+ * Mixpanel can stay loaded across consent changes and toggle tracking with its
+ * own opt-in and opt-out APIs.
+ */
+export declare const mixpanelAnalyticsManifest: {
+    readonly kind: "c15t.vendor-manifest";
+    readonly schemaVersion: 1;
+    readonly vendor: 'mixpanel-analytics';
+    readonly category: 'measurement';
+    readonly alwaysLoad: true;
+    readonly install: [{
+        readonly type: 'setGlobal';
+        readonly name: 'mixpanel';
+        readonly value: readonly [];
+        readonly ifUndefined: true;
+    }, {
+        readonly type: 'setGlobalPath';
+        readonly path: ["mixpanel", "__SV"];
+        readonly value: 1.2;
+    }, {
+        readonly type: 'setGlobalPath';
+        readonly path: ["mixpanel", "_i"];
+        readonly value: readonly [readonly ["{{token}}", "{{initOptions}}", "mixpanel"]];
+    }, {
+        readonly type: 'defineQueueMethods';
+        readonly target: 'mixpanel';
+        readonly methods: ["track", "identify", "reset", "register", "opt_in_tracking", "opt_out_tracking"];
+    }, {
+        readonly type: 'loadScript';
+        readonly src: '{{scriptUrl}}';
+        readonly async: true;
+    }];
+    readonly onLoadGranted: [{
+        readonly type: 'callGlobal';
+        readonly global: 'mixpanel';
+        readonly method: 'opt_in_tracking';
+    }];
+    readonly onLoadDenied: [{
+        readonly type: 'callGlobal';
+        readonly global: 'mixpanel';
+        readonly method: 'opt_out_tracking';
+    }];
+    readonly onConsentGranted: [{
+        readonly type: 'callGlobal';
+        readonly global: 'mixpanel';
+        readonly method: 'opt_in_tracking';
+    }];
+    readonly onConsentDenied: [{
+        readonly type: 'callGlobal';
+        readonly global: 'mixpanel';
+        readonly method: 'opt_out_tracking';
+    }];
+};
+export interface MixpanelAnalyticsOptions {
+    /** Your Mixpanel project token. */
+    token: string;
+    /**
+     * Mixpanel init options passed after the library loads.
+     *
+     * 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). Named instances and nested
+     * `people.*` queue helpers are intentionally out of scope for this helper.
+     */
+    initOptions?: Record<string, unknown>;
+    /** Mixpanel loader URL. */
+    scriptUrl?: string;
+}
+/**
+ * Creates a Mixpanel Analytics script.
+ *
+ * @param options - The options for the Mixpanel Analytics script.
+ * @returns The Mixpanel Analytics script configuration.
+ * @throws {Error} Throws when `token` is not a non-empty 32-character
+ * hexadecimal Mixpanel project token.
+ *
+ * @example
+ * ```ts
+ * import { mixpanelAnalytics } from '@c15t/scripts/mixpanel-analytics';
+ *
+ * const script = mixpanelAnalytics({
+ * 	token: '1234567890abcdef1234567890abcdef',
+ * 	initOptions: { debug: true },
+ * });
+ * ```
+ */
+export declare function mixpanelAnalytics({ token, initOptions, scriptUrl, }: MixpanelAnalyticsOptions): Script;

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

@@ -0,0 +1,96 @@
+import type { Script } from 'c15t';
+declare global {
+    interface Window {
+        pirsch?: (eventName: string, options?: {
+            duration?: number;
+            meta?: Record<string, unknown>;
+            non_interactive?: boolean;
+        }) => Promise<null | undefined>;
+        pirschClearSession?: () => void;
+        pirschInit?: () => void;
+        pirschNotFound?: () => void;
+    }
+}
+/**
+ * Pirsch vendor manifest.
+ *
+ * Configures Pirsch through script attributes. Pirsch finds the script element
+ * by a fixed element id, so the `id` attribute is part of the loader contract.
+ */
+export declare const pirschManifest: {
+    readonly kind: "c15t.vendor-manifest";
+    readonly schemaVersion: 1;
+    readonly vendor: 'pirsch';
+    readonly category: 'measurement';
+    readonly install: [{
+        readonly type: 'loadScript';
+        readonly src: '{{scriptUrl}}';
+        readonly defer: true;
+        readonly attributes: {
+            readonly id: '{{scriptElementId}}';
+            readonly 'data-code': '{{identificationCode}}';
+            readonly 'data-domain': '{{domain}}';
+            readonly 'data-dev': '{{dev}}';
+            readonly 'data-hit-endpoint': '{{hitEndpoint}}';
+            readonly 'data-event-endpoint': '{{eventEndpoint}}';
+            readonly 'data-disable-page-views': '{{disablePageViews}}';
+        };
+    }];
+};
+export interface PirschOptions {
+    /**
+     * Your Pirsch identification code.
+     */
+    identificationCode: string;
+    /**
+     * Additional dashboard domains, optionally including per-domain codes.
+     *
+     * Arrays are serialized as Pirsch's comma-separated `data-domain` value.
+     */
+    domain?: string | string[];
+    /**
+     * Enable localhost testing by rewriting the tracked hostname.
+     */
+    dev?: string;
+    /**
+     * Custom pageview endpoint.
+     */
+    hitEndpoint?: string;
+    /**
+     * Custom event endpoint.
+     */
+    eventEndpoint?: string;
+    /**
+     * Disable automatic pageview tracking.
+     */
+    disablePageViews?: boolean;
+    /**
+     * Load Pirsch's extended script variant.
+     */
+    extended?: boolean;
+    /**
+     * Custom loader URL.
+     */
+    scriptUrl?: string;
+}
+/**
+ * Creates a Pirsch Analytics script.
+ *
+ * @see https://docs.pirsch.io/get-started/frontend-integration
+ *
+ * @param options - The options for the Pirsch script.
+ * @returns The Pirsch script.
+ * @throws {Error} When `identificationCode` is missing, empty, or invalid.
+ * Provide a valid non-empty `identificationCode` string to prevent this error.
+ *
+ * @example
+ * ```ts
+ * import { pirsch } from '@c15t/scripts/pirsch';
+ *
+ * pirsch({
+ *   identificationCode: 'YOUR_IDENTIFICATION_CODE',
+ *   domain: 'rollup.example.com:ROLLUP_CODE',
+ * });
+ * ```
+ */
+export declare function pirsch(options: PirschOptions): Script;

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

@@ -0,0 +1,122 @@
+import type { Script } from 'c15t';
+export type PlausibleExtension = 'hash' | 'outbound-links' | 'file-downloads' | 'tagged-events' | 'revenue' | 'pageview-props' | 'compat' | 'local' | 'manual';
+export interface PlausibleInitOptions {
+    customProperties?: Record<string, unknown>;
+    endpoint?: string;
+    fileDownloads?: {
+        fileExtensions?: string[];
+    };
+    hashBasedRouting?: boolean;
+    autoCapturePageviews?: boolean;
+    captureOnLocalhost?: boolean;
+}
+declare global {
+    interface Window {
+        plausible?: ((...args: unknown[]) => void) & {
+            o?: PlausibleInitOptions;
+            q?: unknown[][];
+        };
+    }
+}
+/**
+ * Plausible Analytics vendor manifest.
+ *
+ * Seeds a small queue stub so early `window.plausible(...)` calls can be
+ * buffered before the real tracker loads. Plausible is cookieless and only
+ * tracks page views, so the script is gated on `measurement` consent and is
+ * unloaded when consent is revoked.
+ */
+export declare const plausibleAnalyticsManifest: {
+    readonly kind: "c15t.vendor-manifest";
+    readonly schemaVersion: 1;
+    readonly vendor: 'plausible-analytics';
+    readonly category: 'measurement';
+    readonly bootstrap: [{
+        readonly type: 'defineStubFunction';
+        readonly name: 'plausible';
+        readonly queue: {
+            readonly property: 'q';
+        };
+        readonly queueFormat: 'array';
+        readonly properties: {
+            readonly o: '{{initOptions}}';
+        };
+        readonly ifUndefined: true;
+    }];
+    readonly install: [{
+        readonly type: 'loadScript';
+        readonly src: '{{scriptUrl}}';
+        readonly defer: true;
+        readonly attributes: {
+            readonly 'data-domain': '{{domain}}';
+            readonly 'data-api': '{{apiAttribute}}';
+        };
+    }];
+};
+export interface PlausibleAnalyticsOptions {
+    /**
+     * Unique Plausible script ID for the new script format.
+     */
+    scriptId?: string;
+    /**
+     * Legacy domain-based site identifier.
+     */
+    domain?: string;
+    /**
+     * Legacy script extensions.
+     */
+    extension?: PlausibleExtension | PlausibleExtension[];
+    /**
+     * Properties tracked with each pageview.
+     */
+    customProperties?: Record<string, unknown>;
+    /**
+     * Custom tracking endpoint.
+     */
+    endpoint?: string;
+    /**
+     * File download tracking configuration.
+     */
+    fileDownloads?: {
+        fileExtensions?: string[];
+    };
+    /**
+     * Enable hash-based routing support.
+     */
+    hashBasedRouting?: boolean;
+    /**
+     * Disable automatic pageview capture when set to `false`.
+     */
+    autoCapturePageviews?: boolean;
+    /**
+     * Enable tracking on localhost.
+     */
+    captureOnLocalhost?: boolean;
+    /**
+     * Custom loader URL.
+     */
+    scriptUrl?: string;
+}
+/**
+ * Creates a Plausible Analytics script.
+ *
+ * Models Plausible's queue bootstrap and loader attributes as a c15t-managed
+ * script. Supports both the new `scriptId`-based loader and the legacy
+ * `domain` + extension-based loader.
+ *
+ * @see https://plausible.io/docs/script-extensions
+ *
+ * @param options - The options for the Plausible Analytics script.
+ * @returns The Plausible Analytics script.
+ *
+ * @example
+ * ```ts
+ * import { plausibleAnalytics } from '@c15t/scripts/plausible-analytics';
+ *
+ * plausibleAnalytics({
+ *   domain: 'example.com',
+ *   extension: ['file-downloads', 'outbound-links'],
+ * });
+ * ```
+ */
+export declare function plausibleAnalytics(options: PlausibleAnalyticsOptions): Script;

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

@@ -0,0 +1,154 @@
+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;
+            capture: (event: string, properties?: Record<string, unknown>) => void;
+        };
+    }
+}
+export type PosthogRegion = 'eu' | 'us';
+export type PosthogLoadMode = 'always' | 'after-consent' | 'disabled';
+/**
+ * PostHog vendor manifest.
+ *
+ * By default, PostHog manages its own consent internally via
+ * opt_in/opt_out capturing. The helper can also gate loading until
+ * measurement consent is granted.
+ */
+export declare const posthogManifest: {
+    readonly kind: "c15t.vendor-manifest";
+    readonly schemaVersion: 1;
+    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: 'capture';
+            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': '{{uiHost}}';
+        };
+    }];
+    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';
+    }];
+};
+export interface PosthogConsentOptions {
+    /**
+     * Your posthog id, begins with 'phc_'.
+     */
+    id: string;
+    /**
+     * PostHog Cloud region used to derive hosts when explicit host options are not
+     * provided.
+     * @default 'eu'
+     */
+    region?: PosthogRegion;
+    /**
+     * Your posthog api host.
+     * @default 'https://eu.i.posthog.com'
+     */
+    apiHost?: string;
+    /**
+     * Your PostHog UI host. Defaults to the UI host for the selected region or
+     * inferred API host region.
+     */
+    uiHost?: string;
+    /** The PostHog array loader URL. */
+    scriptUrl?: string;
+    /**
+     * How c15t should load the PostHog script.
+     *
+     * - `always`: load immediately and synchronize consent through PostHog APIs.
+     * - `after-consent`: wait for measurement consent before loading PostHog.
+     * - `disabled`: return an inert callback-only script with no network request.
+     *
+     * @default 'always'
+     */
+    loadMode?: PosthogLoadMode;
+    /** PostHog init options passed to `posthog.init(...)`. */
+    initOptions?: Record<string, unknown>;
+}
+/**
+ * Creates a c15t PostHog script helper.
+ *
+ * The `posthog()` helper uses `region` to resolve the PostHog API, UI, and
+ * bootstrap script hosts. By default, `loadMode: 'always'` loads PostHog
+ * immediately and syncs consent with `posthog.opt_in_capturing()` or
+ * `posthog.opt_out_capturing()`.
+ *
+ * With `loadMode: 'after-consent'`, the script is consent-gated and c15t calls
+ * `posthog.opt_in_capturing()` or `posthog.opt_out_capturing()` after load
+ * based on the user's measurement consent. With `loadMode: 'disabled'`, no
+ * PostHog script is loaded and no `posthog.opt_in_capturing()` or
+ * `posthog.opt_out_capturing()` calls are made.
+ *
+ * Edge case: `loadMode: 'disabled'` skips consent-related flows entirely; use it
+ * only when consumers manage PostHog loading and consent externally.
+ *
+ * @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/vendors/analytics/promptwatch.d.ts

@@ -0,0 +1,36 @@
+import type { Script } from 'c15t';
+/**
+ * Promptwatch vendor manifest.
+ *
+ * Loads the Promptwatch client with your project id on the script element.
+ */
+export declare const promptwatchManifest: {
+    readonly kind: "c15t.vendor-manifest";
+    readonly schemaVersion: 1;
+    readonly vendor: 'promptwatch';
+    readonly category: 'measurement';
+    readonly install: [{
+        readonly type: 'loadScript';
+        readonly src: '{{scriptUrl}}';
+        readonly async: true;
+        readonly attributes: {
+            readonly 'data-project-id': '{{projectId}}';
+        };
+    }];
+};
+export interface PromptwatchOptions {
+    /** Your Promptwatch project id (UUID from the Promptwatch dashboard). */
+    projectId: string;
+    /** Promptwatch client script URL. */
+    scriptUrl?: string;
+}
+/**
+ * Promptwatch analytics script for AI traffic and usage insights.
+ *
+ * @param options - Promptwatch integration options.
+ * @param options.projectId - Promptwatch project id from your dashboard.
+ * @param options.scriptUrl - Optional custom script URL override.
+ * @throws {Error} When `projectId` is empty or only whitespace.
+ * @returns The Promptwatch script configuration.
+ */
+export declare function promptwatch({ projectId, scriptUrl, }: PromptwatchOptions): Script;