@ianmenethil/zp-observer 6.0.0 → 6.1.0

package/dist/index.d.ts

@@ -0,0 +1,230 @@
+export type TelemetryState =
+  | 'idle'
+  | 'starting'
+  | 'active'
+  | 'backgrounded'
+  | 'degraded'
+  | 'closing'
+  | 'closed'
+  | 'abandoned';
+
+export interface TelemetryEventMap {
+  'session.started': {};
+  'session.stopped': { reason: string };
+  'checkout.session_init': { provider: 'zenpay' | 'custom' | 'unknown' };
+  'checkout.iframe_detected': { iframeSrc: string | null };
+  'checkout.modal_opened': { iframeSrc: string | null };
+  'checkout.modal_closed': { reason: string };
+  'fingerprint.started': { attempt: number };
+  'fingerprint.cache_hit': { ageMs: number };
+  'fingerprint.succeeded': {};
+  'fingerprint.failed': { error: string; attempt: number };
+  'merchant.outcome_reported': {
+    outcome: 'success' | 'declined' | 'abandoned' | 'error' | 'unknown';
+  };
+  'transport.heartbeat': { missedBeats: number };
+  'diagnostic.preflight': { ok: boolean; latencyMs: number };
+}
+
+export type TelemetryEventKind = keyof TelemetryEventMap;
+export type TelemetryEventPayload<K extends TelemetryEventKind> = TelemetryEventMap[K];
+
+export interface TelemetryContext {
+  pageUrl?: string;
+  referrer?: string;
+  userAgent?: string;
+  visibilityState?: string;
+  online?: boolean | null;
+}
+
+export interface TelemetryEnvelope<
+  K extends TelemetryEventKind = TelemetryEventKind,
+  P extends TelemetryEventPayload<K> = TelemetryEventPayload<K>,
+> {
+  schemaVersion: number;
+  libraryVersion: string;
+  eventId: string;
+  sequence: number;
+  kind: K;
+  sessionId: string;
+  correlationId: string;
+  timestamp: number;
+  source: 'browser';
+  payload: P;
+  context: TelemetryContext;
+}
+
+export interface TelemetryTransportResult {
+  ok: boolean;
+  status?: number;
+  error?: string;
+}
+
+export interface TelemetryTransport {
+  send(envelope: TelemetryEnvelope): Promise<TelemetryTransportResult>;
+}
+
+export type PersistenceMode = 'memory' | 'localStorage' | 'none';
+
+export interface PersistencePolicy {
+  shouldPersist(kind: TelemetryEventKind): boolean;
+}
+
+export interface TelemetryOutbox {
+  push(envelope: TelemetryEnvelope): void;
+  remove(eventId: string): void;
+  pending(): TelemetryEnvelope[];
+  clear(): void;
+}
+
+export interface TelemetryDiagnosticsEntry {
+  level: 'info' | 'warn' | 'error';
+  message: string;
+  timestamp: number;
+  details?: Record<string, unknown>;
+}
+
+export interface TelemetryDiagnosticsSnapshot {
+  state: TelemetryState;
+  sessionId: string;
+  correlationId: string;
+  queueDepth: number;
+  delivery: {
+    attempted: number;
+    succeeded: number;
+    failed: number;
+  };
+  recentEnvelopes: TelemetryEnvelope[];
+  entries: TelemetryDiagnosticsEntry[];
+}
+
+export interface TelemetryStateSnapshot {
+  state: TelemetryState;
+  sessionId: string;
+  correlationId: string;
+  startedAt: number | null;
+  stoppedAt: number | null;
+  eventCount: number;
+  elapsedMs: number;
+}
+
+export type TelemetryMiddleware = (
+  envelope: TelemetryEnvelope,
+) => TelemetryEnvelope | null | Promise<TelemetryEnvelope | null>;
+
+export interface CreateTelemetryClientOptions {
+  session: {
+    sessionId: string;
+    correlationId?: string;
+  };
+  transport: TelemetryTransport;
+  outbox?: TelemetryOutbox;
+  persistence?: PersistenceMode;
+  middleware?: TelemetryMiddleware[];
+  persistencePolicy?: PersistencePolicy;
+  context?: TelemetryContext;
+  heartbeat?: {
+    intervalMs: number;
+    missThreshold: number;
+  };
+  now?: () => number;
+  debug?: boolean;
+}
+
+export interface TelemetryClient {
+  readonly sessionId: string;
+  readonly correlationId: string;
+  start(): void;
+  stop(reason?: string): void;
+  emit<K extends TelemetryEventKind>(kind: K, payload: TelemetryEventPayload<K>): Promise<void>;
+  flush(): Promise<void>;
+  getState(): TelemetryStateSnapshot;
+  diagnostics: {
+    snapshot(): TelemetryDiagnosticsSnapshot;
+  };
+}
+
+export interface CallbackTransportOptions {
+  onSend?: (
+    envelope: TelemetryEnvelope,
+  ) => TelemetryTransportResult | Promise<TelemetryTransportResult>;
+}
+
+export interface HttpTransportOptions {
+  endpoint: string;
+  headers?: Record<string, string> | (() => Record<string, string>);
+  fetch?: typeof fetch;
+  timeoutMs?: number;
+  credentials?: RequestCredentials;
+}
+
+export interface MemoryOutboxOptions {
+  maxEntries?: number;
+}
+
+export interface LocalStorageOutboxOptions {
+  storageKey?: string;
+  maxEntries?: number;
+  storage?: Pick<Storage, 'getItem' | 'setItem'>;
+  onUnavailable?: (error: string) => void;
+}
+
+export interface BrowserLifecycleAdapterOptions {
+  emitCloseOnPageHide?: boolean;
+  closeReason?: string;
+  onHidden?: () => void;
+  onVisible?: () => void;
+  onPageHide?: (persisted: boolean) => void;
+}
+
+export interface IframeDetectorAdapterOptions {
+  selectors: string[];
+  intervalMs?: number;
+  timeoutMs?: number;
+  emitCloseOnRemoval?: boolean;
+  emitCloseOnBootstrapHidden?: boolean;
+  closedReason?: string;
+  bootstrapClosedReason?: string;
+  onDetected?: (iframe: HTMLIFrameElement) => void;
+  onRemoved?: () => void;
+  onBootstrapHidden?: () => void;
+  onTimeout?: () => void;
+  onVisibilityChange?: (visible: boolean) => void;
+}
+
+export interface AdapterHandle {
+  uninstall(): void;
+}
+
+export declare const VERSION: string;
+export declare const SCHEMA_VERSION: number;
+export declare function createTelemetryClient(
+  options: CreateTelemetryClientOptions,
+): TelemetryClient;
+export declare function callbackTransport(
+  options?: CallbackTransportOptions,
+): TelemetryTransport;
+export declare function httpTransport(options: HttpTransportOptions): TelemetryTransport;
+export declare function installBrowserLifecycleAdapter(
+  client: Pick<TelemetryClient, 'emit'>,
+  options?: BrowserLifecycleAdapterOptions,
+): AdapterHandle;
+export declare function observeElementVisibility(
+  element: Element,
+  onChange: (visible: boolean) => void,
+): AdapterHandle;
+export declare function installIframeDetectorAdapter(
+  client: Pick<TelemetryClient, 'emit'>,
+  options: IframeDetectorAdapterOptions,
+): AdapterHandle;
+export declare function memoryOutbox(options?: MemoryOutboxOptions): TelemetryOutbox;
+export declare function localStorageOutbox(options?: LocalStorageOutboxOptions): TelemetryOutbox;
+export declare function preflight(options: {
+  transport: TelemetryTransport;
+  now?: () => number;
+}): Promise<{
+  ok: boolean;
+  status?: number;
+  latencyMs: number;
+  networkError: string | null;
+}>;

