@ianmenethil/zp-observer 6.0.0 → 6.1.0

package/README.md

@@ -1,284 +1,27 @@
-# @ianmenethil/zp-observer
+# ZP Telemetry Rewrite
 
-Telemetry for **Zenith hosted checkout**: v6 adds **domain events**, **correlation IDs**, **persistent outbox**, and a **unified session entry point** on top of the proven open/heartbeat/close model. Cross-page outcome reporting, device fingerprint bridge hooks, and HPP lifecycle observation are all wired through a single typed event bus.
+This package is the clean native-only telemetry SDK for internal checkout integrations.
 
-**Pick one path:**
+Current scope:
 
-| You are… | Go to |
-|----------|--------|
-| Using **Vite / webpack / Node ESM** | [npm — ES modules](#npm--es-modules-import) |
-| Using **CommonJS** (`require`) | [npm — CommonJS](#npm--commonjs-require) |
-| Using a **plain HTML page** with no bundler | [CDN — `<script>` tag](#cdn--script-tag-no-bundler) |
+- typed native event map
+- single telemetry envelope contract across client and transports
+- session manager with explicit state machine
+- callback and HTTP transports that both send the same envelope shape
+- memory and local-storage outboxes
+- diagnostics snapshot buffer
+- core telemetry client with middleware, persistence policy, heartbeat, and flush support
 
----
+Removed from this package:
 
-## Install (npm only)
+- legacy observer compatibility wrappers
+- staged migration session helpers
+- one-shot compatibility reporters
+- browser-global compatibility entrypoints
 
-```bash
-npm install @ianmenethil/zp-observer
-```
-
----
-
-## Quickstart (unified session — v6)
-
-```ts
-import { createZenPaySession, httpTransport } from '@ianmenethil/zp-observer/session';
-
-const session = createZenPaySession({
-  sessionId: merchantUPID,
-  transport: httpTransport({ openUrl, aliveUrl, closeUrl }),
-  persistence: 'localStorage',
-  metadata: { merchantId: 'ACME', env: 'prod' },
-});
-
-// session.observer is started automatically.
-// Pass session.hppDefaults.onPluginClose to ZenPay.
-// Pass session.fingerprint.hooks into DEVICEFP's captureThumbmark() options.
-// session.correlationId ties every event together.
-```
-
-## Correlation IDs
-
-Every event carries a `correlationId` — a UUID minted by the observer (or supplied via `createObserver({ correlationId })`). It flows through the fingerprint, HPP init, modal open, heartbeats, close, and outcome events so your backend can join the full payment story without timestamp guessing. Pass it to DEVICEFP via the bridge hooks, or embed it in `merchantUniquePaymentId` metadata.
-
-## npm — ES modules (`import`)
-
-**`headers` on `httpTransport` is optional.** If you omit it, requests still run: heartbeats and fetch fallbacks send **`Content-Type: application/json`** only, and use **`credentials: 'include'`** so **first-party / same-site cookies** are included when the browser allows it. **`navigator.sendBeacon`** (used for `open` / `close` when it succeeds) **cannot set custom headers** — only the JSON body.
-
-So integrators often:
-
-- **No extra auth** — omit `headers`; rely on **session cookies** on your own origin, or **signed query params** baked into the three URLs.
-- **Bearer / API key** — pass `headers: () => ({ Authorization: 'Bearer …' })` (or any static object) so **heartbeat** and **fetch fallbacks** include them; beacons still won’t.
-
-```ts
-import {
-  createObserver,
-  httpTransport,
-  installZenPayAutoPatch,
-} from '@ianmenethil/zp-observer';
-
-const mUPID = 'your-merchant-unique-payment-id';
-
-const observer = createObserver({
-  sessionId: mUPID,
-  transport: httpTransport({
-    openUrl: `https://your-api.example/telemetry/${mUPID}?e=open`,
-    aliveUrl: `https://your-api.example/telemetry/${mUPID}?e=alive`,
-    closeUrl: `https://your-api.example/telemetry/${mUPID}?e=close`,
-    // Optional — only if your server needs extra headers on fetch() calls:
-    // headers: () => ({ Authorization: `Bearer ${getLogsToken()}` }),
-  }),
-});
-
-// Optional: rewrite ZenPay init so onPluginClose uses observer.shortcode automatically
-installZenPayAutoPatch(observer);
-
-observer.start();
-
-// Then open ZenPay as you already do, e.g.:
-// $.zpPayment({ merchantUniquePaymentId: mUPID, onPluginClose: observer.shortcode }).init();
-```
-
-**Without auto-patch:** after `start()`, pass **`observer.shortcode`** (a string like `window.zpcb_…`) to ZenPay’s **`onPluginClose`** — same value as the v4 bridge.
-
-**Optional subpath** (only the ZenPay patch helper):
-
-```ts
-import { installZenPayAutoPatch } from '@ianmenethil/zp-observer/auto-patch';
-```
-
----
-
-## npm — CommonJS (`require`)
-
-```js
-const {
-  createObserver,
-  httpTransport,
-  installZenPayAutoPatch,
-} = require('@ianmenethil/zp-observer');
-
-const mUPID = 'your-merchant-unique-payment-id';
-
-const observer = createObserver({
-  sessionId: mUPID,
-  transport: httpTransport({
-    openUrl: `https://your-api.example/telemetry/${mUPID}?e=open`,
-    aliveUrl: `https://your-api.example/telemetry/${mUPID}?e=alive`,
-    closeUrl: `https://your-api.example/telemetry/${mUPID}?e=close`,
-  }),
-});
-
-installZenPayAutoPatch(observer);
-observer.start();
-```
-
----
-
-## CDN — `<script>` tag (no bundler)
-
-1. Add **one** script from **`dist/`** (published path on unpkg/jsDelivr includes `dist/`).
-
-2. Use the global **`ZPObserver`** — same names as the npm API: `createObserver`, `httpTransport`, `installZenPayAutoPatch`, `callbackTransport`, `VERSION`.
-
-```html
-<script src="https://unpkg.com/@ianmenethil/zp-observer/dist/zp-observer.min.js"></script>
-<script>
-  (function () {
-    var mUPID = ‘your-merchant-unique-payment-id’;
+Run checks:
 
-    var observer = ZPObserver.createObserver({
-      sessionId: mUPID,
-      transport: ZPObserver.httpTransport({
-        openUrl:  ‘/telemetry/’ + mUPID + ‘?e=open’,
-        aliveUrl: ‘/telemetry/’ + mUPID + ‘?e=alive’,
-        closeUrl: ‘/telemetry/’ + mUPID + ‘?e=close’,
-      }),
-    });
-
-    ZPObserver.installZenPayAutoPatch(observer);
-    observer.start();
-
-    // ZenPay init — if you don’t use auto-patch, pass onPluginClose: observer.shortcode
-  })();
-</script>
-```
-
-**Which CDN file?**
-
-| File | When |
-|------|------|
-| `dist/zp-observer.js` | Debugging (readable) |
-| `dist/zp-observer.min.js` | **Default** production |
-| `dist/zp-observer.min.obf.js` | Minified + obfuscated |
-
----
-
-## API (quick reference)
-
-| Export | Role |
-|--------|------|
-| **`createObserver(options)`** | Returns `{ sessionId, correlationId, shortcode, start, stop, getState, emit, diagnostics }`. |
-| **`httpTransport({ openUrl, aliveUrl, closeUrl, eventUrl?, headers?, fetch? })`** | Default HTTP transport. `eventUrl` (optional) receives domain events. |
-| **`callbackTransport({ onOpen?, onHeartbeat?, onClose?, onEvent? })`** | Bring-your-own-sink. `onEvent` receives domain events. |
-| **`installZenPayAutoPatch(observer)`** | Wraps `$.fn.zpPayment` / `window.ZenPay` to inject `observer.shortcode` and emit `payment.hpp_init`. |
-| **`installHPPBridge(observer)`** | Wraps `window.onPaymentPluginLoaded` to emit `payment.hpp_iframe_loaded`. |
-| **`installDeviceFPBridge(observer, opts?)`** | Returns typed hooks (`onFingerprintStarted`, `onFingerprintCacheHit`, `onFingerprintSucceeded`, `onFingerprintFailed`) that emit domain events. Spread into DEVICEFP's `captureThumbmark()`. |
-| **`preflight({ transport, sample? })`** | Sends a `payment.preflight` event and returns a structured `PreflightReport` for integration debugging. |
-| **`reportOutcome({ correlationId, sessionId, outcome, transport })`** | Posts a single `payment.outcome` event from your return/thank-you page. |
-| **`createZenPaySession(options)`** | Unified entry (subpath `@ianmenethil/zp-observer/session`). Composes observer, auto-patch, HPP bridge, and fingerprint hooks. |
-| **`VERSION`** | Package version string. |
-| **`ExperimentalOptions` / `onDiagnostic`** | See [Experimental / lab](#experimental--lab-optional). |
-
-**`observer.emit(event)`** — push any `ObserverEvent` onto the bus (bridges, merchant code).  
-**`observer.diagnostics.dump()`** — JSON-serializable snapshot for support tickets.  
-**`observer.shortcode`** — string to pass to ZenPay as **`onPluginClose`** (e.g. `window.zpcb_abc123`).  
-**`observer.correlationId`** — the UUID tying this session's events together.
-
----
-
-## Experimental / lab (optional)
-
-Use this to **turn on one browser signal at a time** and record what actually fires in your merchants’ browsers. Nothing here changes the core **`open` / `heartbeat` / `close`** contract unless you opt in to extra fields or heartbeats.
-
-- **`onDiagnostic`** — callback with typed **`DiagnosticEvent`** (`exp.pageshow`, `exp.freeze`, `exp.perf_entry`, …).
-- **`experimental.*`** — booleans such as **`capturePageShow`**, **`captureFreezeResume`**, **`capturePerformanceEntries`**, **`captureIframeResize`**, **`captureIframeSrcChanges`**, **`captureVisibilityDetail`** (includes **`navigator.onLine`** as **informational only**), **`captureWindowFocus`**, **`captureWasDiscarded`**, **`captureUserActivation`**, **`captureNavigationTimingDetail`** (adds **`userActivation`** / **`navigationDetail`** on the **`open`** payload when set).
-- **`pageLifecycleBeaconUrl`** — optional URL; sends JSON **`sendBeacon`** for **`navigation`** (at `start()`), **`pageshow`**, **`pagehide`** (mirrors the v1.2 experiment’s page-lifecycle beacons). **`exp.page_lifecycle_beacon`** diagnostics report whether **`sendBeacon`** returned true.
-- **`attachDiagnosticsToHeartbeat`** — append a ring buffer to **`metadata.zpObserverDiagnostics`** on each heartbeat (cap with **`diagnosticsMax`**, default 50).
-
-```ts
-createObserver({
-  sessionId: mUPID,
-  transport: /* … */,
-  debug: true,
-  onDiagnostic: (ev) => {
-    console.table(ev);
-    // or POST to your lab sink
-  },
-  experimental: {
-    capturePageShow: true,
-    captureFreezeResume: true,
-    capturePerformanceEntries: true,
-    captureIframeResize: true,
-    captureIframeSrcChanges: true,
-    attachDiagnosticsToHeartbeat: true,
-    // pageLifecycleBeaconUrl: 'https://your-lab.example/beacon',
-  },
-});
-```
-
----
-
-## Bring your own transport (npm ESM example)
-
-```ts
-import { createObserver, callbackTransport } from '@ianmenethil/zp-observer';
-
-const observer = createObserver({
-  sessionId: mUPID,
-  transport: callbackTransport({
-    onOpen: (ev) => {
-      void navigator.sendBeacon('/telemetry', JSON.stringify(ev));
-    },
-    onHeartbeat: async (ev) => {
-      const res = await fetch('/telemetry', {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify(ev),
-      });
-      return { ok: res.ok, status: res.status };
-    },
-    onClose: (ev) => {
-      void navigator.sendBeacon('/telemetry', JSON.stringify(ev));
-    },
-  }),
-});
-
-observer.start();
+```bash
+node --test ./tests/**/*.test.ts
+node ./scripts/build.mjs
 ```
