@aranova/tracking-react 0.6.0 → 0.7.0

package/dist/index.d.mts

@@ -3,34 +3,99 @@ 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 {
-    gtagId: string;
-}
-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';
+/**
+ * Deployment environment label for event tagging.
+ *
+ * Used to stamp tracking events with the deployment context so the dashboard
+ * can distinguish production traffic from dev test traffic. The backend
+ * enforces this via a Postgres enum, so values are strictly one of
+ * `'production'` or `'development'`.
+ */
+type TrackingEnvironment = 'production' | 'development';
+/**
+ * Labelled map of Google Ads tag IDs.
+ *
+ * ALL entries are loaded simultaneously via `gtag('config', ...)` — the keys
+ * are human-readable labels (e.g. `production`, `test`) and the values are
+ * Google Ads tag IDs (e.g. `AW-123456789`).
+ */
+type GtagEnvironmentMap = Record<string, string>;
+/**
+ * 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;
+    /** Deployment environment label, e.g. `'production'`, `'development'`. */
+    environment: TrackingEnvironment | null;
+    /** All active gtag IDs loaded on this page, keyed by label. */
+    active_gtag_ids: Record<string, 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;
@@ -43,22 +108,46 @@ 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;
+    /**
+     * Labelled map of Google Ads tag IDs. ALL are loaded simultaneously.
+     * When provided, `gtagId` is ignored.
+     */
+    gtagIds?: GtagEnvironmentMap;
+    /** Deployment environment label reported in session context. */
+    environment?: TrackingEnvironment;
+    /** 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 {
@@ -76,8 +165,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 {
@@ -86,6 +188,8 @@ interface TrackingContextInput {
     referrer?: string | null;
     sdkVersion?: string | null;
     siteOrigin?: string | null;
+    environment?: TrackingEnvironment | null;
+    activeGtagIds?: Record<string, string> | null;
 }
 interface TrackingEventInput {
     eventType: string;
@@ -99,13 +203,37 @@ 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<{
@@ -133,9 +261,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>;
@@ -151,6 +291,7 @@ declare const sdkHeartbeatMetadataSchema: z.ZodObject<{
         manual: string[];
     }>;
     trigger_config: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>>>>;
+    configured_gtag_ids: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodString>>>;
 }, "strict", z.ZodTypeAny, {
     sdk_version: string;
     package_name: string | null;
@@ -160,6 +301,7 @@ declare const sdkHeartbeatMetadataSchema: z.ZodObject<{
         manual: string[];
     };
     trigger_config?: Record<string, Record<string, unknown>> | null | undefined;
+    configured_gtag_ids?: Record<string, string> | null | undefined;
 }, {
     sdk_version: string;
     package_name: string | null;
@@ -169,11 +311,22 @@ declare const sdkHeartbeatMetadataSchema: z.ZodObject<{
         manual: string[];
     };
     trigger_config?: Record<string, Record<string, unknown>> | null | undefined;
+    configured_gtag_ids?: Record<string, string> | 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;
@@ -210,6 +363,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, {
@@ -219,9 +378,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;
@@ -298,9 +494,21 @@ 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<{
@@ -322,6 +530,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, {
@@ -331,6 +542,13 @@ 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>;
@@ -385,9 +603,22 @@ 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<{
@@ -412,9 +643,19 @@ 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<{
@@ -436,6 +677,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, {
@@ -445,8 +691,17 @@ 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<{
@@ -468,6 +723,12 @@ 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"]>;
@@ -492,6 +753,12 @@ 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<{
@@ -513,6 +780,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, {
@@ -777,6 +1047,7 @@ declare const EVENT_REGISTRY: {
                 manual: string[];
             }>;
             trigger_config: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>>>>;
+            configured_gtag_ids: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodString>>>;
         }, "strict", z.ZodTypeAny, {
             sdk_version: string;
             package_name: string | null;
@@ -786,6 +1057,7 @@ declare const EVENT_REGISTRY: {
                 manual: string[];
             };
             trigger_config?: Record<string, Record<string, unknown>> | null | undefined;
+            configured_gtag_ids?: Record<string, string> | null | undefined;
         }, {
             sdk_version: string;
             package_name: string | null;
@@ -795,6 +1067,7 @@ declare const EVENT_REGISTRY: {
                 manual: string[];
             };
             trigger_config?: Record<string, Record<string, unknown>> | null | undefined;
+            configured_gtag_ids?: Record<string, string> | null | undefined;
         }>;
         readonly configSchema: z.ZodObject<{}, "strict", z.ZodTypeAny, {}, {}>;
     };
@@ -935,10 +1208,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];
@@ -966,8 +1250,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'>;
@@ -984,29 +1304,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
@@ -1014,19 +1375,75 @@ 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;
 }
 
+/**
+ * Props for the Google Ads tracking component.
+ *
+ * Accepts either a single `gtagId` (legacy) or a labelled `gtagIds` map
+ * where ALL entries are loaded simultaneously via `gtag('config', ...)`.
+ */
+type GoogleAdsTrackingProps = {
+    gtagId: string;
+    gtagIds?: undefined;
+} | {
+    gtagId?: undefined;
+    gtagIds: GtagEnvironmentMap;
+};
+/**
+ * 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(props: GoogleAdsTrackingProps): 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 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
@@ -1034,6 +1451,14 @@ interface CreateTrackingOptions<TRegistry extends TriggerRegistryConfig> {
      * `automatic.page_view` is required — every tracking install needs it.
      */
     triggers: TRegistry;
+    /**
+     * Deployment environment label reported in session context.
+     *
+     * Does not affect which gtag IDs are loaded — all configured IDs are
+     * loaded simultaneously. This value is purely for event tagging so the
+     * dashboard can filter by environment.
+     */
+    environment?: TrackingEnvironment;
     /**
      * When true, the typed client validates every `trackEvent()` metadata
      * payload through the Zod schema before forwarding. Errors are thrown
@@ -1042,12 +1467,35 @@ 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 and `gtagIds` is also omitted, no gtag script is loaded.
+     */
     gtagId?: string;
+    /**
+     * Labelled map of Google Ads tag IDs. ALL are loaded simultaneously.
+     * When provided, `gtagId` is ignored.
+     */
+    gtagIds?: GtagEnvironmentMap;
+    /**
+     * 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>;