@c15t/scripts 2.0.1 → 2.1.0

package/dist-types/vendors/ads-and-pixels/snapchat-pixel.d.ts

@@ -0,0 +1,171 @@
+import type { Script } from 'c15t';
+export type SnapchatPixelEventName = 'PAGE_VIEW' | 'VIEW_CONTENT' | 'ADD_CART' | 'PURCHASE' | 'SIGN_UP' | 'SAVE' | 'START_CHECKOUT' | 'APP_OPEN' | 'ADD_BILLING' | 'SEARCH' | 'SUBSCRIBE' | 'AD_CLICK' | 'AD_VIEW' | 'COMPLETE_TUTORIAL' | 'LEVEL_COMPLETE' | 'INVITE' | 'LOGIN' | 'SHARE' | 'RESERVE' | 'ACHIEVEMENT_UNLOCKED' | 'ADD_TO_WISHLIST' | 'SPENT_CREDITS' | 'RATE' | 'START_TRIAL' | 'LIST_VIEW';
+export interface SnapchatPixelEventProperties {
+    /** Total monetary value for commerce events such as `PURCHASE`. */
+    price?: number;
+    /**
+     * Event identifier used to deduplicate browser Pixel events against
+     * server-side Conversions API events.
+     */
+    client_dedup_id?: string;
+    /** ISO 4217 currency code, for example `USD`. */
+    currency?: string;
+    /** Transaction/order identifier for purchase events. */
+    transaction_id?: string;
+    /** Product, SKU, or content identifiers associated with the event. */
+    item_ids?: string[];
+    /** Product or content category associated with the event. */
+    item_category?: string;
+    /** Free-form description for the event. */
+    description?: string;
+    /** Query text for `SEARCH` events. */
+    search_string?: string;
+    /** Number of items represented by the event. */
+    number_items?: number;
+    /** Whether payment information was available, represented as `0` or `1`. */
+    payment_info_available?: 0 | 1;
+    /** Signup method for `SIGN_UP` events. */
+    sign_up_method?: string;
+    /** Whether the action succeeded, represented as `0` or `1`. */
+    success?: 0 | 1;
+    /** Brand names associated with the event contents. */
+    brands?: string[];
+    /** Fulfillment method for commerce events. */
+    delivery_method?: 'in_store' | 'curbside' | 'delivery';
+    /** Customer lifecycle status associated with the event. */
+    customer_status?: 'new' | 'returning' | 'reactivated';
+    /** Optional custom tag for event segmentation in Snapchat. */
+    event_tag?: string;
+    [key: string]: unknown;
+}
+type SnapchatPixelFunction = {
+    (command: 'track', eventName: SnapchatPixelEventName | (string & {}), properties?: SnapchatPixelEventProperties): void;
+    (command: 'init', pixelId: string, config?: Record<string, unknown>): void;
+    (command: string, ...args: unknown[]): void;
+};
+declare global {
+    interface Window {
+        snaptr?: SnapchatPixelFunction & {
+            handleRequest?: (...args: unknown[]) => void;
+            loaded?: boolean;
+            push?: Window['snaptr'];
+            queue?: unknown[][];
+            version?: string;
+        };
+        _snaptr?: Window['snaptr'];
+    }
+}
+/**
+ * Snapchat Pixel vendor manifest.
+ *
+ * Uses a structured queue stub and queues `init` plus an optional
+ * `PAGE_VIEW` event before the vendor bundle loads.
+ */
+export declare const snapchatPixelManifest: {
+    readonly vendor: "snapchat-pixel";
+    readonly category: "marketing";
+    readonly bootstrap: [{
+        readonly type: "defineStubFunction";
+        readonly name: "snaptr";
+        readonly queue: {
+            readonly property: "queue";
+        };
+        readonly dispatchProperty: "handleRequest";
+        readonly queueFormat: "array";
+        readonly aliases: ["_snaptr"];
+        readonly selfReferences: ["push"];
+        readonly properties: {
+            readonly loaded: true;
+            readonly version: "1.0";
+        };
+        readonly ifUndefined: true;
+    }];
+    readonly install: [{
+        readonly type: "callGlobal";
+        readonly global: "snaptr";
+        readonly args: ["init", "{{pixelId}}"];
+    }, {
+        readonly type: "callGlobal";
+        readonly global: "snaptr";
+        readonly args: ["track", "PAGE_VIEW"];
+    }, {
+        readonly type: "loadScript";
+        readonly src: "{{scriptUrl}}";
+        readonly async: true;
+    }];
+    readonly kind: "c15t.vendor-manifest";
+    readonly schemaVersion: 1;
+};
+export interface SnapchatPixelOptions {
+    /**
+     * Your Snapchat Pixel ID.
+     * @example `123456789012345`
+     */
+    pixelId: string;
+    /** Optional init payload passed to `snaptr('init', ...)`. */
+    initOptions?: Record<string, unknown>;
+    /**
+     * Queue the default `PAGE_VIEW` event during setup.
+     * @default true
+     */
+    trackPageView?: boolean;
+    /** Snapchat Pixel loader URL. */
+    scriptUrl?: string;
+}
+/**
+ * Creates a Snapchat Pixel script.
+ *
+ * @param options.pixelId - Snapchat Pixel ID used in `snaptr('init', ...)`.
+ *   Expected format is a numeric string (commonly 15 digits), for example
+ *   `'123456789012345'`. This value is required and should come directly from
+ *   Snapchat Ads Manager.
+ * @param options.initOptions - Optional object passed as the third argument to
+ *   `snaptr('init', pixelId, initOptions)`, for advanced initialization values.
+ *   Example: `{ user_email: 'user@example.com', user_phone_number: '+15551234567' }`.
+ * @param options.trackPageView - Whether to queue the default
+ *   `snaptr('track', 'PAGE_VIEW')` call during setup. Defaults to `true`; set to
+ *   `false` when you want to control page-view tracking manually.
+ * @returns A resolved c15t `Script` configuration that defines the Snapchat
+ *   queue stub, runs `init` (and optionally `PAGE_VIEW`), and then loads the
+ *   Snapchat SDK script URL.
+ * @throws `resolveManifest` may throw when required placeholders cannot be
+ *   resolved (for example, when `pixelId` is missing/empty) or when provided
+ *   manifest values are invalid for interpolation.
+ *
+ * Edge cases:
+ * - Missing `pixelId` causes manifest resolution to fail.
+ * - Non-numeric or malformed `pixelId` values may initialize incorrectly in
+ *   Snapchat even if local script construction succeeds.
+ *
+ * @example
+ * ```ts
+ * const script = snapchatPixel({
+ * 	pixelId: '123456789012345',
+ * 	initOptions: {
+ * 		user_email: 'user@example.com',
+ * 		user_phone_number: '+15551234567',
+ * 	},
+ * 	trackPageView: false,
+ * });
+ * ```
+ */
+export declare function snapchatPixel({ pixelId, initOptions, trackPageView, scriptUrl, }: SnapchatPixelOptions): Script;
+/**
+ * Tracks a Snapchat Pixel event.
+ *
+ * @param eventName - Snapchat standard event name or a custom event name.
+ * @param properties - Optional event properties, including
+ *   `client_dedup_id` for Pixel plus Conversions API deduplication.
+ *
+ * @example
+ * ```ts
+ * snapchatPixelEvent('PURCHASE', {
+ * 	price: 99,
+ * 	currency: 'USD',
+ * 	transaction_id: 'order-123',
+ * 	client_dedup_id: 'event-123',
+ * });
+ * ```
+ */
+export declare const snapchatPixelEvent: (eventName: SnapchatPixelEventName | (string & {}), properties?: SnapchatPixelEventProperties) => void;
+export {};

