@aranova/tracking-next 0.6.0 → 0.6.1

package/dist/index.d.mts

@@ -1,12 +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 {
@@ -28,13 +41,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<{
@@ -62,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>;
@@ -100,9 +149,19 @@ 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;
@@ -139,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, {
@@ -148,9 +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;
@@ -227,9 +329,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<{
@@ -251,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, {
@@ -260,6 +377,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>;
@@ -314,9 +438,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<{
@@ -341,9 +478,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<{
@@ -365,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, {
@@ -374,8 +526,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<{
@@ -397,6 +558,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"]>;
@@ -421,6 +588,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<{
@@ -442,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, {
@@ -864,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];
@@ -895,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'>;
@@ -913,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
@@ -943,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.