@c15t/scripts 2.0.1 → 2.2.0-canary-20260727202135

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

@@ -0,0 +1,330 @@
+import type { Script } from 'c15t';
+export declare const RUDDERSTACK_QUEUE_METHODS: readonly ['setDefaultInstanceKey', 'load', 'ready', 'page', 'track', 'identify', 'alias', 'group', 'reset', 'setAnonymousId', 'startSession', 'endSession', 'consent', 'addCustomIntegration'];
+type JsonPrimitive = string | number | boolean | null;
+type JsonValue = JsonPrimitive | JsonObject | JsonValue[];
+/**
+ * JSON-serializable object passed to RudderStack's `load()` API.
+ */
+export interface JsonObject {
+    [key: string]: JsonValue;
+}
+/**
+ * RudderStack JavaScript SDK `load()` options.
+ *
+ * The options are interpolated into a script manifest and passed as the third
+ * `rudderanalytics.load(writeKey, dataPlaneUrl, options)` argument. Keep values
+ * JSON-serializable: plain objects, arrays, strings, numbers, booleans, and
+ * `null`. Functions, class instances, Dates, Maps, Sets, and symbols are not
+ * supported.
+ */
+export type RudderStackLoadOptions = JsonObject;
+/**
+ * Public RudderStack JavaScript SDK API exposed on `window.rudderanalytics`.
+ *
+ * The official v3 CDN 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.rudderanalytics?.track('Signup Completed', { plan: 'pro' });
+ * ```
+ */
+export interface RudderStackApi {
+    /**
+     * Sets the default instance key for multi-instance setups.
+     *
+     * @param key - Instance key to use for subsequent calls.
+     * @returns The RudderStack runtime or a promise-like value from the SDK.
+     */
+    setDefaultInstanceKey: (key: string) => unknown;
+    /**
+     * Loads and initializes the RudderStack JavaScript SDK.
+     *
+     * @param writeKey - Source write key from RudderStack.
+     * @param dataPlaneUrl - HTTPS data plane URL for the source.
+     * @param options - Optional JSON-serializable load options.
+     * @returns The RudderStack runtime or a promise-like value from the SDK.
+     */
+    load: (writeKey: string, dataPlaneUrl: string, options?: RudderStackLoadOptions) => unknown;
+    /**
+     * Registers a callback that fires when the SDK is ready.
+     *
+     * @param callback - Function to run once the SDK is ready.
+     * @returns The RudderStack runtime or a promise-like value from the SDK.
+     */
+    ready: (callback: () => void) => unknown;
+    /**
+     * Tracks a page view with optional category, name, properties, and options.
+     *
+     * @param category - Optional page category.
+     * @param name - Optional page name.
+     * @param properties - Optional page metadata payload.
+     * @param options - Optional event context or integrations options.
+     * @param callback - Optional callback after processing.
+     * @returns The RudderStack runtime or a promise-like value from the SDK.
+     */
+    page: (category?: string, name?: string, properties?: Record<string, unknown>, options?: Record<string, unknown>, callback?: () => void) => unknown;
+    /**
+     * Tracks a named event.
+     *
+     * @param event - Event name to record.
+     * @param properties - Optional event properties payload.
+     * @param options - Optional event context or integrations options.
+     * @param callback - Optional callback after processing.
+     * @returns The RudderStack runtime or a promise-like value from the SDK.
+     */
+    track: (event: string, properties?: Record<string, unknown>, options?: Record<string, unknown>, callback?: () => void) => 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 options - Optional event context or integrations options.
+     * @param callback - Optional callback after processing.
+     * @returns The RudderStack runtime or a promise-like value from the SDK.
+     */
+    identify: (userId: string, traits?: Record<string, unknown>, options?: Record<string, unknown>, callback?: () => void) => unknown;
+    /**
+     * Aliases one user identifier to another.
+     *
+     * @param userId - New canonical user identifier.
+     * @param previousId - Optional previous identifier.
+     * @param options - Optional event context or integrations options.
+     * @param callback - Optional callback after processing.
+     * @returns The RudderStack runtime or a promise-like value from the SDK.
+     */
+    alias: (userId: string, previousId?: string, options?: Record<string, unknown>, callback?: () => void) => unknown;
+    /**
+     * Associates the current user with a group or account.
+     *
+     * @param groupId - Group or account identifier.
+     * @param traits - Optional group trait map.
+     * @param options - Optional event context or integrations options.
+     * @param callback - Optional callback after processing.
+     * @returns The RudderStack runtime or a promise-like value from the SDK.
+     */
+    group: (groupId: string, traits?: Record<string, unknown>, options?: Record<string, unknown>, callback?: () => void) => unknown;
+    /**
+     * Clears the current user identity state.
+     *
+     * @returns The RudderStack runtime or a promise-like value from the SDK.
+     */
+    reset: () => unknown;
+    /**
+     * Sets the anonymous ID used for subsequent events.
+     *
+     * @param anonymousId - Anonymous identifier to assign.
+     * @returns The RudderStack runtime or a promise-like value from the SDK.
+     */
+    setAnonymousId: (anonymousId: string) => unknown;
+    /**
+     * Starts a session with an optional session identifier.
+     *
+     * @param sessionId - Optional session identifier.
+     * @returns The RudderStack runtime or a promise-like value from the SDK.
+     */
+    startSession: (sessionId?: string) => unknown;
+    /**
+     * Ends the current session.
+     *
+     * @returns The RudderStack runtime or a promise-like value from the SDK.
+     */
+    endSession: () => unknown;
+    /**
+     * Transitions the SDK from pre-consent to post-consent behavior.
+     *
+     * @param consentOptions - Vendor-supported consent options.
+     * @returns The RudderStack runtime or a promise-like value from the SDK.
+     *
+     * @remarks
+     * This API is for RudderStack's consent-management flow. In the default
+     * (blocked-load) mode it is not a c15t revocation hook; c15t unloads the
+     * SDK when measurement consent is revoked. In the opt-in pre-consent mode
+     * (`consentManagement` option) c15t calls it with the mapped consent IDs on
+     * every consent decision and change.
+     */
+    consent: (consentOptions?: Record<string, unknown>) => unknown;
+    /**
+     * Registers a custom device-mode integration. RudderStack only accepts
+     * registrations made before `load()` completes, which is why this is part
+     * of the pre-load queue.
+     *
+     * @param name - Integration name.
+     * @param integration - Integration implementation object.
+     * @returns The RudderStack runtime or a promise-like value from the SDK.
+     */
+    addCustomIntegration: (name: string, integration: unknown) => unknown;
+}
+declare global {
+    interface Window {
+        rudderanalytics?: RudderStackApi;
+        rudderAnalyticsBuildType?: string;
+        RudderSnippetVersion?: string;
+    }
+}
+/**
+ * RudderStack vendor manifest.
+ *
+ * Creates RudderStack's v3 `window.rudderanalytics` queue, marks the snippet as
+ * seeded, queues the required `load()` call and optional `page()` call, then
+ * lets c15t own the script element.
+ */
+export declare const rudderstackManifest: {
+    readonly kind: "c15t.vendor-manifest";
+    readonly schemaVersion: 1;
+    readonly vendor: 'rudderstack';
+    readonly category: 'measurement';
+    readonly bootstrap: [{
+        readonly type: 'setGlobal';
+        readonly name: 'rudderanalytics';
+        readonly value: readonly [];
+        readonly ifUndefined: true;
+    }, {
+        readonly type: 'setGlobal';
+        readonly name: 'RudderSnippetVersion';
+        readonly value: '3.0.32';
+    }, {
+        readonly type: 'setGlobal';
+        readonly name: 'rudderAnalyticsBuildType';
+        readonly value: 'modern';
+    }, {
+        readonly type: 'setGlobalPath';
+        readonly path: ["rudderanalytics", "snippetExecuted"];
+        readonly value: true;
+    }, {
+        readonly type: 'defineQueueMethods';
+        readonly target: 'rudderanalytics';
+        readonly methods: ["setDefaultInstanceKey", "load", "ready", "page", "track", "identify", "alias", "group", "reset", "setAnonymousId", "startSession", "endSession", "consent", "addCustomIntegration"];
+    }];
+    readonly install: [{
+        readonly type: 'callGlobal';
+        readonly global: 'rudderanalytics';
+        readonly method: 'load';
+        readonly args: ["{{writeKey}}", "{{dataPlaneUrl}}", "{{loadOptions}}"];
+    }, {
+        readonly type: 'callGlobal';
+        readonly global: 'rudderanalytics';
+        readonly method: 'page';
+    }, {
+        readonly type: 'loadScript';
+        readonly src: '{{scriptUrl}}';
+        readonly async: true;
+        readonly attributes: {
+            readonly 'data-loader': 'RS_JS_SDK';
+            readonly 'data-rsa-write-key': '{{writeKey}}';
+        };
+    }];
+};
+/**
+ * c15t consent categories accepted by the RudderStack consent mapping.
+ */
+export type RudderStackConsentCategory = 'necessary' | 'functionality' | 'experience' | 'measurement' | 'marketing';
+/**
+ * Opt-in pre-consent mode configuration.
+ *
+ * When provided, the SDK loads immediately for every visitor in RudderStack's
+ * pre-consent state (no persistent storage, events buffered in memory) and
+ * c15t signals consent decisions through `rudderanalytics.consent()` with the
+ * mapped consent IDs. This preserves pre-consent event attribution for users
+ * who go on to consent, at the cost of running vendor code before consent.
+ *
+ * Every destination in your RudderStack workspace must carry the consent IDs
+ * used here — c15t cannot verify that configuration from the browser, which is
+ * why this mode is opt-in and blocking the load stays the default.
+ */
+export interface RudderStackConsentManagementOptions {
+    /**
+     * c15t consent category → RudderStack consent IDs.
+     *
+     * IDs come from your RudderStack destination consent settings. Categories
+     * granted in c15t contribute their IDs to `allowedConsentIds`; everything
+     * else lands in `deniedConsentIds`.
+     *
+     * @example
+     * ```ts
+     * {
+     *   measurement: ['product-analytics'],
+     *   marketing: ['ad-destinations'],
+     * }
+     * ```
+     */
+    mapping: Partial<Record<RudderStackConsentCategory, string[]>>;
+}
+export interface RudderStackOptions {
+    /**
+     * RudderStack source write key.
+     */
+    writeKey: string;
+    /**
+     * RudderStack HTTPS data plane URL.
+     */
+    dataPlaneUrl: string;
+    /**
+     * Opt into RudderStack's pre-consent mode with c15t as the consent
+     * provider instead of blocking the SDK load until consent.
+     *
+     * Defaults to `undefined`, which keeps the safe default: the SDK does not
+     * load until `measurement` consent is granted. See
+     * {@link RudderStackConsentManagementOptions} for the tradeoffs.
+     */
+    consentManagement?: RudderStackConsentManagementOptions;
+    /**
+     * Optional JSON-serializable RudderStack `load()` options.
+     *
+     * Values must be JSON-serializable because c15t resolves the manifest into
+     * script lifecycle callbacks. Do not pass functions, Dates, Maps, Sets,
+     * class instances, symbols, or other non-JSON values.
+     */
+    loadOptions?: RudderStackLoadOptions;
+    /**
+     * Queue the initial `rudderanalytics.page()` call during setup.
+     *
+     * @default true
+     */
+    trackPageView?: boolean;
+    /**
+     * Optional full loader URL override.
+     *
+     * @default 'https://cdn.rudderlabs.com/v3/modern/rsa.min.js'
+     */
+    scriptUrl?: string;
+}
+/**
+ * Creates a RudderStack JavaScript SDK script.
+ *
+ * @see https://www.rudderstack.com/docs/sources/event-streams/sdks/rudderstack-javascript-sdk/quickstart/
+ *
+ * @param options - The options for the RudderStack script.
+ * @returns The RudderStack script configuration.
+ * @throws {Error} When `writeKey` is missing or only whitespace.
+ * @throws {Error} When `dataPlaneUrl` is missing, invalid, or not HTTPS.
+ *
+ * @remarks
+ * RudderStack collects customer behavior and sends it to destinations through
+ * your configured data plane. By default c15t gates the browser SDK on
+ * `measurement` consent and unloads it when that consent is revoked.
+ * `loadOptions` is passed directly as the third `load()` argument and must be
+ * JSON-serializable.
+ *
+ * Pass `consentManagement` to opt into RudderStack's pre-consent mode instead:
+ * the SDK loads immediately with no persistent storage and buffered events,
+ * and c15t signals every consent decision through `rudderanalytics.consent()`
+ * with your mapped consent IDs — preserving pre-consent event attribution for
+ * users who consent. Requires consent IDs on every RudderStack destination.
+ *
+ * @example
+ * ```ts
+ * import { rudderstack } from '@c15t/scripts/rudderstack';
+ *
+ * rudderstack({
+ * 	writeKey: 'WRITE_KEY',
+ * 	dataPlaneUrl: 'https://example.dataplane.rudderstack.com',
+ * 	loadOptions: {
+ * 		useBeacon: true,
+ * 	},
+ * });
+ * ```
+ */
+export declare function rudderstack({ writeKey, dataPlaneUrl, consentManagement, loadOptions, trackPageView, scriptUrl, }: RudderStackOptions): Script;
+export {};

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 kind: "c15t.vendor-manifest";
+    readonly schemaVersion: 1;
+    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}}';
+        };
+    }];
+};
+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 kind: "c15t.vendor-manifest";
+    readonly schemaVersion: 1;
+    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;
+    }];
+};
+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;

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