package/dist-types/{tiktok-pixel.d.ts → vendors/ads-and-pixels/tiktok-pixel.d.ts}

@@ -1,11 +1,25 @@
 import type { Script } from 'c15t';
+interface TikTokPixelFunction {
+    grantConsent: () => void;
+    revokeConsent: () => void;
+    page: () => void;
+    track: (eventName: string, properties?: Record<string, unknown>) => void;
+    identify: (properties?: Record<string, unknown>) => void;
+    instances: (...args: unknown[]) => void;
+    debug: (...args: unknown[]) => void;
+    on: (...args: unknown[]) => void;
+    off: (...args: unknown[]) => void;
+    once: (...args: unknown[]) => void;
+    ready: (...args: unknown[]) => void;
+    alias: (...args: unknown[]) => void;
+    group: (...args: unknown[]) => void;
+    enableCookie: (...args: unknown[]) => void;
+    disableCookie: (...args: unknown[]) => void;
+    holdConsent: (...args: unknown[]) => void;
+}
 declare global {
     interface Window {
-        ttq: {
-            grantConsent: () => void;
-            revokeConsent: () => void;
-            page: () => void;
-        };
+        ttq: TikTokPixelFunction;
     }
 }
 /**
@@ -89,3 +103,4 @@ export interface TikTokPixelOptions {
  * @see {@link https://ads.tiktok.com/help/article/tiktok-pixel} TikTok Pixel documentation
  */
 export declare function tiktokPixel({ pixelId, scriptSrc, }: TikTokPixelOptions): Script;