package/dist/index.js

@@ -0,0 +1,10 @@
+export { createTelemetryClient } from "./client/create-telemetry-client.js";
+export { installBrowserLifecycleAdapter } from "./adapters/browser-lifecycle-adapter.js";
+export { observeElementVisibility } from "./adapters/browser-lifecycle-adapter.js";
+export { installIframeDetectorAdapter } from "./adapters/iframe-detector-adapter.js";
+export { callbackTransport } from "./transport/callback-transport.js";
+export { httpTransport } from "./transport/http-transport.js";
+export { preflight } from "./diagnostics/preflight.js";
+export { memoryOutbox } from "./persistence/memory-outbox.js";
+export { localStorageOutbox } from "./persistence/local-storage-outbox.js";
+export { VERSION, SCHEMA_VERSION } from "./version.js";

package/dist/persistence/local-storage-outbox.cjs

@@ -0,0 +1,56 @@
+const STORAGE_KEY = "__zptelemetry_outbox_v1";
+function localStorageOutbox(options = {}) {
+  const maxEntries = options.maxEntries ?? 128;
+  const storageKey = options.storageKey ?? STORAGE_KEY;
+  const storage = options.storage ?? (typeof localStorage === "undefined" ? undefined : localStorage);
+  function notify(error) {
+    options.onUnavailable?.(error);
+  }
+  function readEntries() {
+    if (!storage) {
+      notify("localStorage is not available in this runtime.");
+      return [];
+    }
+    try {
+      const raw = storage.getItem(storageKey);
+      if (!raw) {
+        return [];
+      }
+      const parsed = JSON.parse(raw);
+      return Array.isArray(parsed) ? parsed : [];
+    } catch (error) {
+      notify(error instanceof Error ? error.message : "Failed to read localStorage outbox.");
+      return [];
+    }
+  }
+  function writeEntries(entries) {
+    if (!storage) {
+      notify("localStorage is not available in this runtime.");
+      return;
+    }
+    try {
+      storage.setItem(storageKey, JSON.stringify(entries.slice(-maxEntries)));
+    } catch (error) {
+      notify(error instanceof Error ? error.message : "Failed to write localStorage outbox.");
+    }
+  }
+  return {
+    push(envelope) {
+      const entries = readEntries();
+      entries.push(envelope);
+      writeEntries(entries);
+    },
+    remove(eventId) {
+      const entries = readEntries().filter((entry) => entry.eventId !== eventId);
+      writeEntries(entries);
+    },
+    pending() {
+      return readEntries();
+    },
+    clear() {
+      writeEntries([]);
+    }
+  };
+}
+
+exports.localStorageOutbox = localStorageOutbox;

