@aranova/tracking-react 0.3.0 → 0.4.1

package/dist/index.js

@@ -23,8 +23,8 @@ __export(src_exports, {
   ConsentBanner: () => ConsentBanner,
   GoogleAdsTracking: () => GoogleAdsTracking,
   TRACKING_PARAM_KEYS: () => TRACKING_PARAM_KEYS,
-  TrackingProvider: () => TrackingProvider,
   captureTrackingParamsFromLocation: () => captureTrackingParamsFromLocation,
+  createTracking: () => createTracking,
   createTrackingClientContext: () => createTrackingClientContext,
   createTrackingEventCreatePayload: () => createTrackingEventCreatePayload,
   createTrackingSessionUpsertPayload: () => createTrackingSessionUpsertPayload,
@@ -32,7 +32,6 @@ __export(src_exports, {
   setConsentState: () => setConsentState,
   useConsentState: () => useConsentState,
   useGclid: () => useGclid,
-  useTracking: () => useTracking,
   useTrackingParams: () => useTrackingParams
 });
 module.exports = __toCommonJS(src_exports);
@@ -288,6 +287,143 @@ function getOrRotateSessionId(now = Date.now()) {
   return fresh.id;
 }
 
+// ../tracking-core/src/events/page-view.ts
+var import_zod = require("zod");
+var pageViewMetadataSchema = import_zod.z.object({
+  page: import_zod.z.object({
+    title: import_zod.z.string().nullable(),
+    path: import_zod.z.string(),
+    search: import_zod.z.string(),
+    hash: import_zod.z.string()
+  }),
+  referrer: import_zod.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: import_zod.z.object({
+    w: import_zod.z.number(),
+    h: import_zod.z.number()
+  }).nullable().optional()
+}).strict();
+var pageViewConfigSchema = import_zod.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);
+  };
+}
+function attachAutoPageView(client, options = {}) {
+  if (typeof window === "undefined" || typeof history === "undefined") {
+    return () => {
+    };
+  }
+  let lastPath = window.location.pathname + window.location.search;
+  function maybeFire() {
+    const current = window.location.pathname + window.location.search;
+    if (current === lastPath)
+      return;
+    lastPath = current;
+    fireManualPageView(client);
+  }
+  const originalPushState = history.pushState.bind(history);
+  const originalReplaceState = history.replaceState.bind(history);
+  function patchedPushState(...args) {
+    originalPushState(...args);
+    setTimeout(maybeFire, 0);
+  }
+  function patchedReplaceState(...args) {
+    originalReplaceState(...args);
+    setTimeout(maybeFire, 0);
+  }
+  function handlePageShow(event) {
+    if (!event.persisted) return;
+    fireManualPageView(client);
+  }
+  history.pushState = patchedPushState;
+  history.replaceState = patchedReplaceState;
+  window.addEventListener("popstate", maybeFire);
+  window.addEventListener("pageshow", handlePageShow);
+  if (!options.skipInitial)
+    fireManualPageView(client);
+  return () => {
+    history.pushState = originalPushState;
+    history.replaceState = originalReplaceState;
+    window.removeEventListener("popstate", maybeFire);
+    window.removeEventListener("pageshow", handlePageShow);
+  };
+}
+
 // ../tracking-core/src/ingest.ts
 var DEFAULT_FLUSH_INTERVAL_MS = 2e3;
 var DEFAULT_MAX_QUEUE_SIZE = 10;
