@jwiedeman/gtm-kit 1.0.1

package/dist/index.d.cts

@@ -0,0 +1,431 @@
+declare const CONSENT_COMMAND: "consent";
+declare const CONSENT_DEFAULT: "default";
+declare const CONSENT_UPDATE: "update";
+/**
+ * The four consent categories tracked by Google Consent Mode v2.
+ */
+declare const CONSENT_KEYS: readonly ["ad_storage", "analytics_storage", "ad_user_data", "ad_personalization"];
+/**
+ * A consent category key: 'ad_storage' | 'analytics_storage' | 'ad_user_data' | 'ad_personalization'
+ */
+type ConsentKey = (typeof CONSENT_KEYS)[number];
+/**
+ * A consent decision: 'granted' or 'denied'
+ */
+type ConsentDecision = 'granted' | 'denied';
+/**
+ * Consent state object for one or more categories.
+ *
+ * This is a **partial** record - you only need to specify the categories you want to set.
+ * Unspecified categories retain their previous state when using `updateConsent()`.
+ *
+ * @example
+ * ```ts
+ * // All four categories
+ * const fullState: ConsentState = {
+ *   ad_storage: 'granted',
+ *   analytics_storage: 'granted',
+ *   ad_user_data: 'granted',
+ *   ad_personalization: 'granted'
+ * };
+ *
+ * // Single category (partial update)
+ * const partialState: ConsentState = {
+ *   analytics_storage: 'granted'
+ * };
+ *
+ * // Multiple specific categories
+ * const mixedState: ConsentState = {
+ *   analytics_storage: 'granted',
+ *   ad_storage: 'denied'
+ * };
+ * ```
+ */
+type ConsentState = Partial<Record<ConsentKey, ConsentDecision>>;
+interface ConsentRegionOptions {
+    /**
+     * ISO 3166-2 region codes (e.g., `US-CA`, `EEA`) that the consent command applies to.
+     */
+    region?: readonly string[];
+    /**
+     * Milliseconds to wait for an explicit update before firing tags when using the default command.
+     */
+    waitForUpdate?: number;
+}
+type ConsentCommand = typeof CONSENT_DEFAULT | typeof CONSENT_UPDATE;
+interface ConsentCommandInput {
+    command: ConsentCommand;
+    state: ConsentState;
+    options?: ConsentRegionOptions;
+}
+type ConsentCommandValue = [typeof CONSENT_COMMAND, ConsentCommand, ConsentState] | [typeof CONSENT_COMMAND, ConsentCommand, ConsentState, Record<string, unknown>];
+declare const buildConsentCommand: ({ command, state, options }: ConsentCommandInput) => ConsentCommandValue;
+declare const createConsentDefaultsCommand: (state: ConsentState, options?: ConsentRegionOptions) => DataLayerValue;
+declare const createConsentUpdateCommand: (state: ConsentState, options?: ConsentRegionOptions) => DataLayerValue;
+declare const consent: {
+    buildConsentCommand: ({ command, state, options }: ConsentCommandInput) => ConsentCommandValue;
+    createConsentDefaultsCommand: (state: ConsentState, options?: ConsentRegionOptions) => DataLayerValue;
+    createConsentUpdateCommand: (state: ConsentState, options?: ConsentRegionOptions) => DataLayerValue;
+    normalizeConsentState: (state: ConsentState) => ConsentState;
+};
+
+type DataLayerValue = Record<string, unknown> | ((...args: unknown[]) => unknown) | unknown[];
+interface Logger {
+    debug(message: string, details?: Record<string, unknown>): void;
+    info(message: string, details?: Record<string, unknown>): void;
+    warn(message: string, details?: Record<string, unknown>): void;
+    error(message: string, details?: Record<string, unknown>): void;
+}
+type PartialLogger = Partial<Logger>;
+type ScriptAttributeValue = string | boolean | null | undefined;
+interface ScriptAttributes {
+    async?: boolean;
+    defer?: boolean;
+    nonce?: string;
+    [attribute: string]: ScriptAttributeValue;
+}
+type ScriptLoadStatus = 'loaded' | 'failed' | 'skipped';
+interface ScriptLoadState {
+    containerId: string;
+    src?: string;
+    status: ScriptLoadStatus;
+    fromCache?: boolean;
+    error?: string;
+}
+interface ContainerDescriptor {
+    id: string;
+    queryParams?: Record<string, string | number | boolean>;
+}
+type ContainerConfigInput = string | ContainerDescriptor;
+interface CreateGtmClientOptions {
+    containers: ContainerConfigInput[] | ContainerConfigInput;
+    dataLayerName?: string;
+    host?: string;
+    defaultQueryParams?: Record<string, string | number | boolean>;
+    scriptAttributes?: ScriptAttributes;
+    logger?: PartialLogger;
+}
+interface GtmClient {
+    readonly dataLayerName: string;
+    init(): void;
+    push(value: DataLayerValue): void;
+    setConsentDefaults(state: ConsentState, options?: ConsentRegionOptions): void;
+    updateConsent(state: ConsentState, options?: ConsentRegionOptions): void;
+    teardown(): void;
+    isInitialized(): boolean;
+    whenReady(): Promise<ScriptLoadState[]>;
+    onReady(callback: (state: ScriptLoadState[]) => void): () => void;
+}
+
+declare const DEFAULT_GTM_HOST = "https://www.googletagmanager.com";
+declare const DEFAULT_DATA_LAYER_NAME = "dataLayer";
+
+/**
+ * Pre-configured consent state presets for common scenarios.
+ *
+ * These presets cover the most common consent patterns:
+ * - `eeaDefault`: All denied (GDPR compliant default)
+ * - `allGranted`: All granted (user accepts everything)
+ * - `analyticsOnly`: Mixed state (analytics only, no ads)
+ *
+ * For custom combinations, pass a partial `ConsentState` object to `updateConsent()`.
+ * You only need to specify the categories you want to update.
+ *
+ * @example
+ * ```ts
+ * // Use a preset
+ * client.updateConsent(consentPresets.allGranted);
+ *
+ * // Or create a custom state
+ * client.updateConsent({
+ *   analytics_storage: 'granted',
+ *   ad_storage: 'denied'
+ * });
+ *
+ * // Partial updates (only update specific categories)
+ * client.updateConsent({ analytics_storage: 'granted' });
+ * ```
+ */
+declare const consentPresets: {
+    /**
+     * All categories denied - GDPR/EEA compliant default.
+     *
+     * Use as the initial state for regions requiring explicit opt-in consent.
+     * Tags will be blocked until the user grants specific permissions.
+     *
+     * | Category | State |
+     * |----------|-------|
+     * | ad_storage | denied |
+     * | analytics_storage | denied |
+     * | ad_user_data | denied |
+     * | ad_personalization | denied |
+     */
+    readonly eeaDefault: Readonly<{
+        ad_storage: "denied";
+        analytics_storage: "denied";
+        ad_user_data: "denied";
+        ad_personalization: "denied";
+    }>;
+    /**
+     * All categories granted - user accepts all tracking.
+     *
+     * Use when the user clicks "Accept All" or in regions where consent is implied.
+     *
+     * | Category | State |
+     * |----------|-------|
+     * | ad_storage | granted |
+     * | analytics_storage | granted |
+     * | ad_user_data | granted |
+     * | ad_personalization | granted |
+     */
+    readonly allGranted: Readonly<{
+        ad_storage: "granted";
+        analytics_storage: "granted";
+        ad_user_data: "granted";
+        ad_personalization: "granted";
+    }>;
+    /**
+     * Analytics allowed, advertising denied - mixed consent state.
+     *
+     * Use when the user accepts analytics/statistics but rejects advertising cookies.
+     * This is a common "essential + analytics" consent pattern.
+     *
+     * | Category | State |
+     * |----------|-------|
+     * | ad_storage | denied |
+     * | analytics_storage | granted |
+     * | ad_user_data | denied |
+     * | ad_personalization | denied |
+     */
+    readonly analyticsOnly: Readonly<{
+        ad_storage: "denied";
+        analytics_storage: "granted";
+        ad_user_data: "denied";
+        ad_personalization: "denied";
+    }>;
+};
+type ConsentPresetName = keyof typeof consentPresets;
+declare const getConsentPreset: (name: ConsentPresetName) => ConsentState;
+
+declare const createGtmClient: (options: CreateGtmClientOptions) => GtmClient;
+
+type EventName = string;
+type EventPayload = Record<string, unknown>;
+type GtmEvent<TName extends EventName = EventName, TPayload extends EventPayload = EventPayload> = Readonly<{
+    event: TName;
+} & TPayload>;
+type CustomEvent<TName extends EventName, TPayload extends EventPayload = EventPayload> = GtmEvent<TName, TPayload>;
+interface PageViewPayload extends EventPayload {
+    page_title?: string;
+    page_location?: string;
+    page_path?: string;
+    send_to?: string;
+}
+type PageViewEvent = GtmEvent<'page_view', PageViewPayload>;
+interface AdsConversionPayload extends EventPayload {
+    send_to: string;
+    value?: number;
+    currency?: string;
+    transaction_id?: string;
+    user_data?: Record<string, unknown>;
+}
+type AdsConversionEvent = GtmEvent<'conversion', AdsConversionPayload>;
+interface EcommerceItem extends EventPayload {
+    item_id?: string;
+    item_name?: string;
+    item_brand?: string;
+    item_category?: string;
+    item_category2?: string;
+    item_category3?: string;
+    item_category4?: string;
+    item_category5?: string;
+    item_variant?: string;
+    price?: number;
+    quantity?: number;
+    coupon?: string;
+    discount?: number;
+}
+interface EcommercePayload extends EventPayload {
+    affiliation?: string;
+    coupon?: string;
+    currency?: string;
+    items: readonly EcommerceItem[];
+    shipping?: number;
+    tax?: number;
+    transaction_id?: string;
+    value?: number;
+}
+type EcommerceEventName = 'add_payment_info' | 'add_shipping_info' | 'add_to_cart' | 'begin_checkout' | 'purchase' | 'refund' | 'remove_from_cart' | 'select_item' | 'select_promotion' | 'view_cart' | 'view_item' | 'view_item_list' | 'view_promotion';
+type EcommerceEvent<TName extends EventName = EcommerceEventName, TExtras extends EventPayload = EventPayload> = GtmEvent<TName, {
+    ecommerce: EcommercePayload;
+} & TExtras>;
+type EventForName<TName extends EventName> = TName extends 'page_view' ? PageViewEvent : TName extends 'conversion' ? AdsConversionEvent : TName extends EcommerceEventName ? EcommerceEvent<TName> : CustomEvent<TName>;
+
+declare const pushEvent: <TName extends string, TPayload extends EventPayload = EventPayload>(client: Pick<GtmClient, 'push'>, name: TName, payload?: TPayload) => EventForName<TName>;
+interface PushEcommerceOptions<TExtras extends EventPayload = EventPayload> {
+    extras?: TExtras;
+}
+declare const pushEcommerce: <TName extends EcommerceEventName, TExtras extends EventPayload = EventPayload>(client: Pick<GtmClient, 'push'>, name: TName, ecommerce: EcommercePayload, options?: PushEcommerceOptions<TExtras>) => EcommerceEvent<TName, TExtras>;
+
+interface NoscriptOptions {
+    host?: string;
+    defaultQueryParams?: Record<string, string | number | boolean>;
+    iframeAttributes?: Record<string, string | number | boolean>;
+}
+declare const createNoscriptMarkup: (containers: ContainerConfigInput[] | ContainerConfigInput, options?: NoscriptOptions) => string;
+declare const DEFAULT_NOSCRIPT_IFRAME_ATTRIBUTES: {
+    [x: string]: string;
+};
+
+/**
+ * Auto-queue: Automatic dataLayer buffering for race condition elimination.
+ *
+ * This module provides automatic buffering of dataLayer pushes that occur before
+ * GTM.js loads. Events are captured, stored in order, and replayed once GTM is ready.
+ *
+ * @example
+ * ```ts
+ * // Call as early as possible (ideally inline in <head>)
+ * import { installAutoQueue } from '@react-gtm-kit/core';
+ *
+ * installAutoQueue(); // Start buffering immediately
+ *
+ * // Later, events pushed before GTM loads are automatically queued
+ * window.dataLayer.push({ event: 'early_event' }); // Buffered!
+ *
+ * // When GTM loads, all buffered events replay in order
+ * ```
+ *
+ * @example
+ * ```html
+ * <!-- Inline script for earliest possible buffering -->
+ * <script>
+ *   // Minimal inline version for <head>
+ *   (function(w,d,n){
+ *     w[n]=w[n]||[];var q=[],o=w[n].push.bind(w[n]);
+ *     w[n].push=function(){q.push(arguments);return o.apply(this,arguments)};
+ *     w.__gtmkit_buffer=q;
+ *   })(window,document,'dataLayer');
+ * </script>
+ * ```
+ */
+/** Options for configuring the auto-queue behavior */
+interface AutoQueueOptions {
+    /**
+     * Name of the dataLayer array. Defaults to 'dataLayer'.
+     */
+    dataLayerName?: string;
+    /**
+     * Interval in milliseconds to check if GTM has loaded.
+     * Lower values = faster detection, higher CPU usage.
+     * @default 50
+     */
+    pollInterval?: number;
+    /**
+     * Maximum time in milliseconds to wait for GTM before giving up.
+     * Set to 0 for unlimited waiting.
+     * @default 30000 (30 seconds)
+     */
+    timeout?: number;
+    /**
+     * Maximum number of events to buffer.
+     * Prevents memory issues if GTM never loads.
+     * @default 1000
+     */
+    maxBufferSize?: number;
+    /**
+     * Callback fired when the buffer is replayed.
+     */
+    onReplay?: (bufferedCount: number) => void;
+    /**
+     * Callback fired if timeout is reached before GTM loads.
+     */
+    onTimeout?: (bufferedCount: number) => void;
+}
+/** State of the auto-queue system */
+interface AutoQueueState {
+    /** Whether the auto-queue is currently active */
+    active: boolean;
+    /** Number of events currently buffered */
+    bufferedCount: number;
+    /** Whether GTM has been detected as ready */
+    gtmReady: boolean;
+    /** Manually trigger replay (useful for testing) */
+    replay: () => void;
+    /** Uninstall the auto-queue and restore original push */
+    uninstall: () => void;
+}
+/**
+ * Installs automatic dataLayer buffering that captures events before GTM loads.
+ *
+ * Call this as early as possible in your application lifecycle, ideally before
+ * any other scripts that might push to the dataLayer.
+ *
+ * The auto-queue:
+ * 1. Creates the dataLayer if it doesn't exist
+ * 2. Intercepts all pushes to capture them in a buffer
+ * 3. Detects when GTM.js loads by watching for the 'gtm.js' event
+ * 4. Replays all buffered events in order once GTM is ready
+ * 5. Removes itself, allowing normal dataLayer operation
+ *
+ * @param options - Configuration options
+ * @returns State object with control methods
+ *
+ * @example
+ * ```ts
+ * const queue = installAutoQueue({
+ *   onReplay: (count) => console.log(`Replayed ${count} buffered events`),
+ *   onTimeout: (count) => console.warn(`GTM didn't load, ${count} events buffered`)
+ * });
+ *
+ * // Check state
+ * console.log(queue.bufferedCount); // Number of events waiting
+ *
+ * // Manual control (usually not needed)
+ * queue.replay();    // Force replay now
+ * queue.uninstall(); // Remove the interceptor
+ * ```
+ */
+declare function installAutoQueue(options?: AutoQueueOptions): AutoQueueState;
+/**
+ * Creates a minimal inline script for earliest possible buffering.
+ *
+ * This returns a script that can be embedded directly in the HTML `<head>`
+ * before any other scripts. It's a minimal version of installAutoQueue()
+ * that captures events until the full GTM Kit is loaded.
+ *
+ * @param dataLayerName - Name of the dataLayer array
+ * @returns Inline script string to embed in HTML
+ *
+ * @example
+ * ```ts
+ * // In your SSR template
+ * const inlineScript = createAutoQueueScript();
+ * // Output: <script>{inlineScript}</script> in <head>
+ * ```
+ */
+declare function createAutoQueueScript(dataLayerName?: string): string;
+/**
+ * Attaches to an existing inline buffer created by createAutoQueueScript().
+ *
+ * If you used the inline script in your HTML head, call this when the full
+ * GTM Kit loads to take over buffer management and enable replay.
+ *
+ * @param options - Configuration options
+ * @returns State object, or null if no inline buffer exists
+ *
+ * @example
+ * ```ts
+ * // After GTM Kit bundle loads
+ * const queue = attachToInlineBuffer({
+ *   onReplay: (count) => console.log(`Replayed ${count} events`)
+ * });
+ *
+ * if (queue) {
+ *   console.log(`Taking over ${queue.bufferedCount} buffered events`);
+ * }
+ * ```
+ */
+declare function attachToInlineBuffer(options?: Omit<AutoQueueOptions, 'dataLayerName'>): AutoQueueState | null;
+
+export { AdsConversionEvent, AdsConversionPayload, AutoQueueOptions, AutoQueueState, ConsentCommand, ConsentRegionOptions, ConsentState, ContainerConfigInput, ContainerDescriptor, CreateGtmClientOptions, CustomEvent, DEFAULT_DATA_LAYER_NAME, DEFAULT_GTM_HOST, DEFAULT_NOSCRIPT_IFRAME_ATTRIBUTES, DataLayerValue, EcommerceEvent, EcommerceEventName, EcommerceItem, EcommercePayload, EventForName, EventName, EventPayload, GtmClient, GtmEvent, NoscriptOptions, PageViewEvent, PageViewPayload, PushEcommerceOptions, ScriptAttributes, ScriptLoadState, ScriptLoadStatus, attachToInlineBuffer, buildConsentCommand, consent, consentPresets, createAutoQueueScript, createConsentDefaultsCommand, createConsentUpdateCommand, createGtmClient, createNoscriptMarkup, getConsentPreset, installAutoQueue, pushEcommerce, pushEvent };