@probat/react 0.4.4 → 0.4.6

package/dist/index.js

@@ -8,56 +8,34 @@ function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
 
 var React3__default = /*#__PURE__*/_interopDefault(React3);
 
-var ProbatContext = React3.createContext(null);
-var DEFAULT_HOST = "https://gushi.onrender.com";
-function ProbatProvider({
-  customerId,
-  host = DEFAULT_HOST,
-  bootstrap,
-  children
-}) {
-  const value = React3.useMemo(
-    () => ({
-      host: host.replace(/\/$/, ""),
-      customerId,
-      bootstrap: bootstrap ?? {}
-    }),
-    [customerId, host, bootstrap]
-  );
-  return /* @__PURE__ */ React3__default.default.createElement(ProbatContext.Provider, { value }, children);
-}
-function useProbatContext() {
-  const ctx = React3.useContext(ProbatContext);
-  if (!ctx) {
-    throw new Error(
-      "useProbatContext must be used within <ProbatProviderClient>. Wrap your app with <ProbatProviderClient>."
-    );
-  }
-  return ctx;
-}
-
-// src/components/ProbatProviderClient.tsx
-function ProbatProviderClient(props) {
-  return React3__default.default.createElement(ProbatProvider, props);
-}
+// src/types/events.ts
+var PROBAT_ENV_DEV = "dev";
+var PROBAT_ENV_PROD = "prod";
 
 // src/utils/environment.ts
 function detectEnvironment() {
   if (typeof window === "undefined") {
-    return "prod";
+    return PROBAT_ENV_PROD;
   }
   const hostname = window.location.hostname;
   if (hostname === "localhost" || hostname === "127.0.0.1" || hostname === "0.0.0.0" || hostname.startsWith("192.168.") || hostname.startsWith("10.") || hostname.startsWith("172.16.") || hostname.startsWith("172.17.") || hostname.startsWith("172.18.") || hostname.startsWith("172.19.") || hostname.startsWith("172.20.") || hostname.startsWith("172.21.") || hostname.startsWith("172.22.") || hostname.startsWith("172.23.") || hostname.startsWith("172.24.") || hostname.startsWith("172.25.") || hostname.startsWith("172.26.") || hostname.startsWith("172.27.") || hostname.startsWith("172.28.") || hostname.startsWith("172.29.") || hostname.startsWith("172.30.") || hostname.startsWith("172.31.")) {
-    return "dev";
+    return PROBAT_ENV_DEV;
   }
-  return "prod";
+  return PROBAT_ENV_PROD;
 }
 
 // src/utils/eventContext.ts
 var DISTINCT_ID_KEY = "probat:distinct_id";
 var SESSION_ID_KEY = "probat:session_id";
+var SESSION_START_AT_KEY = "probat:session_start_at";
+var SESSION_SEQUENCE_KEY = "probat:session_sequence";
+var SESSION_LAST_ACTIVITY_AT_KEY = "probat:session_last_activity_at";
+var SESSION_IDLE_TIMEOUT_MS = 30 * 60 * 1e3;
 var cachedDistinctId = null;
 var cachedSessionId = null;
