@aranova/tracking-next 0.5.1 → 0.6.1

package/dist/index.d.mts

@@ -1,11 +1,25 @@
-import { C as ConsentState, T as TrackingInstallSurface, a as TrackingClientContext, b as TrackingParams, c as TrackingEventCreatePayload, d as TrackingSessionUpsertPayload } from './types-Gp0ioRiQ.mjs';
-export { e as TrackingInitConfig } from './types-Gp0ioRiQ.mjs';
+import { C as ConsentState, T as TrackingInstallSurface, a as TrackingClientContext, b as TrackingParams, c as TrackingEventCreatePayload, d as TrackingSessionUpsertPayload } from './types-B4VZHWnc.mjs';
+export { e as TrackingInitConfig } from './types-B4VZHWnc.mjs';
 import { z } from 'zod';
+import * as src from 'src';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ReactNode } from 'react';
 
+/**
+ * Google Consent Mode value sent to `gtag('consent', 'update', ...)`.
+ */
 type GtagConsentValue = 'granted' | 'denied';
+/**
+ * Read the persisted visitor consent state from localStorage.
+ *
+ * Returns `pending` when called during SSR or before the visitor has made a
+ * choice.
+ */
 declare function getConsentState(): ConsentState;
+/**
+ * Persist a visitor consent choice and update Google Consent Mode when gtag is
+ * loaded.
+ */
 declare function setConsentState(state: GtagConsentValue): void;
 
 interface TrackingContextInput {
@@ -27,18 +41,42 @@ interface TrackingSessionInput {
     sessionId: string;
     visitorId?: string | null;
 }
+/**
+ * Build runtime context attached to tracking sessions and events.
+ */
 declare function createTrackingClientContext(surface: TrackingInstallSurface, input?: TrackingContextInput): TrackingClientContext;
+/**
+ * Build the session portion of a tracking ingest request.
+ */
 declare function createTrackingSessionUpsertPayload(trackingParams: TrackingParams, input: TrackingSessionInput, context: TrackingClientContext): TrackingSessionUpsertPayload;
+/**
+ * Build one event payload before it is batched into a tracking ingest request.
+ */
 declare function createTrackingEventCreatePayload(trackingParams: TrackingParams, input: TrackingEventInput, context: TrackingClientContext): TrackingEventCreatePayload;
 
+/**
+ * Attribution query/cookie keys captured by the SDK.
+ */
 declare const TRACKING_PARAM_KEYS: readonly ["gclid", "fbclid", "utm_source", "utm_medium", "utm_campaign", "utm_term", "utm_content"];
+/**
+ * Capture tracking params from a URL, persist them to first-party cookies, and
+ * return the current cookie-backed attribution state.
+ *
+ * Defaults to `window.location.href` in the browser.
+ */
 declare function captureTrackingParamsFromLocation(url?: string, maxAgeSeconds?: number): TrackingParams;
 
+/**
+ * Metadata for a manually fired `cta_click` event.
+ *
+ * Use this for non-phone calls to action such as directions, appointment
+ * buttons, downloads, or external booking links.
+ */
 declare const ctaClickMetadataSchema: z.ZodObject<{
     cta_name: z.ZodString;
     page: z.ZodObject<{
         path: z.ZodString;
-    }, "strip", z.ZodTypeAny, {
+    }, "strict", z.ZodTypeAny, {
         path: string;
     }, {
         path: string;
@@ -61,9 +99,21 @@ declare const ctaClickMetadataSchema: z.ZodObject<{
     destination_url?: string | null | undefined;
 }>;
 type CtaClickMetadata = z.infer<typeof ctaClickMetadataSchema>;
+/**
+ * Registration config for `cta_click`.
+ *
+ * This event is manual-only and currently has no registration options.
+ */
 declare const ctaClickConfigSchema: z.ZodObject<{}, "strict", z.ZodTypeAny, {}, {}>;
 type CtaClickConfig = z.infer<typeof ctaClickConfigSchema>;
 
+/**
+ * Metadata for the SDK-internal `sdk_heartbeat` event.
+ *
+ * The SDK fires this once per new session so the dashboard can show which SDK
+ * version, install surface, and trigger registry a client site is running.
+ * Consumers do not manually register or fire this event.
+ */
 declare const sdkHeartbeatMetadataSchema: z.ZodObject<{
     sdk_version: z.ZodString;
     package_name: z.ZodNullable<z.ZodString>;
@@ -99,14 +149,24 @@ declare const sdkHeartbeatMetadataSchema: z.ZodObject<{
     trigger_config?: Record<string, Record<string, unknown>> | null | undefined;
 }>;
 type SdkHeartbeatMetadata = z.infer<typeof sdkHeartbeatMetadataSchema>;
+/**
+ * Internal registration config for `sdk_heartbeat`.
+ *
+ * This event has no consumer-facing options.
+ */
 declare const sdkHeartbeatConfigSchema: z.ZodObject<{}, "strict", z.ZodTypeAny, {}, {}>;
 type SdkHeartbeatConfig = z.infer<typeof sdkHeartbeatConfigSchema>;
 
+/**
+ * Metadata for the automatic `form_start` event.
+ *
+ * The SDK emits this once per form when the visitor first focuses a field.
+ */
 declare const formStartMetadataSchema: z.ZodObject<{
     form: z.ZodObject<{
         id: z.ZodString;
         action: z.ZodNullable<z.ZodString>;
-    }, "strip", z.ZodTypeAny, {
+    }, "strict", z.ZodTypeAny, {
         id: string;
         action: string | null;
     }, {
@@ -115,7 +175,7 @@ declare const formStartMetadataSchema: z.ZodObject<{
     }>;
     page: z.ZodObject<{
         path: z.ZodString;
-    }, "strip", z.ZodTypeAny, {
+    }, "strict", z.ZodTypeAny, {
         path: string;
     }, {
         path: string;
@@ -138,6 +198,12 @@ declare const formStartMetadataSchema: z.ZodObject<{
     };
 }>;
 type FormStartMetadata = z.infer<typeof formStartMetadataSchema>;
+/**
+ * Registration config for automatic `form_start`.
+ *
+ * Use `selector` to narrow which forms can trigger the event. When omitted,
+ * the SDK observes all `<form>` elements.
+ */
 declare const formStartConfigSchema: z.ZodObject<{
     selector: z.ZodOptional<z.ZodString>;
 }, "strict", z.ZodTypeAny, {
@@ -147,6 +213,46 @@ declare const formStartConfigSchema: z.ZodObject<{
 }>;
 type FormStartConfig = z.infer<typeof formStartConfigSchema>;
 
+/**
+ * JSON-serializable value accepted by `form_submit.fields[].value`.
+ *
+ * This intentionally excludes `undefined`, functions, symbols, `Date`
+ * instances, and non-finite numbers. Values are stored in PostgreSQL JSONB, so
+ * consumers should send only data that has a stable JSON representation.
+ */
+type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+/**
+ * Metadata for a manually fired `form_submit` event.
+ *
+ * Register the event with `manual: { form_submit: {} }`, then call
+ * `trackEvent('form_submit', metadata)` from the host site's submit handler.
+ *
+ * `fields` is optional. If present, each field value must be JSON-serializable
+ * and should be explicitly allowlisted by the integration. Do not send names,
+ * emails, visitor phone numbers, addresses, payment data, medical details,
+ * passwords, file contents, or free-text messages.
+ *
+ * @example
+ * ```ts
+ * tracking.trackEvent('form_submit', {
+ *   form: {
+ *     id: 'lead-form',
+ *     action: '/api/lead',
+ *     fields: [
+ *       {
+ *         name: 'service_interest',
+ *         type: 'select',
+ *         label: 'Service interest',
+ *         value: 'teeth_whitening',
+ *       },
+ *     ],
+ *   },
+ *   page: { path: window.location.pathname },
+ * });
+ * ```
+ */
 declare const formSubmitMetadataSchema: z.ZodObject<{
     form: z.ZodObject<{
         id: z.ZodString;
@@ -155,40 +261,40 @@ declare const formSubmitMetadataSchema: z.ZodObject<{
             name: z.ZodString;
             type: z.ZodString;
             label: z.ZodNullable<z.ZodString>;
-            has_value: z.ZodBoolean;
-        }, "strip", z.ZodTypeAny, {
+            value: z.ZodType<JsonValue, z.ZodTypeDef, JsonValue>;
+        }, "strict", z.ZodTypeAny, {
             label: string | null;
+            value: JsonValue;
             type: string;
             name: string;
-            has_value: boolean;
         }, {
             label: string | null;
+            value: JsonValue;
             type: string;
             name: string;
-            has_value: boolean;
         }>, "many">>;
-    }, "strip", z.ZodTypeAny, {
+    }, "strict", z.ZodTypeAny, {
         id: string;
         action: string | null;
         fields?: {
             label: string | null;
+            value: JsonValue;
             type: string;
             name: string;
-            has_value: boolean;
         }[] | undefined;
     }, {
         id: string;
         action: string | null;
         fields?: {
             label: string | null;
+            value: JsonValue;
             type: string;
             name: string;
-            has_value: boolean;
         }[] | undefined;
     }>;
     page: z.ZodObject<{
         path: z.ZodString;
-    }, "strip", z.ZodTypeAny, {
+    }, "strict", z.ZodTypeAny, {
         path: string;
     }, {
         path: string;
@@ -199,9 +305,9 @@ declare const formSubmitMetadataSchema: z.ZodObject<{
         action: string | null;
         fields?: {
             label: string | null;
+            value: JsonValue;
             type: string;
             name: string;
-            has_value: boolean;
         }[] | undefined;
     };
     page: {
@@ -213,9 +319,9 @@ declare const formSubmitMetadataSchema: z.ZodObject<{
         action: string | null;
         fields?: {
             label: string | null;
+            value: JsonValue;
             type: string;
             name: string;
-            has_value: boolean;
         }[] | undefined;
     };
     page: {
@@ -223,14 +329,26 @@ declare const formSubmitMetadataSchema: z.ZodObject<{
     };
 }>;
 type FormSubmitMetadata = z.infer<typeof formSubmitMetadataSchema>;
+/**
+ * Registration config for `form_submit`.
+ *
+ * This event is manual-only and currently has no registration options. The
+ * empty object enables typed `trackEvent('form_submit', ...)` calls.
+ */
 declare const formSubmitConfigSchema: z.ZodObject<{}, "strict", z.ZodTypeAny, {}, {}>;
 type FormSubmitConfig = z.infer<typeof formSubmitConfigSchema>;
 
+/**
+ * Metadata for the automatic `multi_page_session` event.
+ *
+ * Fired when the visitor reaches the configured distinct-page threshold in a
+ * single tracking session.
+ */
 declare const multiPageSessionMetadataSchema: z.ZodObject<{
     page_count: z.ZodNumber;
     page: z.ZodObject<{
         path: z.ZodString;
-    }, "strip", z.ZodTypeAny, {
+    }, "strict", z.ZodTypeAny, {
         path: string;
     }, {
         path: string;
@@ -247,6 +365,9 @@ declare const multiPageSessionMetadataSchema: z.ZodObject<{
     page_count: number;
 }>;
 type MultiPageSessionMetadata = z.infer<typeof multiPageSessionMetadataSchema>;
+/**
+ * Registration config for automatic `multi_page_session`.
+ */
 declare const multiPageSessionConfigSchema: z.ZodObject<{
     pageThreshold: z.ZodNumber;
 }, "strict", z.ZodTypeAny, {
@@ -256,13 +377,20 @@ declare const multiPageSessionConfigSchema: z.ZodObject<{
 }>;
 type MultiPageSessionConfig = z.infer<typeof multiPageSessionConfigSchema>;
 
+/**
+ * Metadata for the automatic `page_view` event.
+ *
+ * The SDK emits this on initial load, SPA route changes, and bfcache restores.
+ * Consumers do not call `trackEvent('page_view', ...)`; registering
+ * `automatic: { page_view: {} }` enables the SDK-owned trigger.
+ */
 declare const pageViewMetadataSchema: z.ZodObject<{
     page: z.ZodObject<{
         title: z.ZodNullable<z.ZodString>;
         path: z.ZodString;
         search: z.ZodString;
         hash: z.ZodString;
-    }, "strip", z.ZodTypeAny, {
+    }, "strict", z.ZodTypeAny, {
         search: string;
         title: string | null;
         path: string;
@@ -277,7 +405,7 @@ declare const pageViewMetadataSchema: z.ZodObject<{
     viewport: z.ZodOptional<z.ZodNullable<z.ZodObject<{
         w: z.ZodNumber;
         h: z.ZodNumber;
-    }, "strip", z.ZodTypeAny, {
+    }, "strict", z.ZodTypeAny, {
         w: number;
         h: number;
     }, {
@@ -310,14 +438,27 @@ declare const pageViewMetadataSchema: z.ZodObject<{
     } | null | undefined;
 }>;
 type PageViewMetadata = z.infer<typeof pageViewMetadataSchema>;
+/**
+ * Registration config for automatic `page_view`.
+ *
+ * `page_view` is required in every trigger registry and currently has no
+ * options. Use `{ page_view: {} }`.
+ */
 declare const pageViewConfigSchema: z.ZodObject<{}, "strict", z.ZodTypeAny, {}, {}>;
 type PageViewConfig = z.infer<typeof pageViewConfigSchema>;
 
+/**
+ * Metadata for a manually fired `phone_click` event.
+ *
+ * `phone_number` should be the business phone number from the clicked `tel:`
+ * link, not a visitor-entered phone number. `section` can distinguish header,
+ * footer, hero, or contact-page links.
+ */
 declare const phoneClickMetadataSchema: z.ZodObject<{
     phone_number: z.ZodString;
     page: z.ZodObject<{
         path: z.ZodString;
-    }, "strip", z.ZodTypeAny, {
+    }, "strict", z.ZodTypeAny, {
         path: string;
     }, {
         path: string;
@@ -337,14 +478,24 @@ declare const phoneClickMetadataSchema: z.ZodObject<{
     section?: string | null | undefined;
 }>;
 type PhoneClickMetadata = z.infer<typeof phoneClickMetadataSchema>;
+/**
+ * Registration config for `phone_click`.
+ *
+ * This event is manual-only and currently has no registration options.
+ */
 declare const phoneClickConfigSchema: z.ZodObject<{}, "strict", z.ZodTypeAny, {}, {}>;
 type PhoneClickConfig = z.infer<typeof phoneClickConfigSchema>;
 
+/**
+ * Metadata for the automatic `scroll_depth` event.
+ *
+ * Fired once per configured threshold per page.
+ */
 declare const scrollDepthMetadataSchema: z.ZodObject<{
     depth_percent: z.ZodNumber;
     page: z.ZodObject<{
         path: z.ZodString;
-    }, "strip", z.ZodTypeAny, {
+    }, "strict", z.ZodTypeAny, {
         path: string;
     }, {
         path: string;
@@ -361,6 +512,11 @@ declare const scrollDepthMetadataSchema: z.ZodObject<{
     depth_percent: number;
 }>;
 type ScrollDepthMetadata = z.infer<typeof scrollDepthMetadataSchema>;
+/**
+ * Registration config for automatic `scroll_depth`.
+ *
+ * `thresholds` are integer percentages from 1 to 100.
+ */
 declare const scrollDepthConfigSchema: z.ZodObject<{
     thresholds: z.ZodArray<z.ZodNumber, "many">;
 }, "strict", z.ZodTypeAny, {
@@ -370,13 +526,22 @@ declare const scrollDepthConfigSchema: z.ZodObject<{
 }>;
 type ScrollDepthConfig = z.infer<typeof scrollDepthConfigSchema>;
 
+/**
+ * Canonical page intent names supported by `specific_page_visit`.
+ */
 declare const SPECIFIC_PAGE_NAMES: readonly ["contact_page", "about_page", "services_page", "booking_page", "location_page", "pricing_page", "faq_page", "testimonials_page"];
 type SpecificPageName = (typeof SPECIFIC_PAGE_NAMES)[number];
+/**
+ * Metadata for the automatic `specific_page_visit` event.
+ *
+ * The SDK emits this when the current pathname matches one of the configured
+ * named page patterns.
+ */
 declare const specificPageVisitMetadataSchema: z.ZodObject<{
     page_name: z.ZodEnum<["contact_page", "about_page", "services_page", "booking_page", "location_page", "pricing_page", "faq_page", "testimonials_page"]>;
     page: z.ZodObject<{
         path: z.ZodString;
-    }, "strip", z.ZodTypeAny, {
+    }, "strict", z.ZodTypeAny, {
         path: string;
     }, {
         path: string;
@@ -393,11 +558,17 @@ declare const specificPageVisitMetadataSchema: z.ZodObject<{
     page_name: "contact_page" | "about_page" | "services_page" | "booking_page" | "location_page" | "pricing_page" | "faq_page" | "testimonials_page";
 }>;
 type SpecificPageVisitMetadata = z.infer<typeof specificPageVisitMetadataSchema>;
+/**
+ * Registration config for automatic `specific_page_visit`.
+ *
+ * Each page entry pairs a semantic `name` with a `RegExp` that matches the
+ * pathname. Use this instead of hard-coding path regexes downstream.
+ */
 declare const specificPageVisitConfigSchema: z.ZodObject<{
     pages: z.ZodArray<z.ZodObject<{
         name: z.ZodEnum<["contact_page", "about_page", "services_page", "booking_page", "location_page", "pricing_page", "faq_page", "testimonials_page"]>;
         pathPattern: z.ZodType<RegExp, z.ZodTypeDef, RegExp>;
-    }, "strip", z.ZodTypeAny, {
+    }, "strict", z.ZodTypeAny, {
         name: "contact_page" | "about_page" | "services_page" | "booking_page" | "location_page" | "pricing_page" | "faq_page" | "testimonials_page";
         pathPattern: RegExp;
     }, {
@@ -417,11 +588,17 @@ declare const specificPageVisitConfigSchema: z.ZodObject<{
 }>;
 type SpecificPageVisitConfig = z.infer<typeof specificPageVisitConfigSchema>;
 
+/**
+ * Metadata for the automatic `time_on_site` event.
+ *
+ * The SDK starts a visibility-aware timer and fires once when visible
+ * engagement crosses the configured threshold.
+ */
 declare const timeOnSiteMetadataSchema: z.ZodObject<{
     duration_ms: z.ZodNumber;
     page: z.ZodObject<{
         path: z.ZodString;
-    }, "strip", z.ZodTypeAny, {
+    }, "strict", z.ZodTypeAny, {
         path: string;
     }, {
         path: string;
@@ -438,6 +615,9 @@ declare const timeOnSiteMetadataSchema: z.ZodObject<{
     duration_ms: number;
 }>;
 type TimeOnSiteMetadata = z.infer<typeof timeOnSiteMetadataSchema>;
+/**
+ * Registration config for automatic `time_on_site`.
+ */
 declare const timeOnSiteConfigSchema: z.ZodObject<{
     thresholdSeconds: z.ZodNumber;
 }, "strict", z.ZodTypeAny, {
@@ -456,7 +636,7 @@ declare const EVENT_REGISTRY: {
                 path: z.ZodString;
                 search: z.ZodString;
                 hash: z.ZodString;
-            }, "strip", z.ZodTypeAny, {
+            }, "strict", z.ZodTypeAny, {
                 search: string;
                 title: string | null;
                 path: string;
@@ -471,7 +651,7 @@ declare const EVENT_REGISTRY: {
             viewport: z.ZodOptional<z.ZodNullable<z.ZodObject<{
                 w: z.ZodNumber;
                 h: z.ZodNumber;
-            }, "strip", z.ZodTypeAny, {
+            }, "strict", z.ZodTypeAny, {
                 w: number;
                 h: number;
             }, {
@@ -511,7 +691,7 @@ declare const EVENT_REGISTRY: {
             duration_ms: z.ZodNumber;
             page: z.ZodObject<{
                 path: z.ZodString;
-            }, "strip", z.ZodTypeAny, {
+            }, "strict", z.ZodTypeAny, {
                 path: string;
             }, {
                 path: string;
@@ -541,7 +721,7 @@ declare const EVENT_REGISTRY: {
             page_name: z.ZodEnum<["contact_page", "about_page", "services_page", "booking_page", "location_page", "pricing_page", "faq_page", "testimonials_page"]>;
             page: z.ZodObject<{
                 path: z.ZodString;
-            }, "strip", z.ZodTypeAny, {
+            }, "strict", z.ZodTypeAny, {
                 path: string;
             }, {
                 path: string;
@@ -561,7 +741,7 @@ declare const EVENT_REGISTRY: {
             pages: z.ZodArray<z.ZodObject<{
                 name: z.ZodEnum<["contact_page", "about_page", "services_page", "booking_page", "location_page", "pricing_page", "faq_page", "testimonials_page"]>;
                 pathPattern: z.ZodType<RegExp, z.ZodTypeDef, RegExp>;
-            }, "strip", z.ZodTypeAny, {
+            }, "strict", z.ZodTypeAny, {
                 name: "contact_page" | "about_page" | "services_page" | "booking_page" | "location_page" | "pricing_page" | "faq_page" | "testimonials_page";
                 pathPattern: RegExp;
             }, {
@@ -586,7 +766,7 @@ declare const EVENT_REGISTRY: {
             depth_percent: z.ZodNumber;
             page: z.ZodObject<{
                 path: z.ZodString;
-            }, "strip", z.ZodTypeAny, {
+            }, "strict", z.ZodTypeAny, {
                 path: string;
             }, {
                 path: string;
@@ -616,7 +796,7 @@ declare const EVENT_REGISTRY: {
             page_count: z.ZodNumber;
             page: z.ZodObject<{
                 path: z.ZodString;
-            }, "strip", z.ZodTypeAny, {
+            }, "strict", z.ZodTypeAny, {
                 path: string;
             }, {
                 path: string;
@@ -646,7 +826,7 @@ declare const EVENT_REGISTRY: {
             form: z.ZodObject<{
                 id: z.ZodString;
                 action: z.ZodNullable<z.ZodString>;
-            }, "strip", z.ZodTypeAny, {
+            }, "strict", z.ZodTypeAny, {
                 id: string;
                 action: string | null;
             }, {
@@ -655,7 +835,7 @@ declare const EVENT_REGISTRY: {
             }>;
             page: z.ZodObject<{
                 path: z.ZodString;
-            }, "strip", z.ZodTypeAny, {
+            }, "strict", z.ZodTypeAny, {
                 path: string;
             }, {
                 path: string;
@@ -733,40 +913,40 @@ declare const EVENT_REGISTRY: {
                     name: z.ZodString;
                     type: z.ZodString;
                     label: z.ZodNullable<z.ZodString>;
-                    has_value: z.ZodBoolean;
-                }, "strip", z.ZodTypeAny, {
+                    value: z.ZodType<src.JsonValue, z.ZodTypeDef, src.JsonValue>;
+                }, "strict", z.ZodTypeAny, {
                     label: string | null;
+                    value: src.JsonValue;
                     type: string;
                     name: string;
-                    has_value: boolean;
                 }, {
                     label: string | null;
+                    value: src.JsonValue;
                     type: string;
                     name: string;
-                    has_value: boolean;
                 }>, "many">>;
-            }, "strip", z.ZodTypeAny, {
+            }, "strict", z.ZodTypeAny, {
                 id: string;
                 action: string | null;
                 fields?: {
                     label: string | null;
+                    value: src.JsonValue;
                     type: string;
                     name: string;
-                    has_value: boolean;
                 }[] | undefined;
             }, {
                 id: string;
                 action: string | null;
                 fields?: {
                     label: string | null;
+                    value: src.JsonValue;
                     type: string;
                     name: string;
-                    has_value: boolean;
                 }[] | undefined;
             }>;
             page: z.ZodObject<{
                 path: z.ZodString;
-            }, "strip", z.ZodTypeAny, {
+            }, "strict", z.ZodTypeAny, {
                 path: string;
             }, {
                 path: string;
@@ -777,9 +957,9 @@ declare const EVENT_REGISTRY: {
                 action: string | null;
                 fields?: {
                     label: string | null;
+                    value: src.JsonValue;
                     type: string;
                     name: string;
-                    has_value: boolean;
                 }[] | undefined;
             };
             page: {
@@ -791,9 +971,9 @@ declare const EVENT_REGISTRY: {
                 action: string | null;
                 fields?: {
                     label: string | null;
+                    value: src.JsonValue;
                     type: string;
                     name: string;
-                    has_value: boolean;
                 }[] | undefined;
             };
             page: {
@@ -808,7 +988,7 @@ declare const EVENT_REGISTRY: {
             phone_number: z.ZodString;
             page: z.ZodObject<{
                 path: z.ZodString;
-            }, "strip", z.ZodTypeAny, {
+            }, "strict", z.ZodTypeAny, {
                 path: string;
             }, {
                 path: string;
@@ -835,7 +1015,7 @@ declare const EVENT_REGISTRY: {
             cta_name: z.ZodString;
             page: z.ZodObject<{
                 path: z.ZodString;
-            }, "strip", z.ZodTypeAny, {
+            }, "strict", z.ZodTypeAny, {
                 path: string;
             }, {
                 path: string;
@@ -860,10 +1040,21 @@ declare const EVENT_REGISTRY: {
         readonly configSchema: z.ZodObject<{}, "strict", z.ZodTypeAny, {}, {}>;
     };
 };
+/**
+ * Name of any event known to the tracking SDK.
+ */
 type EventName = keyof typeof EVENT_REGISTRY;
+/**
+ * Event names that are fired by the SDK when their configured signal occurs.
+ *
+ * Automatic events are not accepted by the typed `trackEvent()` API.
+ */
 type AutomaticEventName = {
     [K in EventName]: (typeof EVENT_REGISTRY)[K]['kind'] extends 'automatic' ? K : never;
 }[EventName];
+/**
+ * Event names that consumer code can fire manually after registering them.
+ */
 type ManualEventName = {
     [K in EventName]: (typeof EVENT_REGISTRY)[K]['kind'] extends 'manual' ? K : never;
 }[EventName];
@@ -891,8 +1082,44 @@ type ConfigByName = {
     phone_click: PhoneClickConfig;
     cta_click: CtaClickConfig;
 };
+/**
+ * Metadata payload type for a specific tracking event.
+ *
+ * @example
+ * ```ts
+ * type SubmitMetadata = EventMetadata<'form_submit'>;
+ * ```
+ */
 type EventMetadata<K extends EventName> = MetadataByName[K];
+/**
+ * Trigger registration config type for a specific tracking event.
+ */
 type EventConfig<K extends EventName> = ConfigByName[K];
+/**
+ * Trigger registry passed to `createTracking({ triggers })`.
+ *
+ * `automatic.page_view` is required because every install should capture page
+ * views. Other automatic events are opt-in. Manual events must be registered
+ * here before the typed client accepts `trackEvent()` calls for them.
+ *
+ * @example
+ * ```ts
+ * createTracking({
+ *   apiKey,
+ *   endpoint,
+ *   triggers: {
+ *     automatic: {
+ *       page_view: {},
+ *       time_on_site: { thresholdSeconds: 60 },
+ *     },
+ *     manual: {
+ *       form_submit: {},
+ *       phone_click: {},
+ *     },
+ *   },
+ * });
+ * ```
+ */
 type TriggerRegistryConfig = {
     automatic: {
         page_view: EventConfig<'page_view'>;
@@ -909,29 +1136,70 @@ type TriggerRegistryConfig = {
         cta_click: EventConfig<'cta_click'>;
     }>;
 };
+/**
+ * Manual event names registered in a concrete trigger registry.
+ *
+ * Used by `TypedTrackingClient` so `trackEvent()` only accepts events the
+ * consumer explicitly enabled.
+ */
 type RegisteredManualEvents<TRegistry extends TriggerRegistryConfig> = Extract<keyof NonNullable<TRegistry['manual']>, ManualEventName>;
+/**
+ * Automatic event names registered in a concrete trigger registry.
+ */
 type RegisteredAutomaticEvents<TRegistry extends TriggerRegistryConfig> = Extract<keyof TRegistry['automatic'], AutomaticEventName>;
 
+/**
+ * Input accepted by the low-level stringly-typed client.
+ *
+ * Prefer the typed `trackEvent(eventName, metadata)` facade exposed by
+ * `useTracking()` in React/Next integrations.
+ */
 interface TrackEventInput {
+    /** Event name to enqueue. */
     eventType: string;
+    /** URL associated with the event. Defaults to the current page URL. */
     pageUrl?: string | null;
+    /** Event-specific metadata. */
     metadata?: Record<string, unknown> | null;
+    /** Timestamp override. Defaults to queue time. */
     occurredAt?: Date | string | null;
 }
+/**
+ * Low-level tracking client responsible for queueing and flushing events.
+ */
 interface TrackingClient {
+    /** Enqueue an event for batched delivery. */
     trackEvent: (input: TrackEventInput) => void;
+    /** Flush queued events immediately. */
     flush: () => Promise<void>;
+    /** Return the current rolling session id. */
     getSessionId: () => string;
+    /** Return the persistent visitor id. */
     getVisitorId: () => string;
+    /** Remove timers/listeners and prevent future flushes. */
     destroy: () => void;
 }
 
 interface TypedTrackEventOptions {
-    /** Override the page URL captured automatically. Rarely needed. */
+    /**
+     * Override the page URL associated with this event.
+     *
+     * Omit this for normal browser usage; the SDK captures `window.location.href`.
+     */
     pageUrl?: string | null;
-    /** Event timestamp override. Defaults to "now" at queue time. */
+    /**
+     * Override the event timestamp.
+     *
+     * Defaults to the time the event is queued. Accepts a `Date` or ISO string.
+     */
     occurredAt?: Date | string | null;
 }
+/**
+ * Typed tracking client returned by `useTracking()`.
+ *
+ * The accepted event names and metadata shapes are narrowed from the concrete
+ * trigger registry supplied to `createTracking()`.
+ */
 interface TypedTrackingClient<TRegistry extends TriggerRegistryConfig> {
     /**
      * Fire a manually-registered event. The event name must be present in
@@ -939,37 +1207,104 @@ interface TypedTrackingClient<TRegistry extends TriggerRegistryConfig> {
      * canonical Zod-derived shape.
      */
     trackEvent<K extends RegisteredManualEvents<TRegistry>>(eventType: K, metadata: EventMetadata<K>, options?: TypedTrackEventOptions): void;
+    /**
+     * Immediately flush queued events to the ingest endpoint.
+     *
+     * Normal consumers rarely need this because the SDK flushes on a debounce,
+     * when the queue reaches the batch threshold, and on `pagehide`.
+     */
     flush(): Promise<void>;
+    /**
+     * Return the current rolling session id.
+     */
     getSessionId(): string;
+    /**
+     * Return the persistent visitor id for this browser profile.
+     */
     getVisitorId(): string;
 }
 
+/**
+ * Default non-blocking consent banner for Next.js installs.
+ *
+ * Renders only while consent is `pending`. Accept/decline choices are stored
+ * in localStorage and propagated to Google Consent Mode when gtag is loaded.
+ */
 declare function ConsentBanner(): react_jsx_runtime.JSX.Element | null;
 
+/**
+ * Read the captured Google Ads click id from first-party cookies.
+ *
+ * Returns `null` during SSR and before the client has mounted.
+ */
 declare function useGclid(): string | null;
+/**
+ * Read all captured attribution parameters from first-party cookies.
+ *
+ * Values are loaded after mount, so the initial render returns all `null`s.
+ */
 declare function useTrackingParams(): TrackingParams;
+/**
+ * Read the current visitor consent state and update when another tab changes
+ * the stored value.
+ */
 declare function useConsentState(): ConsentState;
 
 interface GoogleAdsTrackingProps {
+    /**
+     * Google Ads tag id, for example `AW-123456789`.
+     */
     gtagId: string;
 }
+/**
+ * Next.js client component that loads Google Ads gtag with Consent Mode.
+ *
+ * Render in the root layout `<head>` when the client site runs paid Google
+ * Ads. The component injects Next `<Script>` tags and renders no visible UI.
+ */
 declare function GoogleAdsTracking({ gtagId }: GoogleAdsTrackingProps): react_jsx_runtime.JSX.Element;
 
 interface CreateTrackingOptions<TRegistry extends TriggerRegistryConfig> {
+    /**
+     * Public tracking API key issued for this business.
+     *
+     * This key is safe to expose via `NEXT_PUBLIC_*` env vars.
+     */
     apiKey: string;
+    /**
+     * Tracking endpoint base URL, usually ending in `/tracking`.
+     */
     endpoint: string;
+    /**
+     * Trigger registry that controls automatic events and typed manual events.
+     */
     triggers: TRegistry;
+    /**
+     * Validate manual event metadata at runtime before queueing.
+     *
+     * Enable in development to catch shape bugs. Leave disabled in production so
+     * analytics can never throw into the host app.
+     */
     debug?: boolean;
 }
 interface TrackingProviderProps {
+    /**
+     * Application subtree that should have access to the tracking client.
+     */
     children: ReactNode;
 }
 interface CreateTrackingResult<TRegistry extends TriggerRegistryConfig> {
+    /**
+     * Client component provider for the Next.js App Router integration.
+     */
     TrackingProvider: (props: TrackingProviderProps) => ReactNode;
+    /**
+     * Hook that returns the registry-typed tracking client.
+     */
     useTracking: () => TypedTrackingClient<TRegistry>;
 }
 /**
- * Next.js App Router version of the createTracking factory. Uses
+ * Next.js App Router version of the `createTracking()` factory. Uses
  * `usePathname` + `useSearchParams` from `next/navigation` for SPA route
  * detection rather than patching `history.pushState`, because Next's
  * router does not always go through the History API for transitions.
@@ -982,4 +1317,4 @@ interface CreateTrackingResult<TRegistry extends TriggerRegistryConfig> {
  */
 declare function createTracking<TRegistry extends TriggerRegistryConfig>(options: CreateTrackingOptions<TRegistry>): CreateTrackingResult<TRegistry>;
 
-export { type AutomaticEventName, ConsentBanner, ConsentState, type CreateTrackingOptions, type CreateTrackingResult, type CtaClickConfig, type CtaClickMetadata, type EventConfig, type EventMetadata, type EventName, type FormStartConfig, type FormStartMetadata, type FormSubmitConfig, type FormSubmitMetadata, GoogleAdsTracking, type GoogleAdsTrackingProps, type ManualEventName, type MultiPageSessionConfig, type MultiPageSessionMetadata, type PageViewConfig, type PageViewMetadata, type PhoneClickConfig, type PhoneClickMetadata, type RegisteredAutomaticEvents, type RegisteredManualEvents, type ScrollDepthConfig, type ScrollDepthMetadata, type SpecificPageName, type SpecificPageVisitConfig, type SpecificPageVisitMetadata, TRACKING_PARAM_KEYS, type TimeOnSiteConfig, type TimeOnSiteMetadata, type TrackingClient, TrackingClientContext, TrackingEventCreatePayload, TrackingInstallSurface, TrackingParams, type TrackingProviderProps, TrackingSessionUpsertPayload, type TriggerRegistryConfig, type TypedTrackEventOptions, type TypedTrackingClient, captureTrackingParamsFromLocation, createTracking, createTrackingClientContext, createTrackingEventCreatePayload, createTrackingSessionUpsertPayload, getConsentState, setConsentState, useConsentState, useGclid, useTrackingParams };
+export { type AutomaticEventName, ConsentBanner, ConsentState, type CreateTrackingOptions, type CreateTrackingResult, type CtaClickConfig, type CtaClickMetadata, type EventConfig, type EventMetadata, type EventName, type FormStartConfig, type FormStartMetadata, type FormSubmitConfig, type FormSubmitMetadata, GoogleAdsTracking, type GoogleAdsTrackingProps, type JsonValue, type ManualEventName, type MultiPageSessionConfig, type MultiPageSessionMetadata, type PageViewConfig, type PageViewMetadata, type PhoneClickConfig, type PhoneClickMetadata, type RegisteredAutomaticEvents, type RegisteredManualEvents, type ScrollDepthConfig, type ScrollDepthMetadata, type SpecificPageName, type SpecificPageVisitConfig, type SpecificPageVisitMetadata, TRACKING_PARAM_KEYS, type TimeOnSiteConfig, type TimeOnSiteMetadata, type TrackingClient, TrackingClientContext, TrackingEventCreatePayload, TrackingInstallSurface, TrackingParams, type TrackingProviderProps, TrackingSessionUpsertPayload, type TriggerRegistryConfig, type TypedTrackEventOptions, type TypedTrackingClient, captureTrackingParamsFromLocation, createTracking, createTrackingClientContext, createTrackingEventCreatePayload, createTrackingSessionUpsertPayload, getConsentState, setConsentState, useConsentState, useGclid, useTrackingParams };