-
----
-
-## Build output layout (`dist/`)
-
-| File | Purpose |
-|------|---------|
-| **`dist/zp-observer.mjs`** | **npm ESM** — `import` resolves here |
-| **`dist/zp-observer.cjs`** | **npm CJS** — `require()` resolves here |
-| **`dist/auto-patch.mjs`** | **npm ESM subpath** — `@ianmenethil/zp-observer/auto-patch` |
-| **`dist/auto-patch.cjs`** | **npm CJS subpath** |
-| **`dist/session.mjs`** | **npm ESM subpath** — `@ianmenethil/zp-observer/session` |
-| **`dist/session.cjs`** | **npm CJS subpath** |
-| **`dist/zp-observer.min.js`** | **CDN** — `<script src>` IIFE, global `ZPObserver` |
-| **`dist/zp-observer.js`** | **CDN debug** — unminified IIFE |
-| **`dist/zp-observer.min.obf.js`** | **CDN obfuscated** — minified + obfuscated |
-| **`dist/types/`** | **TypeScript** — `.d.ts` declarations |
-
-Do not point a raw `<script>` at `.mjs` / `.cjs` files (those use ESM `import`/`export` or CJS `require`).
-
----
-
-## Close reasons
-
-Typed as **`CloseReason`** in the published `.d.ts`. Examples: `user.callback_invoked`, `user.modal_closed`, `system.idle_timeout`, `system.network_abandoned`, `page.pagehide`, `user.manual_close`.
-
----
-
-## Publishing (`@ianmenethil/zp-observer`)
-
-1. `npm login` with an account that can publish the **`@ianmenethil`** scope.
-2. Bump **`version`** in `package.json` (or run `npm version patch|minor|major`).
-3. Run **`npm run publish:npm`** (same as **`npm publish --access public`**). **`prepack`** runs **`npm run check`** (lint + typecheck + test + knip + jscpd) and **`npm run build`** before the tarball is packed.
-
-**Internal CDN:** On the Anticide build machine, run `npm run build:local` to copy the IIFE bundles to `_ZP-CDN-server\public`.
-
----
-
-## Privacy
-
-See [`PRIVACY.md`](PRIVACY.md).
-
-## License
-
-MIT © Zenith Payments