package/dist/persistence/local-storage-outbox.js

@@ -0,0 +1,54 @@
+const STORAGE_KEY = "__zptelemetry_outbox_v1";
+export function localStorageOutbox(options = {}) {
+  const maxEntries = options.maxEntries ?? 128;
+  const storageKey = options.storageKey ?? STORAGE_KEY;
+  const storage = options.storage ?? (typeof localStorage === "undefined" ? undefined : localStorage);
+  function notify(error) {
+    options.onUnavailable?.(error);
+  }
+  function readEntries() {
+    if (!storage) {
+      notify("localStorage is not available in this runtime.");
+      return [];
+    }
+    try {
+      const raw = storage.getItem(storageKey);
+      if (!raw) {
+        return [];
+      }
+      const parsed = JSON.parse(raw);
+      return Array.isArray(parsed) ? parsed : [];
+    } catch (error) {
+      notify(error instanceof Error ? error.message : "Failed to read localStorage outbox.");
+      return [];
+    }
+  }
+  function writeEntries(entries) {
+    if (!storage) {
+      notify("localStorage is not available in this runtime.");
+      return;
+    }
+    try {
+      storage.setItem(storageKey, JSON.stringify(entries.slice(-maxEntries)));
+    } catch (error) {
+      notify(error instanceof Error ? error.message : "Failed to write localStorage outbox.");
+    }
+  }
+  return {
+    push(envelope) {
+      const entries = readEntries();
+      entries.push(envelope);
+      writeEntries(entries);
+    },
+    remove(eventId) {
+      const entries = readEntries().filter((entry) => entry.eventId !== eventId);
+      writeEntries(entries);
+    },
+    pending() {
+      return readEntries();
+    },
+    clear() {
+      writeEntries([]);
+    }
+  };
+}

package/dist/persistence/memory-outbox.cjs

@@ -0,0 +1,23 @@
+function memoryOutbox(options = {}) {
+  const maxEntries = options.maxEntries ?? 128;
+  let entries = [];
+  return {
+    push(envelope) {
+      entries.push(envelope);
+      if (entries.length > maxEntries) {
+        entries = entries.slice(-maxEntries);
+      }
+    },
+    remove(eventId) {
+      entries = entries.filter((entry) => entry.eventId !== eventId);
+    },
+    pending() {
+      return entries.slice();
+    },
+    clear() {
+      entries = [];
+    }
+  };
+}
+
+exports.memoryOutbox = memoryOutbox;

package/dist/persistence/memory-outbox.js

