@aranova/tracking-react 0.2.3 → 0.4.0

package/dist/index.js

@@ -24,6 +24,7 @@ __export(src_exports, {
   GoogleAdsTracking: () => GoogleAdsTracking,
   TRACKING_PARAM_KEYS: () => TRACKING_PARAM_KEYS,
   captureTrackingParamsFromLocation: () => captureTrackingParamsFromLocation,
+  createTracking: () => createTracking,
   createTrackingClientContext: () => createTrackingClientContext,
   createTrackingEventCreatePayload: () => createTrackingEventCreatePayload,
   createTrackingSessionUpsertPayload: () => createTrackingSessionUpsertPayload,
@@ -86,6 +87,7 @@ function createTrackingClientContext(surface, input = {}) {
 function createTrackingSessionUpsertPayload(trackingParams, input, context) {
   return {
     session_id: input.sessionId,
+    visitor_id: input.visitorId ?? null,
     gclid: trackingParams.gclid,
     fbclid: trackingParams.fbclid,
     utm_source: trackingParams.utm_source,
@@ -231,6 +233,596 @@ function captureTrackingParamsFromLocation(url = typeof window === "undefined" ?
   return getTrackingParamsFromCookieReader(getCookieValueFromDocument);
 }
 
+// ../tracking-core/src/session.ts
+var VISITOR_STORAGE_KEY = "aranova_tracking_visitor";
+var SESSION_STORAGE_KEY = "aranova_tracking_session";
+var SESSION_IDLE_MS = 30 * 60 * 1e3;
+function safeUuid() {
+  if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function")
+    return crypto.randomUUID();
+  return `${Date.now().toString(16)}-${Math.random().toString(16).slice(2)}-${Math.random().toString(16).slice(2)}`;
+}
+function readLocalStorage(key) {
+  try {
+    return window.localStorage.getItem(key);
+  } catch {
+    return null;
+  }
+}
+function writeLocalStorage(key, value) {
+  try {
+    window.localStorage.setItem(key, value);
+  } catch {
+  }
+}
+function getVisitorId() {
+  if (typeof window === "undefined")
+    return safeUuid();
+  const existing = readLocalStorage(VISITOR_STORAGE_KEY);
+  if (existing && existing.length > 0)
+    return existing;
+  const fresh = safeUuid();
+  writeLocalStorage(VISITOR_STORAGE_KEY, fresh);
+  return fresh;
+}
+function getOrRotateSessionId(now = Date.now()) {
+  if (typeof window === "undefined")
+    return safeUuid();
+  const raw = readLocalStorage(SESSION_STORAGE_KEY);
+  if (raw) {
+    try {
+      const parsed = JSON.parse(raw);
+      if (typeof parsed.id === "string" && typeof parsed.last_event_at === "number") {
+        if (now - parsed.last_event_at <= SESSION_IDLE_MS) {
+          const refreshed = { id: parsed.id, last_event_at: now };
+          writeLocalStorage(SESSION_STORAGE_KEY, JSON.stringify(refreshed));
+          return parsed.id;
+        }
+      }
+    } catch {
+    }
+  }
+  const fresh = { id: safeUuid(), last_event_at: now };
+  writeLocalStorage(SESSION_STORAGE_KEY, JSON.stringify(fresh));
+  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;
+var HARD_MAX_BATCH = 50;
+var API_KEY_HEADER = "X-Aranova-Api-Key";
+function buildContext(surface, sdkVersion, packageName) {
+  return {
+    surface,
+    sdk_version: sdkVersion,
+    package_name: packageName,
+    site_origin: typeof window === "undefined" ? null : window.location.origin,
+    page_title: typeof document === "undefined" ? null : document.title || null,
+    referrer: typeof document === "undefined" ? null : document.referrer || null
+  };
+}
+function readTrackingParams() {
+  if (typeof window === "undefined")
+    return createEmptyTrackingParams();
+  try {
+    captureTrackingParamsFromLocation();
+  } catch {
+  }
+  return getTrackingParamsFromCookieReader(getCookieValueFromDocument);
+}
+function consentSnapshot() {
+  try {
+    return { state: getConsentState() };
+  } catch {
+    return null;
+  }
+}
+async function postWithFetch(url, body, apiKey, keepalive) {
+  if (typeof fetch !== "function")
+    return;
+  try {
+    await fetch(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        [API_KEY_HEADER]: apiKey
+      },
+      body,
+      keepalive,
+      // CORS is open on the tracking endpoint; never send cookies.
+      credentials: "omit",
+      mode: "cors"
+    });
+  } 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);
+  const sdkVersion = config.sdkVersion ?? null;
+  const packageName = config.packageName ?? null;
+  const endpointBase = config.endpoint.replace(/\/$/, "");
+  const eventsUrl = `${endpointBase}/events`;
+  let queue = [];
+  let flushTimer = null;
+  let firstPage = null;
+  let destroyed = false;
+  const visitorId = getVisitorId();
+  let sessionId = getOrRotateSessionId();
+  if (typeof window !== "undefined")
+    firstPage = window.location.href;
+  function buildSessionPayload() {
+    sessionId = getOrRotateSessionId();
+    const params = readTrackingParams();
+    const context = buildContext(config.surface, sdkVersion, packageName);
+    return {
+      session_id: sessionId,
+      visitor_id: visitorId,
+      gclid: params.gclid,
+      fbclid: params.fbclid,
+      utm_source: params.utm_source,
+      utm_medium: params.utm_medium,
+      utm_campaign: params.utm_campaign,
+      utm_term: params.utm_term,
+      utm_content: params.utm_content,
+      first_page: firstPage,
+      consent_state: consentSnapshot(),
+      context
+    };
+  }
+  function scheduleFlush() {
+    if (flushTimer !== null || destroyed)
+      return;
+    flushTimer = setTimeout(() => {
+      flushTimer = null;
+      void flush();
+    }, flushIntervalMs);
+  }
+  function clearScheduledFlush() {
+    if (flushTimer !== null) {
+      clearTimeout(flushTimer);
+      flushTimer = null;
+    }
+  }
+  async function flush() {
+    if (queue.length === 0)
+      return;
+    const events = queue.slice(0, HARD_MAX_BATCH);
+    queue = queue.slice(events.length);
+    clearScheduledFlush();
+    const body = {
+      session: buildSessionPayload(),
+      events
+    };
+    const serialized = JSON.stringify(body);
+    await postWithFetch(eventsUrl, serialized, config.apiKey, false);
+  }
+  function trackEvent(input) {
+    if (destroyed)
+      return;
+    if (!input || typeof input.eventType !== "string" || input.eventType.length === 0)
+      return;
+    const occurredAt = input.occurredAt instanceof Date ? input.occurredAt.toISOString() : typeof input.occurredAt === "string" ? input.occurredAt : (/* @__PURE__ */ new Date()).toISOString();
+    queue.push({
+      event_type: input.eventType,
+      page_url: input.pageUrl ?? (typeof window === "undefined" ? null : window.location.href),
+      metadata: input.metadata ?? null,
+      occurred_at: occurredAt
+    });
+    if (queue.length >= maxQueueSize) {
+      void flush();
+    } else {
+      scheduleFlush();
+    }
+  }
+  function flushOnUnload() {
+    if (queue.length === 0)
+      return;
+    const events = queue.slice(0, HARD_MAX_BATCH);
+    queue = queue.slice(events.length);
+    clearScheduledFlush();
+    const body = {
+      session: buildSessionPayload(),
+      events
+    };
+    const serialized = JSON.stringify(body);
+    void postWithFetch(eventsUrl, serialized, config.apiKey, true);
+  }
+  if (typeof window !== "undefined") {
+    window.addEventListener("pagehide", flushOnUnload);
+    window.addEventListener("visibilitychange", () => {
+      if (document.visibilityState === "hidden") flushOnUnload();
+    });
+  }
+  return {
+    trackEvent,
+    flush,
+    getSessionId: () => sessionId,
+    getVisitorId: () => visitorId,
+    destroy: () => {
+      destroyed = true;
+      if (queue.length > 0) {
+        flushOnUnload();
+      }
+      clearScheduledFlush();
+      queue = [];
+      if (typeof window !== "undefined") {
+        window.removeEventListener("pagehide", flushOnUnload);
+      }
+    }
+  };
+}
+
+// ../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 {
+    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
+      });
+    },
+    flush: raw.flush.bind(raw),
+    getSessionId: raw.getSessionId.bind(raw),
+    getVisitorId: raw.getVisitorId.bind(raw)
+  };
+}
+
+// ../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);
+  };
+}
+
+// ../tracking-core/src/triggers/contact-page-visit.ts
+function attachContactPageVisit(client, config) {
+  if (typeof window === "undefined" || typeof history === "undefined") {
+    return () => {
+    };
+  }
+  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(check, 0);
+  }
+  function patchedReplaceState(...args) {
+    originalReplaceState(...args);
+    setTimeout(check, 0);
+  }
+  history.pushState = patchedPushState;
+  history.replaceState = patchedReplaceState;
+  window.addEventListener("popstate", check);
+  check();
+  return () => {
+    history.pushState = originalPushState;
+    history.replaceState = originalReplaceState;
+    window.removeEventListener("popstate", check);
+  };
+}
+
 // src/ConsentBanner.tsx
 var import_jsx_runtime = require("react/jsx-runtime");
 function ConsentBanner() {
@@ -315,12 +907,79 @@ function useConsentState() {
   }, []);
   return consentState;
 }
+
+// src/factory.tsx
+var import_react4 = require("react");
+var import_jsx_runtime2 = require("react/jsx-runtime");
+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 = (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,
   captureTrackingParamsFromLocation,
+  createTracking,
   createTrackingClientContext,
   createTrackingEventCreatePayload,
   createTrackingSessionUpsertPayload,