@@ -338,6 +474,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);
@@ -443,6 +596,9 @@ function createTrackingClient(config) {
     getVisitorId: () => visitorId,
     destroy: () => {
       destroyed = true;
+      if (queue.length > 0) {
+        flushOnUnload();
+      }
       clearScheduledFlush();
       queue = [];
       if (typeof window !== "undefined") {
@@ -452,61 +608,218 @@ 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
+var import_zod2 = require("zod");
+var contactPageVisitMetadataSchema = import_zod2.z.object({
+  page: import_zod2.z.object({
+    path: import_zod2.z.string()
+  })
+}).strict();
+var contactPageVisitConfigSchema = import_zod2.z.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: import_zod2.z.custom(
+    (value) => value instanceof RegExp,
+    { message: "pathPattern must be a RegExp" }
+  )
+}).strict();
+
+// ../tracking-core/src/events/form-submit.ts
+var import_zod3 = require("zod");
+var formSubmitMetadataSchema = import_zod3.z.object({
+  form: import_zod3.z.object({
+    id: import_zod3.z.string(),
+    action: import_zod3.z.string().nullable()
+  }),
+  page: import_zod3.z.object({
+    path: import_zod3.z.string()
+  })
+}).strict();
+var formSubmitConfigSchema = import_zod3.z.object({}).strict();
+
+// ../tracking-core/src/events/phone-click.ts
+var import_zod4 = require("zod");
+var phoneClickMetadataSchema = import_zod4.z.object({
+  element: import_zod4.z.object({
+    tag: import_zod4.z.string(),
+    text: import_zod4.z.string().nullable(),
+    href: import_zod4.z.string()
+  }),
+  page: import_zod4.z.object({
+    path: import_zod4.z.string()
+  })
+}).strict();
+var phoneClickConfigSchema = import_zod4.z.object({}).strict();
+
+// ../tracking-core/src/events/time-on-site.ts
+var import_zod5 = require("zod");
+var timeOnSiteMetadataSchema = import_zod5.z.object({
+  duration_ms: import_zod5.z.number().int().nonnegative(),
+  page: import_zod5.z.object({
+    path: import_zod5.z.string()
+  })
+}).strict();
+var timeOnSiteConfigSchema = import_zod5.z.object({
+  thresholdSeconds: import_zod5.z.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);
+  };
 }
