@corbado/observe 1.10.1 → 1.11.0

package/dist/analysis/default-tracker.mjs

@@ -0,0 +1,16 @@
+// src/default-tracker.ts
+var current;
+function setDefaultTracker(tracker) {
+  current = tracker;
+}
+function getDefaultTracker() {
+  return current;
+}
+function isTracker(value) {
+  return !!value && typeof value === "object" && typeof value.track === "function" && typeof value.enqueueLowEvent === "function";
+}
+export {
+  getDefaultTracker,
+  isTracker,
+  setDefaultTracker
+};

package/dist/analysis/index.mjs

@@ -1,8 +1,17 @@
 // src/index.ts
 import { CorbadoTracker } from "./client.mjs";
+import { CorbadoTrackerCore } from "./tracker-core.mjs";
+import { getDefaultTracker, setDefaultTracker } from "./default-tracker.mjs";
 import { SDK_NAME, SDK_VERSION } from "./version.mjs";
 export * from "./types.mjs";
 export * from "./client.mjs";
+export * from "./tracker-core.mjs";
+export * from "./tracker-functions.mjs";
+export * from "./plugins/cookie-storage.mjs";
+export * from "./plugins/cross-origin-session.mjs";
+export * from "./plugins/raw-errors.mjs";
+export * from "./plugins/probes.mjs";
+export * from "./probe-lane.mjs";
 export * from "./transport.mjs";
 export * from "./queue.mjs";
 export * from "./config.mjs";
@@ -41,78 +50,57 @@ import {
   sanitizeRequestOptions,
   sanitizeAssertionResponse
 } from "./utils/webauthn-payloads.mjs";
-var currentTracker;
 function init(options) {
   const tracker = new CorbadoTracker(options);
-  currentTracker = tracker;
+  setDefaultTracker(tracker);
+  return tracker;
+}
+function initCore(options) {
+  const tracker = new CorbadoTrackerCore(options);
+  setDefaultTracker(tracker);
   return tracker;
 }
 function getTracker() {
-  return currentTracker;
+  const tracker = getDefaultTracker();
+  return tracker?.isFullTracker() ? tracker : void 0;
 }