@@ -0,0 +1,21 @@
+export function memoryOutbox(options = {}) {
+  const maxEntries = options.maxEntries ?? 128;
+  let entries = [];
+  return {
+    push(envelope) {
+      entries.push(envelope);
+      if (entries.length > maxEntries) {
+        entries = entries.slice(-maxEntries);
+      }
+    },
+    remove(eventId) {
+      entries = entries.filter((entry) => entry.eventId !== eventId);
+    },
+    pending() {
+      return entries.slice();
+    },
+    clear() {
+      entries = [];
+    }
+  };
+}

package/dist/runtime/event-pipeline.cjs

@@ -0,0 +1,64 @@
+async function applyMiddleware(envelope, middleware) {
+  let current = envelope;
+  for (const handler of middleware) {
+    if (current === null) {
+      return null;
+    }
+    current = await handler(current);
+  }
+  return current;
+}
+function createEventPipeline(options) {
+  async function sendEnvelope(envelope) {
+    const nextEnvelope = await applyMiddleware(envelope, options.middleware);
+    if (nextEnvelope === null) {
+      options.diagnostics.add({
+        level: "info",
+        message: "Envelope dropped by middleware.",
+        timestamp: Date.now(),
+        details: { eventId: envelope.eventId, kind: envelope.kind }
+      });
+      return { ok: true };
+    }
+    options.diagnostics.recordEnvelope(nextEnvelope);
+    const persist = options.persistencePolicy.shouldPersist(nextEnvelope.kind);
+    if (persist) {
+      options.outbox?.push(nextEnvelope);
+    }
+    const result = await options.transport.send(nextEnvelope);
+    if (result.ok) {
+      options.outbox?.remove(nextEnvelope.eventId);
+    } else {
+      options.diagnostics.add({
+        level: "warn",
+        message: "Transport send failed.",
+        timestamp: Date.now(),
+        details: {
+          eventId: nextEnvelope.eventId,
+          kind: nextEnvelope.kind,
+          status: result.status,
+          error: result.error
+        }
+      });
+    }
+    return result;
+  }
+  return {
+    dispatch(envelope) {
+      return sendEnvelope(envelope);
+    },
+    async flush() {
+      for (const envelope of options.outbox?.pending() ?? []) {
+        const result = await options.transport.send(envelope);
+        if (result.ok) {
+          options.outbox?.remove(envelope.eventId);
+        }
+      }
+    },
+    queueDepth() {
+      return options.outbox?.pending().length ?? 0;
+    }
+  };
+}
+
+exports.createEventPipeline = createEventPipeline;

package/dist/runtime/event-pipeline.js

@@ -0,0 +1,62 @@
+async function applyMiddleware(envelope, middleware) {
+  let current = envelope;
+  for (const handler of middleware) {
+    if (current === null) {
+      return null;
+    }
+    current = await handler(current);
+  }
+  return current;
+}
+export function createEventPipeline(options) {
+  async function sendEnvelope(envelope) {
+    const nextEnvelope = await applyMiddleware(envelope, options.middleware);
+    if (nextEnvelope === null) {
+      options.diagnostics.add({
+        level: "info",
+        message: "Envelope dropped by middleware.",
+        timestamp: Date.now(),
+        details: { eventId: envelope.eventId, kind: envelope.kind }
+      });
+      return { ok: true };
+    }
+    options.diagnostics.recordEnvelope(nextEnvelope);
+    const persist = options.persistencePolicy.shouldPersist(nextEnvelope.kind);
+    if (persist) {
+      options.outbox?.push(nextEnvelope);
+    }
+    const result = await options.transport.send(nextEnvelope);
+    if (result.ok) {
+      options.outbox?.remove(nextEnvelope.eventId);
+    } else {
+      options.diagnostics.add({
+        level: "warn",
+        message: "Transport send failed.",
+        timestamp: Date.now(),
+        details: {
+          eventId: nextEnvelope.eventId,
+          kind: nextEnvelope.kind,
+          status: result.status,
+          error: result.error
+        }
+      });
+    }
+    return result;
+  }
+  return {
+    dispatch(envelope) {
+      return sendEnvelope(envelope);
+    },
+    async flush() {
+      for (const envelope of options.outbox?.pending() ?? []) {
+        const result = await options.transport.send(envelope);
+        if (result.ok) {
+          options.outbox?.remove(envelope.eventId);
+        }
+      }
+    },
+    queueDepth() {
+      return options.outbox?.pending().length ?? 0;
+    }
+  };
+}