-function attachAutoPageView(client, options = {}) {
+
+// ../tracking-core/src/triggers/contact-page-visit.ts
+function attachContactPageVisit(client, config) {
   if (typeof window === "undefined" || typeof history === "undefined") {
     return () => {
     };
   }
-  let lastPath = window.location.pathname + window.location.search;
-  function maybeFire() {
-    const current = window.location.pathname + window.location.search;
-    if (current === lastPath)
-      return;
-    lastPath = current;
-    fireManualPageView(client);
+  const { pathPattern } = config;
+  let lastFiredPath = null;
+  function check() {
+    const path = window.location.pathname;
+    if (!pathPattern.test(path)) return;
+    if (lastFiredPath === path) return;
+    lastFiredPath = path;
+    client.trackEvent({
+      eventType: "contact_page_visit",
+      metadata: { page: { path } },
+      pageUrl: window.location.href,
+      occurredAt: null
+    });
   }
   const originalPushState = history.pushState.bind(history);
   const originalReplaceState = history.replaceState.bind(history);
   function patchedPushState(...args) {
     originalPushState(...args);
-    setTimeout(maybeFire, 0);
+    setTimeout(check, 0);
   }
   function patchedReplaceState(...args) {
     originalReplaceState(...args);
-    setTimeout(maybeFire, 0);
+    setTimeout(check, 0);
   }
   history.pushState = patchedPushState;
   history.replaceState = patchedReplaceState;
-  window.addEventListener("popstate", maybeFire);
-  if (!options.skipInitial)
-    fireManualPageView(client);
+  window.addEventListener("popstate", check);
+  check();
   return () => {
     history.pushState = originalPushState;
     history.replaceState = originalReplaceState;
-    window.removeEventListener("popstate", maybeFire);
+    window.removeEventListener("popstate", check);
   };
 }
 
@@ -595,68 +908,96 @@ function useConsentState() {
   return consentState;
 }
 
-// src/TrackingProvider.tsx
+// src/factory.tsx
 var import_react4 = require("react");
 var import_jsx_runtime2 = require("react/jsx-runtime");
-var TrackingContext = (0, import_react4.createContext)(null);
-function TrackingProvider({
-  apiKey,
-  endpoint,
-  gtagId,
-  disableAutoPageView,
-  debug,
-  children
-}) {
-  if (!apiKey)
-    throw new Error("TrackingProvider: apiKey is required");
-  if (!endpoint)
-    throw new Error("TrackingProvider: endpoint is required");
-  const clientRef = (0, import_react4.useRef)(null);
-  if (clientRef.current === null) {
-    clientRef.current = createTrackingClient({
-      apiKey,
-      endpoint,
-      surface: "react",
-      packageName: "@aranova/tracking-react",
-      debug
-    });
-  }
-  (0, import_react4.useEffect)(() => {
-    if (!gtagId)
-      return;
-    bootstrapGoogleAdsTracking(gtagId);
-  }, [gtagId]);
-  (0, import_react4.useEffect)(() => {
-    const client = clientRef.current;
-    if (client === null || disableAutoPageView)
-      return;
-    const detach = attachAutoPageView(client);
-    return () => {
-      detach();
-    };
-  }, [disableAutoPageView]);
-  (0, import_react4.useEffect)(() => {
-    return () => {
-      clientRef.current?.destroy();
-      clientRef.current = null;
+var NOOP_CLIENT = {
+  trackEvent: () => {
+  },
+  flush: async () => {
+  },
+  getSessionId: () => "",
+  getVisitorId: () => ""
+};
+function createTracking(options) {
+  const { apiKey, endpoint, triggers, debug } = options;
+  if (!apiKey || !endpoint) {
+    if (apiKey || endpoint) {
+      console.warn(
+        "[AranovaTracking] createTracking() requires both `apiKey` and `endpoint`. Tracking is disabled for this session."
+      );
+    }
+    const noopTyped = NOOP_CLIENT;
+    return {
+      TrackingProvider: ({ children }) => children,
+      useTracking: () => noopTyped
     };
-  }, []);
-  const contextValue = (0, import_react4.useMemo)(() => clientRef.current, []);
-  return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(TrackingContext.Provider, { value: contextValue, children });
-}
-function useTracking() {
-  const client = (0, import_react4.useContext)(TrackingContext);
-  if (client === null)
-    throw new Error("useTracking must be called inside a <TrackingProvider>");
-  return client;
+  }
+  const TrackingContext = (0, import_react4.createContext)(null);
+  function TrackingProvider({ gtagId, children }) {
+    const client = (0, import_react4.useMemo)(
+      () => createTypedClient(
+        getOrCreateTrackingClient({
+          apiKey,
+          endpoint,
+          surface: "react",
+          packageName: "@aranova/tracking-react",
+          debug
+        }),
+        triggers,
+        { debug }
+      ),
+      []
+    );
+    (0, import_react4.useEffect)(() => {
+      if (!gtagId) return;
+      bootstrapGoogleAdsTracking(gtagId);
+    }, [gtagId]);
+    (0, import_react4.useEffect)(() => {
+      const detachers = [];
+      const rawClient = getOrCreateTrackingClient({
+        apiKey,
+        endpoint,
+        surface: "react",
+        packageName: "@aranova/tracking-react",
+        debug
+      });
+      detachers.push(attachAutoPageView(rawClient));
+      detachers.push(attachBfcacheRestore(rawClient));
+      const timeOnSite = triggers.automatic.time_on_site;
+      if (timeOnSite) {
+        detachers.push(attachTimeOnSite(rawClient, timeOnSite));
+      }
+      const contactPageVisit = triggers.automatic.contact_page_visit;
+      if (contactPageVisit) {
+        detachers.push(attachContactPageVisit(rawClient, contactPageVisit));
+      }
+      return () => {
+        for (let i = detachers.length - 1; i >= 0; i--) {
+          detachers[i]();
+        }
+      };
+    }, []);
+    return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(TrackingContext.Provider, { value: client, children });
+  }
+  function useTracking() {
+    const client = (0, import_react4.useContext)(TrackingContext);
+    if (client === null) {
+      throw new Error(
+        "useTracking must be called inside a <TrackingProvider> returned by createTracking()"
+      );
+    }
+    return client;
+  }
+  return { TrackingProvider, useTracking };
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ConsentBanner,
   GoogleAdsTracking,
   TRACKING_PARAM_KEYS,
-  TrackingProvider,
   captureTrackingParamsFromLocation,
+  createTracking,
   createTrackingClientContext,
   createTrackingEventCreatePayload,
   createTrackingSessionUpsertPayload,
@@ -664,7 +1005,6 @@ function useTracking() {
   setConsentState,
   useConsentState,
   useGclid,
-  useTracking,
   useTrackingParams
 });
 //# sourceMappingURL=index.js.map