@c15t/scripts 2.0.1 → 2.1.0

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

@@ -0,0 +1,86 @@
+import type { Script } from 'c15t';
+export type ClarityConsentValue = boolean | Record<string, string>;
+type ClarityFunction = {
+    (command: 'consent', value?: ClarityConsentValue): 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[][];
+            v?: string;
+        };
+    }
+}
+/**
+ * Microsoft Clarity vendor manifest.
+ *
+ * Seeds the global queue stub before loading the vendor bundle and uses
+ * Clarity's consent API for simple granted and denied transitions.
+ */
+export declare const clarityManifest: {
+    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 properties: {
+            readonly v: "0.7.0";
+        };
+        readonly ifUndefined: true;
+    }];
+    readonly install: [{
+        readonly type: "loadScript";
+        readonly src: "{{scriptUrl}}";
+        readonly async: true;
+    }];
+    readonly onConsentGranted: [{
+        readonly type: "callGlobal";
+        readonly global: "clarity";
+        readonly args: ["consent", true];
+    }];
+    readonly onConsentDenied: [{
+        readonly type: "callGlobal";
+        readonly global: "clarity";
+        readonly args: ["consent", false];
+    }];
+    readonly kind: "c15t.vendor-manifest";
+    readonly schemaVersion: 1;
+};
+export interface ClarityOptions {
+    /**
+     * Your Microsoft Clarity project ID.
+     * @example `abcdef1234`
+     */
+    id: string;
+    /**
+     * Optional initial consent value queued before the script loads.
+     *
+     * Object-shaped advanced consent vectors are supported only for this initial
+     * boot-time value. Later c15t consent changes are mapped to simple booleans.
+     */
+    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 {};

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

@@ -0,0 +1,101 @@
+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;
+        };
+    }
+}
+/**
+ * Mixpanel vendor manifest.
+ *
+ * Mixpanel can stay loaded across consent changes and toggle tracking with its
+ * own opt-in and opt-out APIs.
+ */
+export declare const mixpanelAnalyticsManifest: {
+    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: "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 afterLoad: [{
+        readonly type: "callGlobal";
+        readonly global: "mixpanel";
+        readonly method: "init";
+        readonly args: ["{{token}}", "{{initOptions}}"];
+    }];
+    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";
+    }];
+    readonly kind: "c15t.vendor-manifest";
+    readonly schemaVersion: 1;
+};
+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/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 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}}";
+        };
+    }];
+    readonly kind: "c15t.vendor-manifest";
+    readonly schemaVersion: 1;
+};
+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/{posthog.d.ts → vendors/analytics/posthog.d.ts}

