@aranova/tracking-next 0.2.2 → 0.3.0

package/dist/index.d.mts

@@ -1,8 +1,7 @@
-import { C as ConsentState, T as TrackingInstallSurface, a as TrackingClientContext, b as TrackingParams, c as TrackingEventCreatePayload, d as TrackingSessionUpsertPayload } from './server-BMTa7njW.mjs';
-export { e as TrackingInitConfig, g as getTrackingParamsServer } from './server-BMTa7njW.mjs';
+import { C as ConsentState, T as TrackingInstallSurface, a as TrackingClientContext, b as TrackingParams, c as TrackingEventCreatePayload, d as TrackingSessionUpsertPayload } from './types-CFWz-qi9.mjs';
+export { e as TrackingInitConfig } from './types-CFWz-qi9.mjs';
 import * as react_jsx_runtime from 'react/jsx-runtime';
-export { createTrackingMiddleware } from './middleware.mjs';
-import 'next/server';
+import { ReactNode } from 'react';
 
 type GtagConsentValue = 'granted' | 'denied';
 declare function getConsentState(): ConsentState;
@@ -25,6 +24,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 +33,20 @@ 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 function ConsentBanner(): react_jsx_runtime.JSX.Element | null;
 
 declare function useGclid(): string | null;
@@ -44,4 +58,26 @@ 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 TrackingProviderProps {
+    /** Public tracking API key issued for this business. Required. */
+    apiKey: string;
+    /** Full ingest endpoint base URL, e.g. https://api.aranova.io/tracking. Required. */
+    endpoint: string;
+    /** Disable automatic page_view emission (manual tracking only). */
+    disableAutoPageView?: boolean;
+    /** Optional debug flag — currently a no-op, reserved for verbose logging. */
+    debug?: boolean;
+    children: ReactNode;
+}
+/**
+ * Provider for App Router projects. Uses `usePathname` for SPA route detection
+ * instead of patching `history.pushState`, because Next's router does not
+ * always go through the History API for transitions.
+ *
+ * `gtagId` lives on the existing <GoogleAdsTracking> component — keep them
+ * separate so a client without paid Google Ads can install just this provider.
+ */
+declare function TrackingProvider({ apiKey, endpoint, disableAutoPageView, debug, children, }: TrackingProviderProps): react_jsx_runtime.JSX.Element;
+declare function useTracking(): TrackingClient;
+
+export { ConsentBanner, ConsentState, GoogleAdsTracking, type GoogleAdsTrackingProps, TRACKING_PARAM_KEYS, type TrackingClient, TrackingClientContext, TrackingEventCreatePayload, TrackingInstallSurface, TrackingParams, TrackingProvider, type TrackingProviderProps, TrackingSessionUpsertPayload, captureTrackingParamsFromLocation, createTrackingClientContext, createTrackingEventCreatePayload, createTrackingSessionUpsertPayload, getConsentState, setConsentState, useConsentState, useGclid, useTracking, useTrackingParams };

package/dist/index.d.ts

@@ -1,8 +1,7 @@
-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-CFWz-qi9.js';
+export { e as TrackingInitConfig } from './types-CFWz-qi9.js';
 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 +24,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 +33,20 @@ 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 function ConsentBanner(): react_jsx_runtime.JSX.Element | null;
 
 declare function useGclid(): string | null;
@@ -44,4 +58,26 @@ 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 TrackingProviderProps {
+    /** Public tracking API key issued for this business. Required. */
+    apiKey: string;
+    /** Full ingest endpoint base URL, e.g. https://api.aranova.io/tracking. Required. */
+    endpoint: string;
+    /** Disable automatic page_view emission (manual tracking only). */
+    disableAutoPageView?: boolean;
+    /** Optional debug flag — currently a no-op, reserved for verbose logging. */
+    debug?: boolean;
+    children: ReactNode;
+}
+/**
+ * Provider for App Router projects. Uses `usePathname` for SPA route detection
+ * instead of patching `history.pushState`, because Next's router does not
+ * always go through the History API for transitions.
+ *
+ * `gtagId` lives on the existing <GoogleAdsTracking> component — keep them
+ * separate so a client without paid Google Ads can install just this provider.
+ */
+declare function TrackingProvider({ apiKey, endpoint, disableAutoPageView, debug, children, }: TrackingProviderProps): react_jsx_runtime.JSX.Element;
+declare function useTracking(): TrackingClient;
+
+export { ConsentBanner, ConsentState, GoogleAdsTracking, type GoogleAdsTrackingProps, TRACKING_PARAM_KEYS, type TrackingClient, TrackingClientContext, TrackingEventCreatePayload, TrackingInstallSurface, TrackingParams, TrackingProvider, type TrackingProviderProps, TrackingSessionUpsertPayload, captureTrackingParamsFromLocation, createTrackingClientContext, createTrackingEventCreatePayload, createTrackingSessionUpsertPayload, getConsentState, setConsentState, useConsentState, useGclid, useTracking, useTrackingParams };

package/dist/index.js