package/dist/adapters/browser-lifecycle-adapter.cjs

@@ -0,0 +1,51 @@
+function observeElementVisibility(element, onChange) {
+  if (typeof IntersectionObserver === "undefined") {
+    return { uninstall() {} };
+  }
+  const observer = new IntersectionObserver((entries) => {
+    const entry = entries[entries.length - 1];
+    if (entry) {
+      onChange(entry.isIntersecting);
+    }
+  }, { threshold: 0.01 });
+  observer.observe(element);
+  return {
+    uninstall() {
+      observer.disconnect();
+    }
+  };
+}
+function installBrowserLifecycleAdapter(client, options = {}) {
+  if (typeof document === "undefined" || typeof window === "undefined") {
+    return { uninstall() {} };
+  }
+  const visibilityHandler = () => {
+    if (document.visibilityState === "hidden") {
+      options.onHidden?.();
+      return;
+    }
+    if (document.visibilityState === "visible") {
+      options.onVisible?.();
+    }
+  };
+  const pageHideHandler = (event) => {
+    const persisted = event.persisted === true;
+    options.onPageHide?.(persisted);
+    if (options.emitCloseOnPageHide) {
+      client.emit("checkout.modal_closed", {
+        reason: options.closeReason ?? "pagehide"
+      });
+    }
+  };
+  document.addEventListener("visibilitychange", visibilityHandler);
+  window.addEventListener("pagehide", pageHideHandler);
+  return {
+    uninstall() {
+      document.removeEventListener("visibilitychange", visibilityHandler);
+      window.removeEventListener("pagehide", pageHideHandler);
+    }
+  };
+}
+
+exports.observeElementVisibility = observeElementVisibility;
+exports.installBrowserLifecycleAdapter = installBrowserLifecycleAdapter;

