@aranova/tracking-react 0.4.2 → 0.5.1

package/dist/index.mjs

@@ -229,7 +229,7 @@ function getVisitorId() {
 }
 function getOrRotateSessionId(now = Date.now()) {
   if (typeof window === "undefined")
-    return safeUuid();
+    return { id: safeUuid(), isNew: true };
   const raw = readLocalStorage(SESSION_STORAGE_KEY);
   if (raw) {
     try {
@@ -238,7 +238,7 @@ function getOrRotateSessionId(now = Date.now()) {
         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;
+          return { id: parsed.id, isNew: false };
         }
       }
     } catch {
@@ -246,7 +246,7 @@ function getOrRotateSessionId(now = Date.now()) {
   }
   const fresh = { id: safeUuid(), last_event_at: now };
   writeLocalStorage(SESSION_STORAGE_KEY, JSON.stringify(fresh));
-  return fresh.id;
+  return { id: fresh.id, isNew: true };
 }
 
 // ../tracking-core/src/events/page-view.ts
@@ -386,6 +386,56 @@ function attachAutoPageView(client, options = {}) {
   };
 }
 
+// ../tracking-core/src/heartbeat.ts
+function serializeValue(value) {
+  if (value instanceof RegExp) return value.source;
+  if (Array.isArray(value)) return value.map(serializeValue);
+  if (value !== null && typeof value === "object") {
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+      out[k] = serializeValue(v);
+    }
+    return out;
+  }
+  return value;
+}
+function buildHeartbeatMetadata(surface, sdkVersion, packageName, triggers) {
+  const automaticNames = triggers ? Object.keys(triggers.automatic) : [];
+  const manualNames = triggers?.manual ? Object.keys(triggers.manual) : [];
+  let triggerConfig = null;
+  if (triggers) {
+    const cfg = {};
+    for (const [name, config] of Object.entries(triggers.automatic)) {
+      const serialized = serializeValue(config);
+      if (Object.keys(serialized).length > 0) {
+        cfg[name] = serialized;
+      }
+    }
+    if (triggers.manual) {
+      for (const [name, config] of Object.entries(triggers.manual)) {
+        if (config === void 0) continue;
+        const serialized = serializeValue(config);
+        if (Object.keys(serialized).length > 0) {
+          cfg[name] = serialized;
+        }
+      }
+    }
+    if (Object.keys(cfg).length > 0) {
+      triggerConfig = cfg;
+    }
+  }
+  return {
+    sdk_version: sdkVersion ?? "unknown",
+    package_name: packageName,
+    surface,
+    triggers: {
+      automatic: automaticNames,
+      manual: manualNames
+    },
+    trigger_config: triggerConfig
+  };
+}
+
 // ../tracking-core/src/ingest.ts
 var DEFAULT_FLUSH_INTERVAL_MS = 2e3;
 var DEFAULT_MAX_QUEUE_SIZE = 10;
@@ -465,11 +515,33 @@ function createTrackingClient(config) {
   let firstPage = null;
   let destroyed = false;
   const visitorId = getVisitorId();
-  let sessionId = getOrRotateSessionId();
+  const initialSession = getOrRotateSessionId();
+  let sessionId = initialSession.id;
   if (typeof window !== "undefined")
     firstPage = window.location.href;
+  function enqueueHeartbeat() {
+    const metadata = buildHeartbeatMetadata(
+      config.surface,
+      sdkVersion,
+      packageName,
+      config.triggers ?? null
+    );
+    queue.push({
+      event_type: "sdk_heartbeat",
+      page_url: typeof window === "undefined" ? null : window.location.href,
+      metadata,
+      occurred_at: (/* @__PURE__ */ new Date()).toISOString()
+    });
+  }
+  if (initialSession.isNew) {
+    enqueueHeartbeat();
+  }
   function buildSessionPayload() {
-    sessionId = getOrRotateSessionId();
+    const rotated = getOrRotateSessionId();
+    if (rotated.isNew && rotated.id !== sessionId) {
+      enqueueHeartbeat();
+    }
+    sessionId = rotated.id;
     const params = readTrackingParams();
     const context = buildContext(config.surface, sdkVersion, packageName);
     return {
@@ -570,60 +642,144 @@ function createTrackingClient(config) {
   };
 }
 
-// ../tracking-core/src/events/contact-page-visit.ts
+// ../tracking-core/src/events/cta-click.ts
 import { z as z2 } from "zod";
-var contactPageVisitMetadataSchema = z2.object({
+var ctaClickMetadataSchema = z2.object({
+  cta_name: z2.string(),
   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" }
-  )
+  }),
+  section: z2.string().nullable().optional(),
+  destination_url: z2.string().nullable().optional()
 }).strict();
+var ctaClickConfigSchema = z2.object({}).strict();
 
-// ../tracking-core/src/events/form-submit.ts
+// ../tracking-core/src/events/sdk-heartbeat.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()
-  })
+var sdkHeartbeatTriggersSchema = z3.object({
+  automatic: z3.array(z3.string()),
+  manual: z3.array(z3.string())
+}).strict();
+var sdkHeartbeatMetadataSchema = z3.object({
+  sdk_version: z3.string(),
+  package_name: z3.string().nullable(),
+  surface: z3.enum(["next", "react", "script"]),
+  triggers: sdkHeartbeatTriggersSchema,
+  trigger_config: z3.record(z3.string(), z3.record(z3.string(), z3.unknown())).nullable().optional()
 }).strict();
