@aranova/tracking-next 0.3.0 → 0.4.1

package/dist/index.d.ts

@@ -1,5 +1,6 @@
-import { C as ConsentState, T as TrackingInstallSurface, a as TrackingClientContext, b as TrackingParams, c as TrackingEventCreatePayload, d as TrackingSessionUpsertPayload } from './types-CFWz-qi9.js';
-export { e as TrackingInitConfig } from './types-CFWz-qi9.js';
+import { C as ConsentState, T as TrackingInstallSurface, a as TrackingClientContext, b as TrackingParams, c as TrackingEventCreatePayload, d as TrackingSessionUpsertPayload } from './types-Gp0ioRiQ.js';
+export { e as TrackingInitConfig } from './types-Gp0ioRiQ.js';
+import { z } from 'zod';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ReactNode } from 'react';
 
@@ -47,6 +48,458 @@ interface TrackingClient {
     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 ConsentBanner(): react_jsx_runtime.JSX.Element | null;
 
 declare function useGclid(): string | null;
@@ -58,26 +511,31 @@ interface GoogleAdsTrackingProps {
 }
 declare function GoogleAdsTracking({ gtagId }: GoogleAdsTrackingProps): react_jsx_runtime.JSX.Element;
 
-interface TrackingProviderProps {
-    /** Public tracking API key issued for this business. Required. */
+interface CreateTrackingOptions<TRegistry extends TriggerRegistryConfig> {
     apiKey: string;
-    /** Full ingest endpoint base URL, e.g. https://api.aranova.io/tracking. Required. */
     endpoint: string;
-    /** Disable automatic page_view emission (manual tracking only). */
-    disableAutoPageView?: boolean;
-    /** Optional debug flag — currently a no-op, reserved for verbose logging. */
+    triggers: TRegistry;
     debug?: boolean;
+}
+interface TrackingProviderProps {
     children: ReactNode;
 }
+interface CreateTrackingResult<TRegistry extends TriggerRegistryConfig> {
+    TrackingProvider: (props: TrackingProviderProps) => ReactNode;
+    useTracking: () => TypedTrackingClient<TRegistry>;
+}
 /**
- * Provider for App Router projects. Uses `usePathname` for SPA route detection
- * instead of patching `history.pushState`, because Next's router does not
- * always go through the History API for transitions.
+ * 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.
  *
- * `gtagId` lives on the existing <GoogleAdsTracking> component — keep them
- * separate so a client without paid Google Ads can install just this provider.
+ * Usage is identical to the React factory — call this once at app
+ * startup and export the returned `TrackingProvider` + `useTracking`
+ * from your own module, then import them everywhere else. `GoogleAdsTracking`
+ * is still imported separately and placed in the root layout's `<head>`
+ * when the client runs paid ads.
  */
-declare function TrackingProvider({ apiKey, endpoint, disableAutoPageView, debug, children, }: TrackingProviderProps): react_jsx_runtime.JSX.Element;
-declare function useTracking(): TrackingClient;
+declare function createTracking<TRegistry extends TriggerRegistryConfig>(options: CreateTrackingOptions<TRegistry>): CreateTrackingResult<TRegistry>;
 
-export { ConsentBanner, ConsentState, GoogleAdsTracking, type GoogleAdsTrackingProps, TRACKING_PARAM_KEYS, type TrackingClient, TrackingClientContext, TrackingEventCreatePayload, TrackingInstallSurface, TrackingParams, TrackingProvider, type TrackingProviderProps, TrackingSessionUpsertPayload, captureTrackingParamsFromLocation, createTrackingClientContext, createTrackingEventCreatePayload, createTrackingSessionUpsertPayload, getConsentState, setConsentState, useConsentState, useGclid, useTracking, useTrackingParams };
+export { type AutomaticEventName, ConsentBanner, 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, TrackingClientContext, TrackingEventCreatePayload, TrackingInstallSurface, TrackingParams, type TrackingProviderProps, TrackingSessionUpsertPayload, type TriggerRegistryConfig, type TypedTrackEventOptions, type TypedTrackingClient, captureTrackingParamsFromLocation, createTracking, createTrackingClientContext, createTrackingEventCreatePayload, createTrackingSessionUpsertPayload, getConsentState, setConsentState, useConsentState, useGclid, useTrackingParams };