@c15t/scripts 2.0.1 → 2.2.0-canary-20260727202135

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

@@ -0,0 +1,66 @@
+import type { Script } from 'c15t';
+export type VercelAnalyticsMode = 'auto' | 'development' | 'production';
+declare global {
+    interface Window {
+        va?: (event: string, properties?: unknown) => void;
+        vaq?: [string, unknown?][];
+        vam?: 'development' | 'production';
+    }
+}
+/**
+ * Vercel Analytics vendor manifest.
+ *
+ * Seeds Vercel's event queue before loading the tracker bundle.
+ */
+export declare const vercelAnalyticsManifest: {
+    readonly kind: "c15t.vendor-manifest";
+    readonly schemaVersion: 1;
+    readonly vendor: 'vercel-analytics';
+    readonly category: 'measurement';
+    readonly bootstrap: [{
+        readonly type: 'setGlobal';
+        readonly name: 'vaq';
+        readonly value: readonly [];
+        readonly ifUndefined: true;
+    }, {
+        readonly type: 'defineStubFunction';
+        readonly name: 'va';
+        readonly queue: {
+            readonly global: 'vaq';
+        };
+        readonly queueFormat: 'array';
+        readonly ifUndefined: true;
+    }];
+    readonly install: [{
+        readonly type: 'loadScript';
+        readonly src: '{{scriptUrl}}';
+        readonly defer: true;
+        readonly attributes: {
+            readonly 'data-sdkn': 'c15t';
+            readonly 'data-dsn': '{{dsn}}';
+            readonly 'data-disable-auto-track': '{{disableAutoTrackAttribute}}';
+            readonly 'data-endpoint': '{{endpoint}}';
+        };
+    }];
+};
+export interface VercelAnalyticsOptions {
+    /** Project DSN for self-hosted or non-Vercel deployments. */
+    dsn?: string;
+    /** Disable automatic pageview tracking. */
+    disableAutoTrack?: boolean;
+    /** Preferred script mode. */
+    mode?: VercelAnalyticsMode;
+    /** Load Vercel's debug bundle when set to `true`. */
+    debug?: boolean;
+    /** Custom ingestion endpoint. */
+    endpoint?: string;
+    /** Custom loader URL. */
+    scriptUrl?: string;
+}
+/**
+ * Creates a Vercel Analytics script.
+ *
+ * @param options - The options for the Vercel Analytics script.
+ * @returns The Vercel Analytics script.
+ */
+export declare function vercelAnalytics(options?: VercelAnalyticsOptions): Script;

package/dist-types/vendors/functional/crisp.d.ts

@@ -0,0 +1,78 @@
+import type { Script } from 'c15t';
+declare global {
+    interface Window {
+        $crisp: unknown[][];
+        CRISP_WEBSITE_ID: string;
+        CRISP_RUNTIME_CONFIG?: {
+            locale?: string;
+            session_merge?: boolean;
+        };
+        CRISP_COOKIE_DOMAIN?: string;
+        CRISP_COOKIE_EXPIRE?: number;
+        CRISP_TOKEN_ID?: string;
+    }
+}
+/**
+ * Crisp vendor manifest.
+ *
+ * Seeds the Crisp queue and website ID before loading the chat client.
+ * Optional runtime globals are added when provided by the helper options.
+ */
+export declare const crispManifest: {
+    readonly kind: "c15t.vendor-manifest";
+    readonly schemaVersion: 1;
+    readonly vendor: 'crisp';
+    readonly category: 'functionality';
+    readonly install: [{
+        readonly type: 'setGlobal';
+        readonly name: '$crisp';
+        readonly value: readonly [];
+        readonly ifUndefined: false;
+    }, {
+        readonly type: 'setGlobal';
+        readonly name: 'CRISP_WEBSITE_ID';
+        readonly value: '{{websiteId}}';
+        readonly ifUndefined: false;
+    }, {
+        readonly type: 'loadScript';
+        readonly src: '{{scriptSrc}}';
+        readonly async: true;
+    }];
+};
+export interface CrispOptions {
+    /** Your Crisp website ID. */
+    websiteId: string;
+    /** Optional locale passed through `window.CRISP_RUNTIME_CONFIG`. */
+    locale?: string;
+    /** Optional cookie domain override for Crisp. */
+    cookieDomain?: string;
+    /** Optional cookie expiration in seconds. */
+    cookieExpiry?: number;
+    /** Optional Crisp token ID for session continuity. */
+    tokenId?: string;
+    /** Whether to merge anonymous sessions into token-backed sessions. */
+    sessionMerge?: boolean;
+    /** Whether to enable `$crisp` safe mode before other queued calls. */
+    safeMode?: boolean;
+    /** Crisp loader URL. */
+    scriptSrc?: string;
+}
+/**
+ * Creates a Crisp chat script.
+ *
+ * This manifest-based helper keeps the serializable queue/bootstrap globals and
+ * omits the upstream ready callback wrapper.
+ *
+ * @param options - The options for the Crisp script.
+ * @returns The Crisp script configuration.
+ *
+ * @example
+ * ```ts
+ * const crispScript = crisp({
+ * 	websiteId: '1234-abcd',
+ * });
+ * ```
+ *
+ * @see {@link https://help.crisp.chat/en/article/how-do-i-install-crisp-live-chat-on-my-website-10wcj3l/} Crisp installation documentation.
+ */
+export declare function crisp(options: CrispOptions): Script;

