@aranova/tracking-react 0.5.1 → 0.6.1

package/dist/index.d.ts

@@ -1,35 +1,94 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ReactNode } from 'react';
+import * as src from 'src';
 import { z } from 'zod';
 
+/**
+ * Default non-blocking consent banner.
+ *
+ * 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;
 
 interface GoogleAdsTrackingProps {
+    /**
+     * Google Ads tag id, for example `AW-123456789`.
+     */
     gtagId: string;
 }
+/**
+ * Client component that loads Google Ads gtag and restores stored consent.
+ *
+ * Render once near the application root when the client site runs paid Google
+ * Ads. The component renders nothing.
+ */
 declare function GoogleAdsTracking({ gtagId }: GoogleAdsTrackingProps): null;
 
+/**
+ * Visitor consent state stored by the SDK.
+ *
+ * - `pending`: the visitor has not accepted or declined yet.
+ * - `granted`: consent was accepted and Google Consent Mode is updated to granted.
+ * - `denied`: consent was declined and Google Consent Mode is updated to denied.
+ */
 type ConsentState = 'granted' | 'denied' | 'pending';
+/**
+ * Attribution parameters captured from the landing URL and persisted in cookies.
+ *
+ * Missing params are represented as `null` so payloads can be serialized
+ * directly without checking for `undefined`.
+ */
 interface TrackingParams {
+    /** Google Ads click id. */
     gclid: string | null;
+    /** Meta/Facebook click id. */
     fbclid: string | null;
+    /** UTM source, for example `google` or `newsletter`. */
     utm_source: string | null;
+    /** UTM medium, for example `cpc` or `email`. */
     utm_medium: string | null;
+    /** UTM campaign name. */
     utm_campaign: string | null;
+    /** UTM paid-search term. */
     utm_term: string | null;
+    /** UTM content/ad creative label. */
     utm_content: string | null;
 }
+/**
+ * Runtime surface that installed the tracking SDK.
+ *
+ * Included in ingest payloads and heartbeat events so the dashboard can tell
+ * whether a site uses the Next, React, or script-tag integration.
+ */
 type TrackingInstallSurface = 'next' | 'react' | 'script';
+/**
+ * Runtime context attached to tracking sessions and events.
+ */
 interface TrackingClientContext {
+    /** Install surface that created the client. */
     surface: TrackingInstallSurface;
+    /** Package version, when available. */
     sdk_version: string | null;
+    /** Package name, for example `@aranova/tracking-react`. */
     package_name: string | null;
+    /** Browser origin of the tracked site. */
     site_origin: string | null;
+    /** Current document title at client creation time. */
     page_title: string | null;
+    /** Browser document referrer at client creation time. */
     referrer: string | null;
 }