@@ -33,16 +33,16 @@ __export(src_exports, {
   ConsentBanner: () => ConsentBanner,
   GoogleAdsTracking: () => GoogleAdsTracking,
   TRACKING_PARAM_KEYS: () => TRACKING_PARAM_KEYS,
+  TrackingProvider: () => TrackingProvider,
   captureTrackingParamsFromLocation: () => captureTrackingParamsFromLocation,
   createTrackingClientContext: () => createTrackingClientContext,
   createTrackingEventCreatePayload: () => createTrackingEventCreatePayload,
-  createTrackingMiddleware: () => createTrackingMiddleware,
   createTrackingSessionUpsertPayload: () => createTrackingSessionUpsertPayload,
   getConsentState: () => getConsentState,
-  getTrackingParamsServer: () => getTrackingParamsServer,
   setConsentState: () => setConsentState,
   useConsentState: () => useConsentState,
   useGclid: () => useGclid,
+  useTracking: () => useTracking,
   useTrackingParams: () => useTrackingParams
 });
 module.exports = __toCommonJS(src_exports);
@@ -89,6 +89,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,
@@ -194,8 +195,8 @@ function getTrackingQueryValues(searchParams) {
 function getCookieValueFromDocument(key) {
   if (typeof document === "undefined")
     return null;
-  const cookies2 = document.cookie ? document.cookie.split("; ") : [];
-  const match = cookies2.find((cookie) => cookie.startsWith(`${key}=`));
+  const cookies = document.cookie ? document.cookie.split("; ") : [];
+  const match = cookies.find((cookie) => cookie.startsWith(`${key}=`));
   if (!match)
     return null;
   const [, rawValue = ""] = match.split("=");
@@ -220,6 +221,248 @@ 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/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 {
+  }
+}
+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;
+      clearScheduledFlush();
+      queue = [];
+      if (typeof window !== "undefined") {
+        window.removeEventListener("pagehide", flushOnUnload);
+      }
+    }
+  };
+}
+
+// ../tracking-core/src/page-view.ts
+function buildPageViewMetadata() {
+  if (typeof window === "undefined" || typeof document === "undefined")
+    return null;
+  return {
+    page: {
+      title: document.title || null,
+      path: window.location.pathname,
+      search: window.location.search,
+      hash: window.location.hash
+    },
+    referrer: document.referrer || null,
+    viewport: { w: window.innerWidth, h: window.innerHeight }
+  };
+}
+function fireManualPageView(client) {
+  const metadata = buildPageViewMetadata();
+  client.trackEvent({
+    eventType: "page_view",
+    pageUrl: typeof window === "undefined" ? null : window.location.href,
+    metadata
+  });
+}
+
 // src/ConsentBanner.tsx
 var import_react = require("react");
 var import_jsx_runtime = require("react/jsx-runtime");
@@ -315,49 +558,72 @@ function GoogleAdsTracking({ gtagId }) {
   ] });
 }
 
-// src/middleware.ts
-var import_server_only = require("server-only");
-var import_server = require("next/server");
-function createTrackingMiddleware() {
-  return (request) => {
-    const response = import_server.NextResponse.next();
-    const trackingValues = getTrackingQueryValues(request.nextUrl.searchParams);
-    Object.entries(trackingValues).forEach(([param, value]) => {
-      response.cookies.set(param, value, {
-        maxAge: 7776e3,
-        path: "/",
-        httpOnly: false
-      });
+// src/TrackingProvider.tsx
+var import_navigation = require("next/navigation");
+var import_react3 = require("react");
+var import_jsx_runtime3 = require("react/jsx-runtime");
+var TrackingContext = (0, import_react3.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 = (0, import_navigation.usePathname)();
+  const searchParams = (0, import_navigation.useSearchParams)();
+  const clientRef = (0, import_react3.useRef)(null);
+  if (clientRef.current === null) {
+    clientRef.current = createTrackingClient({
+      apiKey,
+      endpoint,
+      surface: "next",
+      packageName: "@aranova/tracking-next",
+      debug
     });
-    return response;
-  };
-}
-
-// src/server.ts
-var import_server_only2 = require("server-only");
-var import_headers = require("next/headers");
-function getCookieStore() {
-  return (0, import_headers.cookies)();
+  }
+  (0, import_react3.useEffect)(() => {
+    if (disableAutoPageView)
+      return;
+    const client = clientRef.current;
+    if (client === null)
+      return;
+    fireManualPageView(client);
+  }, [pathname, searchParams, disableAutoPageView]);
+  (0, import_react3.useEffect)(() => {
+    return () => {
+      clientRef.current?.destroy();
+      clientRef.current = null;
+    };
+  }, []);
+  const contextValue = (0, import_react3.useMemo)(() => clientRef.current, []);
+  return /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(TrackingContext.Provider, { value: contextValue, children });
 }
-function getTrackingParamsServer() {
-  const cookieStore = getCookieStore();
-  return getTrackingParamsFromCookieReader((key) => cookieStore.get(key)?.value);
+function useTracking() {
+  const client = (0, import_react3.useContext)(TrackingContext);
+  if (client === null)
+    throw new Error("useTracking must be called inside a <TrackingProvider>");
+  return client;
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ConsentBanner,
   GoogleAdsTracking,
   TRACKING_PARAM_KEYS,
+  TrackingProvider,
   captureTrackingParamsFromLocation,
   createTrackingClientContext,
   createTrackingEventCreatePayload,
-  createTrackingMiddleware,
   createTrackingSessionUpsertPayload,
   getConsentState,
-  getTrackingParamsServer,
   setConsentState,
   useConsentState,
   useGclid,
+  useTracking,
   useTrackingParams
 });
 //# sourceMappingURL=index.js.map