package/dist-types/vendors/functional/intercom.d.ts

@@ -0,0 +1,135 @@
+import type { Script } from 'c15t';
+export declare const INTERCOM_API_BASES: {
+    readonly us: 'https://api-iam.intercom.io';
+    readonly eu: 'https://api-iam.eu.intercom.io';
+    readonly au: 'https://api-iam.au.intercom.io';
+};
+export type IntercomApiBase = (typeof INTERCOM_API_BASES)[keyof typeof INTERCOM_API_BASES] | (string & {});
+export type IntercomThemeMode = 'light' | 'dark' | 'system';
+export interface IntercomAvatar {
+    type: 'avatar';
+    image_url: string;
+}
+export interface IntercomCompany {
+    id?: string;
+    company_id?: string;
+    name?: string;
+    created_at?: number;
+    remote_created_at?: number;
+    plan?: string;
+    monthly_spend?: number;
+    size?: number;
+    website?: string;
+    industry?: string;
+    [key: string]: unknown;
+}
+export interface IntercomSettings extends Record<string, unknown> {
+    app_id: string;
+    api_base: IntercomApiBase;
+    custom_launcher_selector?: string;
+    alignment?: 'left' | 'right';
+    vertical_padding?: number;
+    horizontal_padding?: number;
+    z_index?: number;
+    hide_default_launcher?: boolean;
+    hide_notifications?: boolean;
+    theme_mode?: IntercomThemeMode;
+    session_duration?: number;
+    action_color?: string;
+    background_color?: string;
+    link_color?: string;
+    email?: string;
+    user_id?: string;
+    created_at?: number;
+    name?: string;
+    phone?: string;
+    unsubscribed_from_emails?: boolean;
+    language_override?: string;
+    utm_campaign?: string;
+    utm_content?: string;
+    utm_medium?: string;
+    utm_source?: string;
+    utm_term?: string;
+    avatar?: IntercomAvatar;
+    user_hash?: string;
+    company?: IntercomCompany;
+    companies?: IntercomCompany[];
+    page_title?: string;
+}
+export type IntercomCustomSettings = Partial<Omit<IntercomSettings, 'app_id' | 'api_base'>> & Record<string, unknown>;
+declare global {
+    interface Window {
+        Intercom?: ((...args: unknown[]) => void) & {
+            q?: unknown[][];
+        };
+        intercomSettings?: IntercomSettings;
+    }
+}
+/**
+ * Intercom vendor manifest.
+ *
+ * Seeds `window.intercomSettings` and a queueing `Intercom` stub before loading
+ * the messenger widget bundle.
+ */
+export declare const intercomManifest: {
+    readonly kind: "c15t.vendor-manifest";
+    readonly schemaVersion: 1;
+    readonly vendor: 'intercom';
+    readonly category: 'functionality';
+    readonly install: [{
+        readonly type: 'defineStubFunction';
+        readonly name: 'Intercom';
+        readonly queue: {
+            readonly property: 'q';
+        };
+        readonly queueFormat: 'array';
+        readonly ifUndefined: true;
+    }, {
+        readonly type: 'setGlobal';
+        readonly name: 'intercomSettings';
+        readonly value: '{{settings}}';
+        readonly ifUndefined: false;
+    }, {
+        readonly type: 'loadScript';
+        readonly src: '{{scriptSrc}}';
+        readonly async: true;
+    }];
+};
+export interface IntercomOptions {
+    /**
+     * Your Intercom app ID.
+     */
+    appId: string;
+    /**
+     * Regional Intercom API base.
+     *
+     * @default 'https://api-iam.intercom.io'
+     */
+    apiBase?: IntercomApiBase;
+    /**
+     * Additional serializable Intercom settings merged into
+     * `window.intercomSettings`.
+     */
+    settings?: IntercomCustomSettings;
+    /** Intercom loader URL. */
+    scriptSrc?: string;
+}
+/**
+ * Creates an Intercom messenger script.
+ *
+ * The helper bootstraps the documented Intercom settings object and queues
+ * early `Intercom(...)` calls until the messenger bundle loads.
+ *
+ * @param options - The options for the Intercom script.
+ * @returns The Intercom script configuration.
+ *
+ * @example
+ * ```ts
+ * const intercomScript = intercom({
+ * 	appId: 'abc123',
+ * });
+ * ```
+ *
+ * @see {@link https://developers.intercom.com/installing-intercom/web/installation} Intercom installation documentation.
+ */
+export declare function intercom({ appId, apiBase, settings, scriptSrc, }: IntercomOptions): Script;

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