@@ -0,0 +1,93 @@
+import type { Script } from 'c15t';
+declare global {
+    interface Window {
+        umami?: {
+            identify: (sessionData?: Record<string, unknown> | string) => void;
+            track: {
+                (payload?: Record<string, unknown>): void;
+                (eventName: string, eventData?: Record<string, unknown>): void;
+            };
+        };
+    }
+}
+/**
+ * Umami Analytics vendor manifest.
+ *
+ * Configures Umami entirely through script `data-*` attributes. Umami is a
+ * cookieless analytics product, so the script is consent-gated on
+ * `measurement` and unloaded when consent is revoked.
+ */
+export declare const umamiAnalyticsManifest: {
+    readonly kind: "c15t.vendor-manifest";
+    readonly schemaVersion: 1;
+    readonly vendor: 'umami-analytics';
+    readonly category: 'measurement';
+    readonly install: [{
+        readonly type: 'loadScript';
+        readonly src: '{{scriptUrl}}';
+        readonly defer: true;
+        readonly attributes: {
+            readonly 'data-website-id': '{{websiteId}}';
+            readonly 'data-host-url': '{{hostUrl}}';
+            readonly 'data-auto-track': '{{autoTrackAttribute}}';
+            readonly 'data-domains': '{{domains}}';
+            readonly 'data-tag': '{{tag}}';
+            readonly 'data-before-send': '{{beforeSend}}';
+        };
+    }];
+};
+export interface UmamiAnalyticsOptions {
+    /**
+     * Your Umami website ID.
+     */
+    websiteId: string;
+    /**
+     * Override the host that receives analytics events.
+     */
+    hostUrl?: string;
+    /**
+     * Disable automatic tracking when set to `false`.
+     */
+    autoTrack?: boolean;
+    /**
+     * Restrict tracking to specific domains.
+     */
+    domains?: string[] | string;
+    /**
+     * Attach a tag to tracked events.
+     */
+    tag?: string;
+    /**
+     * Optional global hook name used for Umami's `data-before-send` attribute.
+     *
+     * Callback functions are intentionally not supported here because the c15t
+     * manifest runtime cannot serialize custom JavaScript functions.
+     */
+    beforeSend?: string;
+    /**
+     * Custom loader URL.
+     * @default 'https://cloud.umami.is/script.js'
+     */
+    scriptUrl?: string;
+}
+/**
+ * Creates an Umami Analytics script.
+ *
+ * @see https://umami.is/docs/tracker-config
+ *
+ * @param options - The options for the Umami Analytics script.
+ * @returns The Umami Analytics script.
+ * @throws {Error} When `websiteId` is missing, empty, or invalid. Provide a
+ * valid non-empty `websiteId` string to prevent this error.
+ *
+ * @example
+ * ```ts
+ * import { umamiAnalytics } from '@c15t/scripts/umami-analytics';
+ *
+ * umamiAnalytics({
+ *   websiteId: 'site-abc-123',
+ *   domains: ['example.com', 'www.example.com'],
+ * });
+ * ```
+ */
+export declare function umamiAnalytics(options: UmamiAnalyticsOptions): Script;