@ianmenethil/zp-observer 6.0.0 → 6.1.0

package/dist/client/create-telemetry-client.cjs

@@ -0,0 +1,136 @@
+const {createDiagnosticsBuffer} = require('../diagnostics/diagnostics-buffer.cjs');
+const {createEnvelopeBuilder} = require('../events/envelope.cjs');
+const {createEventPipeline} = require('../runtime/event-pipeline.cjs');
+const {createHeartbeatScheduler} = require('../runtime/heartbeat-scheduler.cjs');
+const {createSessionManager} = require('../runtime/session-manager.cjs');
+const {localStorageOutbox} = require('../persistence/local-storage-outbox.cjs');
+const {memoryOutbox} = require('../persistence/memory-outbox.cjs');
+const {readDefaultContext} = require('../utils/safe-globals.cjs');
+const DEFAULT_PERSISTENCE_POLICY = {
+  shouldPersist(kind) {
+    return [
+      "session.started",
+      "session.stopped",
+      "checkout.session_init",
+      "checkout.modal_opened",
+      "checkout.modal_closed",
+      "merchant.outcome_reported"
+    ].includes(kind);
+  }
+};
+function createTelemetryClient(options) {
+  if (!options?.session?.sessionId) {
+    throw new Error("createTelemetryClient requires session.sessionId");
+  }
+  if (!options.transport) {
+    throw new Error("createTelemetryClient requires a transport");
+  }
+  const now = options.now ?? Date.now;
+  const session = createSessionManager({
+    sessionId: options.session.sessionId,
+    correlationId: options.session.correlationId,
+    now
+  });
+  const diagnostics = createDiagnosticsBuffer();
+  const buildEnvelope = createEnvelopeBuilder({
+    session,
+    now,
+    context: () => ({
+      ...readDefaultContext(),
+      ...options.context ?? {}
+    })
+  });
+  let delivery = {
+    attempted: 0,
+    succeeded: 0,
+    failed: 0
+  };
+  const outbox = options.outbox ?? (options.persistence === "memory" ? memoryOutbox() : options.persistence === "localStorage" ? localStorageOutbox() : undefined);
+  const pipeline = createEventPipeline({
+    transport: options.transport,
+    outbox,
+    persistencePolicy: options.persistencePolicy ?? DEFAULT_PERSISTENCE_POLICY,
+    middleware: options.middleware ?? [],
+    diagnostics
+  });
+  let heartbeat = null;
+  async function dispatch(kind, payload, updateDelivery = true) {
+    const envelope = buildEnvelope(kind, payload);
+    if (updateDelivery) {
+      delivery.attempted += 1;
+    }
+    const result = await pipeline.dispatch(envelope);
+    if (updateDelivery) {
+      if (result.ok) {
+        delivery.succeeded += 1;
+      } else {
+        delivery.failed += 1;
+      }
+    }
+    return result;
+  }
+  return {
+    sessionId: session.sessionId,
+    correlationId: session.correlationId,
+    start() {
+      if (session.snapshot().state !== "idle") {
+        return;
+      }
+      session.transition("starting");
+      session.transition("active");
+      if (options.heartbeat && heartbeat === null) {
+        heartbeat = createHeartbeatScheduler({
+          intervalMs: options.heartbeat.intervalMs,
+          missThreshold: options.heartbeat.missThreshold,
+          sendHeartbeat: (missedBeats) => dispatch("transport.heartbeat", { missedBeats }, false),
+          onMissThreshold(missedBeats) {
+            diagnostics.add({
+              level: "warn",
+              message: "Heartbeat miss threshold reached.",
+              timestamp: now(),
+              details: { missedBeats }
+            });
+            const state = session.snapshot().state;
+            if (state === "active" || state === "backgrounded" || state === "degraded") {
+              session.transition("abandoned");
+            }
+          }
+        });
+      }
+      dispatch("session.started", {});
+    },
+    stop(reason = "manual_stop") {
+      const current = session.snapshot().state;
+      if (current === "closed") {
+        return;
+      }
+      heartbeat?.stop();
+      heartbeat = null;
+      session.transition("closing");
+      dispatch("session.stopped", { reason }).finally(() => {
+        session.transition("closed");
+      });
+    },
+    emit(kind, payload) {
+      return dispatch(kind, payload);
+    },
+    flush() {
+      return pipeline.flush();
+    },
+    getState() {
+      return session.snapshot();
+    },
+    diagnostics: {
+      snapshot() {
+        const state = session.snapshot();
+        return diagnostics.snapshot(pipeline.queueDepth(), delivery, {
+          state: state.state,
+          sessionId: state.sessionId,
+          correlationId: state.correlationId
+        });
+      }
+    }
+  };
+}
+
+exports.createTelemetryClient = createTelemetryClient;