@@ -14,47 +14,44 @@ declare global {
  * - Signals consent state via `gtag('consent', 'default'|'update', ...)`
  */
 export declare const googleTagManagerManifest: {
-    readonly vendor: "google-tag-manager";
-    readonly category: "necessary";
+    readonly kind: "c15t.vendor-manifest";
+    readonly schemaVersion: 1;
+    readonly vendor: 'google-tag-manager';
+    readonly category: 'necessary';
     readonly alwaysLoad: 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: "pushToQueue";
-        readonly queue: "dataLayer";
+        readonly type: 'pushToQueue';
+        readonly queue: 'dataLayer';
         readonly value: {
-            readonly 'gtm.start': "{{loadTime}}";
-            readonly event: "gtm.js";
+            readonly 'gtm.start': {
+                readonly kind: "c15t.runtime-value";
+                readonly value: 'timestamp';
+            };
+            readonly event: 'gtm.js';
         };
     }, {
-        readonly type: "loadScript";
-        readonly src: "https://www.googletagmanager.com/gtm.js?id={{id}}";
+        readonly type: 'loadScript';
+        readonly src: 'https://www.googletagmanager.com/gtm.js?id={{id}}';
         readonly async: true;
     }];
     readonly onConsentChange: [{
-        readonly type: "callGlobal";
-        readonly global: "gtag";
+        readonly type: 'callGlobal';
+        readonly global: 'gtag';
         readonly args: ["event", "{{updateEventName}}"];
     }];
