@anyreplay/electron 0.0.0-stage → 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Baem Tech
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,83 @@
-# Temporary Holding Version
+# @anyreplay/electron
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Session replay for Electron apps. Each window is recorded with
+[`@anyreplay/browser`](../browser) — the same masking, transport and rrweb
+setup as on the web — and reported as an Electron session with your app's id
+and version.
+
+```bash
+npm install @anyreplay/electron
+```
+
+Three lines, one per Electron context.
+
+```ts
+// main.ts — the main process
+import { setupAnyReplay } from '@anyreplay/electron/main';
+setupAnyReplay({ appId: 'com.example.notes' });
+```
+
+```ts
+// preload.ts — bundled with your preload script
+import { exposeAnyReplay } from '@anyreplay/electron/preload';
+exposeAnyReplay();
+```
+
+```ts
+// renderer — as early as you can in each window
+import { init } from '@anyreplay/electron';
+const replay = init({ projectKey: 'ar_pk_live_…' });
+replay.track('note_opened');
+```
+
+## What each piece does
+
+- **`setupAnyReplay(options)`** (main) answers the windows' request for the app
+  id and `app.getVersion()`; holds quitting back until every window has sent
+  what it recorded (`quitFlushTimeoutMs`, default 1500, `0` turns it off); and
+  forwards uncaught main-process exceptions into the focused window's session
+  as an error, recorded exactly as one the window caught itself would be
+  (`forwardMainErrors`, default on). It
+  observes them with `uncaughtExceptionMonitor`, so how your app handles them
+  does not change. Returns `{ dispose }`.
+- **`exposeAnyReplay()`** (preload) puts `window.anyreplayElectron` on the page
+  through `contextBridge`: the app info, a flush the main process can ask for,
+  and the main-process errors. Nothing else — no generic IPC. Works with
+  `contextIsolation: true`, `sandbox: true` and no `nodeIntegration`
+  (Electron's defaults). A sandboxed preload cannot load `node_modules` at run
+  time, so bundle it.
+- **`init(options)`** (renderer) takes every option of `@anyreplay/browser`,
+  plus `appId` and `appVersion` (normally left to the main process) and
+  `flushOnBlur` (default on). It returns at once; recording starts when the
+  app info arrives, and calls made before that are queued.
+
+## The app id
+
+Electron has no API for your bundle id, so pass it to `setupAnyReplay` — the
+`appId` from electron-builder, or Forge's `appBundleId`. Without it the id is
+made from `app.getName()` (`"Acme Notes"` → `acme-notes`). A packaged window
+loads from `file://` and has no web origin, so a project that lists allowed
+apps admits it by this id.
+
+## Windows and sessions
+
+Each `BrowserWindow` is its own session: the session id lives in the window's
+`sessionStorage`. The visitor id lives in `localStorage`, which Electron keeps
+across launches and shares between the windows of one session partition, so
+one person is one visitor however many windows they open.
+
+## Content Security Policy
+
+If your app sets a CSP, allow the ingest host in `connect-src`:
+
+```
+connect-src 'self' https://in.anyreplay.com
+```
+
+(or your self-hosted ingest URL).
+
+## Requirements
+
+Electron 28 or later.
+
+MIT © Baem Tech

package/dist/bridge-BQKD7rrG.d.cts

@@ -0,0 +1,53 @@
+/**
+ * The contract between the three halves of the Electron SDK.
+ *
+ * The renderer records; the preload script is the only code that can talk to
+ * the main process; the main process knows the app's id and version and sees
+ * the app quit. They share nothing but these names, so each entry point can be
+ * imported on its own without pulling in the others (or the recorder, which
+ * has no business in the main process).
+ */
+/** The global the preload script exposes through `contextBridge`. */
+declare const BRIDGE_KEY = "anyreplayElectron";
+/** IPC channels. All of them, so a reviewer can see exactly what crosses. */
+declare const CHANNELS: {
+    /** renderer → main (invoke): `AppInfo`. */
+    readonly appInfo: "anyreplay:app-info";
+    /** main → renderer: flush now, then answer on `flushed` with the same id. */
+    readonly flush: "anyreplay:flush";
+    /** renderer → main: a flush asked for by `flush` has finished. */
+    readonly flushed: "anyreplay:flushed";
+    /** main → renderer: an uncaught exception in the main process. */
+    readonly mainError: "anyreplay:main-error";
+};
+/** What the main process says about the app. */
+interface AppInfo {
+    /** The app id (§2.2 of the SDK contract), already checked against the id pattern. Absent when none could be found. */
+    appId?: string;
+    /** `app.getVersion()`. */
+    appVersion?: string;
+}
+/** An uncaught exception in the main process, as sent to a window. Raw: the renderer redacts it. */
+interface MainErrorMessage {
+    name?: string;
+    message: string;
+    stack?: string;
+}
+/**
+ * What the preload script exposes on `window.anyreplayElectron`.
+ *
+ * Deliberately narrow: three fixed channels, no generic `send` or `invoke`, so
+ * exposing it gives page script no more reach into the main process than
+ * asking for the app's version and answering a flush.
+ */
+interface AnyReplayBridge {
+    /** The bridge's own version, so a newer renderer can tell an older preload apart. */
+    readonly version: 1;
+    appInfo: () => Promise<AppInfo>;
+    /** The renderer's flush; called when the main process is about to quit. Replaces any earlier one. */
+    onFlushRequest: (flush: () => Promise<void> | void) => void;
+    /** Called with each main-process error forwarded to this window. Replaces any earlier listener. */
+    onMainError: (listener: (error: MainErrorMessage) => void) => void;
+}
+
+export { type AppInfo as A, BRIDGE_KEY as B, CHANNELS as C, type MainErrorMessage as M, type AnyReplayBridge as a };

package/dist/bridge-BQKD7rrG.d.ts

@@ -0,0 +1,53 @@
+/**
+ * The contract between the three halves of the Electron SDK.
+ *
+ * The renderer records; the preload script is the only code that can talk to
+ * the main process; the main process knows the app's id and version and sees
+ * the app quit. They share nothing but these names, so each entry point can be
+ * imported on its own without pulling in the others (or the recorder, which
+ * has no business in the main process).
+ */
+/** The global the preload script exposes through `contextBridge`. */
+declare const BRIDGE_KEY = "anyreplayElectron";
+/** IPC channels. All of them, so a reviewer can see exactly what crosses. */
+declare const CHANNELS: {
+    /** renderer → main (invoke): `AppInfo`. */
+    readonly appInfo: "anyreplay:app-info";
+    /** main → renderer: flush now, then answer on `flushed` with the same id. */
+    readonly flush: "anyreplay:flush";
+    /** renderer → main: a flush asked for by `flush` has finished. */
+    readonly flushed: "anyreplay:flushed";
+    /** main → renderer: an uncaught exception in the main process. */
+    readonly mainError: "anyreplay:main-error";
+};
+/** What the main process says about the app. */
+interface AppInfo {
+    /** The app id (§2.2 of the SDK contract), already checked against the id pattern. Absent when none could be found. */
+    appId?: string;
+    /** `app.getVersion()`. */
+    appVersion?: string;
+}
+/** An uncaught exception in the main process, as sent to a window. Raw: the renderer redacts it. */
+interface MainErrorMessage {
+    name?: string;
+    message: string;
+    stack?: string;
+}
+/**
+ * What the preload script exposes on `window.anyreplayElectron`.
+ *
+ * Deliberately narrow: three fixed channels, no generic `send` or `invoke`, so
+ * exposing it gives page script no more reach into the main process than
+ * asking for the app's version and answering a flush.
+ */
+interface AnyReplayBridge {
+    /** The bridge's own version, so a newer renderer can tell an older preload apart. */
+    readonly version: 1;
+    appInfo: () => Promise<AppInfo>;
+    /** The renderer's flush; called when the main process is about to quit. Replaces any earlier one. */
+    onFlushRequest: (flush: () => Promise<void> | void) => void;
+    /** Called with each main-process error forwarded to this window. Replaces any earlier listener. */
+    onMainError: (listener: (error: MainErrorMessage) => void) => void;
+}
+
+export { type AppInfo as A, BRIDGE_KEY as B, CHANNELS as C, type MainErrorMessage as M, type AnyReplayBridge as a };

package/dist/chunk-5TQ2HVGX.js

@@ -0,0 +1,18 @@
+// src/bridge.ts
+var BRIDGE_KEY = "anyreplayElectron";
+var CHANNELS = {
+  /** renderer → main (invoke): `AppInfo`. */
+  appInfo: "anyreplay:app-info",
+  /** main → renderer: flush now, then answer on `flushed` with the same id. */
+  flush: "anyreplay:flush",
+  /** renderer → main: a flush asked for by `flush` has finished. */
+  flushed: "anyreplay:flushed",
+  /** main → renderer: an uncaught exception in the main process. */
+  mainError: "anyreplay:main-error"
+};
+
+export {
+  BRIDGE_KEY,
+  CHANNELS
+};
+//# sourceMappingURL=chunk-5TQ2HVGX.js.map

package/dist/chunk-5TQ2HVGX.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/bridge.ts"],"sourcesContent":["/**\n * The contract between the three halves of the Electron SDK.\n *\n * The renderer records; the preload script is the only code that can talk to\n * the main process; the main process knows the app's id and version and sees\n * the app quit. They share nothing but these names, so each entry point can be\n * imported on its own without pulling in the others (or the recorder, which\n * has no business in the main process).\n */\n\n/** The global the preload script exposes through `contextBridge`. */\nexport const BRIDGE_KEY = 'anyreplayElectron';\n\n/** IPC channels. All of them, so a reviewer can see exactly what crosses. */\nexport const CHANNELS = {\n  /** renderer → main (invoke): `AppInfo`. */\n  appInfo: 'anyreplay:app-info',\n  /** main → renderer: flush now, then answer on `flushed` with the same id. */\n  flush: 'anyreplay:flush',\n  /** renderer → main: a flush asked for by `flush` has finished. */\n  flushed: 'anyreplay:flushed',\n  /** main → renderer: an uncaught exception in the main process. */\n  mainError: 'anyreplay:main-error',\n} as const;\n\n/** What the main process says about the app. */\nexport interface AppInfo {\n  /** The app id (§2.2 of the SDK contract), already checked against the id pattern. Absent when none could be found. */\n  appId?: string;\n  /** `app.getVersion()`. */\n  appVersion?: string;\n}\n\n/** An uncaught exception in the main process, as sent to a window. Raw: the renderer redacts it. */\nexport interface MainErrorMessage {\n  name?: string;\n  message: string;\n  stack?: string;\n}\n\n/**\n * What the preload script exposes on `window.anyreplayElectron`.\n *\n * Deliberately narrow: three fixed channels, no generic `send` or `invoke`, so\n * exposing it gives page script no more reach into the main process than\n * asking for the app's version and answering a flush.\n */\nexport interface AnyReplayBridge {\n  /** The bridge's own version, so a newer renderer can tell an older preload apart. */\n  readonly version: 1;\n  appInfo: () => Promise<AppInfo>;\n  /** The renderer's flush; called when the main process is about to quit. Replaces any earlier one. */\n  onFlushRequest: (flush: () => Promise<void> | void) => void;\n  /** Called with each main-process error forwarded to this window. Replaces any earlier listener. */\n  onMainError: (listener: (error: MainErrorMessage) => void) => void;\n}\n"],"mappings":";AAWO,IAAM,aAAa;AAGnB,IAAM,WAAW;AAAA;AAAA,EAEtB,SAAS;AAAA;AAAA,EAET,OAAO;AAAA;AAAA,EAEP,SAAS;AAAA;AAAA,EAET,WAAW;AACb;","names":[]}

package/dist/index.cjs

@@ -0,0 +1,177 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  BRIDGE_KEY: () => BRIDGE_KEY,
+  CHANNELS: () => CHANNELS,
+  SDK_NAME: () => SDK_NAME,
+  SDK_VERSION: () => SDK_VERSION,
+  __resetForTests: () => __resetForTests,
+  electronSetup: () => electronSetup,
+  init: () => init,
+  mainError: () => mainError
+});
+module.exports = __toCommonJS(src_exports);
+
+// src/bridge.ts
+var BRIDGE_KEY = "anyreplayElectron";
+var CHANNELS = {
+  /** renderer → main (invoke): `AppInfo`. */
+  appInfo: "anyreplay:app-info",
+  /** main → renderer: flush now, then answer on `flushed` with the same id. */
+  flush: "anyreplay:flush",
+  /** renderer → main: a flush asked for by `flush` has finished. */
+  flushed: "anyreplay:flushed",
+  /** main → renderer: an uncaught exception in the main process. */
+  mainError: "anyreplay:main-error"
+};
+
+// src/version.ts
+var SDK_NAME = "@anyreplay/electron";
+var SDK_VERSION = true ? "0.2.1" : "0.0.0-dev";
+var PLATFORM = "electron";
+
+// src/web-family.ts
+var import_browser = require("@anyreplay/browser");
+var MAX_QUEUED = 64;
+function deferredRecorder(start, onStarted) {
+  let real = null;
+  let stopped = false;
+  const queue = [];
+  const run = (call) => {
+    if (real) {
+      call(real);
+      return;
+    }
+    if (stopped || queue.length >= MAX_QUEUED) return;
+    queue.push(call);
+  };
+  const ready = start().then((setup) => {
+    if (!setup || stopped) return;
+    real = (0, import_browser.createRecorder)(setup.options, setup.shell);
+    for (const call of queue.splice(0)) call(real);
+    onStarted?.(real);
+  }).catch((error) => {
+    if (typeof console !== "undefined") console.warn("[anyreplay]", error);
+  });
+  return {
+    ready,
+    status: () => real ? real.status() : stopped ? "stopped" : "idle",
+    sessionId: () => real?.sessionId() ?? null,
+    consent: (granted) => run((h) => h.consent(granted)),
+    identify: (traits) => run((h) => h.identify(traits)),
+    track: (name, properties) => run((h) => h.track(name, properties)),
+    trackError: (error) => run((h) => h.trackError(error)),
+    stop: () => {
+      if (real) real.stop();
+      else {
+        stopped = true;
+        queue.length = 0;
+      }
+    },
+    flush: async () => {
+      await ready;
+      await real?.flush();
+    }
+  };
+}
+var APP_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{1,254}$/;
+var clipVersion = (version) => {
+  const trimmed = version?.trim();
+  return trimmed ? trimmed.slice(0, 40) : void 0;
+};
+
+// src/index.ts
+var current = null;
+function init(options) {
+  if (current) return current;
+  const bridge = findBridge();
+  const { flushOnBlur = true, ...rest } = options;
+  const handle = deferredRecorder(
+    async () => {
+      const info = bridge ? await bridge.appInfo() : {};
+      return electronSetup(rest, info);
+    },
+    (recorder) => wire(recorder, bridge, flushOnBlur)
+  );
+  current = handle;
+  return handle;
+}
+function electronSetup(options, info) {
+  const appId = options.appId?.trim() || info.appId;
+  if (!appId && typeof console !== "undefined") {
+    console.warn("[anyreplay] no appId: call setupAnyReplay({ appId }) in the main process and exposeAnyReplay() in the preload. A project that lists allowed apps refuses sessions without one.");
+  }
+  if (appId && !APP_ID_PATTERN.test(appId)) {
+    throw new Error(`anyreplay: appId ${JSON.stringify(appId)} should be an app identifier such as com.example.app`);
+  }
+  const { appVersion: ownVersion, ...browserOptions } = options;
+  const appVersion = clipVersion(ownVersion ?? info.appVersion);
+  return {
+    options: {
+      // Inline unless the app says otherwise: a window loaded from the app's
+      // own files has addresses no reviewer can load (contract §9.1).
+      assets: "inline",
+      ...browserOptions,
+      ...appId ? { appId } : {}
+    },
+    shell: {
+      platform: PLATFORM,
+      sdk: { name: SDK_NAME, version: SDK_VERSION },
+      ...appVersion ? { appVersion } : {}
+    }
+  };
+}
+function wire(recorder, bridge, flushOnBlur) {
+  bridge?.onFlushRequest(() => recorder.flush());
+  bridge?.onMainError((error) => recorder.trackError(mainError(error)));
+  if (flushOnBlur && typeof window !== "undefined") {
+    window.addEventListener("blur", () => {
+      void recorder.flush();
+    });
+  }
+}
+function mainError(error) {
+  const value = new Error(typeof error?.message === "string" ? error.message : "error");
+  value.name = typeof error?.name === "string" && error.name ? error.name : "Error";
+  value.stack = typeof error?.stack === "string" ? error.stack : "";
+  return value;
+}
+function findBridge() {
+  const candidate = globalThis[BRIDGE_KEY];
+  return candidate && typeof candidate.appInfo === "function" ? candidate : null;
+}
+function __resetForTests() {
+  current?.stop();
+  current = null;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  BRIDGE_KEY,
+  CHANNELS,
+  SDK_NAME,
+  SDK_VERSION,
+  __resetForTests,
+  electronSetup,
+  init,
+  mainError
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/bridge.ts","../src/version.ts","../src/web-family.ts"],"sourcesContent":["import type { AnyReplayOptions, RecorderHandle } from '@anyreplay/browser';\nimport { BRIDGE_KEY, type AnyReplayBridge, type AppInfo, type MainErrorMessage } from './bridge.js';\nimport { PLATFORM, SDK_NAME, SDK_VERSION } from './version.js';\nimport { APP_ID_PATTERN, clipVersion, deferredRecorder, type DeferredHandle, type RecorderSetup } from './web-family.js';\n\nexport { BRIDGE_KEY, CHANNELS, type AnyReplayBridge, type AppInfo, type MainErrorMessage } from './bridge.js';\nexport { SDK_NAME, SDK_VERSION } from './version.js';\nexport type { RecorderSetup } from './web-family.js';\n\nexport interface AnyReplayElectronOptions extends AnyReplayOptions {\n  /**\n   * The app id. Normally left out: the main process supplies it\n   * (`setupAnyReplay({ appId })`). Set here, it wins.\n   */\n  appId?: string;\n  /** The app version. Normally left out: the main process supplies `app.getVersion()`. */\n  appVersion?: string;\n  /**\n   * Send what has been recorded whenever the window loses focus. On by\n   * default: a desktop app is rarely closed the way a tab is, and the main\n   * process can be killed without `before-quit`.\n   */\n  flushOnBlur?: boolean;\n}\n\nexport type AnyReplayElectron = DeferredHandle;\n\nlet current: AnyReplayElectron | null = null;\n\n/**\n * Starts recording this window. Call it once in the renderer, as early as you\n * can:\n *\n * ```ts\n * import { init } from '@anyreplay/electron';\n * const replay = init({ projectKey: 'ar_pk_live_…' });\n * replay.track('document_opened');\n * ```\n *\n * The app id and version come from the main process through the preload\n * bridge (`exposeAnyReplay()` and `setupAnyReplay()`), so recording starts a\n * moment after this returns; calls made in between are queued. A second call\n * returns the first handle.\n *\n * Each window is its own session: the session id lives in the window's\n * `sessionStorage`, the visitor id in `localStorage`, which Electron keeps\n * across launches and shares between windows of the same session partition.\n */\nexport function init(options: AnyReplayElectronOptions): AnyReplayElectron {\n  if (current) return current;\n  const bridge = findBridge();\n  const { flushOnBlur = true, ...rest } = options;\n\n  const handle = deferredRecorder(\n    async () => {\n      const info: AppInfo = bridge ? await bridge.appInfo() : {};\n      return electronSetup(rest, info);\n    },\n    (recorder) => wire(recorder, bridge, flushOnBlur),\n  );\n  current = handle;\n  return handle;\n}\n\n/**\n * The browser SDK's options for this window — the installer's, with the app\n * id filled in — and the shell it runs in, which only the wrapper knows.\n */\nexport function electronSetup(options: AnyReplayElectronOptions, info: AppInfo): RecorderSetup {\n  const appId = options.appId?.trim() || info.appId;\n  if (!appId && typeof console !== 'undefined') {\n    console.warn('[anyreplay] no appId: call setupAnyReplay({ appId }) in the main process and exposeAnyReplay() in the preload. A project that lists allowed apps refuses sessions without one.');\n  }\n  if (appId && !APP_ID_PATTERN.test(appId)) {\n    // Thrown by the browser SDK too; said here in the shell's own terms.\n    throw new Error(`anyreplay: appId ${JSON.stringify(appId)} should be an app identifier such as com.example.app`);\n  }\n  const { appVersion: ownVersion, ...browserOptions } = options;\n  const appVersion = clipVersion(ownVersion ?? info.appVersion);\n  return {\n    options: {\n      // Inline unless the app says otherwise: a window loaded from the app's\n      // own files has addresses no reviewer can load (contract §9.1).\n      assets: 'inline',\n      ...browserOptions,\n      ...(appId ? { appId } : {}),\n    },\n    shell: {\n      platform: PLATFORM,\n      sdk: { name: SDK_NAME, version: SDK_VERSION },\n      ...(appVersion ? { appVersion } : {}),\n    },\n  };\n}\n\nfunction wire(recorder: RecorderHandle, bridge: AnyReplayBridge | null, flushOnBlur: boolean): void {\n  bridge?.onFlushRequest(() => recorder.flush());\n  // An error like the window's own: the same `anyreplay.error` event, the same\n  // redaction and ceiling, and the session's `hasError` set (contract §8.3).\n  bridge?.onMainError((error) => recorder.trackError(mainError(error)));\n  if (flushOnBlur && typeof window !== 'undefined') {\n    window.addEventListener('blur', () => { void recorder.flush(); });\n  }\n}\n\n/**\n * A main-process error as an `Error` again — it crossed IPC as plain fields —\n * for the browser SDK to redact and clip like any other.\n */\nexport function mainError(error: MainErrorMessage | undefined): Error {\n  const value = new Error(typeof error?.message === 'string' ? error.message : 'error');\n  value.name = typeof error?.name === 'string' && error.name ? error.name : 'Error';\n  value.stack = typeof error?.stack === 'string' ? error.stack : '';\n  return value;\n}\n\nfunction findBridge(): AnyReplayBridge | null {\n  const candidate = (globalThis as Record<string, unknown>)[BRIDGE_KEY] as AnyReplayBridge | undefined;\n  return candidate && typeof candidate.appInfo === 'function' ? candidate : null;\n}\n\n/** For tests: forget the handle `init` returned. */\nexport function __resetForTests(): void {\n  current?.stop();\n  current = null;\n}\n","/**\n * The contract between the three halves of the Electron SDK.\n *\n * The renderer records; the preload script is the only code that can talk to\n * the main process; the main process knows the app's id and version and sees\n * the app quit. They share nothing but these names, so each entry point can be\n * imported on its own without pulling in the others (or the recorder, which\n * has no business in the main process).\n */\n\n/** The global the preload script exposes through `contextBridge`. */\nexport const BRIDGE_KEY = 'anyreplayElectron';\n\n/** IPC channels. All of them, so a reviewer can see exactly what crosses. */\nexport const CHANNELS = {\n  /** renderer → main (invoke): `AppInfo`. */\n  appInfo: 'anyreplay:app-info',\n  /** main → renderer: flush now, then answer on `flushed` with the same id. */\n  flush: 'anyreplay:flush',\n  /** renderer → main: a flush asked for by `flush` has finished. */\n  flushed: 'anyreplay:flushed',\n  /** main → renderer: an uncaught exception in the main process. */\n  mainError: 'anyreplay:main-error',\n} as const;\n\n/** What the main process says about the app. */\nexport interface AppInfo {\n  /** The app id (§2.2 of the SDK contract), already checked against the id pattern. Absent when none could be found. */\n  appId?: string;\n  /** `app.getVersion()`. */\n  appVersion?: string;\n}\n\n/** An uncaught exception in the main process, as sent to a window. Raw: the renderer redacts it. */\nexport interface MainErrorMessage {\n  name?: string;\n  message: string;\n  stack?: string;\n}\n\n/**\n * What the preload script exposes on `window.anyreplayElectron`.\n *\n * Deliberately narrow: three fixed channels, no generic `send` or `invoke`, so\n * exposing it gives page script no more reach into the main process than\n * asking for the app's version and answering a flush.\n */\nexport interface AnyReplayBridge {\n  /** The bridge's own version, so a newer renderer can tell an older preload apart. */\n  readonly version: 1;\n  appInfo: () => Promise<AppInfo>;\n  /** The renderer's flush; called when the main process is about to quit. Replaces any earlier one. */\n  onFlushRequest: (flush: () => Promise<void> | void) => void;\n  /** Called with each main-process error forwarded to this window. Replaces any earlier listener. */\n  onMainError: (listener: (error: MainErrorMessage) => void) => void;\n}\n","/**\n * Which SDK recorded a session (docs/SDK-CONTRACT.md §2.4).\n *\n * The version is written in at build time by tsup (and by Vitest for the\n * tests) from package.json, as in the browser SDK; source used without that\n * step reports `0.0.0-dev`.\n */\ndeclare const __ANYREPLAY_SDK_VERSION__: string | undefined;\n\nexport const SDK_NAME = '@anyreplay/electron';\n\nexport const SDK_VERSION: string =\n  typeof __ANYREPLAY_SDK_VERSION__ === 'string' ? __ANYREPLAY_SDK_VERSION__ : '0.0.0-dev';\n\nexport const PLATFORM = 'electron';\n","import {\n  createRecorder, type AnyReplayOptions, type RecorderHandle, type RecorderStatus, type ShellInfo,\n} from '@anyreplay/browser';\n\n/**\n * What a desktop shell hands the browser SDK: its options, and who is\n * recording (docs/SDK-CONTRACT.md §1, §4) — the platform and SDK the session\n * reports and the app's version. `createRecorder(options, shell)` is how a\n * wrapper names itself without a public option a website could set.\n */\nexport interface RecorderSetup {\n  options: AnyReplayOptions;\n  shell: ShellInfo;\n}\n\n/**\n * A recorder handle that exists before the recorder does.\n *\n * A shell learns its app id and version asynchronously (an IPC round trip in\n * Electron, a Tauri command), but `init` has to hand something back at once so\n * an app can call `track` on its next line. Calls made in between are queued\n * in order and replayed on the real handle; `flush` waits for it.\n */\nexport interface DeferredHandle extends RecorderHandle {\n  /** Resolves once the recorder has started (or failed to). Never rejects. */\n  ready: Promise<void>;\n}\n\ntype Queued = (handle: RecorderHandle) => void;\n\n/** At most this many calls wait for the app info; enough for a boot sequence. */\nconst MAX_QUEUED = 64;\n\nexport function deferredRecorder(\n  start: () => Promise<RecorderSetup | null>,\n  onStarted?: (handle: RecorderHandle) => void,\n): DeferredHandle {\n  let real: RecorderHandle | null = null;\n  let stopped = false;\n  const queue: Queued[] = [];\n\n  const run = (call: Queued): void => {\n    if (real) {\n      call(real);\n      return;\n    }\n    if (stopped || queue.length >= MAX_QUEUED) return;\n    queue.push(call);\n  };\n\n  const ready = start()\n    .then((setup) => {\n      if (!setup || stopped) return;\n      real = createRecorder(setup.options, setup.shell);\n      for (const call of queue.splice(0)) call(real);\n      onStarted?.(real);\n    })\n    .catch((error: unknown) => {\n      // Nothing this library does may surface as an error in the app.\n      if (typeof console !== 'undefined') console.warn('[anyreplay]', error);\n    });\n\n  return {\n    ready,\n    status: (): RecorderStatus => (real ? real.status() : stopped ? 'stopped' : 'idle'),\n    sessionId: () => real?.sessionId() ?? null,\n    consent: (granted) => run((h) => h.consent(granted)),\n    identify: (traits) => run((h) => h.identify(traits)),\n    track: (name, properties) => run((h) => h.track(name, properties)),\n    trackError: (error) => run((h) => h.trackError(error)),\n    stop: () => {\n      if (real) real.stop();\n      else { stopped = true; queue.length = 0; }\n    },\n    flush: async () => {\n      await ready;\n      await real?.flush();\n    },\n  };\n}\n\n/** The browser SDK's app-id rule (`APP_ID_PATTERN`), so a bad id is caught here with a better message. */\nexport const APP_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{1,254}$/;\n\n/** `meta.appVersion` is at most 40 characters (§2.5). */\nexport const clipVersion = (version: string | undefined): string | undefined => {\n  const trimmed = version?.trim();\n  return trimmed ? trimmed.slice(0, 40) : undefined;\n};\n"],"mappings":"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","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,80 @@
+import { RecorderHandle, AnyReplayOptions, ShellInfo } from '@anyreplay/browser';
+import { A as AppInfo, M as MainErrorMessage } from './bridge-BQKD7rrG.cjs';
+export { a as AnyReplayBridge, B as BRIDGE_KEY, C as CHANNELS } from './bridge-BQKD7rrG.cjs';
+
+/**
+ * What a desktop shell hands the browser SDK: its options, and who is
+ * recording (docs/SDK-CONTRACT.md §1, §4) — the platform and SDK the session
+ * reports and the app's version. `createRecorder(options, shell)` is how a
+ * wrapper names itself without a public option a website could set.
+ */
+interface RecorderSetup {
+    options: AnyReplayOptions;
+    shell: ShellInfo;
+}
+/**
+ * A recorder handle that exists before the recorder does.
+ *
+ * A shell learns its app id and version asynchronously (an IPC round trip in
+ * Electron, a Tauri command), but `init` has to hand something back at once so
+ * an app can call `track` on its next line. Calls made in between are queued
+ * in order and replayed on the real handle; `flush` waits for it.
+ */
+interface DeferredHandle extends RecorderHandle {
+    /** Resolves once the recorder has started (or failed to). Never rejects. */
+    ready: Promise<void>;
+}
+
+declare const SDK_NAME = "@anyreplay/electron";
+declare const SDK_VERSION: string;
+
+interface AnyReplayElectronOptions extends AnyReplayOptions {
+    /**
+     * The app id. Normally left out: the main process supplies it
+     * (`setupAnyReplay({ appId })`). Set here, it wins.
+     */
+    appId?: string;
+    /** The app version. Normally left out: the main process supplies `app.getVersion()`. */
+    appVersion?: string;
+    /**
+     * Send what has been recorded whenever the window loses focus. On by
+     * default: a desktop app is rarely closed the way a tab is, and the main
+     * process can be killed without `before-quit`.
+     */
+    flushOnBlur?: boolean;
+}
+type AnyReplayElectron = DeferredHandle;
+/**
+ * Starts recording this window. Call it once in the renderer, as early as you
+ * can:
+ *
+ * ```ts
+ * import { init } from '@anyreplay/electron';
+ * const replay = init({ projectKey: 'ar_pk_live_…' });
+ * replay.track('document_opened');
+ * ```
+ *
+ * The app id and version come from the main process through the preload
+ * bridge (`exposeAnyReplay()` and `setupAnyReplay()`), so recording starts a
+ * moment after this returns; calls made in between are queued. A second call
+ * returns the first handle.
+ *
+ * Each window is its own session: the session id lives in the window's
+ * `sessionStorage`, the visitor id in `localStorage`, which Electron keeps
+ * across launches and shares between windows of the same session partition.
+ */
+declare function init(options: AnyReplayElectronOptions): AnyReplayElectron;
+/**
+ * The browser SDK's options for this window — the installer's, with the app
+ * id filled in — and the shell it runs in, which only the wrapper knows.
+ */
+declare function electronSetup(options: AnyReplayElectronOptions, info: AppInfo): RecorderSetup;
+/**
+ * A main-process error as an `Error` again — it crossed IPC as plain fields —
+ * for the browser SDK to redact and clip like any other.
+ */
+declare function mainError(error: MainErrorMessage | undefined): Error;
+/** For tests: forget the handle `init` returned. */
+declare function __resetForTests(): void;
+
+export { type AnyReplayElectron, type AnyReplayElectronOptions, AppInfo, MainErrorMessage, type RecorderSetup, SDK_NAME, SDK_VERSION, __resetForTests, electronSetup, init, mainError };

package/dist/index.d.ts

@@ -0,0 +1,80 @@
+import { RecorderHandle, AnyReplayOptions, ShellInfo } from '@anyreplay/browser';
+import { A as AppInfo, M as MainErrorMessage } from './bridge-BQKD7rrG.js';
+export { a as AnyReplayBridge, B as BRIDGE_KEY, C as CHANNELS } from './bridge-BQKD7rrG.js';
+
+/**
+ * What a desktop shell hands the browser SDK: its options, and who is
+ * recording (docs/SDK-CONTRACT.md §1, §4) — the platform and SDK the session
+ * reports and the app's version. `createRecorder(options, shell)` is how a
+ * wrapper names itself without a public option a website could set.
+ */
+interface RecorderSetup {
+    options: AnyReplayOptions;
+    shell: ShellInfo;
+}
+/**
+ * A recorder handle that exists before the recorder does.
+ *
+ * A shell learns its app id and version asynchronously (an IPC round trip in
+ * Electron, a Tauri command), but `init` has to hand something back at once so
+ * an app can call `track` on its next line. Calls made in between are queued
+ * in order and replayed on the real handle; `flush` waits for it.
+ */
+interface DeferredHandle extends RecorderHandle {
+    /** Resolves once the recorder has started (or failed to). Never rejects. */
+    ready: Promise<void>;
+}
+
+declare const SDK_NAME = "@anyreplay/electron";
+declare const SDK_VERSION: string;
+
+interface AnyReplayElectronOptions extends AnyReplayOptions {
+    /**
+     * The app id. Normally left out: the main process supplies it
+     * (`setupAnyReplay({ appId })`). Set here, it wins.
+     */
+    appId?: string;
+    /** The app version. Normally left out: the main process supplies `app.getVersion()`. */
+    appVersion?: string;
+    /**
+     * Send what has been recorded whenever the window loses focus. On by
+     * default: a desktop app is rarely closed the way a tab is, and the main
+     * process can be killed without `before-quit`.
+     */
+    flushOnBlur?: boolean;
+}
+type AnyReplayElectron = DeferredHandle;
+/**
+ * Starts recording this window. Call it once in the renderer, as early as you
+ * can:
+ *
+ * ```ts
+ * import { init } from '@anyreplay/electron';
+ * const replay = init({ projectKey: 'ar_pk_live_…' });
+ * replay.track('document_opened');
+ * ```
+ *
+ * The app id and version come from the main process through the preload
+ * bridge (`exposeAnyReplay()` and `setupAnyReplay()`), so recording starts a
+ * moment after this returns; calls made in between are queued. A second call
+ * returns the first handle.
+ *
+ * Each window is its own session: the session id lives in the window's
+ * `sessionStorage`, the visitor id in `localStorage`, which Electron keeps
+ * across launches and shares between windows of the same session partition.
+ */
+declare function init(options: AnyReplayElectronOptions): AnyReplayElectron;
+/**
+ * The browser SDK's options for this window — the installer's, with the app
+ * id filled in — and the shell it runs in, which only the wrapper knows.
+ */
+declare function electronSetup(options: AnyReplayElectronOptions, info: AppInfo): RecorderSetup;
+/**
+ * A main-process error as an `Error` again — it crossed IPC as plain fields —
+ * for the browser SDK to redact and clip like any other.
+ */
+declare function mainError(error: MainErrorMessage | undefined): Error;
+/** For tests: forget the handle `init` returned. */
+declare function __resetForTests(): void;
+
+export { type AnyReplayElectron, type AnyReplayElectronOptions, AppInfo, MainErrorMessage, type RecorderSetup, SDK_NAME, SDK_VERSION, __resetForTests, electronSetup, init, mainError };