package/dist/adapters/browser-lifecycle-adapter.js

@@ -0,0 +1,48 @@
+export function observeElementVisibility(element, onChange) {
+  if (typeof IntersectionObserver === "undefined") {
+    return { uninstall() {} };
+  }
+  const observer = new IntersectionObserver((entries) => {
+    const entry = entries[entries.length - 1];
+    if (entry) {
+      onChange(entry.isIntersecting);
+    }
+  }, { threshold: 0.01 });
+  observer.observe(element);
+  return {
+    uninstall() {
+      observer.disconnect();
+    }
+  };
+}
+export function installBrowserLifecycleAdapter(client, options = {}) {
+  if (typeof document === "undefined" || typeof window === "undefined") {
+    return { uninstall() {} };
+  }
+  const visibilityHandler = () => {
+    if (document.visibilityState === "hidden") {
+      options.onHidden?.();
+      return;
+    }
+    if (document.visibilityState === "visible") {
+      options.onVisible?.();
+    }
+  };
+  const pageHideHandler = (event) => {
+    const persisted = event.persisted === true;
+    options.onPageHide?.(persisted);
+    if (options.emitCloseOnPageHide) {
+      client.emit("checkout.modal_closed", {
+        reason: options.closeReason ?? "pagehide"
+      });
+    }
+  };
+  document.addEventListener("visibilitychange", visibilityHandler);
+  window.addEventListener("pagehide", pageHideHandler);
+  return {
+    uninstall() {
+      document.removeEventListener("visibilitychange", visibilityHandler);
+      window.removeEventListener("pagehide", pageHideHandler);
+    }
+  };
+}