-var formSubmitConfigSchema = z3.object({}).strict();
+var sdkHeartbeatConfigSchema = z3.object({}).strict();
 
-// ../tracking-core/src/events/phone-click.ts
+// ../tracking-core/src/events/form-start.ts
 import { z as z4 } from "zod";
-var phoneClickMetadataSchema = z4.object({
-  element: z4.object({
-    tag: z4.string(),
-    text: z4.string().nullable(),
-    href: z4.string()
+var formStartMetadataSchema = z4.object({
+  form: z4.object({
+    id: z4.string(),
+    action: z4.string().nullable()
   }),
   page: z4.object({
     path: z4.string()
   })
 }).strict();
-var phoneClickConfigSchema = z4.object({}).strict();
+var formStartConfigSchema = z4.object({
+  selector: z4.string().optional()
+}).strict();
 
-// ../tracking-core/src/events/time-on-site.ts
+// ../tracking-core/src/events/form-submit.ts
 import { z as z5 } from "zod";
-var timeOnSiteMetadataSchema = z5.object({
-  duration_ms: z5.number().int().nonnegative(),
+var formSubmitMetadataSchema = z5.object({
+  form: z5.object({
+    id: z5.string(),
+    action: z5.string().nullable(),
+    fields: z5.array(
+      z5.object({
+        name: z5.string(),
+        type: z5.string(),
+        label: z5.string().nullable(),
+        has_value: z5.boolean()
+      })
+    ).optional()
+  }),
   page: z5.object({
     path: z5.string()
   })
 }).strict();
-var timeOnSiteConfigSchema = z5.object({
-  thresholdSeconds: z5.number().int().positive()
+var formSubmitConfigSchema = z5.object({}).strict();
+
+// ../tracking-core/src/events/multi-page-session.ts
+import { z as z6 } from "zod";
+var multiPageSessionMetadataSchema = z6.object({
+  page_count: z6.number().int().min(2),
+  page: z6.object({
+    path: z6.string()
+  })
+}).strict();
+var multiPageSessionConfigSchema = z6.object({
+  pageThreshold: z6.number().int().min(2)
+}).strict();
+
+// ../tracking-core/src/events/phone-click.ts
+import { z as z7 } from "zod";
+var phoneClickMetadataSchema = z7.object({
+  phone_number: z7.string(),
+  page: z7.object({
+    path: z7.string()
+  }),
+  section: z7.string().nullable().optional()
+}).strict();
+var phoneClickConfigSchema = z7.object({}).strict();
+
+// ../tracking-core/src/events/scroll-depth.ts
+import { z as z8 } from "zod";
+var scrollDepthMetadataSchema = z8.object({
+  depth_percent: z8.number().int().min(1).max(100),
+  page: z8.object({
+    path: z8.string()
+  })
+}).strict();
+var scrollDepthConfigSchema = z8.object({
+  thresholds: z8.array(z8.number().int().min(1).max(100)).min(1)
+}).strict();
+
+// ../tracking-core/src/events/specific-page-visit.ts
+import { z as z9 } from "zod";
+var SPECIFIC_PAGE_NAMES = [
+  "contact_page",
+  "about_page",
+  "services_page",
+  "booking_page",
+  "location_page",
+  "pricing_page",
+  "faq_page",
+  "testimonials_page"
+];
+var specificPageNameSchema = z9.enum(SPECIFIC_PAGE_NAMES);
+var specificPageVisitMetadataSchema = z9.object({
+  page_name: specificPageNameSchema,
+  page: z9.object({
+    path: z9.string()
+  })
+}).strict();
+var specificPageVisitConfigSchema = z9.object({
+  pages: z9.array(
+    z9.object({
+      name: specificPageNameSchema,
+      pathPattern: z9.custom((value) => value instanceof RegExp, {
+        message: "pathPattern must be a RegExp"
+      })
+    })
+  ).min(1)
+}).strict();
+
+// ../tracking-core/src/events/time-on-site.ts
+import { z as z10 } from "zod";
+var timeOnSiteMetadataSchema = z10.object({
+  duration_ms: z10.number().int().nonnegative(),
+  page: z10.object({
+    path: z10.string()
+  })
+}).strict();
+var timeOnSiteConfigSchema = z10.object({
+  thresholdSeconds: z10.number().int().positive()
 }).strict();
 
 // ../tracking-core/src/events/registry.ts
@@ -639,10 +795,31 @@ var EVENT_REGISTRY = {
     metadataSchema: timeOnSiteMetadataSchema,
     configSchema: timeOnSiteConfigSchema
   },
-  contact_page_visit: {
+  specific_page_visit: {
+    kind: "automatic",
+    metadataSchema: specificPageVisitMetadataSchema,
+    configSchema: specificPageVisitConfigSchema
+  },
+  scroll_depth: {
     kind: "automatic",
-    metadataSchema: contactPageVisitMetadataSchema,
-    configSchema: contactPageVisitConfigSchema
+    metadataSchema: scrollDepthMetadataSchema,
+    configSchema: scrollDepthConfigSchema
+  },
+  multi_page_session: {
+    kind: "automatic",
+    metadataSchema: multiPageSessionMetadataSchema,
+    configSchema: multiPageSessionConfigSchema
+  },
+  form_start: {
+    kind: "automatic",
+    metadataSchema: formStartMetadataSchema,
+    configSchema: formStartConfigSchema
+  },
+  // --- SDK-internal automatic (not consumer-configurable) ---
+  sdk_heartbeat: {
+    kind: "automatic",
+    metadataSchema: sdkHeartbeatMetadataSchema,
+    configSchema: sdkHeartbeatConfigSchema
   },
   // --- manual triggers ---
   form_submit: {
@@ -654,6 +831,11 @@ var EVENT_REGISTRY = {
     kind: "manual",
     metadataSchema: phoneClickMetadataSchema,
     configSchema: phoneClickConfigSchema
+  },
+  cta_click: {
+    kind: "manual",
+    metadataSchema: ctaClickMetadataSchema,
+    configSchema: ctaClickConfigSchema
   }
 };
 var ALL_AUTOMATIC_EVENT_NAMES = Object.entries(EVENT_REGISTRY).filter(([, def]) => def.kind === "automatic").map(([name]) => name);
@@ -744,26 +926,193 @@ function attachTimeOnSite(client, config) {
   };
 }
 
-// ../tracking-core/src/triggers/contact-page-visit.ts
-function attachContactPageVisit(client, config) {
+// ../tracking-core/src/triggers/specific-page-visit.ts
+function attachSpecificPageVisit(client, config) {
   if (typeof window === "undefined" || typeof history === "undefined") {
     return () => {
     };
   }
-  const { pathPattern } = config;
-  let lastFiredPath = null;
+  const { pages } = config;
+  const firedSet = /* @__PURE__ */ new Set();
   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
+    for (const { name, pathPattern } of pages) {
+      pathPattern.lastIndex = 0;
+      if (!pathPattern.test(path)) continue;
+      const key = `${name}:${path}`;
+      if (firedSet.has(key)) continue;
+      firedSet.add(key);
+      client.trackEvent({
+        eventType: "specific_page_visit",
+        metadata: { page_name: name, 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);
+  };
+}
+
+// ../tracking-core/src/triggers/scroll-depth.ts
+function attachScrollDepth(client, config) {
+  if (typeof window === "undefined" || typeof document === "undefined") {
+    return () => {
+    };
+  }
+  const thresholds = new Set(config.thresholds);
+  let firedForPath = /* @__PURE__ */ new Set();
+  let currentPath = window.location.pathname;
+  let rafId = null;
+  function getScrollPercent() {
+    const doc = document.documentElement;
+    const scrollTop = window.scrollY || doc.scrollTop;
+    const scrollHeight = doc.scrollHeight;
+    const clientHeight = doc.clientHeight;
+    if (scrollHeight <= clientHeight) return 100;
+    return Math.round((scrollTop + clientHeight) / scrollHeight * 100);
+  }
+  function checkThresholds() {
+    const percent = getScrollPercent();
+    for (const threshold of thresholds) {
+      if (percent >= threshold && !firedForPath.has(threshold)) {
+        firedForPath.add(threshold);
+        client.trackEvent({
+          eventType: "scroll_depth",
+          metadata: {
+            depth_percent: threshold,
+            page: { path: currentPath }
+          },
+          pageUrl: window.location.href,
+          occurredAt: null
+        });
+      }
+    }
+  }
+  function onScroll() {
+    if (rafId !== null) return;
+    rafId = requestAnimationFrame(() => {
+      rafId = null;
+      checkThresholds();
     });
   }
+  function resetIfPathChanged() {
+    const newPath = window.location.pathname;
+    if (newPath === currentPath) return;
+    currentPath = newPath;
+    firedForPath = /* @__PURE__ */ new Set();
+    setTimeout(checkThresholds, 0);
+  }
+  const originalPushState = history.pushState.bind(history);
+  const originalReplaceState = history.replaceState.bind(history);
+  function patchedPushState(...args) {
+    originalPushState(...args);
+    setTimeout(resetIfPathChanged, 0);
+  }
+  function patchedReplaceState(...args) {
+    originalReplaceState(...args);
+    setTimeout(resetIfPathChanged, 0);
+  }
+  history.pushState = patchedPushState;
+  history.replaceState = patchedReplaceState;
+  window.addEventListener("popstate", resetIfPathChanged);
+  window.addEventListener("scroll", onScroll, { passive: true });
+  setTimeout(checkThresholds, 0);
+  return () => {
+    if (rafId !== null) cancelAnimationFrame(rafId);
+    history.pushState = originalPushState;
+    history.replaceState = originalReplaceState;
+    window.removeEventListener("popstate", resetIfPathChanged);
+    window.removeEventListener("scroll", onScroll);
+  };
+}
+
+// ../tracking-core/src/triggers/multi-page-session.ts
+var STORAGE_KEY = "aranova_tracking_mps_paths";
+var SESSION_KEY = "aranova_tracking_mps_session";
+var FIRED_KEY = "aranova_tracking_mps_fired";
+function getSessionStorage() {
+  try {
+    return typeof window !== "undefined" ? window.sessionStorage : null;
+  } catch {
+    return null;
+  }
+}
+function attachMultiPageSession(client, config) {
+  if (typeof window === "undefined" || typeof history === "undefined") {
+    return () => {
+    };
+  }
+  const storage = getSessionStorage();
+  if (!storage) return () => {
+  };
+  const { pageThreshold } = config;
+  let lastCheckedPath = "";
+  function getDistinctPaths() {
+    try {
+      const raw = storage.getItem(STORAGE_KEY);
+      return raw ? new Set(JSON.parse(raw)) : /* @__PURE__ */ new Set();
+    } catch {
+      return /* @__PURE__ */ new Set();
+    }
+  }
+  function saveDistinctPaths(paths) {
+    try {
+      storage.setItem(STORAGE_KEY, JSON.stringify([...paths]));
+    } catch {
+    }
+  }
+  function resetIfSessionChanged() {
+    const currentSession = getOrRotateSessionId().id;
+    const storedSession = storage.getItem(SESSION_KEY);
+    if (storedSession !== currentSession) {
+      storage.setItem(SESSION_KEY, currentSession);
+      storage.removeItem(STORAGE_KEY);
+      storage.removeItem(FIRED_KEY);
+    }
+  }
+  function hasFired() {
+    return storage.getItem(FIRED_KEY) === "1";
+  }
+  function check() {
+    const currentPath = window.location.pathname;
+    if (currentPath === lastCheckedPath) return;
+    lastCheckedPath = currentPath;
+    resetIfSessionChanged();
+    if (hasFired()) return;
+    const paths = getDistinctPaths();
+    paths.add(currentPath);
+    saveDistinctPaths(paths);
+    if (paths.size >= pageThreshold) {
+      storage.setItem(FIRED_KEY, "1");
+      client.trackEvent({
+        eventType: "multi_page_session",
+        metadata: {
+          page_count: paths.size,
+          page: { path: window.location.pathname }
+        },
+        pageUrl: window.location.href,
+        occurredAt: null
+      });
+    }
+  }
   const originalPushState = history.pushState.bind(history);
   const originalReplaceState = history.replaceState.bind(history);
   function patchedPushState(...args) {
@@ -785,6 +1134,71 @@ function attachContactPageVisit(client, config) {
   };
 }
 
+// ../tracking-core/src/triggers/form-start.ts
+function attachFormStart(client, config) {
+  if (typeof window === "undefined" || typeof document === "undefined") {
+    return () => {
+    };
+  }
+  const selector = config.selector ?? "form";
+  let firedForms = /* @__PURE__ */ new Set();
+  let currentPath = window.location.pathname;
+  function getFormKey(form) {
+    if (form.id) return `id:${form.id}`;
+    const explicitAction = form.getAttribute("action");
+    if (explicitAction) return `action:${explicitAction}`;
+    const forms = Array.from(document.querySelectorAll(selector));
+    return `index:${forms.indexOf(form)}`;
+  }
+  function onFocusIn(event) {
+    const target = event.target;
+    if (!(target instanceof HTMLElement)) return;
+    const form = target.closest(selector);
+    if (!form || form.tagName !== "FORM") return;
+    const key = getFormKey(form);
+    if (firedForms.has(key)) return;
+    firedForms.add(key);
+    client.trackEvent({
+      eventType: "form_start",
+      metadata: {
+        form: {
+          id: form.id || "",
+          action: form.getAttribute("action") ?? null
+        },
+        page: { path: window.location.pathname }
+      },
+      pageUrl: window.location.href,
+      occurredAt: null
+    });
+  }
+  function resetIfPathChanged() {
+    const newPath = window.location.pathname;
+    if (newPath === currentPath) return;
+    currentPath = newPath;
+    firedForms = /* @__PURE__ */ new Set();
+  }
+  const originalPushState = history.pushState.bind(history);
+  const originalReplaceState = history.replaceState.bind(history);
+  function patchedPushState(...args) {
+    originalPushState(...args);
+    setTimeout(resetIfPathChanged, 0);
+  }
+  function patchedReplaceState(...args) {
+    originalReplaceState(...args);
+    setTimeout(resetIfPathChanged, 0);
+  }
+  history.pushState = patchedPushState;
+  history.replaceState = patchedReplaceState;
+  window.addEventListener("popstate", resetIfPathChanged);
+  document.addEventListener("focusin", onFocusIn);
+  return () => {
+    history.pushState = originalPushState;
+    history.replaceState = originalReplaceState;
+    window.removeEventListener("popstate", resetIfPathChanged);
+    document.removeEventListener("focusin", onFocusIn);
+  };
+}
+
 // src/ConsentBanner.tsx
 import { jsx, jsxs } from "react/jsx-runtime";
 function ConsentBanner() {
@@ -879,7 +1293,7 @@ import {
 } from "react";
 
 // package.json
-var version = "0.4.2";
+var version = "0.5.1";
 
 // src/factory.tsx
 import { jsx as jsx2 } from "react/jsx-runtime";
@@ -915,6 +1329,7 @@ function createTracking(options) {
           surface: "react",
           packageName: "@aranova/tracking-react",
           sdkVersion: version,
+          triggers,
           debug
         }),
         triggers,
@@ -933,6 +1348,7 @@ function createTracking(options) {
         endpoint,
         surface: "react",
         packageName: "@aranova/tracking-react",
+        triggers,
         debug
       });
       detachers.push(attachAutoPageView(rawClient));
@@ -941,9 +1357,21 @@ function createTracking(options) {
       if (timeOnSite) {
         detachers.push(attachTimeOnSite(rawClient, timeOnSite));
       }
-      const contactPageVisit = triggers.automatic.contact_page_visit;
-      if (contactPageVisit) {
-        detachers.push(attachContactPageVisit(rawClient, contactPageVisit));
+      const specificPageVisit = triggers.automatic.specific_page_visit;
+      if (specificPageVisit) {
+        detachers.push(attachSpecificPageVisit(rawClient, specificPageVisit));
+      }
+      const scrollDepth = triggers.automatic.scroll_depth;
+      if (scrollDepth) {
+        detachers.push(attachScrollDepth(rawClient, scrollDepth));
+      }
+      const multiPageSession = triggers.automatic.multi_page_session;
+      if (multiPageSession) {
+        detachers.push(attachMultiPageSession(rawClient, multiPageSession));
+      }
+      const formStart = triggers.automatic.form_start;
+      if (formStart) {
+        detachers.push(attachFormStart(rawClient, formStart));
       }
       return () => {
         for (let i = detachers.length - 1; i >= 0; i--) {