-    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 GoogleTagManagerOptions {
     /**

package/docs/README.md

@@ -0,0 +1,62 @@
+# @c15t/scripts
+
+> Consent-aware script integration docs for analytics, advertising pixels, tag managers, widgets, and custom loaders.
+
+These docs ship inside the package so coding agents can read them offline. Open the topic file you need from the list below — paths are relative to this file.
+
+## Frameworks
+
+Install and configure c15t in JavaScript, React, and Next.js applications.
+
+- [Script Loader](./frameworks/javascript/script-loader.md): Gate third-party scripts behind consent — load Google Analytics, Meta Pixel, and other tracking scripts only when users grant permission.
+- [Script Loader](./frameworks/next/script-loader.md): Gate third-party scripts behind consent in Next.js — load Google Analytics, Meta Pixel, and other tracking scripts only when users grant permission.
+- [Script Loader](./frameworks/react/script-loader.md): Gate third-party scripts behind consent in React — load Google Analytics, Meta Pixel, and other tracking scripts only when users grant permission.
+
+## Integrations
+
+Connect analytics, advertising, maps, media, and other third-party tools behind consent.
+
+- [Adobe Analytics](./integrations/adobe-analytics.md): Adobe Analytics loaded through an Adobe Experience Platform Data Collection Tags embed URL.
+- [Ahrefs Analytics](./integrations/ahrefs-analytics.md): Cookieless web analytics from Ahrefs with a prebuilt helper that wires the project key into a c15t-managed script.
+- [Amplitude](./integrations/amplitude.md): Load Amplitude Browser SDK 2 with c15t and gate product analytics behind measurement consent.
+- [Build a Custom Script Integration](./integrations/building-integrations.md): Learn when to use a raw Script, when to build a reusable manifest-backed integration, and how to debug and test custom consent-aware scripts in c15t.
+- [Clearbit](./integrations/clearbit.md): Visitor and company enrichment loaded with Clearbit's account-keyed tags.js snippet.
+- [Cloudflare Web Analytics](./integrations/cloudflare-web-analytics.md): Cookieless analytics from Cloudflare with a prebuilt helper that serializes the beacon config into the `data-cf-beacon` attribute.
+- [Crisp](./integrations/crisp.md): Load Crisp live chat with website ID, runtime, cookie, and session options.
+- [Databuddy](./integrations/databuddy.md): Databuddy is a privacy-focused analytics platform that helps you understand user behavior and track events. It supports cookieless tracking and manages consent automatically through c15t's consent state synchronization.
+- [Fathom Analytics](./integrations/fathom-analytics.md): Privacy-friendly cookieless analytics with a prebuilt helper that maps Fathom's data attributes into a c15t-managed script.
+- [Google Maps](./integrations/google-maps.md): Render Google Maps only after consent with one shared Maps JavaScript API loader and independently managed map instances.
+- [GA4 + Google Ads (gtag.js)](./integrations/google-tag.md): Send data to Google Analytics 4 and Google Ads with automatic Consent Mode v2 support.
+- [Google Tag Manager](./integrations/google-tag-manager.md): Deploy and manage marketing tags centrally with automatic consent state synchronization.
+- [Heap](./integrations/heap.md): Load Heap with c15t and gate autocapture product analytics behind measurement consent.
+- [Hightouch](./integrations/hightouch.md): Load Hightouch Events with c15t and gate the browser SDK behind measurement consent.
+- [Hotjar](./integrations/hotjar.md): Product analytics and behavior insights with a prebuilt helper that seeds Hotjar globals before loading the vendor bundle.
+- [Intercom](./integrations/intercom.md): Bootstrap Intercom settings and load the messenger widget bundle.
+- [LinkedIn Insights](./integrations/linkedin-insights.md): Track conversions and build matched audiences for LinkedIn advertising campaigns.
+- [LogRocket](./integrations/logrocket.md): Session replay and monitoring loaded after measurement consent with LogRocket's browser SDK.
+- [Matomo Analytics](./integrations/matomo-analytics.md): Load Matomo with c15t and keep Matomo's queue aligned with measurement consent.
+- [Meta Pixel](./integrations/meta-pixel.md): Track conversions and build audiences for Facebook and Instagram advertising campaigns.
+- [Microsoft Clarity](./integrations/microsoft-clarity.md): Session replay and behavior analytics with a prebuilt helper that keeps Clarity consent synchronized with c15t measurement state.
+- [Microsoft UET](./integrations/microsoft-uet.md): Track conversions and measure performance for Microsoft Advertising and Bing Ads.
+- [Mixpanel Analytics](./integrations/mixpanel-analytics.md): Load Mixpanel with c15t and let Mixpanel's own opt-in and opt-out APIs follow measurement consent.
+- [Integrations](./integrations/overview.md): Load analytics, pixels, tag managers, and widgets through c15t so consent state controls when they run, update, and appear in your consent UI.
+- [Pirsch](./integrations/pirsch.md): Privacy-friendly, cookieless analytics loaded with Pirsch's fixed script id and identification-code attributes.
+- [Plausible Analytics](./integrations/plausible-analytics.md): Privacy-friendly cookieless analytics with a prebuilt helper that preserves Plausible's queue bootstrap and loader attributes.
+- [PostHog](./integrations/posthog.md): PostHog is an open-source product analytics platform for tracking user behavior, session replays, feature flags, and A/B testing. It supports cookieless tracking, allowing analytics to continue even without cookie consent.
+- [Promptwatch](./integrations/promptwatch.md): Promptwatch analyzes traffic on your site for Artificial Intelligence (AI) traffic and usage insights. Data is stored in the EU without user-identifiable information.
+- [Reddit Pixel](./integrations/reddit-pixel.md): Track conversions and build retargeting audiences for Reddit advertising campaigns.
+- [RudderStack](./integrations/rudderstack.md): Load RudderStack's JavaScript SDK with c15t and gate the browser SDK behind measurement consent.
+- [Rybbit Analytics](./integrations/rybbit-analytics.md): Privacy-friendly analytics with script-tag configuration via Rybbit's data attributes.
+- [Segment](./integrations/segment.md): Load Segment Analytics.js with c15t and gate it behind measurement consent.
+- [Snapchat Pixel](./integrations/snapchat-pixel.md): Measure Snapchat ad performance and build remarketing audiences with a prebuilt pixel helper.
+- [TikTok Pixel](./integrations/tiktok-pixel.md): Measure ad performance and build audiences for TikTok advertising campaigns.
+- [Umami Analytics](./integrations/umami-analytics.md): Open-source, cookieless analytics with a prebuilt helper that maps Umami's data attributes into a c15t-managed script.
+- [Vercel Analytics](./integrations/vercel-analytics.md): Bootstrap Vercel Analytics with a declarative queue and script attributes.
+- [X Pixel (Twitter Pixel)](./integrations/x-pixel.md): Track conversions and build audiences for advertising campaigns on X (formerly Twitter).
+- [YouTube](./integrations/youtube.md): Keep YouTube iframes unmounted until consent with a privacy-enhanced, lazy-loaded React or Next.js embed.
+
+## Reference
+
+Concepts, legal templates, open-source policies, and contributor documentation.
+
+- [Script Loader](./shared/react/guides/script-loader.md): Reference page for script loader.