package/dist/adapters/iframe-detector-adapter.cjs

@@ -0,0 +1,108 @@
+const {observeElementVisibility} = require('./browser-lifecycle-adapter.cjs');
+function installIframeDetectorAdapter(client, options) {
+  if (typeof document === "undefined") {
+    return { uninstall() {} };
+  }
+  const intervalMs = options.intervalMs ?? 100;
+  const timeoutMs = options.timeoutMs ?? 30000;
+  const startedAt = Date.now();
+  let pollTimer = null;
+  let mutationObserver = null;
+  let visibilityHandle = null;
+  let bootstrapHandler = null;
+  let detectedIframe = null;
+  const findIframe = () => {
+    for (const selector of options.selectors) {
+      const element = document.querySelector(selector);
+      if (element instanceof HTMLIFrameElement) {
+        return element;
+      }
+    }
+    return null;
+  };
+  const stopPolling = () => {
+    if (pollTimer !== null) {
+      clearInterval(pollTimer);
+      pollTimer = null;
+    }
+  };
+  const installRemovalObserver = (iframe) => {
+    if (typeof MutationObserver === "undefined" || !document.body) {
+      return;
+    }
+    mutationObserver = new MutationObserver((mutations) => {
+      for (const mutation of mutations) {
+        for (const node of Array.from(mutation.removedNodes)) {
+          if (node === iframe || node instanceof Node && node.contains(iframe)) {
+            options.onRemoved?.();
+            if (options.emitCloseOnRemoval) {
+              client.emit("checkout.modal_closed", {
+                reason: options.closedReason ?? "iframe_removed"
+              });
+            }
+            return;
+          }
+        }
+      }
+    });
+    mutationObserver.observe(document.body, { childList: true, subtree: true });
+  };
+  const installBootstrapObserver = () => {
+    if (typeof document.addEventListener !== "function") {
+      return;
+    }
+    bootstrapHandler = () => {
+      options.onBootstrapHidden?.();
+      if (options.emitCloseOnBootstrapHidden) {
+        client.emit("checkout.modal_closed", {
+          reason: options.bootstrapClosedReason ?? options.closedReason ?? "bootstrap_hidden"
+        });
+      }
+    };
+    document.addEventListener("hidden.bs.modal", bootstrapHandler, true);
+  };
+  const handleDetected = (iframe) => {
+    detectedIframe = iframe;
+    stopPolling();
+    installRemovalObserver(iframe);
+    installBootstrapObserver();
+    visibilityHandle = observeElementVisibility(iframe, (visible) => {
+      options.onVisibilityChange?.(visible);
+    });
+    options.onDetected?.(iframe);
+    client.emit("checkout.iframe_detected", {
+      iframeSrc: iframe.src || null
+    });
+  };
+  const existing = findIframe();
+  if (existing) {
+    queueMicrotask(() => handleDetected(existing));
+  } else {
+    pollTimer = setInterval(() => {
+      if (Date.now() - startedAt > timeoutMs) {
+        stopPolling();
+        options.onTimeout?.();
+        return;
+      }
+      const iframe = findIframe();
+      if (iframe && iframe !== detectedIframe) {
+        handleDetected(iframe);
+      }
+    }, intervalMs);
+  }
+  return {
+    uninstall() {
+      stopPolling();
+      mutationObserver?.disconnect();
+      mutationObserver = null;
+      visibilityHandle?.uninstall();
+      visibilityHandle = null;
+      if (bootstrapHandler) {
+        document.removeEventListener("hidden.bs.modal", bootstrapHandler, true);
+        bootstrapHandler = null;
+      }
+    }
+  };
+}
+
+exports.installIframeDetectorAdapter = installIframeDetectorAdapter;

