@aranova/tracking-react 0.2.3 → 0.4.0

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+import { z } from 'zod';
 
 declare function ConsentBanner(): react_jsx_runtime.JSX.Element | null;
 
@@ -28,6 +30,7 @@ interface TrackingClientContext {
 }
 interface TrackingSessionUpsertPayload {
     session_id: string;
+    visitor_id: string | null;
     gclid: string | null;
     fbclid: string | null;
     utm_source: string | null;
@@ -67,6 +70,7 @@ declare global {
             getTrackingParams: () => TrackingParams;
             getConsentState: () => ConsentState;
             setConsentState: (state: 'granted' | 'denied') => void;
+            trackEvent: (eventType: string, metadata: Record<string, unknown>) => void;
         };
     }
 }
@@ -92,6 +96,7 @@ interface TrackingSessionInput {
     consentState?: Record<string, unknown> | null;
     firstPage?: string | null;
     sessionId: string;
+    visitorId?: string | null;
 }
 declare function createTrackingClientContext(surface: TrackingInstallSurface, input?: TrackingContextInput): TrackingClientContext;
 declare function createTrackingSessionUpsertPayload(trackingParams: TrackingParams, input: TrackingSessionInput, context: TrackingClientContext): TrackingSessionUpsertPayload;
@@ -100,8 +105,532 @@ declare function createTrackingEventCreatePayload(trackingParams: TrackingParams
 declare const TRACKING_PARAM_KEYS: readonly ["gclid", "fbclid", "utm_source", "utm_medium", "utm_campaign", "utm_term", "utm_content"];
 declare function captureTrackingParamsFromLocation(url?: string, maxAgeSeconds?: number): TrackingParams;
 
+interface TrackEventInput {
+    eventType: string;
+    pageUrl?: string | null;
+    metadata?: Record<string, unknown> | null;
+    occurredAt?: Date | string | null;
+}
+interface TrackingClient {
+    trackEvent: (input: TrackEventInput) => void;
+    flush: () => Promise<void>;
+    getSessionId: () => string;
+    getVisitorId: () => string;
+    destroy: () => void;
+}
+
+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, {
+        search: string;
+        title: string | null;
+        path: string;
+        hash: string;
+    }, {
+        search: string;
+        title: string | null;
+        path: string;
+        hash: string;
+    }>;
+    referrer: z.ZodNullable<z.ZodString>;
+    viewport: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        w: z.ZodNumber;
+        h: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        w: number;
+        h: number;
+    }, {
+        w: number;
+        h: number;
+    }>>>;
+}, "strict", z.ZodTypeAny, {
+    page: {
+        search: string;
+        title: string | null;
+        path: string;
+        hash: string;
+    };
+    referrer: string | null;
+    viewport?: {
+        w: number;
+        h: number;
+    } | null | undefined;
+}, {
+    page: {
+        search: string;
+        title: string | null;
+        path: string;
+        hash: string;
+    };
+    referrer: string | null;
+    viewport?: {
+        w: number;
+        h: number;
+    } | null | undefined;
+}>;
+type PageViewMetadata = z.infer<typeof pageViewMetadataSchema>;
+declare const pageViewConfigSchema: z.ZodObject<{}, "strict", z.ZodTypeAny, {}, {}>;
+type PageViewConfig = z.infer<typeof pageViewConfigSchema>;
+
+declare const contactPageVisitMetadataSchema: z.ZodObject<{
+    page: z.ZodObject<{
+        path: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        path: string;
+    }, {
+        path: string;
+    }>;
+}, "strict", z.ZodTypeAny, {
+    page: {
+        path: string;
+    };
+}, {
+    page: {
+        path: string;
+    };
+}>;
+type ContactPageVisitMetadata = z.infer<typeof contactPageVisitMetadataSchema>;
+declare const contactPageVisitConfigSchema: z.ZodObject<{
+    pathPattern: z.ZodType<RegExp, z.ZodTypeDef, RegExp>;
+}, "strict", z.ZodTypeAny, {
+    pathPattern: RegExp;
+}, {
+    pathPattern: RegExp;
+}>;
+type ContactPageVisitConfig = z.infer<typeof contactPageVisitConfigSchema>;
+
+declare const formSubmitMetadataSchema: z.ZodObject<{
+    form: z.ZodObject<{
+        id: z.ZodString;
+        action: z.ZodNullable<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        action: string | null;
+    }, {
+        id: string;
+        action: string | null;
+    }>;
+    page: z.ZodObject<{
+        path: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        path: string;
+    }, {
+        path: string;
+    }>;
+}, "strict", z.ZodTypeAny, {
+    form: {
+        id: string;
+        action: string | null;
+    };
+    page: {
+        path: string;
+    };
+}, {
+    form: {
+        id: string;
+        action: string | null;
+    };
+    page: {
+        path: string;
+    };
+}>;
+type FormSubmitMetadata = z.infer<typeof formSubmitMetadataSchema>;
+declare const formSubmitConfigSchema: z.ZodObject<{}, "strict", z.ZodTypeAny, {}, {}>;
+type FormSubmitConfig = z.infer<typeof formSubmitConfigSchema>;
+
+declare const phoneClickMetadataSchema: z.ZodObject<{
+    element: z.ZodObject<{
+        tag: z.ZodString;
+        text: z.ZodNullable<z.ZodString>;
+        href: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        text: string | null;
+        tag: string;
+        href: string;
+    }, {
+        text: string | null;
+        tag: string;
+        href: string;
+    }>;
+    page: z.ZodObject<{
+        path: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        path: string;
+    }, {
+        path: string;
+    }>;
+}, "strict", z.ZodTypeAny, {
+    page: {
+        path: string;
+    };
+    element: {
+        text: string | null;
+        tag: string;
+        href: string;
+    };
+}, {
+    page: {
+        path: string;
+    };
+    element: {
+        text: string | null;
+        tag: string;
+        href: string;
+    };
+}>;
+type PhoneClickMetadata = z.infer<typeof phoneClickMetadataSchema>;
+declare const phoneClickConfigSchema: z.ZodObject<{}, "strict", z.ZodTypeAny, {}, {}>;
+type PhoneClickConfig = z.infer<typeof phoneClickConfigSchema>;
+
+declare const timeOnSiteMetadataSchema: z.ZodObject<{
+    duration_ms: z.ZodNumber;
+    page: z.ZodObject<{
+        path: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        path: string;
+    }, {
+        path: string;
+    }>;
+}, "strict", z.ZodTypeAny, {
+    page: {
+        path: string;
+    };
+    duration_ms: number;
+}, {
+    page: {
+        path: string;
+    };
+    duration_ms: number;
+}>;
+type TimeOnSiteMetadata = z.infer<typeof timeOnSiteMetadataSchema>;
+declare const timeOnSiteConfigSchema: z.ZodObject<{
+    thresholdSeconds: z.ZodNumber;
+}, "strict", z.ZodTypeAny, {
+    thresholdSeconds: number;
+}, {
+    thresholdSeconds: number;
+}>;
+type TimeOnSiteConfig = z.infer<typeof timeOnSiteConfigSchema>;
+
+declare const EVENT_REGISTRY: {
+    readonly page_view: {
+        readonly kind: "automatic";
+        readonly metadataSchema: z.ZodObject<{
+            page: z.ZodObject<{
+                title: z.ZodNullable<z.ZodString>;
+                path: z.ZodString;
+                search: z.ZodString;
+                hash: z.ZodString;
+            }, "strip", z.ZodTypeAny, {
+                search: string;
+                title: string | null;
+                path: string;
+                hash: string;
+            }, {
+                search: string;
+                title: string | null;
+                path: string;
+                hash: string;
+            }>;
+            referrer: z.ZodNullable<z.ZodString>;
+            viewport: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+                w: z.ZodNumber;
+                h: z.ZodNumber;
+            }, "strip", z.ZodTypeAny, {
+                w: number;
+                h: number;
+            }, {
+                w: number;
+                h: number;
+            }>>>;
+        }, "strict", z.ZodTypeAny, {
+            page: {
+                search: string;
+                title: string | null;
+                path: string;
+                hash: string;
+            };
+            referrer: string | null;
+            viewport?: {
+                w: number;
+                h: number;
+            } | null | undefined;
+        }, {
+            page: {
+                search: string;
+                title: string | null;
+                path: string;
+                hash: string;
+            };
+            referrer: string | null;
+            viewport?: {
+                w: number;
+                h: number;
+            } | null | undefined;
+        }>;
+        readonly configSchema: z.ZodObject<{}, "strict", z.ZodTypeAny, {}, {}>;
+    };
+    readonly time_on_site: {
+        readonly kind: "automatic";
+        readonly metadataSchema: z.ZodObject<{
+            duration_ms: z.ZodNumber;
+            page: z.ZodObject<{
+                path: z.ZodString;
+            }, "strip", z.ZodTypeAny, {
+                path: string;
+            }, {
+                path: string;
+            }>;
+        }, "strict", z.ZodTypeAny, {
+            page: {
+                path: string;
+            };
+            duration_ms: number;
+        }, {
+            page: {
+                path: string;
+            };
+            duration_ms: number;
+        }>;
+        readonly configSchema: z.ZodObject<{
+            thresholdSeconds: z.ZodNumber;
+        }, "strict", z.ZodTypeAny, {
+            thresholdSeconds: number;
+        }, {
+            thresholdSeconds: number;
+        }>;
+    };
+    readonly contact_page_visit: {
+        readonly kind: "automatic";
+        readonly metadataSchema: z.ZodObject<{
+            page: z.ZodObject<{
+                path: z.ZodString;
+            }, "strip", z.ZodTypeAny, {
+                path: string;
+            }, {
+                path: string;
+            }>;
+        }, "strict", z.ZodTypeAny, {
+            page: {
+                path: string;
+            };
+        }, {
+            page: {
+                path: string;
+            };
+        }>;
+        readonly configSchema: z.ZodObject<{
+            pathPattern: z.ZodType<RegExp, z.ZodTypeDef, RegExp>;
+        }, "strict", z.ZodTypeAny, {
+            pathPattern: RegExp;
+        }, {
+            pathPattern: RegExp;
+        }>;
+    };
+    readonly form_submit: {
+        readonly kind: "manual";
+        readonly metadataSchema: z.ZodObject<{
+            form: z.ZodObject<{
+                id: z.ZodString;
+                action: z.ZodNullable<z.ZodString>;
+            }, "strip", z.ZodTypeAny, {
+                id: string;
+                action: string | null;
+            }, {
+                id: string;
+                action: string | null;
+            }>;
+            page: z.ZodObject<{
+                path: z.ZodString;
+            }, "strip", z.ZodTypeAny, {
+                path: string;
+            }, {
+                path: string;
+            }>;
+        }, "strict", z.ZodTypeAny, {
+            form: {
+                id: string;
+                action: string | null;
+            };
+            page: {
+                path: string;
+            };
+        }, {
+            form: {
+                id: string;
+                action: string | null;
+            };
+            page: {
+                path: string;
+            };
+        }>;
+        readonly configSchema: z.ZodObject<{}, "strict", z.ZodTypeAny, {}, {}>;
+    };
+    readonly phone_click: {
+        readonly kind: "manual";
+        readonly metadataSchema: z.ZodObject<{
+            element: z.ZodObject<{
+                tag: z.ZodString;
+                text: z.ZodNullable<z.ZodString>;
+                href: z.ZodString;
+            }, "strip", z.ZodTypeAny, {
+                text: string | null;
+                tag: string;
+                href: string;
+            }, {
+                text: string | null;
+                tag: string;
+                href: string;
+            }>;
+            page: z.ZodObject<{
+                path: z.ZodString;
+            }, "strip", z.ZodTypeAny, {
+                path: string;
+            }, {
+                path: string;
+            }>;
+        }, "strict", z.ZodTypeAny, {
+            page: {
+                path: string;
+            };
+            element: {
+                text: string | null;
+                tag: string;
+                href: string;
+            };
+        }, {
+            page: {
+                path: string;
+            };
+            element: {
+                text: string | null;
+                tag: string;
+                href: string;
+            };
+        }>;
+        readonly configSchema: z.ZodObject<{}, "strict", z.ZodTypeAny, {}, {}>;
+    };
+};
+type EventName = keyof typeof EVENT_REGISTRY;
+type AutomaticEventName = {
+    [K in EventName]: (typeof EVENT_REGISTRY)[K]['kind'] extends 'automatic' ? K : never;
+}[EventName];
+type ManualEventName = {
+    [K in EventName]: (typeof EVENT_REGISTRY)[K]['kind'] extends 'manual' ? K : never;
+}[EventName];
+type MetadataByName = {
+    page_view: PageViewMetadata;
+    time_on_site: TimeOnSiteMetadata;
+    contact_page_visit: ContactPageVisitMetadata;
+    form_submit: FormSubmitMetadata;
+    phone_click: PhoneClickMetadata;
+};
+type ConfigByName = {
+    page_view: PageViewConfig;
+    time_on_site: TimeOnSiteConfig;
+    contact_page_visit: ContactPageVisitConfig;
+    form_submit: FormSubmitConfig;
+    phone_click: PhoneClickConfig;
+};
+type EventMetadata<K extends EventName> = MetadataByName[K];
+type EventConfig<K extends EventName> = ConfigByName[K];
+type TriggerRegistryConfig = {
+    automatic: {
+        page_view: EventConfig<'page_view'>;
+    } & Partial<{
+        time_on_site: EventConfig<'time_on_site'>;
+        contact_page_visit: EventConfig<'contact_page_visit'>;
+    }>;
+    manual?: Partial<{
+        form_submit: EventConfig<'form_submit'>;
+        phone_click: EventConfig<'phone_click'>;
+    }>;
+};
+type RegisteredManualEvents<TRegistry extends TriggerRegistryConfig> = Extract<keyof NonNullable<TRegistry['manual']>, ManualEventName>;
+type RegisteredAutomaticEvents<TRegistry extends TriggerRegistryConfig> = Extract<keyof TRegistry['automatic'], AutomaticEventName>;
+
+interface TypedTrackEventOptions {
+    /** Override the page URL captured automatically. Rarely needed. */
+    pageUrl?: string | null;
+    /** Event timestamp override. Defaults to "now" at queue time. */
+    occurredAt?: Date | string | null;
+}
+interface TypedTrackingClient<TRegistry extends TriggerRegistryConfig> {
+    /**
+     * Fire a manually-registered event. The event name must be present in
+     * the registry's `manual` map and the metadata must match that event's
+     * canonical Zod-derived shape.
+     */
+    trackEvent<K extends RegisteredManualEvents<TRegistry>>(eventType: K, metadata: EventMetadata<K>, options?: TypedTrackEventOptions): void;
+    flush(): Promise<void>;
+    getSessionId(): string;
+    getVisitorId(): string;
+}
+
 declare function useGclid(): string | null;
 declare function useTrackingParams(): TrackingParams;
 declare function useConsentState(): ConsentState;
 