-function resetSession() {
-  return currentTracker?.resetSession();
+function getTrackerCore() {
+  return getDefaultTracker();
 }
 function getSessionId() {
-  return currentTracker?.getSessionId();
-}
-function setUser(user) {
-  currentTracker?.setUser(user);
-}
-function setFlowTags(tags, options) {
-  currentTracker?.setFlowTags(tags, options);
-}
-function setExperiment(key, variant) {
-  currentTracker?.setExperiment(key, variant);
+  return getDefaultTracker()?.getSessionId();
 }
 function setExperiments(assignments) {
-  currentTracker?.setExperiments(assignments);
-}
-function clearExperiment(key) {
-  currentTracker?.clearExperiment(key);
-}
-function clearExperiments() {
-  currentTracker?.clearExperiments();
+  getDefaultTracker()?.setExperiments(assignments);
 }
 function getExperiments() {
-  return currentTracker?.getExperiments() ?? {};
+  return getDefaultTracker()?.getExperiments() ?? {};
 }
 function telemetry(level, message) {
-  currentTracker?.telemetry(level, message);
-}
-function logInfo(message) {
-  currentTracker?.logInfo(message);
-}
-function logError(message) {
-  currentTracker?.logError(message);
+  getDefaultTracker()?.telemetry(level, message);
 }
 async function destroy() {
-  if (!currentTracker) return;
-  await currentTracker.destroy();
-  currentTracker = void 0;
+  const tracker = getDefaultTracker();
+  if (!tracker) return;
+  await tracker.destroy();
+  setDefaultTracker(void 0);
 }
 export {
   READER_EXPOSURES,
   SDK_NAME,
   SDK_VERSION,
-  clearExperiment,
-  clearExperiments,
   destroy,
   detectPasswordManagerExtensions,
   getExperiments,
   getSessionId,
   getTracker,
+  getTrackerCore,
   init,
-  logError,
-  logInfo,
-  resetSession,
+  initCore,
   sanitizeAssertionResponse,
   sanitizeCreationOptions,
   sanitizeCreationResponse,
   sanitizeRequestOptions,
-  setExperiment,
   setExperiments,
-  setFlowTags,
-  setUser,
   telemetry
 };

package/dist/analysis/plugins/cookie-storage.mjs

@@ -0,0 +1,11 @@
+// src/plugins/cookie-storage.ts
+import { CookieStorage } from "../storage/index.mjs";
+function cookieStorage(options = {}) {
+  const cookieDomain = options?.cookieDomain;
+  return {
+    storage: (logger) => ({ engine: new CookieStorage(logger, cookieDomain), source: "cookie" })
+  };
+}
+export {
+  cookieStorage
+};

package/dist/analysis/plugins/cross-origin-session.mjs

@@ -0,0 +1,171 @@
+// src/plugins/cross-origin-session.ts
+import { CrossOriginSession, isValidCrossOriginContext } from "../cross-origin-session.mjs";
+import {
+  SEQ_STORAGE_KEY,
+  SESSION_CONTINUITY_KEY,
+  SESSION_STORAGE_KEY
+} from "../session-keys.mjs";
+function crossOriginSession(config) {
+  const cookieDomain = config && typeof config === "object" ? config.cookieDomain : void 0;
+  return {
+    session: (tracker) => typeof cookieDomain === "string" ? CrossOriginBridge.create(tracker, cookieDomain) : void 0
+  };
+}
+var CrossOriginBridge = class _CrossOriginBridge {
+  constructor(tracker, cookie) {
+    this.tracker = tracker;
+    this.cookie = cookie;
+  }
+  /** The session this load took from the cross-origin cookie, if any (`meta.crossOriginSession`). */
+  adoptedId;
+  /** The bridge when the cookie is usable here; undefined (feature off) otherwise. Never throws. */
+  static create(tracker, cookieDomain) {
+    try {
+      if (tracker["isTrackingBlocked"]()) {
+        return void 0;
+      }
+      const cookie = CrossOriginSession.create({
+        projectId: tracker["options"].projectId,
+        cookieDomain,
+        logger: tracker.getLogger(),
+        inactivityMs: () => tracker["config"].sessionInactivityMs,
+        report: (level, message) => tracker["reportTelemetry"](level, message)
+      });
+      return cookie ? new _CrossOriginBridge(tracker, cookie) : void 0;
+    } catch (error) {
+      tracker.getLogger().error("Failed to set up the cross-origin session", error);
+      return void 0;
+    }
+  }
+  resolve() {
+    const tracker = this.tracker;
+    const localActivity = this.readLocalSessionActivity();
+    tracker["sessionId"] = tracker["resolveSessionId"]();
+    this.boot(localActivity);
+    return tracker["sessionId"];
+  }
+  claim(sessionId, seq, now) {
+    return this.cookie.claim(sessionId, seq, now);
+  }
+  /** `meta.crossOriginSession` of a batch of `sessionId`; undefined while the cookie is off on this page. */
+  meta(sessionId) {
+    if (!this.cookie.isEnabled()) {
+      return void 0;
+    }
+    return sessionId && sessionId === this.adoptedId ? "adopted" : "own";
+  }
+  reset(sessionId) {
+    this.cookie.reset(sessionId);
+  }
+  stop() {
+    this.cookie.stop();
+  }
+  /** The seq the tracker continues from (persisted counter under continuity). */
+  localSeq() {
+    const tracker = this.tracker;
+    return tracker["config"].sessionContinuity ? Math.max(tracker["seq"], tracker["persistentStorage"].getItem(SEQ_STORAGE_KEY) ?? 0) : tracker["seq"];
+  }
+  /**
+   * Last activity of the local session records BEFORE this load rewrites them (both paths, by id), so the
+   * cross-origin boot can tell a session that was active here from one this load just created.
+   */
+  readLocalSessionActivity() {
+    const tracker = this.tracker;
+    const activity = /* @__PURE__ */ new Map();
+    try {
+      const continuity = tracker["persistentStorage"].getItem(SESSION_CONTINUITY_KEY);
+      if (continuity?.id && typeof continuity.lastActiveAt === "number") {
+        activity.set(continuity.id, continuity.lastActiveAt);
+      }
+      const perTab = tracker["sessionStorage"].getItem(SESSION_STORAGE_KEY);
+      if (perTab && typeof perTab === "object" && perTab.id && typeof perTab.lastActiveAt === "number") {
+        activity.set(perTab.id, Math.max(activity.get(perTab.id) ?? 0, perTab.lastActiveAt));
+      }
+    } catch (error) {
+      tracker.getLogger().error("Failed to read local session activity", error);
+    }
+    return activity;
+  }
+  /**
+   * Reconcile the session this load resolved locally with the cross-origin cookie before the first event:
+   * adopt the cookie's session (and persist it locally, so reloads and same-origin tabs follow) or keep
+   * the local one, and continue the seq at or above the cookie's mark. Never throws.
+   */
+  boot(localActivity) {
+    const tracker = this.tracker;
+    try {
+      this.adoptedId = void 0;
+      const now = Date.now();
+      const continuity = tracker["config"].sessionContinuity;
+      const sessionId = tracker["sessionId"];
+      const result = this.cookie.boot(
+        {
+          sessionId,
+          lastActiveAt: sessionId && localActivity.get(sessionId) || 0,
+          seq: this.localSeq()
+        },
+        now
+      );
+      if (!result || !result.sessionId) {
+        return;
+      }
+      if (result.adopted) {
+        tracker["sessionId"] = result.sessionId;
+        this.adoptedId = result.sessionId;
+        if (continuity) {
+          tracker["persistContinuitySession"](result.sessionId, now);
+        } else {
+          tracker["persistPerTabSession"](result.sessionId, now);
+        }
+        tracker.getLogger().debug("Adopted cross-origin session id", result.sessionId);
+      }
+      tracker["seq"] = result.seq;
+      if (continuity) {
+        tracker["persistentStorage"].setItem(SEQ_STORAGE_KEY, result.seq);
+      }
+    } catch (error) {
+      tracker.getLogger().error("Failed to apply the cross-origin session", error);
+    }
+  }
+};
+function setCrossOriginContext(tracker, context) {
+  try {
+    const bridge = tracker["bridge"];
+    if (!(bridge instanceof CrossOriginBridge)) {
+      return false;
+    }
+    const value = context === null || context === void 0 || context === "" ? void 0 : context;
+    if (value !== void 0 && !isValidCrossOriginContext(value)) {
+      tracker.getLogger().debug("Ignoring invalid cross-origin context (expected <= 128 chars of [A-Za-z0-9._~-])");
+      return false;
+    }
+    const next = bridge.cookie.setContext(tracker["sessionId"], bridge.localSeq(), value);
+    if (next === void 0) {
+      return false;
+    }
+    if (next > tracker["seq"]) {
+      tracker["seq"] = next;
+      if (tracker["config"].sessionContinuity) {
+        tracker["persistentStorage"].setItem(SEQ_STORAGE_KEY, next);
+      }
+    }
+    return true;
+  } catch (error) {
+    tracker.getLogger().error("Failed to set the cross-origin context", error);
+    return false;
+  }
+}
+function getCrossOriginContext(tracker) {
+  try {
+    const bridge = tracker["bridge"];
+    return bridge instanceof CrossOriginBridge ? bridge.cookie.getContext(tracker["sessionId"]) : void 0;
+  } catch (error) {
+    tracker.getLogger().error("Failed to read the cross-origin context", error);
+    return void 0;
+  }
+}
+export {
+  crossOriginSession,
+  getCrossOriginContext,
+  setCrossOriginContext
+};

package/dist/analysis/plugins/probes.mjs

@@ -0,0 +1,69 @@
+// src/plugins/probes.ts
+import { v7 as uuidv7 } from "uuid";
+import { installProbeLane } from "../probe-lane.mjs";
+var PROBE_KIND_RE = /^[a-z][a-z0-9_-]{0,31}$/;
+var PROBE_ID_RE = /^[A-Za-z0-9_-]{1,16}$/;
+var PROBE_CTX_MAX = 64;
+function probes() {
+  return {
+    setup: (tracker) => {
+      installProbeLane(tracker["queue"]);
+    }
+  };
+}
+function probe(tracker, input) {
+  const logger = tracker.getLogger();
+  try {
+    if (tracker["isTrackingBlocked"]()) {
+      logger.debug("Skipping probe for blocked user agent.");
+      return;
+    }
+    const queue = tracker["queue"];
+    const lane = queue["lane"];
+    if (!lane) {
+      logger.debug("Dropping probe: no probes() plugin.");
+      return;
+    }
+    if (!input || typeof input !== "object" || typeof input.kind !== "string" || !PROBE_KIND_RE.test(input.kind)) {
+      logger.debug("Dropping probe with an invalid kind.");
+      return;
+    }
+    const payload = input.payload;
+    if (!payload || typeof payload !== "object") {
+      logger.debug(`Dropping probe "${input.kind}" without an object payload.`);
+      return;
+    }
+    const pageId = typeof input.pageId === "string" && PROBE_ID_RE.test(input.pageId) ? input.pageId : lane.defaultPageId();
+    const entry = {
+      id: uuidv7(),
+      kind: input.kind,
+      ts: typeof input.ts === "number" && Number.isFinite(input.ts) ? Math.round(input.ts) : Date.now(),
+      pageId,
+      seq: lane.nextSeq(pageId),
+      payload
+    };
+    if (typeof input.cfg === "string" && PROBE_ID_RE.test(input.cfg)) {
+      entry.cfg = input.cfg;
+    }
+    const ctx = sanitizeProbeContext(input.ctx);
+    if (ctx) {
+      entry.ctx = ctx;
+    }
+    queue.enqueueProbe(entry);
+  } catch (error) {
+    logger.error("Failed to process probe before enqueue", error);
+  }
+}
+function sanitizeProbeContext(ctx) {
+  if (!ctx || typeof ctx !== "object") return void 0;
+  const out = {};
+  for (const key of ["state", "flowType", "step"]) {
+    const value = ctx[key];
+    if (typeof value === "string" && value.length > 0) out[key] = value.slice(0, PROBE_CTX_MAX);
+  }
+  return Object.keys(out).length > 0 ? out : void 0;
+}
+export {
+  probe,
+  probes
+};

package/dist/analysis/plugins/raw-errors.mjs

@@ -0,0 +1,8 @@
+// src/plugins/raw-errors.ts
+import { serializeRawError } from "../utils/serialize-raw-error.mjs";
+function rawErrors() {
+  return { rawErrors: serializeRawError };
+}
+export {
+  rawErrors
+};

package/dist/analysis/probe-lane.mjs

@@ -0,0 +1,175 @@
+// src/probe-lane.ts
+import { utf8Length } from "./queue.mjs";
+var PROBE_QUEUE_MAX_ITEMS = 500;
+var PROBE_QUEUE_MAX_BYTES = 512 * 1024;
+var PROBE_BATCH_MAX_ITEMS = 200;
+var PROBE_BATCH_MAX_BYTES = 200 * 1024;
+var PROBE_PAYLOAD_MAX_BYTES = 16 * 1024;
+var UNLOAD_PROBE_MAX_BYTES = 32e3;
+function installProbeLane(queue) {
+  const existing = queue["lane"];
+  if (existing) return existing;
+  const lane = new ProbeLane(queue);
+  queue["lane"] = lane;
+  queue.enqueueProbe = (entry, capturedSessionId = queue["sessionId"]) => {
+    try {
+      if (!queue["destroyed"]) lane.enqueue(entry, capturedSessionId);
+    } catch (error) {
+      queue["logger"].error("Failed to enqueue probe", error);
+    }
+  };
+  queue.droppedProbeCount = () => lane.dropped;
+  return lane;
+}
+var PROBE_PAGE_IDS_MAX = 32;
+var ProbeLane = class {
+  constructor(queue) {
+    this.queue = queue;
+  }
+  /** Queued items, oldest first; read by the queue's flush paths. */
+  items = [];
+  bytes = 0;
+  /** Probe items dropped on this load (caps, permanent rejection, exhausted retries, unload budget). */
+  dropped = 0;
+  /** Default probe page id (one per tracker instance) and the probe seq counter per page id. */
+  pageId;
+  seqs = /* @__PURE__ */ new Map();
+  /**
+   * Queue a probe item. The payload is snapshotted (serialized once) so later host mutations cannot
+   * change it; items over {@link PROBE_PAYLOAD_MAX_BYTES} are dropped, and the oldest items are dropped
+   * beyond the queue caps. Arms the normal flush timer. Throws on unexpected errors (the queue logs).
+   */
+  enqueue(entry, capturedSessionId) {
+    const payloadJson = JSON.stringify(entry.payload);
+    if (typeof payloadJson !== "string" || utf8Length(payloadJson) > PROBE_PAYLOAD_MAX_BYTES) {
+      this.dropped++;
+      return;
+    }
+    const snapshot = { ...entry, payload: JSON.parse(payloadJson) };
+    const bytes = utf8Length(JSON.stringify(snapshot));
+    this.items.push({ sessionId: capturedSessionId, entry: snapshot, bytes, attempts: 0, flushAfter: 0 });
+    this.bytes += bytes;
+    while (this.items.length > PROBE_QUEUE_MAX_ITEMS || this.bytes > PROBE_QUEUE_MAX_BYTES && this.items.length > 1) {
+      const dropped = this.items.shift();
+      this.bytes -= dropped.bytes;
+      this.dropped++;
+    }
+    this.queue["scheduleFlush"](this.queue["flushInterval"](), "timer");
+  }
+  /** The probe part of one regular batch of `sessionId`. */
+  selectBatch(candidates, sessionId) {
+    return this.select(candidates, sessionId, PROBE_BATCH_MAX_ITEMS, PROBE_BATCH_MAX_BYTES);
+  }
+  /** Oldest-first selection for one session, within an item and byte cap (at least one item when any fits the item cap). */
+  select(candidates, sessionId, maxItems, maxBytes) {
+    const selected = [];
+    let bytes = 0;
+    for (const item of candidates) {
+      if (selected.length >= maxItems) break;
+      if (item.sessionId !== sessionId) continue;
+      if (bytes + item.bytes > maxBytes) {
+        if (selected.length === 0 && maxBytes >= PROBE_BATCH_MAX_BYTES) selected.push(item);
+        break;
+      }
+      bytes += item.bytes;
+      selected.push(item);
+    }
+    return selected;
+  }
+  remove(items) {
+    if (items.length === 0) return;
+    const removed = new Set(items);
+    this.items = this.items.filter((item) => !removed.has(item));
+    for (const item of items) this.bytes -= item.bytes;
+  }
+  /** Drop `items` (all of them: `drop(lane.items.slice())`), counting them as dropped. */
+  drop(items) {
+    this.remove(items);
+    this.dropped += items.length;
+  }
+  /** Same policy as events: 2xx delivered, non-retryable dropped, retryable backed off up to `config.retry.maxAttempts`. */
+  handleResult(response, items, now) {
+    if (items.length === 0) return;
+    const queue = this.queue;
+    const status = response.statusCode;
+    if (typeof status === "number" && status >= 200 && status < 300) {
+      this.remove(items);
+      return;
+    }
+    if (!queue["isRetryable"](status)) {
+      this.drop(items);
+      return;
+    }
+    const maxAttempts = Math.max(1, queue["config"].retry.maxAttempts);
+    const retryAfterMs = queue["parseRetryAfter"](response);
+    const exhausted = [];
+    for (const item of items) {
+      item.attempts += 1;
+      if (item.attempts >= maxAttempts) exhausted.push(item);
+      else item.flushAfter = now + queue["backoffForAttempt"](item.attempts, retryAfterMs);
+    }
+    this.drop(exhausted);
+  }
+  /**
+   * Unload / final teardown: one probe-only request for the current session within `budget` bytes,
+   * sent after the event request so the events' delivery is unaffected. Leftovers are dropped when
+   * `dropRest` (pagehide, destroy); otherwise they stay queued.
+   */
+  sendUnload(budget, reason, dropRest, useBeacon) {
+    const queue = this.queue;
+    const sessionId = queue["sessionId"];
+    const envelope = { sessionId, events: [], sdk: queue["sdk"], probes: [] };
+    queue["attachBatchMeta"](envelope, [], reason);
+    const overhead = utf8Length(JSON.stringify(envelope)) + 120;
+    const items = budget > overhead ? this.select(this.items, sessionId, PROBE_BATCH_MAX_ITEMS, budget - overhead) : [];
+    if (items.length > 0) {
+      envelope.probes = items.map((item) => item.entry);
+      queue["attachBatchMeta"](envelope, items, reason);
+      const transport = queue["transport"];
+      if (useBeacon && queue["config"].beaconKeepalive && transport.sendBeacon) {
+        transport.sendBeacon(envelope);
+      } else {
+        void Promise.resolve(transport.send(envelope)).catch(() => void 0);
+      }
+      this.remove(items);
+    }
+    if (dropRest) this.drop(this.items.slice());
+  }
+  /** Default page id of probe items without one: one random id per lane (= per tracker instance). */
+  defaultPageId() {
+    return this.pageId ??= randomProbePageId();
+  }
+  /** Next probe seq of `pageId` (per-page counters, the oldest forgotten beyond {@link PROBE_PAGE_IDS_MAX}). */
+  nextSeq(pageId) {
+    const seq = this.seqs.get(pageId) ?? 0;
+    this.seqs.delete(pageId);
+    this.seqs.set(pageId, seq + 1);
+    if (this.seqs.size > PROBE_PAGE_IDS_MAX) {
+      const oldest = this.seqs.keys().next().value;
+      if (oldest !== void 0) this.seqs.delete(oldest);
+    }
+    return seq;
+  }
+};
+var PROBE_PAGE_ID_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789_-";
+function randomProbePageId() {
+  const bytes = new Uint8Array(16);
+  try {
+    crypto.getRandomValues(bytes);
+  } catch {
+    for (let i = 0; i < bytes.length; i++) bytes[i] = Math.floor(Math.random() * 256);
+  }
+  let out = "";
+  for (let i = 0; i < bytes.length; i++) out += PROBE_PAGE_ID_ALPHABET[bytes[i] & 63];
+  return out;
+}
+export {
+  PROBE_BATCH_MAX_BYTES,
+  PROBE_BATCH_MAX_ITEMS,
+  PROBE_PAYLOAD_MAX_BYTES,
+  PROBE_QUEUE_MAX_BYTES,
+  PROBE_QUEUE_MAX_ITEMS,
+  ProbeLane,
+  UNLOAD_PROBE_MAX_BYTES,
+  installProbeLane
+};