+var cachedSessionStartAt = null;
+var cachedSessionSequence = 0;
+var cachedLastActivityAt = 0;
 function generateId() {
   if (typeof crypto !== "undefined" && crypto.randomUUID) {
     return crypto.randomUUID();
@@ -70,6 +48,77 @@ function generateId() {
   }
   return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
 }
+function nowMs() {
+  return Date.now();
+}
+function startNewSession(tsMs) {
+  if (typeof window === "undefined") return;
+  const sid = `sess_${generateId()}`;
+  const startedAt = new Date(tsMs).toISOString();
+  cachedSessionId = sid;
+  cachedSessionStartAt = startedAt;
+  cachedSessionSequence = 0;
+  cachedLastActivityAt = tsMs;
+  try {
+    sessionStorage.setItem(SESSION_ID_KEY, sid);
+    sessionStorage.setItem(SESSION_START_AT_KEY, startedAt);
+    sessionStorage.setItem(SESSION_SEQUENCE_KEY, "0");
+    sessionStorage.setItem(SESSION_LAST_ACTIVITY_AT_KEY, String(tsMs));
+  } catch {
+  }
+}
+function hydrateSessionFromStorage(tsMs) {
+  if (typeof window === "undefined") return;
+  if (cachedSessionId && cachedSessionStartAt) {
+    const expiredInMemory = !Number.isFinite(cachedLastActivityAt) || cachedLastActivityAt <= 0 || tsMs - cachedLastActivityAt > SESSION_IDLE_TIMEOUT_MS;
+    if (expiredInMemory) {
+      startNewSession(tsMs);
+    }
+    return;
+  }
+  try {
+    const sid = sessionStorage.getItem(SESSION_ID_KEY);
+    const startedAt = sessionStorage.getItem(SESSION_START_AT_KEY);
+    const sequenceRaw = sessionStorage.getItem(SESSION_SEQUENCE_KEY);
+    const lastActivityRaw = sessionStorage.getItem(SESSION_LAST_ACTIVITY_AT_KEY);
+    const sequence = Number(sequenceRaw || "0");
+    const lastActivity = Number(lastActivityRaw || "0");
+    if (!sid || !startedAt) {
+      startNewSession(tsMs);
+      return;
+    }
+    const expired = !Number.isFinite(lastActivity) || lastActivity <= 0 || tsMs - lastActivity > SESSION_IDLE_TIMEOUT_MS;
+    if (expired) {
+      startNewSession(tsMs);
+      return;
+    }
+    cachedSessionId = sid;
+    cachedSessionStartAt = startedAt;
+    cachedSessionSequence = Number.isFinite(sequence) && sequence >= 0 ? sequence : 0;
+    cachedLastActivityAt = lastActivity > 0 ? lastActivity : tsMs;
+  } catch {
+    startNewSession(tsMs);
+  }
+}
+function ensureSession(tsMs) {
+  if (typeof window === "undefined") return;
+  hydrateSessionFromStorage(tsMs);
+  if (!cachedSessionId || !cachedSessionStartAt) {
+    startNewSession(tsMs);
+  }
+}
+function bumpSequence(tsMs) {
+  if (typeof window === "undefined") return 0;
+  ensureSession(tsMs);
+  cachedSessionSequence += 1;
+  cachedLastActivityAt = tsMs;
+  try {
+    sessionStorage.setItem(SESSION_SEQUENCE_KEY, String(cachedSessionSequence));
+    sessionStorage.setItem(SESSION_LAST_ACTIVITY_AT_KEY, String(tsMs));
+  } catch {
+  }
+  return cachedSessionSequence;
+}
 function getDistinctId() {
   if (cachedDistinctId) return cachedDistinctId;
   if (typeof window === "undefined") return "server";
@@ -90,23 +139,14 @@ function getDistinctId() {
   return id;
 }
 function getSessionId() {
-  if (cachedSessionId) return cachedSessionId;
   if (typeof window === "undefined") return "server";
-  try {
-    const stored = sessionStorage.getItem(SESSION_ID_KEY);
-    if (stored) {
-      cachedSessionId = stored;
-      return stored;
-    }
-  } catch {
-  }
-  const id = `sess_${generateId()}`;
-  cachedSessionId = id;
-  try {
-    sessionStorage.setItem(SESSION_ID_KEY, id);
-  } catch {
-  }
-  return id;
+  ensureSession(nowMs());
+  return cachedSessionId || "server";
+}
+function getSessionStartAt() {
+  if (typeof window === "undefined") return (/* @__PURE__ */ new Date(0)).toISOString();
+  ensureSession(nowMs());
+  return cachedSessionStartAt || (/* @__PURE__ */ new Date(0)).toISOString();
 }
 function getPageKey() {
   if (typeof window === "undefined") return "";
@@ -121,29 +161,152 @@ function getReferrer() {
   return document.referrer;
 }
 function buildEventContext() {
+  const ts = nowMs();
   return {
     distinct_id: getDistinctId(),
     session_id: getSessionId(),
     $page_url: getPageUrl(),
     $pathname: typeof window !== "undefined" ? window.location.pathname : "",
-    $referrer: getReferrer()
+    $referrer: getReferrer(),
+    $session_sequence: bumpSequence(ts),
+    $session_start_at: getSessionStartAt()
   };
 }
 
+// src/utils/eventQueue.ts
+var EventQueue = class {
+  constructor(host, apiKey) {
+    this.queue = [];
+    this.flushTimer = null;
+    this.maxBatchSize = 20;
+    this.flushIntervalMs = 5e3;
+    const normalized = host.replace(/\/$/, "");
+    this.endpointBatch = `${normalized}/experiment/metrics/batch`;
+    this.endpointSingle = `${normalized}/experiment/metrics`;
+    this.apiKey = apiKey;
+  }
+  enqueue(event) {
+    this.queue.push(event);
+    if (this.queue.length >= this.maxBatchSize) {
+      this.flush();
+      return;
+    }
+    if (!this.flushTimer) {
+      this.flushTimer = setTimeout(() => {
+        this.flush();
+      }, this.flushIntervalMs);
+    }
+  }
+  flush(forceBeacon = false) {
+    if (this.flushTimer) {
+      clearTimeout(this.flushTimer);
+      this.flushTimer = null;
+    }
+    if (this.queue.length === 0) return;
+    const batch = this.queue.splice(0, this.maxBatchSize);
+    this.send(batch, forceBeacon);
+    if (this.queue.length > 0) {
+      this.flushTimer = setTimeout(() => {
+        this.flush();
+      }, this.flushIntervalMs);
+    }
+  }
+  send(batch, forceBeacon = false) {
+    const body = { events: batch };
+    const encodedBody = JSON.stringify(body);
+    const headers = { "Content-Type": "application/json" };
+    if (this.apiKey) headers.Authorization = `Bearer ${this.apiKey}`;
+    const canBeacon = typeof navigator !== "undefined" && typeof navigator.sendBeacon === "function" && !this.apiKey && (forceBeacon || typeof document !== "undefined" && document.visibilityState === "hidden");
+    if (canBeacon) {
+      navigator.sendBeacon(this.endpointBatch, encodedBody);
+      return;
+    }
+    try {
+      if (batch.length === 1) {
+        fetch(this.endpointSingle, {
+          method: "POST",
+          headers,
+          credentials: "include",
+          body: JSON.stringify(batch[0]),
+          keepalive: true
+        }).catch(() => {
+        });
+        return;
+      }
+      fetch(this.endpointBatch, {
+        method: "POST",
+        headers,
+        credentials: "include",
+        body: encodedBody,
+        keepalive: true
+      }).catch(() => {
+      });
+    } catch {
+    }
+  }
+};
+var queuesByHost = /* @__PURE__ */ new Map();
+var lifecycleListenersInstalled = false;
+function installLifecycleListeners() {
+  if (lifecycleListenersInstalled || typeof window === "undefined") return;
+  lifecycleListenersInstalled = true;
+  const flushWithBeacon = () => {
+    for (const queue of queuesByHost.values()) {
+      queue.flush(true);
+    }
+  };
+  const flushNormally = () => {
+    for (const queue of queuesByHost.values()) {
+      queue.flush(false);
+    }
+  };
+  window.addEventListener("pagehide", flushWithBeacon);
+  window.addEventListener("beforeunload", flushWithBeacon);
+  document.addEventListener("visibilitychange", () => {
+    if (document.visibilityState === "hidden") {
+      flushWithBeacon();
+    } else {
+      flushNormally();
+    }
+  });
+}
+function queueKey(host, apiKey) {
+  const normalized = host.replace(/\/$/, "");
+  return apiKey ? `${normalized}::${apiKey}` : `${normalized}::__no_key__`;
+}
+function getEventQueue(host, apiKey) {
+  const normalized = host.replace(/\/$/, "");
+  const key = queueKey(normalized, apiKey);
+  let queue = queuesByHost.get(key);
+  if (!queue) {
+    queue = new EventQueue(normalized, apiKey);
+    queuesByHost.set(key, queue);
+  }
+  installLifecycleListeners();
+  return queue;
+}
+function flushEventQueue(host, forceBeacon = false, apiKey) {
+  const queue = queuesByHost.get(queueKey(host, apiKey));
+  if (!queue) return;
+  queue.flush(forceBeacon);
+}
+
 // src/utils/api.ts
 var pendingDecisions = /* @__PURE__ */ new Map();
-async function fetchDecision(host, experimentId, distinctId) {
+async function fetchDecision(host, experimentId, distinctId, apiKey) {
   const existing = pendingDecisions.get(experimentId);
   if (existing) return existing;
   const promise = (async () => {
     try {
       const url = `${host.replace(/\/$/, "")}/experiment/decide`;
+      const headers = {
+        "Content-Type": "application/json",
+        Accept: "application/json"
+      };
+      if (apiKey) headers["Authorization"] = `Bearer ${apiKey}`;
       const res = await fetch(url, {
         method: "POST",
-        headers: {
-          "Content-Type": "application/json",
-          Accept: "application/json"
-        },
+        headers,
         credentials: "include",
         body: JSON.stringify({
           experiment_id: experimentId,
@@ -160,31 +323,35 @@ async function fetchDecision(host, experimentId, distinctId) {
   pendingDecisions.set(experimentId, promise);
   return promise;
 }
-function sendMetric(host, event, properties) {
+function sendMetric(host, event, properties, apiKey) {
   if (typeof window === "undefined") return;
+  const environment = detectEnvironment();
   const ctx = buildEventContext();
   const payload = {
     event,
-    environment: detectEnvironment(),
+    environment,
     properties: {
       ...ctx,
+      environment,
       source: "react-sdk",
       captured_at: (/* @__PURE__ */ new Date()).toISOString(),
       ...properties
     }
   };
-  try {
-    const url = `${host.replace(/\/$/, "")}/experiment/metrics`;
-    fetch(url, {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      credentials: "include",
-      body: JSON.stringify(payload)
-    }).catch(() => {
-    });
-  } catch {
+  const queuePayload = {
+    event: payload.event,
+    environment: payload.environment,
+    properties: payload.properties
+  };
+  const queue = getEventQueue(host, apiKey);
+  queue.enqueue(queuePayload);
+  if (event === "$experiment_exposure" || event === "$experiment_click") {
+    queue.flush(false);
   }
 }
+function flushMetrics(host, forceBeacon = false, apiKey) {
+  flushEventQueue(host, forceBeacon, apiKey);
+}
 function extractClickMeta(target) {
   if (!target || !(target instanceof HTMLElement)) return null;
   const primary = target.closest('[data-probat-click="primary"]');
@@ -204,7 +371,56 @@ function buildMeta(el, isPrimary) {
   return meta;
 }
 
-// src/hooks/useExperiment.ts
+// src/context/ProbatContext.tsx
+var ProbatContext = React3.createContext(null);
+var DEFAULT_HOST = "https://api.probat.app";
+function ProbatProvider({
+  customerId,
+  host = DEFAULT_HOST,
+  apiKey,
+  bootstrap,
+  trackSessionLifecycle = true,
+  children
+}) {
+  const normalizedHost = host.replace(/\/$/, "");
+  React3.useEffect(() => {
+    if (!trackSessionLifecycle) return;
+    if (typeof window === "undefined") return;
+    sendMetric(normalizedHost, "$session_start", {
+      ...customerId ? { distinct_id: customerId } : {}
+    }, apiKey);
+    return () => {
+      sendMetric(normalizedHost, "$session_end", {
+        ...customerId ? { distinct_id: customerId } : {}
+      }, apiKey);
+      flushMetrics(normalizedHost, true, apiKey);
+    };
+  }, [normalizedHost, customerId, trackSessionLifecycle, apiKey]);
+  const value = React3.useMemo(
+    () => ({
+      host: normalizedHost,
+      apiKey,
+      customerId,
+      bootstrap: bootstrap ?? {}
+    }),
+    [customerId, normalizedHost, apiKey, bootstrap]
+  );
+  return /* @__PURE__ */ React3__default.default.createElement(ProbatContext.Provider, { value }, children);
+}
+function useProbatContext() {
+  const ctx = React3.useContext(ProbatContext);
+  if (!ctx) {
+    throw new Error(
+      "useProbatContext must be used within <ProbatProviderClient>. Wrap your app with <ProbatProviderClient>."
+    );
+  }
+  return ctx;
+}
+
+// src/components/ProbatProviderClient.tsx
+function ProbatProviderClient(props) {
+  return React3__default.default.createElement(ProbatProvider, props);
+}
 var ASSIGNMENT_PREFIX = "probat:assignment:";
 function readAssignment(id) {
   if (typeof window === "undefined") return null;
@@ -225,17 +441,33 @@ function writeAssignment(id, variantKey) {
   } catch {
   }
 }
+function readForceParam() {
+  if (typeof window === "undefined") return null;
+  try {
+    return new URLSearchParams(window.location.search).get("__probat_force");
+  } catch {
+    return null;
+  }
+}
 function useExperiment(id, options = {}) {
   const { fallback = "control", debug = false } = options;
-  const { host, bootstrap, customerId } = useProbatContext();
+  const { host, bootstrap, customerId, apiKey } = useProbatContext();
   const [variantKey, setVariantKey] = React3.useState(() => {
+    const forced = readForceParam();
+    if (forced) return forced;
     if (bootstrap[id]) return bootstrap[id];
     return "control";
   });
   const [resolved, setResolved] = React3.useState(() => {
-    return !!bootstrap[id];
+    return !!(readForceParam() || bootstrap[id]);
   });
   React3.useEffect(() => {
+    const forced = readForceParam();
+    if (forced) {
+      setVariantKey(forced);
+      setResolved(true);
+      return;
+    }
     if (bootstrap[id] || readAssignment(id)) {
       const key = bootstrap[id] ?? readAssignment(id) ?? "control";
       setVariantKey(key);
@@ -246,7 +478,7 @@ function useExperiment(id, options = {}) {
     (async () => {
       try {
         const distinctId = customerId ?? getDistinctId();
-        const key = await fetchDecision(host, id, distinctId);
+        const key = await fetchDecision(host, id, distinctId, apiKey);
         if (cancelled) return;
         setVariantKey(key);
         writeAssignment(id, key);
@@ -365,6 +597,7 @@ function useTrack(options) {
   const {
     experimentId,
     componentInstanceId,
+    resolved = true,
     impression: trackImpression = true,
     click: trackClick = true,
     impressionEventName = "$experiment_exposure",
@@ -373,7 +606,7 @@ function useTrack(options) {
   } = options;
   const variantKey = options.variantKey ?? void 0;
   const explicitCustomerId = "customerId" in options ? options.customerId : void 0;
-  const { host, customerId: providerCustomerId } = useProbatContext();
+  const { host, customerId: providerCustomerId, apiKey } = useProbatContext();
   const resolvedCustomerId = explicitCustomerId ?? providerCustomerId;
   const isCustomerMode = !variantKey;
   const autoInstanceId = useStableInstanceId(experimentId);
@@ -398,7 +631,7 @@ function useTrack(options) {
   );
   const dedupeVariant = variantKey ?? resolvedCustomerId ?? "__anon__";
   React3.useEffect(() => {
-    if (!trackImpression) return;
+    if (!trackImpression || !resolved) return;
     impressionSent.current = false;
     const pageKey = getPageKey();
     const dedupeKey = makeDedupeKey(experimentId, dedupeVariant, instanceId, pageKey);
@@ -412,7 +645,7 @@ function useTrack(options) {
       if (!impressionSent.current) {
         impressionSent.current = true;
         markSeen(dedupeKey);
-        sendMetric(host, impressionEventName, eventProps);
+        sendMetric(host, impressionEventName, eventProps, apiKey);
         if (debug) console.log(`[probat] Impression sent (no IO) for "${experimentId}"`);
       }
       return;
@@ -426,7 +659,7 @@ function useTrack(options) {
             if (impressionSent.current) return;
             impressionSent.current = true;
             markSeen(dedupeKey);
-            sendMetric(host, impressionEventName, eventProps);
+            sendMetric(host, impressionEventName, eventProps, apiKey);
             if (debug) console.log(`[probat] Impression sent for "${experimentId}"`);
             observer.disconnect();
           }, 250);
@@ -444,6 +677,7 @@ function useTrack(options) {
     };
   }, [
     trackImpression,
+    resolved,
     experimentId,
     dedupeVariant,
     instanceId,
@@ -454,18 +688,18 @@ function useTrack(options) {
   ]);
   const handleClick = React3.useCallback(
     (e) => {
-      if (!trackClick) return;
+      if (!trackClick || !resolved) return;
       const meta = extractClickMeta(e.target);
       if (!meta) return;
       sendMetric(host, clickEventName, {
         ...eventProps,
         ...meta
-      });
+      }, apiKey);
       if (debug) {
         console.log(`[probat] Click tracked for "${experimentId}"`, meta);
       }
     },
-    [trackClick, host, clickEventName, eventProps, experimentId, debug]
+    [trackClick, resolved, host, clickEventName, eventProps, experimentId, debug]
   );
   React3.useEffect(() => {
     const el = containerRef.current;
@@ -499,7 +733,8 @@ function Experiment({
     experimentId: id,
     variantKey,
     componentInstanceId,
-    impression: resolved ? track?.impression !== false : false,
+    resolved,
+    impression: track?.impression !== false,
     click: track?.primaryClick !== false,
     impressionEventName: track?.impressionEventName,
     clickEventName: track?.clickEventName,
@@ -537,17 +772,42 @@ function Track({ children, ...trackOptions }) {
   );
 }
 function useProbatMetrics() {
-  const { host, customerId } = useProbatContext();
+  const { host, customerId, apiKey } = useProbatContext();
   const capture = React3.useCallback(
     (event, properties = {}) => {
       sendMetric(host, event, {
         ...customerId ? { distinct_id: customerId } : {},
         ...properties
+      }, apiKey);
+    },
+    [host, customerId, apiKey]
+  );
+  const captureGoal = React3.useCallback(
+    (funnelId, funnelStep, properties = {}) => {
+      sendMetric(host, "$goal_reached", {
+        ...customerId ? { distinct_id: customerId } : {},
+        $funnel_id: funnelId,
+        $funnel_step: funnelStep,
+        ...properties
       });
     },
     [host, customerId]
   );
-  return { capture };
+  const captureFeatureInteraction = React3.useCallback(
+    (interactionName, properties = {}) => {
+      sendMetric(host, "$feature_interaction", {
+        ...customerId ? { distinct_id: customerId } : {},
+        interaction_name: interactionName,
+        ...properties
+      });
+    },
+    [host, customerId]
+  );
+  return {
+    capture,
+    captureGoal,
+    captureFeatureInteraction
+  };
 }
 function createExperimentContext(experimentId) {
   const Ctx = React3.createContext(null);
@@ -570,10 +830,13 @@ function createExperimentContext(experimentId) {
 }
 
 exports.Experiment = Experiment;
+exports.PROBAT_ENV_DEV = PROBAT_ENV_DEV;
+exports.PROBAT_ENV_PROD = PROBAT_ENV_PROD;
 exports.ProbatProviderClient = ProbatProviderClient;
 exports.Track = Track;
 exports.createExperimentContext = createExperimentContext;
 exports.fetchDecision = fetchDecision;
+exports.flushMetrics = flushMetrics;
 exports.sendMetric = sendMetric;
 exports.useExperiment = useExperiment;
 exports.useProbatMetrics = useProbatMetrics;