package/dist/client/create-telemetry-client.js

@@ -0,0 +1,134 @@
+import { createDiagnosticsBuffer } from "../diagnostics/diagnostics-buffer.js";
+import { createEnvelopeBuilder } from "../events/envelope.js";
+import { createEventPipeline } from "../runtime/event-pipeline.js";
+import { createHeartbeatScheduler } from "../runtime/heartbeat-scheduler.js";
+import { createSessionManager } from "../runtime/session-manager.js";
+import { localStorageOutbox } from "../persistence/local-storage-outbox.js";
+import { memoryOutbox } from "../persistence/memory-outbox.js";
+import { readDefaultContext } from "../utils/safe-globals.js";
+const DEFAULT_PERSISTENCE_POLICY = {
+  shouldPersist(kind) {
+    return [
+      "session.started",
+      "session.stopped",
+      "checkout.session_init",
+      "checkout.modal_opened",
+      "checkout.modal_closed",
+      "merchant.outcome_reported"
+    ].includes(kind);
+  }
+};
+export function createTelemetryClient(options) {
+  if (!options?.session?.sessionId) {
+    throw new Error("createTelemetryClient requires session.sessionId");
+  }
+  if (!options.transport) {
+    throw new Error("createTelemetryClient requires a transport");
+  }
+  const now = options.now ?? Date.now;
+  const session = createSessionManager({
+    sessionId: options.session.sessionId,
+    correlationId: options.session.correlationId,
+    now
+  });
+  const diagnostics = createDiagnosticsBuffer();
+  const buildEnvelope = createEnvelopeBuilder({
+    session,
+    now,
+    context: () => ({
+      ...readDefaultContext(),
+      ...options.context ?? {}
+    })
+  });
+  let delivery = {
+    attempted: 0,
+    succeeded: 0,
+    failed: 0
+  };
+  const outbox = options.outbox ?? (options.persistence === "memory" ? memoryOutbox() : options.persistence === "localStorage" ? localStorageOutbox() : undefined);
+  const pipeline = createEventPipeline({
+    transport: options.transport,
+    outbox,
+    persistencePolicy: options.persistencePolicy ?? DEFAULT_PERSISTENCE_POLICY,
+    middleware: options.middleware ?? [],
+    diagnostics
+  });
+  let heartbeat = null;
+  async function dispatch(kind, payload, updateDelivery = true) {
+    const envelope = buildEnvelope(kind, payload);
+    if (updateDelivery) {
+      delivery.attempted += 1;
+    }
+    const result = await pipeline.dispatch(envelope);
+    if (updateDelivery) {
+      if (result.ok) {
+        delivery.succeeded += 1;
+      } else {
+        delivery.failed += 1;
+      }
+    }
+    return result;
+  }
+  return {
+    sessionId: session.sessionId,
+    correlationId: session.correlationId,
+    start() {
+      if (session.snapshot().state !== "idle") {
+        return;
+      }
+      session.transition("starting");
+      session.transition("active");
+      if (options.heartbeat && heartbeat === null) {
+        heartbeat = createHeartbeatScheduler({
+          intervalMs: options.heartbeat.intervalMs,
+          missThreshold: options.heartbeat.missThreshold,
+          sendHeartbeat: (missedBeats) => dispatch("transport.heartbeat", { missedBeats }, false),
+          onMissThreshold(missedBeats) {
+            diagnostics.add({
+              level: "warn",
+              message: "Heartbeat miss threshold reached.",
+              timestamp: now(),
+              details: { missedBeats }
+            });
+            const state = session.snapshot().state;
+            if (state === "active" || state === "backgrounded" || state === "degraded") {
+              session.transition("abandoned");
+            }
+          }
+        });
+      }
+      dispatch("session.started", {});
+    },
+    stop(reason = "manual_stop") {
+      const current = session.snapshot().state;
+      if (current === "closed") {
+        return;
+      }
+      heartbeat?.stop();
+      heartbeat = null;
+      session.transition("closing");
+      dispatch("session.stopped", { reason }).finally(() => {
+        session.transition("closed");
+      });
+    },
+    emit(kind, payload) {
+      return dispatch(kind, payload);
+    },
+    flush() {
+      return pipeline.flush();
+    },
+    getState() {
+      return session.snapshot();
+    },
+    diagnostics: {
+      snapshot() {
+        const state = session.snapshot();
+        return diagnostics.snapshot(pipeline.queueDepth(), delivery, {
+          state: state.state,
+          sessionId: state.sessionId,
+          correlationId: state.correlationId
+        });
+      }
+    }
+  };
+}

