@aranova/tracking-next 0.3.0 → 0.4.0

package/dist/index.mjs

@@ -226,6 +226,103 @@ function getOrRotateSessionId(now = Date.now()) {
   return fresh.id;
 }
 
+// ../tracking-core/src/events/page-view.ts
+import { z } from "zod";
+var pageViewMetadataSchema = z.object({
+  page: z.object({
+    title: z.string().nullable(),
+    path: z.string(),
+    search: z.string(),
+    hash: z.string()
+  }),
+  referrer: z.string().nullable(),
+  // `.nullable().optional()` — absent (undefined) OR explicit null OR a
+  // real viewport object. Mirrors Pydantic's `_Viewport | None = None`
+  // on the backend side so the drift test stays clean.
+  viewport: z.object({
+    w: z.number(),
+    h: z.number()
+  }).nullable().optional()
+}).strict();
+var pageViewConfigSchema = z.object({}).strict();
+
+// ../tracking-core/src/page-view.ts
+var LAST_FIRED_URL_STORAGE_KEY = "aranova_tracking_last_fired_url";
+var lastFiredUrl = null;
+var lastFiredUrlHydrated = false;
+function readSessionStorage(key) {
+  try {
+    if (typeof window === "undefined") return null;
+    return window.sessionStorage.getItem(key);
+  } catch {
+    return null;
+  }
+}
+function writeSessionStorage(key, value) {
+  try {
+    if (typeof window === "undefined") return;
+    window.sessionStorage.setItem(key, value);
+  } catch {
+  }
+}
+function getLastFiredUrl() {
+  if (!lastFiredUrlHydrated) {
+    lastFiredUrlHydrated = true;
+    const stored = readSessionStorage(LAST_FIRED_URL_STORAGE_KEY);
+    if (stored !== null) lastFiredUrl = stored;
+  }
+  return lastFiredUrl;
+}
+function setLastFiredUrl(url) {
+  lastFiredUrl = url;
+  lastFiredUrlHydrated = true;
+  writeSessionStorage(LAST_FIRED_URL_STORAGE_KEY, url);
+}
+function buildPageViewMetadata(referrerOverride) {
+  if (typeof window === "undefined" || typeof document === "undefined")
+    return null;
+  return pageViewMetadataSchema.parse({
+    page: {
+      title: document.title || null,
+      path: window.location.pathname,
+      search: window.location.search,
+      hash: window.location.hash
+    },
+    referrer: referrerOverride !== void 0 ? referrerOverride : document.referrer || null,
+    viewport: { w: window.innerWidth, h: window.innerHeight }
+  });
+}
+function fireManualPageView(client) {
+  if (typeof window === "undefined")
+    return;
+  const currentHref = window.location.href;
+  const previousFiredUrl = getLastFiredUrl();
+  const internalReferrer = previousFiredUrl !== null && previousFiredUrl !== currentHref ? previousFiredUrl : null;
+  const externalReferrer = typeof document !== "undefined" ? document.referrer || null : null;
+  const referrer = internalReferrer ?? externalReferrer;
+  const metadata = buildPageViewMetadata(referrer);
+  client.trackEvent({
+    eventType: "page_view",
+    pageUrl: currentHref,
+    metadata
+  });
+  if (currentHref !== previousFiredUrl) {
+    setLastFiredUrl(currentHref);
+  }
+}
+function attachBfcacheRestore(client) {
+  if (typeof window === "undefined") return () => {
+  };
+  function handlePageShow(event) {
+    if (!event.persisted) return;
+    fireManualPageView(client);
+  }
+  window.addEventListener("pageshow", handlePageShow);
+  return () => {
+    window.removeEventListener("pageshow", handlePageShow);
+  };
+}
+
 // ../tracking-core/src/ingest.ts
 var DEFAULT_FLUSH_INTERVAL_MS = 2e3;
 var DEFAULT_MAX_QUEUE_SIZE = 10;
@@ -276,6 +373,23 @@ async function postWithFetch(url, body, apiKey, keepalive) {
   } catch {
   }
 }
