@aranova/tracking-next 0.2.3 → 0.4.0

package/dist/index.d.ts

@@ -1,8 +1,8 @@
-import { C as ConsentState, T as TrackingInstallSurface, a as TrackingClientContext, b as TrackingParams, c as TrackingEventCreatePayload, d as TrackingSessionUpsertPayload } from './server-BMTa7njW.js';
-export { e as TrackingInitConfig, g as getTrackingParamsServer } from './server-BMTa7njW.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';
-export { createTrackingMiddleware } from './middleware.js';
-import 'next/server';
+import { ReactNode } from 'react';
 
 type GtagConsentValue = 'granted' | 'denied';
 declare function getConsentState(): ConsentState;
@@ -25,6 +25,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;
@@ -33,6 +34,472 @@ 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 ConsentBanner(): react_jsx_runtime.JSX.Element | null;
 
 declare function useGclid(): string | null;
@@ -44,4 +511,31 @@ interface GoogleAdsTrackingProps {
 }
 declare function GoogleAdsTracking({ gtagId }: GoogleAdsTrackingProps): react_jsx_runtime.JSX.Element;
 
-export { ConsentBanner, ConsentState, GoogleAdsTracking, type GoogleAdsTrackingProps, TRACKING_PARAM_KEYS, TrackingClientContext, TrackingEventCreatePayload, TrackingInstallSurface, TrackingParams, TrackingSessionUpsertPayload, captureTrackingParamsFromLocation, createTrackingClientContext, createTrackingEventCreatePayload, createTrackingSessionUpsertPayload, getConsentState, setConsentState, useConsentState, useGclid, useTrackingParams };
+interface CreateTrackingOptions<TRegistry extends TriggerRegistryConfig> {
+    apiKey: string;
+    endpoint: string;
+    triggers: TRegistry;
+    debug?: boolean;
+}
+interface TrackingProviderProps {
+    children: ReactNode;
+}
+interface CreateTrackingResult<TRegistry extends TriggerRegistryConfig> {
+    TrackingProvider: (props: TrackingProviderProps) => ReactNode;
+    useTracking: () => TypedTrackingClient<TRegistry>;
+}
+/**
+ * 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.
+ *
+ * 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 createTracking<TRegistry extends TriggerRegistryConfig>(options: CreateTrackingOptions<TRegistry>): CreateTrackingResult<TRegistry>;
+
+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 };