package/dist/client/state-machine.cjs

@@ -0,0 +1,20 @@
+const ALLOWED_TRANSITIONS = {
+  idle: ["starting"],
+  starting: ["active", "degraded", "closed"],
+  active: ["backgrounded", "degraded", "closing", "abandoned"],
+  backgrounded: ["active", "degraded", "closing", "abandoned"],
+  degraded: ["active", "backgrounded", "closing", "abandoned"],
+  closing: ["closed"],
+  closed: [],
+  abandoned: ["closing", "closed"]
+};
+function assertTransition(current, next) {
+  if (current === next) {
+    return;
+  }
+  if (!ALLOWED_TRANSITIONS[current].includes(next)) {
+    throw new Error(`Invalid telemetry state transition: ${current} -> ${next}`);
+  }
+}
+
+exports.assertTransition = assertTransition;

package/dist/client/state-machine.js

@@ -0,0 +1,18 @@
+const ALLOWED_TRANSITIONS = {
+  idle: ["starting"],
+  starting: ["active", "degraded", "closed"],
+  active: ["backgrounded", "degraded", "closing", "abandoned"],
+  backgrounded: ["active", "degraded", "closing", "abandoned"],
+  degraded: ["active", "backgrounded", "closing", "abandoned"],
+  closing: ["closed"],
+  closed: [],
+  abandoned: ["closing", "closed"]
+};
+export function assertTransition(current, next) {
+  if (current === next) {
+    return;
+  }
+  if (!ALLOWED_TRANSITIONS[current].includes(next)) {
+    throw new Error(`Invalid telemetry state transition: ${current} -> ${next}`);
+  }
+}

package/dist/diagnostics/diagnostics-buffer.cjs

@@ -0,0 +1,34 @@
+function createDiagnosticsBuffer(options = {}) {
+  const entriesMax = options.entriesMax ?? 100;
+  const envelopesMax = options.envelopesMax ?? 50;
+  const entries = [];
+  const envelopes = [];
+  function trim(items, max) {
+    while (items.length > max) {
+      items.shift();
+    }
+  }
+  return {
+    add(entry) {
+      entries.push(entry);
+      trim(entries, entriesMax);
+    },
+    recordEnvelope(envelope) {
+      envelopes.push(envelope);
+      trim(envelopes, envelopesMax);
+    },
+    snapshot(queueDepth, delivery, state) {
+      return {
+        state: state.state,
+        sessionId: state.sessionId,
+        correlationId: state.correlationId,
+        queueDepth,
+        delivery,
+        recentEnvelopes: envelopes.slice(),
+        entries: entries.slice()
+      };
+    }
+  };
+}
+
+exports.createDiagnosticsBuffer = createDiagnosticsBuffer;

package/dist/diagnostics/diagnostics-buffer.js

@@ -0,0 +1,32 @@
+export function createDiagnosticsBuffer(options = {}) {
+  const entriesMax = options.entriesMax ?? 100;
+  const envelopesMax = options.envelopesMax ?? 50;
+  const entries = [];
+  const envelopes = [];
+  function trim(items, max) {
+    while (items.length > max) {
+      items.shift();
+    }
+  }
+  return {
+    add(entry) {
+      entries.push(entry);
+      trim(entries, entriesMax);
+    },
+    recordEnvelope(envelope) {
+      envelopes.push(envelope);
+      trim(envelopes, envelopesMax);
+    },
+    snapshot(queueDepth, delivery, state) {
+      return {
+        state: state.state,
+        sessionId: state.sessionId,
+        correlationId: state.correlationId,
+        queueDepth,
+        delivery,
+        recentEnvelopes: envelopes.slice(),
+        entries: entries.slice()
+      };
+    }
+  };
+}

package/dist/diagnostics/preflight.cjs

@@ -0,0 +1,36 @@
+async function preflight(options) {
+  const now = options.now ?? Date.now;
+  const startedAt = now();
+  try {
+    const result = await options.transport.send({
+      schemaVersion: 1,
+      libraryVersion: "preflight",
+      eventId: "evt_preflight",
+      sequence: 1,
+      kind: "diagnostic.preflight",
+      sessionId: "__preflight__",
+      correlationId: "__preflight__",
+      timestamp: startedAt,
+      source: "browser",
+      payload: {
+        ok: true,
+        latencyMs: 0
+      },
+      context: {}
+    });
+    return {
+      ok: result.ok,
+      status: result.status,
+      latencyMs: now() - startedAt,
+      networkError: result.ok ? null : result.error ?? null
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      latencyMs: now() - startedAt,
+      networkError: error instanceof Error ? error.message : String(error)
+    };
+  }
+}
+
+exports.preflight = preflight;