+export {};

package/dist-types/{x-pixel.d.ts → vendors/ads-and-pixels/x-pixel.d.ts}

@@ -69,9 +69,23 @@ export interface XPixelEvent {
     twclid?: string;
     /**
      * Status of the conversion event
-     * @example completed
+     * Should be set to values like "started" or "completed".
+     * @example "completed"
      */
-    status?: boolean;
+    status?: 'started' | 'completed';
+    /**
+     * Email address used for user matching.
+     * The X Pixel hashes this value before transmission.
+     * @example "[email protected]"
+     */
+    email_address?: string;
+    /**
+     * Phone number used for user matching.
+     * Include country code in E.164 format (for example, +11234567890).
+     * The X Pixel hashes this value before transmission.
+     * @example "+11234567890"
+     */
+    phone_number?: string;
     /**
      * Content/products associated with the conversion event
      * @example [{content_id: 'OT001', content_name: 'bird seed', content_price: 50, num_items: 1}]
@@ -141,7 +155,7 @@ export interface XPixelOptions {
  * });
  * ```
  *
- * @see {@link https://ads.twitter.com/help/article/x-pixel} X Pixel documentation
+ * @see {@link https://business.x.com/en/help/campaign-measurement-and-analytics/conversion-tracking-for-websites} X conversion tracking documentation
  */
 export declare function xPixel({ pixelId, scriptSrc }: XPixelOptions): Script;
 /**
@@ -162,5 +176,8 @@ export declare function xPixel({ pixelId, scriptSrc }: XPixelOptions): Script;
  * ```
  *
  * @see {@link https://business.x.com/en/help/campaign-measurement-and-analytics/conversion-tracking-for-websites#event-types-and-parameters}
+ * @throws {Error} Throws when `window` is unavailable or `window.twq` is not a
+ * function. Ensure marketing consent is granted and the X Pixel has loaded
+ * before calling this helper.
  */
-export declare const xPixelEvent: (eventId: string, metadata?: XPixelEvent) => void | undefined;
+export declare const xPixelEvent: (eventId: string, metadata?: XPixelEvent) => void;

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

@@ -0,0 +1,62 @@
+import type { Script } from 'c15t';
+declare global {
+    interface Window {
+        AhrefsAnalytics?: {
+            sendEvent: (name: string, options?: {
+                props?: Record<string, string>;
+                meta?: Record<string, unknown>;
+            }) => void;
+        };
+    }
+}
+/**
+ * Ahrefs Analytics vendor manifest.
+ *
+ * Loads Ahrefs Web Analytics and passes the project key via `data-key`. Ahrefs
+ * Web Analytics is cookieless, so the script is consent-gated on `measurement`
+ * and unloaded when consent is revoked.
+ */
+export declare const ahrefsAnalyticsManifest: {
+    readonly vendor: "ahrefs-analytics";
+    readonly category: "measurement";
+    readonly install: [{
+        readonly type: "loadScript";
+        readonly src: "{{scriptUrl}}";
+        readonly async: true;
+        readonly attributes: {
+            readonly 'data-key': "{{key}}";
+        };
+    }];
+    readonly kind: "c15t.vendor-manifest";
+    readonly schemaVersion: 1;
+};
+export interface AhrefsAnalyticsOptions {
+    /**
+     * Your Ahrefs Web Analytics project key.
+     */
+    key: string;
+    /**
+     * Custom loader URL.
+     * @default 'https://analytics.ahrefs.com/analytics.js'
+     */
+    scriptUrl?: string;
+}
+/**
+ * Creates an Ahrefs Analytics script.
+ *
+ * The Ahrefs SDK exposes its runtime API on `window.AhrefsAnalytics` after
+ * load. This helper only models the serializable script manifest.
+ *
+ * @see https://ahrefs.com/web-analytics
+ *
+ * @param options - The options for the Ahrefs Analytics script.
+ * @returns The Ahrefs Analytics script.
+ *
+ * @example
+ * ```ts
+ * import { ahrefsAnalytics } from '@c15t/scripts/ahrefs-analytics';
+ *
+ * ahrefsAnalytics({ key: 'YOUR_PROJECT_KEY' });
+ * ```
+ */
+export declare function ahrefsAnalytics(options: AhrefsAnalyticsOptions): Script;

package/dist-types/vendors/analytics/cloudflare-web-analytics.d.ts

@@ -0,0 +1,67 @@
+import type { Script } from 'c15t';
+declare global {
+    interface Window {
+        __cfBeacon?: {
+            spa?: boolean;
+            token: string;
+        };
+    }
+}
+/**
+ * Cloudflare Web Analytics vendor manifest.
+ *
+ * Serializes Cloudflare's beacon config into the `data-cf-beacon` attribute.
+ * Cloudflare Web Analytics is cookieless, so the script is consent-gated on
+ * `measurement` and unloaded when consent is revoked.
+ */
+export declare const cloudflareWebAnalyticsManifest: {
+    readonly vendor: "cloudflare-web-analytics";
+    readonly category: "measurement";
+    readonly install: [{
+        readonly type: "loadScript";
+        readonly src: "{{scriptUrl}}";
+        readonly defer: true;
+        readonly attributes: {
+            readonly 'data-cf-beacon': "{{beaconConfig}}";
+        };
+    }];
+    readonly kind: "c15t.vendor-manifest";
+    readonly schemaVersion: 1;
+};
+export interface CloudflareWebAnalyticsOptions {
+    /**
+     * Your Cloudflare Web Analytics token.
+     */
+    token: string;
+    /**
+     * Enable Cloudflare's SPA route tracking.
+     * @default true
+     */
+    spa?: boolean;
+    /**
+     * Custom loader URL.
+     * @default 'https://static.cloudflareinsights.com/beacon.min.js'
+     */
+    scriptUrl?: string;
+}
+/**
+ * Creates a Cloudflare Web Analytics script.
+ *
+ * @see https://developers.cloudflare.com/analytics/web-analytics/get-started/
+ *
+ * @param options - The options for the Cloudflare Web Analytics script.
+ * @returns The Cloudflare Web Analytics script.
+ * @throws {Error} Throws `cloudflareWebAnalytics: missing token` when
+ * `options.token` is missing, invalid, or trims to an empty string.
+ *
+ * @example
+ * ```ts
+ * import { cloudflareWebAnalytics } from '@c15t/scripts/cloudflare-web-analytics';
+ *
+ * cloudflareWebAnalytics({
+ *   token: 'abc123...',
+ *   spa: true,
+ * });
+ * ```
+ */
+export declare function cloudflareWebAnalytics(options: CloudflareWebAnalyticsOptions): Script;

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

@@ -30,7 +30,10 @@ export declare const gtagManifest: {
     readonly install: [{
         readonly type: "callGlobal";
         readonly global: "gtag";
-        readonly args: ["js", "{{loadTime}}"];
+        readonly args: ["js", {
+            readonly kind: "c15t.runtime-value";
+            readonly value: "date";
+        }];
     }, {
         readonly type: "callGlobal";
         readonly global: "gtag";
@@ -40,13 +43,7 @@ export declare const gtagManifest: {
         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 consentMapping: Record<string, string[]>;
     readonly consentSignal: "gtag";
     readonly kind: "c15t.vendor-manifest";
     readonly schemaVersion: 1;

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

@@ -0,0 +1,73 @@
+import type { Script } from 'c15t';
+declare global {
+    interface Window {
+        hj?: ((...args: unknown[]) => void) & {
+            q?: unknown[][];
+        };
+        _hjSettings?: {
+            hjid: number | string;
+            hjsv: number;
+        };
+    }
+}
+/**
+ * Hotjar vendor manifest.
+ *
+ * Seeds the global Hotjar settings object and queue stub before loading
+ * the vendor bundle.
+ */
+export declare const hotjarManifest: {
+    readonly vendor: "hotjar";
+    readonly category: "measurement";
+    readonly install: [{
+        readonly type: "setGlobal";
+        readonly name: "_hjSettings";
+        readonly value: {
+            readonly hjid: "{{siteId}}";
+            readonly hjsv: "{{version}}";
+        };
+        readonly ifUndefined: true;
+    }, {
+        readonly type: "defineStubFunction";
+        readonly name: "hj";
+        readonly queue: {
+            readonly property: "q";
+        };
+        readonly queueFormat: "array";
+        readonly ifUndefined: true;
+    }, {
+        readonly type: "loadScript";
+        readonly src: "{{scriptUrl}}";
+        readonly async: true;
+    }];
+    readonly kind: "c15t.vendor-manifest";
+    readonly schemaVersion: 1;
+};
+export interface HotjarOptions {
+    /**
+     * Your Hotjar site ID.
+     * @example `1234567`
+     */
+    siteId: number | string;
+    /**
+     * Hotjar script version.
+     * @default 6
+     */
+    version?: number;
+    /** Hotjar loader URL. */
+    scriptUrl?: string;
+}
+/**
+ * Creates a Hotjar script.
+ *
+ * @param options - The options for the Hotjar script.
+ * @returns The Hotjar script configuration.
+ *
+ * @example
+ * ```ts
+ * import { hotjar } from '@c15t/scripts/hotjar';
+ *
+ * hotjar({ siteId: 1234567 });
+ * ```
+ */
+export declare function hotjar({ siteId, version, scriptUrl, }: HotjarOptions): Script;

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

@@ -0,0 +1,41 @@
+import type { Script } from 'c15t';
+import { type VendorManifest } from '../../types';
+declare global {
+    interface Window {
+        _paq?: unknown[];
+    }
+}
+export declare const matomoAnalyticsManifest: VendorManifest;
+export interface MatomoAnalyticsOptions {
+    /** Your Matomo site ID. */
+    siteId?: string | number;
+    /** Your Matomo base URL, for example `https://analytics.example.com`. */
+    matomoUrl?: string;
+    /** Your Matomo Cloud identifier, for example `my-site.matomo.cloud`. */
+    cloudId?: string;
+    /** Optional explicit tracker endpoint override. */
+    trackerUrl?: string;
+    /** Optional explicit script URL override. */
+    scriptUrl?: string;
+    /** Queue `enableLinkTracking`. */
+    enableLinkTracking?: boolean;
+    /** Queue `disableCookies`. */
+    disableCookies?: boolean;
+    /** Queue an initial `trackPageView`. */
+    trackPageView?: boolean;
+    /** Default Matomo consent state (`required` blocks, `given` starts enabled). */
+    defaultConsent?: 'required' | 'given';
+}
+/**
+ * Creates a Matomo Analytics script.
+ *
+ * @param options - The options for the Matomo Analytics script.
+ * @returns The Matomo Analytics script configuration.
+ * @throws {Error} Throws
+ * `'matomoAnalytics requires \`matomoUrl\`, \`cloudId\`, or explicit \`trackerUrl\` and \`scriptUrl\` values.'`
+ * when either resolved `trackerUrl` or `scriptUrl` is missing (for example,
+ * when neither `matomoUrl` nor `cloudId` is provided and explicit
+ * `trackerUrl`/`scriptUrl` values are not supplied). Provide `matomoUrl`, or
+ * provide both explicit `trackerUrl` and `scriptUrl`.
+ */
+export declare function matomoAnalytics(options?: MatomoAnalyticsOptions): Script;