+/**
+ * Session payload sent to `POST /tracking/events`.
+ *
+ * The backend upserts this by `(business_id, session_id)` before inserting
+ * individual events.
+ */
 interface TrackingSessionUpsertPayload {
+    /** Rolling 30-minute client-side session id. */
     session_id: string;
+    /** Persistent client-side visitor id. */
     visitor_id: string | null;
     gclid: string | null;
     fbclid: string | null;
@@ -42,22 +101,39 @@ interface TrackingSessionUpsertPayload {
     consent_state: Record<string, unknown> | null;
     context: TrackingClientContext;
 }
+/**
+ * Event payload shape before batching into the ingest request.
+ */
 interface TrackingEventCreatePayload {
+    /** Session id that logically owns the event. */
     session_id: string;
+    /** Registered event name, for example `page_view` or `form_submit`. */
     event_type: string;
     gclid: string | null;
     fbclid: string | null;
+    /** Full page URL associated with the event, if known. */
     page_url: string | null;
+    /** Event-specific metadata. Runtime shape depends on `event_type`. */
     metadata: Record<string, unknown> | null;
     context: TrackingClientContext;
 }
+/**
+ * Browser-script initialization config passed to `window.AranovaTracking.init()`.
+ */
 interface TrackingInitConfig {
+    /** Public tracking API key issued from the Aranova dashboard. */
     apiKey?: string;
+    /** Tracking endpoint base URL, usually ending in `/tracking`. */
     endpoint?: string;
+    /** Optional Google Ads tag id, for example `AW-123456789`. */
     gtagId?: string;
+    /** Whether to capture attribution params from `window.location`. Defaults to true. */
     autoCaptureTrackingParams?: boolean;
+    /** Whether the browser script should inject the default consent banner. */
     renderConsentBanner?: boolean;
+    /** Attribution cookie max age in seconds. Defaults to 90 days. */
     cookieMaxAgeSeconds?: number;
+    /** Override the install surface reported in payload context. */
     surface?: TrackingInstallSurface;
 }
 declare global {
@@ -75,8 +151,21 @@ declare global {
     }
 }
 
+/**
+ * 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 {
@@ -98,18 +187,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;
@@ -132,9 +245,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>;
@@ -170,14 +295,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;
     }, {
@@ -186,7 +321,7 @@ declare const formStartMetadataSchema: z.ZodObject<{
     }>;
     page: z.ZodObject<{
         path: z.ZodString;
-    }, "strip", z.ZodTypeAny, {
+    }, "strict", z.ZodTypeAny, {
         path: string;
     }, {
         path: string;
@@ -209,6 +344,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, {
@@ -218,6 +359,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;
@@ -226,40 +407,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;
@@ -270,9 +451,9 @@ declare const formSubmitMetadataSchema: z.ZodObject<{
         action: string | null;
         fields?: {
             label: string | null;
+            value: JsonValue;
             type: string;
             name: string;
-            has_value: boolean;
         }[] | undefined;
     };
     page: {
@@ -284,9 +465,9 @@ declare const formSubmitMetadataSchema: z.ZodObject<{
         action: string | null;
         fields?: {
             label: string | null;
+            value: JsonValue;
             type: string;
             name: string;
-            has_value: boolean;
         }[] | undefined;
     };
     page: {
@@ -294,14 +475,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;
@@ -318,6 +511,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, {
@@ -327,13 +523,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;
@@ -348,7 +551,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;
     }, {
@@ -381,14 +584,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;
@@ -408,14 +624,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;
@@ -432,6 +658,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, {
@@ -441,13 +672,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;
@@ -464,11 +704,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;
     }, {
@@ -488,11 +734,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;
@@ -509,6 +761,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, {
@@ -527,7 +782,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;
@@ -542,7 +797,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;
             }, {
@@ -582,7 +837,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;
@@ -612,7 +867,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;
@@ -632,7 +887,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;
             }, {
@@ -657,7 +912,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;
@@ -687,7 +942,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;
@@ -717,7 +972,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;
             }, {
@@ -726,7 +981,7 @@ declare const EVENT_REGISTRY: {
             }>;
             page: z.ZodObject<{
                 path: z.ZodString;
-            }, "strip", z.ZodTypeAny, {
+            }, "strict", z.ZodTypeAny, {
                 path: string;
             }, {
                 path: string;
@@ -804,40 +1059,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;
@@ -848,9 +1103,9 @@ declare const EVENT_REGISTRY: {
                 action: string | null;
                 fields?: {
                     label: string | null;
+                    value: src.JsonValue;
                     type: string;
                     name: string;
-                    has_value: boolean;
                 }[] | undefined;
             };
             page: {
@@ -862,9 +1117,9 @@ declare const EVENT_REGISTRY: {
                 action: string | null;
                 fields?: {
                     label: string | null;
+                    value: src.JsonValue;
                     type: string;
                     name: string;
-                    has_value: boolean;
                 }[] | undefined;
             };
             page: {
@@ -879,7 +1134,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;
@@ -906,7 +1161,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;
@@ -931,10 +1186,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];
@@ -962,8 +1228,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'>;
@@ -980,29 +1282,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
@@ -1010,19 +1353,54 @@ 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;
 }
 
+/**
+ * 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 CreateTrackingOptions<TRegistry extends TriggerRegistryConfig> {
-    /** Public tracking API key issued for this business. Required. */
+    /**
+     * Public tracking API key issued for this business.
+     *
+     * This key is safe to expose in browser code. Abuse is bounded by the
+     * server-side origin allowlist and rate limits.
+     */
     apiKey: string;
-    /** Full ingest endpoint base URL, e.g. https://api.aranova.io/tracking. Required. */
+    /**
+     * Tracking endpoint base URL, usually ending in `/tracking`.
+     *
+     * The client posts events to `${endpoint}/events`.
+     */
     endpoint: string;
     /**
      * Trigger registry. Determines which events the SDK fires automatically
@@ -1038,14 +1416,32 @@ interface CreateTrackingOptions<TRegistry extends TriggerRegistryConfig> {
     debug?: boolean;
 }
 interface TrackingProviderProps {
-    /** Optional Google Ads gtag id. If omitted, no gtag script is loaded. */
+    /**
+     * Optional Google Ads tag id, for example `AW-123456789`.
+     *
+     * If omitted, no gtag script is loaded by the provider.
+     */
     gtagId?: string;
+    /**
+     * Application tree that should have access to the scoped tracking client.
+     */
     children: ReactNode;
 }
 interface CreateTrackingResult<TRegistry extends TriggerRegistryConfig> {
+    /**
+     * Provider component that initializes the page-level tracking client.
+     *
+     * Mount this once near the root of the React tree.
+     */
     TrackingProvider: (props: TrackingProviderProps) => ReactNode;
+    /**
+     * Hook that returns the registry-typed tracking client.
+     *
+     * Import this hook from your local tracking module, not directly from the
+     * package root, so TypeScript preserves your trigger registry.
+     */
     useTracking: () => TypedTrackingClient<TRegistry>;
 }
 declare function createTracking<TRegistry extends TriggerRegistryConfig>(options: CreateTrackingOptions<TRegistry>): CreateTrackingResult<TRegistry>;
 
-export { type AutomaticEventName, ConsentBanner, type 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, type TrackingClientContext, type TrackingEventCreatePayload, type TrackingInitConfig, type TrackingInstallSurface, type TrackingParams, type TrackingProviderProps, type TrackingSessionUpsertPayload, type TriggerRegistryConfig, type TypedTrackEventOptions, type TypedTrackingClient, captureTrackingParamsFromLocation, createTracking, createTrackingClientContext, createTrackingEventCreatePayload, createTrackingSessionUpsertPayload, getConsentState, setConsentState, useConsentState, useGclid, useTrackingParams };
+export { type AutomaticEventName, ConsentBanner, type 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, type TrackingClientContext, type TrackingEventCreatePayload, type TrackingInitConfig, type TrackingInstallSurface, type TrackingParams, type TrackingProviderProps, type TrackingSessionUpsertPayload, type TriggerRegistryConfig, type TypedTrackEventOptions, type TypedTrackingClient, captureTrackingParamsFromLocation, createTracking, createTrackingClientContext, createTrackingEventCreatePayload, createTrackingSessionUpsertPayload, getConsentState, setConsentState, useConsentState, useGclid, useTrackingParams };