package/dist/diagnostics/preflight.js

@@ -0,0 +1,34 @@
+export async function preflight(options) {
+  const now = options.now ?? Date.now;
+  const startedAt = now();
+  try {
+    const result = await options.transport.send({
+      schemaVersion: 1,
+      libraryVersion: "preflight",
+      eventId: "evt_preflight",
+      sequence: 1,
+      kind: "diagnostic.preflight",
+      sessionId: "__preflight__",
+      correlationId: "__preflight__",
+      timestamp: startedAt,
+      source: "browser",
+      payload: {
+        ok: true,
+        latencyMs: 0
+      },
+      context: {}
+    });
+    return {
+      ok: result.ok,
+      status: result.status,
+      latencyMs: now() - startedAt,
+      networkError: result.ok ? null : result.error ?? null
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      latencyMs: now() - startedAt,
+      networkError: error instanceof Error ? error.message : String(error)
+    };
+  }
+}

package/dist/events/envelope.cjs

@@ -0,0 +1,23 @@
+const {SCHEMA_VERSION, VERSION} = require('../version.cjs');
+function createEnvelopeBuilder(options) {
+  const now = options.now ?? Date.now;
+  const contextFactory = options.context ?? (() => ({}));
+  return function buildEnvelope(kind, payload) {
+    const sequence = options.session.nextSequence();
+    return {
+      schemaVersion: SCHEMA_VERSION,
+      libraryVersion: VERSION,
+      eventId: options.session.nextEventId(),
+      sequence,
+      kind,
+      sessionId: options.session.sessionId,
+      correlationId: options.session.correlationId,
+      timestamp: now(),
+      source: "browser",
+      payload,
+      context: contextFactory()
+    };
+  };
+}
+
+exports.createEnvelopeBuilder = createEnvelopeBuilder;

package/dist/events/envelope.js

@@ -0,0 +1,21 @@
+import { SCHEMA_VERSION, VERSION } from "../version.js";
+export function createEnvelopeBuilder(options) {
+  const now = options.now ?? Date.now;
+  const contextFactory = options.context ?? (() => ({}));
+  return function buildEnvelope(kind, payload) {
+    const sequence = options.session.nextSequence();
+    return {
+      schemaVersion: SCHEMA_VERSION,
+      libraryVersion: VERSION,
+      eventId: options.session.nextEventId(),
+      sequence,
+      kind,
+      sessionId: options.session.sessionId,
+      correlationId: options.session.correlationId,
+      timestamp: now(),
+      source: "browser",
+      payload,
+      context: contextFactory()
+    };
+  };
+}

package/dist/index.cjs

@@ -0,0 +1,23 @@
+const __reexport_1 = require('./client/create-telemetry-client.cjs');
+exports.createTelemetryClient = __reexport_1.createTelemetryClient;
+const __reexport_2 = require('./adapters/browser-lifecycle-adapter.cjs');
+exports.installBrowserLifecycleAdapter = __reexport_2.installBrowserLifecycleAdapter;
+const __reexport_3 = require('./adapters/browser-lifecycle-adapter.cjs');
+exports.observeElementVisibility = __reexport_3.observeElementVisibility;
+const __reexport_4 = require('./adapters/iframe-detector-adapter.cjs');
+exports.installIframeDetectorAdapter = __reexport_4.installIframeDetectorAdapter;
+const __reexport_5 = require('./transport/callback-transport.cjs');
+exports.callbackTransport = __reexport_5.callbackTransport;
+const __reexport_6 = require('./transport/http-transport.cjs');
+exports.httpTransport = __reexport_6.httpTransport;
+const __reexport_7 = require('./diagnostics/preflight.cjs');
+exports.preflight = __reexport_7.preflight;
+const __reexport_8 = require('./persistence/memory-outbox.cjs');
+exports.memoryOutbox = __reexport_8.memoryOutbox;
+const __reexport_9 = require('./persistence/local-storage-outbox.cjs');
+exports.localStorageOutbox = __reexport_9.localStorageOutbox;
+const __reexport_10 = require('./version.cjs');
+exports.VERSION = __reexport_10.VERSION;
+exports.SCHEMA_VERSION = __reexport_10.SCHEMA_VERSION;
+
+