+var globalClient = null;
+var globalClientKey = null;
+function clientConfigKey(config) {
+  return `${config.apiKey}@${config.endpoint}#${config.surface}`;
+}
+function getOrCreateTrackingClient(config) {
+  const key = clientConfigKey(config);
+  if (globalClient !== null && globalClientKey === key) {
+    return globalClient;
+  }
+  if (globalClient !== null) {
+    globalClient.destroy();
+  }
+  globalClient = createTrackingClient(config);
+  globalClientKey = key;
+  return globalClient;
+}
 function createTrackingClient(config) {
   const flushIntervalMs = config.flushIntervalMs ?? DEFAULT_FLUSH_INTERVAL_MS;
   const maxQueueSize = Math.min(config.maxQueueSize ?? DEFAULT_MAX_QUEUE_SIZE, HARD_MAX_BATCH);
@@ -381,6 +495,9 @@ function createTrackingClient(config) {
     getVisitorId: () => visitorId,
     destroy: () => {
       destroyed = true;
+      if (queue.length > 0) {
+        flushOnUnload();
+      }
       clearScheduledFlush();
       queue = [];
       if (typeof window !== "undefined") {
@@ -390,28 +507,178 @@ function createTrackingClient(config) {
   };
 }
 
-// ../tracking-core/src/page-view.ts
-function buildPageViewMetadata() {
-  if (typeof window === "undefined" || typeof document === "undefined")
-    return null;
+// ../tracking-core/src/events/contact-page-visit.ts
+import { z as z2 } from "zod";
+var contactPageVisitMetadataSchema = z2.object({
+  page: z2.object({
+    path: z2.string()
+  })
+}).strict();
+var contactPageVisitConfigSchema = z2.object({
+  // RegExp is runtime-only so we wrap it via z.custom. Consumers pass a
+  // real regex at createTracking() time; the factory validates with this
+  // schema and then keeps the live RegExp reference for runtime matching.
+  pathPattern: z2.custom(
+    (value) => value instanceof RegExp,
+    { message: "pathPattern must be a RegExp" }
+  )
+}).strict();
+
+// ../tracking-core/src/events/form-submit.ts
+import { z as z3 } from "zod";
+var formSubmitMetadataSchema = z3.object({
+  form: z3.object({
+    id: z3.string(),
+    action: z3.string().nullable()
+  }),
+  page: z3.object({
+    path: z3.string()
+  })
+}).strict();
+var formSubmitConfigSchema = z3.object({}).strict();
+
+// ../tracking-core/src/events/phone-click.ts
+import { z as z4 } from "zod";
+var phoneClickMetadataSchema = z4.object({
+  element: z4.object({
+    tag: z4.string(),
+    text: z4.string().nullable(),
+    href: z4.string()
+  }),
+  page: z4.object({
+    path: z4.string()
+  })
+}).strict();
+var phoneClickConfigSchema = z4.object({}).strict();
+
+// ../tracking-core/src/events/time-on-site.ts
+import { z as z5 } from "zod";
+var timeOnSiteMetadataSchema = z5.object({
+  duration_ms: z5.number().int().nonnegative(),
+  page: z5.object({
+    path: z5.string()
+  })
+}).strict();
+var timeOnSiteConfigSchema = z5.object({
+  thresholdSeconds: z5.number().int().positive()
+}).strict();
+
+// ../tracking-core/src/events/registry.ts
+var EVENT_REGISTRY = {
+  // --- automatic triggers ---
+  page_view: {
+    kind: "automatic",
+    metadataSchema: pageViewMetadataSchema,
+    configSchema: pageViewConfigSchema
+  },
+  time_on_site: {
+    kind: "automatic",
+    metadataSchema: timeOnSiteMetadataSchema,
+    configSchema: timeOnSiteConfigSchema
+  },
+  contact_page_visit: {
+    kind: "automatic",
+    metadataSchema: contactPageVisitMetadataSchema,
+    configSchema: contactPageVisitConfigSchema
+  },
+  // --- manual triggers ---
+  form_submit: {
+    kind: "manual",
+    metadataSchema: formSubmitMetadataSchema,
+    configSchema: formSubmitConfigSchema
+  },
+  phone_click: {
+    kind: "manual",
+    metadataSchema: phoneClickMetadataSchema,
+    configSchema: phoneClickConfigSchema
+  }
+};
+var ALL_AUTOMATIC_EVENT_NAMES = Object.entries(EVENT_REGISTRY).filter(([, def]) => def.kind === "automatic").map(([name]) => name);
+var ALL_MANUAL_EVENT_NAMES = Object.entries(EVENT_REGISTRY).filter(([, def]) => def.kind === "manual").map(([name]) => name);
+function getEventDefinition(name) {
+  return EVENT_REGISTRY[name];
+}
+
+// ../tracking-core/src/ingest-typed.ts
+function createTypedClient(raw, _registry, options = {}) {
+  const debug = options.debug ?? false;
   return {
-    page: {
-      title: document.title || null,
-      path: window.location.pathname,
-      search: window.location.search,
-      hash: window.location.hash
+    trackEvent(eventType, metadata, opts) {
+      if (debug) {
+        const def = getEventDefinition(eventType);
+        def.metadataSchema.parse(metadata);
+      }
+      raw.trackEvent({
+        eventType,
+        metadata,
+        pageUrl: opts?.pageUrl ?? null,
+        occurredAt: opts?.occurredAt ?? null
+      });
     },
-    referrer: document.referrer || null,
-    viewport: { w: window.innerWidth, h: window.innerHeight }
+    flush: raw.flush.bind(raw),
+    getSessionId: raw.getSessionId.bind(raw),
+    getVisitorId: raw.getVisitorId.bind(raw)
   };
 }
-function fireManualPageView(client) {
-  const metadata = buildPageViewMetadata();
-  client.trackEvent({
-    eventType: "page_view",
-    pageUrl: typeof window === "undefined" ? null : window.location.href,
-    metadata
-  });
+
+// ../tracking-core/src/triggers/time-on-site.ts
+function attachTimeOnSite(client, config) {
+  if (typeof window === "undefined" || typeof document === "undefined") {
+    return () => {
+    };
+  }
+  const thresholdMs = config.thresholdSeconds * 1e3;
+  let accumulatedMs = 0;
+  let activeSince = document.visibilityState === "visible" ? Date.now() : null;
+  let timer = null;
+  let fired = false;
+  function fire() {
+    if (fired) return;
+    fired = true;
+    client.trackEvent({
+      eventType: "time_on_site",
+      metadata: {
+        duration_ms: thresholdMs,
+        page: { path: window.location.pathname }
+      },
+      pageUrl: window.location.href,
+      occurredAt: null
+    });
+  }
+  function scheduleNext() {
+    if (fired || activeSince === null) return;
+    const remaining = thresholdMs - accumulatedMs;
+    if (remaining <= 0) {
+      fire();
+      return;
+    }
+    timer = setTimeout(fire, remaining);
+  }
+  function clearTimer() {
+    if (timer !== null) {
+      clearTimeout(timer);
+      timer = null;
+    }
+  }
+  function onVisibilityChange() {
+    if (fired) return;
+    if (document.visibilityState === "hidden") {
+      if (activeSince !== null) {
+        accumulatedMs += Date.now() - activeSince;
+        activeSince = null;
+      }
+      clearTimer();
+    } else {
+      activeSince = Date.now();
+      scheduleNext();
+    }
+  }
+  document.addEventListener("visibilitychange", onVisibilityChange);
+  scheduleNext();
+  return () => {
+    clearTimer();
+    document.removeEventListener("visibilitychange", onVisibilityChange);
+  };
 }
 
 // src/ConsentBanner.tsx
@@ -509,7 +776,7 @@ function GoogleAdsTracking({ gtagId }) {
   ] });
 }
 
-// src/TrackingProvider.tsx
+// src/factory.tsx
 import { usePathname, useSearchParams } from "next/navigation";
 import {
   createContext,
@@ -519,59 +786,100 @@ import {
   useRef
 } from "react";
 import { jsx as jsx3 } from "react/jsx-runtime";
-var TrackingContext = createContext(null);
-function TrackingProvider({
-  apiKey,
-  endpoint,
-  disableAutoPageView,
-  debug,
-  children
-}) {
-  if (!apiKey)
-    throw new Error("TrackingProvider: apiKey is required");
-  if (!endpoint)
-    throw new Error("TrackingProvider: endpoint is required");
-  const pathname = usePathname();
-  const searchParams = useSearchParams();
-  const clientRef = useRef(null);
-  if (clientRef.current === null) {
-    clientRef.current = createTrackingClient({
-      apiKey,
-      endpoint,
-      surface: "next",
-      packageName: "@aranova/tracking-next",
-      debug
-    });
+function createTracking(options) {
+  const { apiKey, endpoint, triggers, debug } = options;
+  if (!apiKey) throw new Error("createTracking: apiKey is required");
+  if (!endpoint) throw new Error("createTracking: endpoint is required");
+  const TrackingContext = createContext(null);
+  const contactPageVisitConfig = triggers.automatic.contact_page_visit ?? null;
+  const timeOnSiteConfig = triggers.automatic.time_on_site ?? null;
+  function TrackingProvider({ children }) {
+    const pathname = usePathname();
+    const searchParams = useSearchParams();
+    const client = useMemo(
+      () => createTypedClient(
+        getOrCreateTrackingClient({
+          apiKey,
+          endpoint,
+          surface: "next",
+          packageName: "@aranova/tracking-next",
+          debug
+        }),
+        triggers,
+        { debug }
+      ),
+      []
+    );
+    useEffect3(() => {
+      const rawClient = getOrCreateTrackingClient({
+        apiKey,
+        endpoint,
+        surface: "next",
+        packageName: "@aranova/tracking-next",
+        debug
+      });
+      fireManualPageView(rawClient);
+    }, [pathname, searchParams]);
+    const lastContactPathRef = useRef(null);
+    useEffect3(() => {
+      if (!contactPageVisitConfig || pathname === null) return;
+      if (!contactPageVisitConfig.pathPattern.test(pathname)) return;
+      if (lastContactPathRef.current === pathname) return;
+      lastContactPathRef.current = pathname;
+      const rawClient = getOrCreateTrackingClient({
+        apiKey,
+        endpoint,
+        surface: "next",
+        packageName: "@aranova/tracking-next",
+        debug
+      });
+      rawClient.trackEvent({
+        eventType: "contact_page_visit",
+        metadata: { page: { path: pathname } },
+        pageUrl: null,
+        occurredAt: null
+      });
+    }, [pathname]);
+    useEffect3(() => {
+      const rawClient = getOrCreateTrackingClient({
+        apiKey,
+        endpoint,
+        surface: "next",
+        packageName: "@aranova/tracking-next",
+        debug
+      });
+      return attachBfcacheRestore(rawClient);
+    }, []);
+    useEffect3(() => {
+      if (!timeOnSiteConfig) return;
+      const rawClient = getOrCreateTrackingClient({
+        apiKey,
+        endpoint,
+        surface: "next",
+        packageName: "@aranova/tracking-next",
+        debug
+      });
+      return attachTimeOnSite(rawClient, timeOnSiteConfig);
+    }, []);
+    return /* @__PURE__ */ jsx3(TrackingContext.Provider, { value: client, children });
   }
-  useEffect3(() => {
-    if (disableAutoPageView)
-      return;
-    const client = clientRef.current;
-    if (client === null)
-      return;
-    fireManualPageView(client);
-  }, [pathname, searchParams, disableAutoPageView]);
-  useEffect3(() => {
-    return () => {
-      clientRef.current?.destroy();
-      clientRef.current = null;
-    };
-  }, []);
-  const contextValue = useMemo(() => clientRef.current, []);
-  return /* @__PURE__ */ jsx3(TrackingContext.Provider, { value: contextValue, children });
-}
-function useTracking() {
-  const client = useContext(TrackingContext);
-  if (client === null)
-    throw new Error("useTracking must be called inside a <TrackingProvider>");
-  return client;
+  function useTracking() {
+    const client = useContext(TrackingContext);
+    if (client === null) {
+      throw new Error(
+        "useTracking must be called inside a <TrackingProvider> returned by createTracking()"
+      );
+    }
+    return client;
+  }
+  return { TrackingProvider, useTracking };
 }
 export {
   ConsentBanner,
   GoogleAdsTracking,
   TRACKING_PARAM_KEYS,
-  TrackingProvider,
   captureTrackingParamsFromLocation,
+  createTracking,
   createTrackingClientContext,
   createTrackingEventCreatePayload,
   createTrackingSessionUpsertPayload,
@@ -579,7 +887,6 @@ export {
   setConsentState,
   useConsentState,
   useGclid,
-  useTracking,
   useTrackingParams
 };
 //# sourceMappingURL=index.mjs.map