package/dist/adapters/iframe-detector-adapter.js

@@ -0,0 +1,106 @@
+import { observeElementVisibility } from "./browser-lifecycle-adapter.js";
+export function installIframeDetectorAdapter(client, options) {
+  if (typeof document === "undefined") {
+    return { uninstall() {} };
+  }
+  const intervalMs = options.intervalMs ?? 100;
+  const timeoutMs = options.timeoutMs ?? 30000;
+  const startedAt = Date.now();
+  let pollTimer = null;
+  let mutationObserver = null;
+  let visibilityHandle = null;
+  let bootstrapHandler = null;
+  let detectedIframe = null;
+  const findIframe = () => {
+    for (const selector of options.selectors) {
+      const element = document.querySelector(selector);
+      if (element instanceof HTMLIFrameElement) {
+        return element;
+      }
+    }
+    return null;
+  };
+  const stopPolling = () => {
+    if (pollTimer !== null) {
+      clearInterval(pollTimer);
+      pollTimer = null;
+    }
+  };
+  const installRemovalObserver = (iframe) => {
+    if (typeof MutationObserver === "undefined" || !document.body) {
+      return;
+    }
+    mutationObserver = new MutationObserver((mutations) => {
+      for (const mutation of mutations) {
+        for (const node of Array.from(mutation.removedNodes)) {
+          if (node === iframe || node instanceof Node && node.contains(iframe)) {
+            options.onRemoved?.();
+            if (options.emitCloseOnRemoval) {
+              client.emit("checkout.modal_closed", {
+                reason: options.closedReason ?? "iframe_removed"
+              });
+            }
+            return;
+          }
+        }
+      }
+    });
+    mutationObserver.observe(document.body, { childList: true, subtree: true });
+  };
+  const installBootstrapObserver = () => {
+    if (typeof document.addEventListener !== "function") {
+      return;
+    }
+    bootstrapHandler = () => {
+      options.onBootstrapHidden?.();
+      if (options.emitCloseOnBootstrapHidden) {
+        client.emit("checkout.modal_closed", {
+          reason: options.bootstrapClosedReason ?? options.closedReason ?? "bootstrap_hidden"
+        });
+      }
+    };
+    document.addEventListener("hidden.bs.modal", bootstrapHandler, true);
+  };
+  const handleDetected = (iframe) => {
+    detectedIframe = iframe;
+    stopPolling();
+    installRemovalObserver(iframe);
+    installBootstrapObserver();
+    visibilityHandle = observeElementVisibility(iframe, (visible) => {
+      options.onVisibilityChange?.(visible);
+    });
+    options.onDetected?.(iframe);
+    client.emit("checkout.iframe_detected", {
+      iframeSrc: iframe.src || null
+    });
+  };
+  const existing = findIframe();
+  if (existing) {
+    queueMicrotask(() => handleDetected(existing));
+  } else {
+    pollTimer = setInterval(() => {
+      if (Date.now() - startedAt > timeoutMs) {
+        stopPolling();
+        options.onTimeout?.();
+        return;
+      }
+      const iframe = findIframe();
+      if (iframe && iframe !== detectedIframe) {
+        handleDetected(iframe);
+      }
+    }, intervalMs);
+  }
+  return {
+    uninstall() {
+      stopPolling();
+      mutationObserver?.disconnect();
+      mutationObserver = null;
+      visibilityHandle?.uninstall();
+      visibilityHandle = null;
+      if (bootstrapHandler) {
+        document.removeEventListener("hidden.bs.modal", bootstrapHandler, true);
+        bootstrapHandler = null;
+      }
+    }
+  };
+}