@@ -11,14 +11,18 @@ declare global {
             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.
  *
- * PostHog manages its own consent internally via opt_in/opt_out capturing.
- * The script always loads, and consent is toggled via the PostHog API.
+ * 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 vendor: "posthog";
@@ -35,6 +39,9 @@ export declare const posthogManifest: {
         readonly methods: [{
             readonly name: "init";
             readonly behavior: "noop";
+        }, {
+            readonly name: "capture";
+            readonly behavior: "noop";
         }, {
             readonly name: "opt_in_capturing";
             readonly behavior: "noop";
@@ -54,7 +61,7 @@ export declare const posthogManifest: {
         readonly attributes: {
             readonly crossorigin: "anonymous";
             readonly 'data-api-host': "{{apiHost}}";
-            readonly 'data-ui-host': "{{apiHost}}";
+            readonly 'data-ui-host': "{{uiHost}}";
         };
     }];
     readonly afterLoad: [{
@@ -91,19 +98,54 @@ 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>;
 }
 /**
- * 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.
+ * 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

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 vendor: "promptwatch";
+    readonly category: "measurement";
+    readonly install: [{
+        readonly type: "loadScript";
+        readonly src: "{{scriptUrl}}";
+        readonly async: true;
+        readonly attributes: {
+            readonly 'data-project-id': "{{projectId}}";
+        };
+    }];
+    readonly kind: "c15t.vendor-manifest";
+    readonly schemaVersion: 1;
+};
+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;

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

@@ -0,0 +1,82 @@
+import type { Script } from 'c15t';
+declare global {
+    interface Window {
+        rybbit?: {
+            clearUserId: () => void;
+            event: (name: string, properties?: Record<string, unknown>) => void;
+            getUserId: () => string | null;
+            identify: (userId: string) => void;
+            pageview: () => void;
+        };
+    }
+}
+/**
+ * Rybbit Analytics vendor manifest.
+ *
+ * Rybbit reads its configuration from script data attributes at load time.
+ */
+export declare const rybbitAnalyticsManifest: {
+    readonly vendor: "rybbit-analytics";
+    readonly category: "measurement";
+    readonly install: [{
+        readonly type: "loadScript";
+        readonly src: "{{scriptUrl}}";
+        readonly defer: true;
+        readonly attributes: {
+            readonly 'data-site-id': "{{siteId}}";
+            readonly 'data-auto-track-pageview': "{{autoTrackPageview}}";
+            readonly 'data-track-spa': "{{trackSpa}}";
+            readonly 'data-track-query': "{{trackQuery}}";
+            readonly 'data-track-outbound': "{{trackOutbound}}";
+            readonly 'data-track-errors': "{{trackErrors}}";
+            readonly 'data-session-replay': "{{sessionReplay}}";
+            readonly 'data-web-vitals': "{{webVitals}}";
+            readonly 'data-skip-patterns': "{{skipPatterns}}";
+            readonly 'data-mask-patterns': "{{maskPatterns}}";
+            readonly 'data-debounce': "{{debounce}}";
+            readonly 'data-api-key': "{{apiKey}}";
+        };
+    }];
+    readonly kind: "c15t.vendor-manifest";
+    readonly schemaVersion: 1;
+};
+export interface RybbitAnalyticsOptions {
+    /** Your Rybbit site ID. */
+    siteId: string | number;
+    /** Automatically track pageviews. */
+    autoTrackPageview?: boolean;
+    /** Enable SPA route tracking. */
+    trackSpa?: boolean;
+    /** Include query parameters in tracked URLs. */
+    trackQuery?: boolean;
+    /** Track outbound link clicks. */
+    trackOutbound?: boolean;
+    /** Track JavaScript errors. */
+    trackErrors?: boolean;
+    /** Enable session replay. */
+    sessionReplay?: boolean;
+    /** Enable Web Vitals tracking. */
+    webVitals?: boolean;
+    /** URL patterns to skip from tracking. */
+    skipPatterns?: string[];
+    /** URL patterns to mask in tracked data. */
+    maskPatterns?: string[];
+    /** Debounce interval for pageview tracking. */
+    debounce?: number;
+    /** API key for authenticated tracking. */
+    apiKey?: string;
+    /** Override the analytics host URL. */
+    analyticsHost?: string;
+    /** Custom loader URL. */
+    scriptUrl?: string;
+}
+/**
+ * Creates a Rybbit Analytics script.
+ *
+ * @param options - The options for the Rybbit Analytics script.
+ * @returns The Rybbit Analytics script.
+ * @throws {Error} Throws `rybbitAnalytics: missing siteId` when
+ * `options.siteId` is undefined, null, or trims to an empty string. Provide a
+ * valid non-empty site ID string to prevent this error.
+ */
+export declare function rybbitAnalytics(options: RybbitAnalyticsOptions): Script;

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

@@ -0,0 +1,158 @@
+import type { Script } from 'c15t';
+/**
+ * Public Segment Analytics.js API exposed on `window.analytics`.
+ *
+ * Use this interface when interacting with Segment calls queued before or after
+ * the client library is fully initialized.
+ *
+ * @example
+ * ```ts
+ * window.analytics.track('Signup', { plan: 'pro' });
+ * ```
+ */
+export interface SegmentApi {
+    /**
+     * Queues an event tracking call.
+     *
+     * @param event - Event name to record.
+     * @param properties - Optional event properties payload.
+     * @returns `void`.
+     *
+     * @remarks
+     * Calls are queued until Analytics.js initializes.
+     *
+     * @example
+     * ```ts
+     * window.analytics.track('Signup', { plan: 'pro' });
+     * ```
+     */
+    track: (event: string, properties?: Record<string, unknown>) => void;
+    /**
+     * Queues a page tracking call.
+     *
+     * @param name - Optional page name override.
+     * @param properties - Optional page metadata payload.
+     * @returns `void`.
+     *
+     * @remarks
+     * If no name is passed, Segment infers the current page context.
+     *
+     * @example
+     * ```ts
+     * window.analytics.page('Pricing');
+     * ```
+     */
+    page: (name?: string, properties?: Record<string, unknown>) => void;
+    /**
+     * Queues a user identification call.
+     *
+     * @param userId - Stable user identifier.
+     * @param traits - Optional trait map associated with the user.
+     * @param options - Optional Segment call options.
+     * @returns `void`.
+     *
+     * @remarks
+     * Ensure the client is initialized and use a stable `userId` to avoid
+     * fragmented user profiles.
+     *
+     * @example
+     * ```ts
+     * window.analytics.identify('user_123', { email: 'dev@example.com' });
+     * ```
+     */
+    identify: (userId: string, traits?: Record<string, unknown>, options?: Record<string, unknown>) => void;
+    /**
+     * Queues a group association call for account-level analytics.
+     *
+     * @param groupId - Group or account identifier.
+     * @param traits - Optional group trait map.
+     * @param options - Optional Segment call options.
+     * @returns `void`.
+     *
+     * @example
+     * ```ts
+     * window.analytics.group('acme-inc', { plan: 'enterprise' });
+     * ```
+     */
+    group: (groupId: string, traits?: Record<string, unknown>, options?: Record<string, unknown>) => void;
+    /**
+     * Queues a user alias call to merge identities.
+     *
+     * @param userId - New canonical user identifier.
+     * @param previousId - Optional previous anonymous or legacy identifier.
+     * @param options - Optional Segment call options.
+     * @returns `void`.
+     *
+     * @remarks
+     * Use `previousId` only when linking an existing anonymous identity to the
+     * new `userId`.
+     *
+     * @example
+     * ```ts
+     * window.analytics.alias('user_123', 'anon_456');
+     * ```
+     */
+    alias: (userId: string, previousId?: string, options?: Record<string, unknown>) => void;
+    /**
+     * Queues a reset call that clears current user identity state.
+     *
+     * @returns `void`.
+     *
+     * @example
+     * ```ts
+     * window.analytics.reset();
+     * ```
+     */
+    reset: () => void;
+}
+declare global {
+    interface Window {
+        analytics?: SegmentApi;
+    }
+}
+/**
+ * Segment vendor manifest.
+ *
+ * Uses Segment's standard `window.analytics` queue shape and optionally queues
+ * the initial `page()` call before the bundle loads.
+ */
+export declare const segmentManifest: {
+    readonly vendor: "segment";
+    readonly category: "measurement";
+    readonly bootstrap: [{
+        readonly type: "setGlobal";
+        readonly name: "analytics";
+        readonly value: readonly [];
+        readonly ifUndefined: true;
+    }, {
+        readonly type: "defineQueueMethods";
+        readonly target: "analytics";
+        readonly methods: ["track", "page", "identify", "group", "alias", "reset"];
+    }];
+    readonly install: [{
+        readonly type: "callGlobal";
+        readonly global: "analytics";
+        readonly method: "page";
+    }, {
+        readonly type: "loadScript";
+        readonly src: "{{scriptUrl}}";
+        readonly async: true;
+    }];
+    readonly kind: "c15t.vendor-manifest";
+    readonly schemaVersion: 1;
+};
+export interface SegmentOptions {
+    /** Your Segment write key. */
+    writeKey: string;
+    /** Queue the initial `analytics.page()` call during setup. */
+    trackPageView?: boolean;
+    /** Optional full loader URL override. */
+    scriptUrl?: string;
+}
+/**
+ * Creates a Segment Analytics.js script.
+ *
+ * @param options - The options for the Segment script.
+ * @returns The Segment script configuration.
+ */
+export declare function segment({ writeKey, trackPageView, scriptUrl, }: SegmentOptions): Script;