package/dist/runtime/heartbeat-scheduler.cjs

@@ -0,0 +1,46 @@
+function createHeartbeatScheduler(options) {
+  let heartbeatCount = 0;
+  let missedBeats = 0;
+  let stopped = false;
+  let thresholdNotified = false;
+  const timer = setInterval(() => {
+    if (stopped) {
+      return;
+    }
+    heartbeatCount += 1;
+    options.sendHeartbeat(missedBeats).then((result) => {
+      if (result.ok) {
+        missedBeats = 0;
+        thresholdNotified = false;
+      } else {
+        missedBeats += 1;
+        if (missedBeats >= options.missThreshold && !thresholdNotified) {
+          thresholdNotified = true;
+          options.onMissThreshold?.(missedBeats);
+        }
+      }
+      options.onTick?.(heartbeatCount, missedBeats);
+    }).catch(() => {
+      missedBeats += 1;
+      if (missedBeats >= options.missThreshold && !thresholdNotified) {
+        thresholdNotified = true;
+        options.onMissThreshold?.(missedBeats);
+      }
+      options.onTick?.(heartbeatCount, missedBeats);
+    });
+  }, options.intervalMs);
+  return {
+    stop() {
+      stopped = true;
+      clearInterval(timer);
+    },
+    heartbeatCount() {
+      return heartbeatCount;
+    },
+    missedBeats() {
+      return missedBeats;
+    }
+  };
+}
+
+exports.createHeartbeatScheduler = createHeartbeatScheduler;

package/dist/runtime/heartbeat-scheduler.js

@@ -0,0 +1,44 @@
+export function createHeartbeatScheduler(options) {
+  let heartbeatCount = 0;
+  let missedBeats = 0;
+  let stopped = false;
+  let thresholdNotified = false;
+  const timer = setInterval(() => {
+    if (stopped) {
+      return;
+    }
+    heartbeatCount += 1;
+    options.sendHeartbeat(missedBeats).then((result) => {
+      if (result.ok) {
+        missedBeats = 0;
+        thresholdNotified = false;
+      } else {
+        missedBeats += 1;
+        if (missedBeats >= options.missThreshold && !thresholdNotified) {
+          thresholdNotified = true;
+          options.onMissThreshold?.(missedBeats);
+        }
+      }
+      options.onTick?.(heartbeatCount, missedBeats);
+    }).catch(() => {
+      missedBeats += 1;
+      if (missedBeats >= options.missThreshold && !thresholdNotified) {
+        thresholdNotified = true;
+        options.onMissThreshold?.(missedBeats);
+      }
+      options.onTick?.(heartbeatCount, missedBeats);
+    });
+  }, options.intervalMs);
+  return {
+    stop() {
+      stopped = true;
+      clearInterval(timer);
+    },
+    heartbeatCount() {
+      return heartbeatCount;
+    },
+    missedBeats() {
+      return missedBeats;
+    }
+  };
+}

package/dist/runtime/session-manager.cjs

@@ -0,0 +1,47 @@
+const {assertTransition} = require('../client/state-machine.cjs');
+const {generateCorrelationId, generateEventId} = require('../utils/ids.cjs');
+function createSessionManager(options) {
+  const now = options.now ?? Date.now;
+  const sessionId = options.sessionId;
+  const correlationId = options.correlationId ?? generateCorrelationId();
+  let state = "idle";
+  let sequence = 0;
+  let startedAt = null;
+  let stoppedAt = null;
+  return {
+    sessionId,
+    correlationId,
+    nextSequence() {
+      sequence += 1;
+      return sequence;
+    },
+    nextEventId() {
+      return generateEventId(sequence);
+    },
+    transition(next) {
+      assertTransition(state, next);
+      state = next;
+      if (next === "starting" && startedAt === null) {
+        startedAt = now();
+      }
+      if (next === "closed") {
+        stoppedAt = now();
+      }
+    },
+    snapshot() {
+      const currentNow = now();
+      const elapsedMs = startedAt === null ? 0 : (stoppedAt ?? currentNow) - startedAt;
+      return {
+        state,
+        sessionId,
+        correlationId,
+        startedAt,
+        stoppedAt,
+        eventCount: sequence,
+        elapsedMs
+      };
+    }
+  };
+}
+
+exports.createSessionManager = createSessionManager;