-export { ConsentBanner, type ConsentState, GoogleAdsTracking, type GoogleAdsTrackingProps, TRACKING_PARAM_KEYS, type TrackingClientContext, type TrackingEventCreatePayload, type TrackingInitConfig, type TrackingInstallSurface, type TrackingParams, type TrackingSessionUpsertPayload, captureTrackingParamsFromLocation, createTrackingClientContext, createTrackingEventCreatePayload, createTrackingSessionUpsertPayload, getConsentState, setConsentState, useConsentState, useGclid, useTrackingParams };
+interface CreateTrackingOptions<TRegistry extends TriggerRegistryConfig> {
+    /** Public tracking API key issued for this business. Required. */
+    apiKey: string;
+    /** Full ingest endpoint base URL, e.g. https://api.aranova.io/tracking. Required. */
+    endpoint: string;
+    /**
+     * Trigger registry. Determines which events the SDK fires automatically
+     * and which ones the consumer can fire manually via `trackEvent()`.
+     * `automatic.page_view` is required — every tracking install needs it.
+     */
+    triggers: TRegistry;
+    /**
+     * When true, the typed client validates every `trackEvent()` metadata
+     * payload through the Zod schema before forwarding. Errors are thrown
+     * loudly. Leave off in prod; turn on in dev to catch shape bugs early.
+     */
+    debug?: boolean;
+}
+interface TrackingProviderProps {
+    /** Optional Google Ads gtag id. If omitted, no gtag script is loaded. */
+    gtagId?: string;
+    children: ReactNode;
+}
+interface CreateTrackingResult<TRegistry extends TriggerRegistryConfig> {
+    TrackingProvider: (props: TrackingProviderProps) => ReactNode;
+    useTracking: () => TypedTrackingClient<TRegistry>;
+}
+/**
+ * Create a scoped TrackingProvider + useTracking hook for a specific
+ * trigger registry. Call this once at app startup (e.g. in a shared
+ * `lib/tracking.ts` file) and import the returned `TrackingProvider` /
+ * `useTracking` from that module, not from `@aranova/tracking-react`
+ * directly. This lets TypeScript thread the registry type through every
+ * consumer so `trackEvent()` autocompletes + rejects unregistered events.
+ *
+ * Example:
+ *
+ * ```ts
+ * // src/lib/tracking.ts
+ * import { createTracking } from '@aranova/tracking-react';
+ *
+ * export const { TrackingProvider, useTracking } = createTracking({
+ *   apiKey: import.meta.env.VITE_ARANOVA_TRACKING_API_KEY,
+ *   endpoint: import.meta.env.VITE_ARANOVA_TRACKING_ENDPOINT,
+ *   triggers: {
+ *     automatic: {
+ *       page_view: {},
+ *       time_on_site: { thresholdSeconds: 60 },
+ *     },
+ *     manual: {
+ *       form_submit: {},
+ *     },
+ *   },
+ * });
+ * ```
+ */
+declare function createTracking<TRegistry extends TriggerRegistryConfig>(options: CreateTrackingOptions<TRegistry>): CreateTrackingResult<TRegistry>;
+
+export { type AutomaticEventName, ConsentBanner, type ConsentState, type ContactPageVisitConfig, type ContactPageVisitMetadata, type CreateTrackingOptions, type CreateTrackingResult, type EventConfig, type EventMetadata, type EventName, type FormSubmitConfig, type FormSubmitMetadata, GoogleAdsTracking, type GoogleAdsTrackingProps, type ManualEventName, type PageViewConfig, type PageViewMetadata, type PhoneClickConfig, type PhoneClickMetadata, type RegisteredAutomaticEvents, type RegisteredManualEvents, 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 };