@usereelay/browser 0.1.0

package/README.md

@@ -0,0 +1,152 @@
+# @usereelay/browser
+
+Reelay error tracking for browsers. Captures uncaught errors and unhandled
+promise rejections, records click/console/fetch breadcrumbs and a
+masked-by-default DOM session replay, and stitches frontend sessions to
+backend traces — with **zero runtime dependencies** and a hard rule of zero
+host-app disruption.
+
+Standalone project: everything the SDK needs (transport, PII scrubbing,
+stack parsing, trace ids, replay) is built in. Ships as a single ESM bundle
+(~22 KB unminified) plus CJS + types.
+
+## Install
+
+```bash
+# from npm (when published)
+npm install @usereelay/browser
+
+# or as a local file dependency
+npm install /path/to/reelay-browser-sdk
+```
+
+## Quick start
+
+```ts
+import * as Reelay from '@usereelay/browser';
+
+Reelay.init({
+  endpoint: 'https://api.usereelay.com', // your Reelay ingest base URL
+  token: 'rlyt_live_…',                  // node API key for this frontend
+  release: 'web@' + import.meta.env.VITE_GIT_SHA,
+  environment: 'production',
+  // Origins that receive trace headers so backend errors link to this session:
+  tracePropagationTargets: ['https://api.acme.com'],
+});
+```
+
+Call `init()` once, as early as possible (before your app boots). Everything
+else is automatic. The built `dist/index.js` is dependency-free ESM, so it
+also works without a bundler:
+
+```html
+<script type="module">
+  import * as Reelay from '/vendor/reelay-browser.js';
+  Reelay.init({ endpoint: '…', token: '…' });
+</script>
+```
+
+## What each piece does
+
+| Export / feature | Purpose |
+|---|---|
+| `init(options)` | Creates the singleton client and installs all instrumentation. Idempotent — repeat calls return the existing client. |
+| Global error capture | `window` `error` + `unhandledrejection` via `addEventListener` — never by overwriting `window.onerror`, so other tooling keeps working. |
+| Breadcrumbs | Clicks (element descriptor only, no text), `popstate` navigations, `console.error`/`console.warn` (wrapped, originals preserved), and every `fetch` (method + URL + status). Ring buffer of the latest 50, attached to every event. |
+| Fetch trace stitching | For URLs matching `tracePropagationTargets`, outgoing requests get W3C `traceparent` + `reelay-session-id` headers. The `@usereelay/node` middleware adopts them, so a backend error and this page's replay share one `trace_id`. Same-origin only by default; **never** cross-origin unless you allow-list it. |
+| Session replay | Initial DOM snapshot + `MutationObserver` deltas, serialized inside `requestIdleCallback`, shipped as sequenced chunks every 5 s. With `maskAllText` (default) every text node is masked **before** serialization and inputs are always masked — content never leaves the page. |
+| `captureException(err)` | Manually report a handled error. Returns the event id (`''` if dropped). |
+| `captureMessage(msg)` | Report a string message as an event. |
+| `getClient()` | The active `BrowserClient` (exposes `sessionId`, `addBreadcrumb`, `flush`, `uninstall`). |
+
+## Options
+
+```ts
+Reelay.init({
+  endpoint: 'https://api.usereelay.com', // required: ingest base URL
+  token: 'rlyt_live_…',                  // required: node API key
+  release: 'web@abc123',                 // optional: ties events to a deploy
+  environment: 'production',             // optional
+  sampleRate: 1,                         // 0–1 probability an event is sent
+  beforeSend: (event) => event,          // mutate or return null to drop
+  scrubPatterns: [/order-\d{6}/g],       // extra PII regexes (additive)
+  maxQueueSize: 30,                      // offline/retry buffer (drop-oldest)
+  tracePropagationTargets: [             // origins/patterns that get trace headers
+    'https://api.acme.com',
+    /^https:\/\/.*\.internal\.acme\.com/,
+  ],
+  replay: true,                          // DOM session replay on/off
+  maskAllText: true,                     // mask every text node in replay
+  debug: (msg, detail) => {},            // SDK self-diagnostics (silent by default)
+});
+```
+
+## Engineering guarantees
+
+- **Zero host disruption** — every listener and public API runs inside a
+  defensive boundary; SDK failures go to the `debug` hook, never your app.
+  `fetch` wrapping preserves the original's exact arguments/return; failed
+  instrumentation degrades to a passthrough call.
+- **Performance budget** — replay serialization runs in `requestIdleCallback`,
+  click listeners are passive + capture-phase, breadcrumbs are an O(1) ring
+  buffer; nothing blocks the UI thread, so LCP/INP/CLS are unaffected.
+- **No data loss on navigation** — events flush on `visibilitychange: hidden`
+  using `keepalive` fetch, which survives page unload.
+- **PII never leaves the page** — sensitive keys redacted wholesale; tokens,
+  JWTs, card numbers and emails pattern-scrubbed; replay masks all text and
+  all input values by default.
+- **Bounded memory** — breadcrumb ring (50), transport queue (30,
+  drop-oldest), replay delta buffer (500), traced-request map (100).
+
+## Source maps (frontend symbolication)
+
+Production bundles are minified, so raw stack frames point at hashed files like
+`assets/index-a1b2c3.js:1:54023`. To see original files, lines, and function
+names in Reelay, provision your source maps at build/deploy time with the
+bundled `reelay-sourcemaps` CLI.
+
+```bash
+# 1. Build your app with source maps enabled (prefer hidden-source-map so the
+#    maps are emitted but not referenced from shipped JS).
+npm run build
+
+# 2. Inject debug ids into the built JS + maps (the robust, release-independent
+#    match key), then upload the maps to Reelay.
+npx reelay-sourcemaps inject-and-upload ./dist \
+  --url https://api.reelay.app \
+  --token "$REELAY_TOKEN" \
+  --release "web@$(git rev-parse --short HEAD)" \
+  --delete   # remove .map files after upload so they never reach your CDN
+```
+
+`--url`, `--token`, and `--release` also read from `REELAY_URL`, `REELAY_TOKEN`,
+and `REELAY_RELEASE`. Set the **same `release`** in `Reelay.init({ release })`
+so release-based matching works even for bundles without debug ids.
+
+How it works:
+
+- **Debug ids (preferred).** `inject` stamps each chunk with a content-derived
+  id, recorded both in the JS (a tiny runtime snippet) and in the map. The SDK
+  reads that registry at capture time and tags each frame with its bundle's
+  debug id, so the backend resolves the exact map regardless of release naming
+  or CDN hashing. The injector offsets the map's `mappings` for the one line it
+  adds, so positions stay exact.
+- **Release + filename (fallback).** When a frame has no debug id, the backend
+  matches on the event's `release` and the minified file's basename.
+- Already using a Sentry bundler plugin? The SDK also reads `_sentryDebugIds`,
+  so existing debug ids are picked up with no extra tooling.
+
+Source maps expose original source — Reelay stores them privately, never serves
+them back, and expires them on the same retention window as your events.
+
+## Development
+
+```bash
+npm install
+npm run build      # tsup → dist/ (ESM + CJS + .d.ts)
+npm test           # vitest
+npm run typecheck
+```
+
+See `../reelay-test-project/frontend` for a runnable page wired up with this
+SDK (including buttons that trigger every class of frontend error).

package/bin/reelay-sourcemaps.mjs

@@ -0,0 +1,277 @@
+#!/usr/bin/env node
+/**
+ * reelay-sourcemaps — build/deploy-time source-map provisioning for the Reelay
+ * browser SDK. Zero dependencies; runs on Node 18+ (uses global fetch).
+ *
+ *   reelay-sourcemaps inject <dir>              Inject debug ids into built JS + maps
+ *   reelay-sourcemaps upload <dir> [opts]       Upload maps to Reelay
+ *   reelay-sourcemaps inject-and-upload <dir>   Both, in order
+ *
+ * Options (or env: REELAY_URL, REELAY_TOKEN, REELAY_RELEASE):
+ *   --url <endpoint>     Reelay ingestion base URL          [REELAY_URL]
+ *   --token <token>      Node API key (rlyt_live_…)          [REELAY_TOKEN]
+ *   --release <release>  Release tag matching your SDK init  [REELAY_RELEASE]
+ *   --delete             Delete .map files after a successful upload
+ *
+ * Debug ids are the primary, unambiguous match key: each bundle is stamped with
+ * a content-derived id recorded both in the JS (a tiny runtime snippet the SDK
+ * reads) and in the map. `upload` also sends release+filename as a fallback, so
+ * symbolication works even for bundlers that emit no debug ids.
+ *
+ * Source maps expose original source — keep them private. Prefer `hidden-source-map`
+ * (no sourceMappingURL comment in shipped JS) and pass --delete so maps never
+ * reach your CDN.
+ */
+import { createHash } from 'node:crypto';
+import { readFileSync, writeFileSync, rmSync, readdirSync, statSync } from 'node:fs';
+import { join, basename, dirname, resolve } from 'node:path';
+
+const JS_EXT = /\.(?:js|mjs|cjs)$/;
+const SOURCE_MAPPING_URL = /\/\/# sourceMappingURL=([^\s'"]+)\s*$/m;
+const DEBUG_ID_COMMENT = /\/\/# debugId=([0-9a-fA-F-]+)/;
+
+function log(msg) {
+  process.stdout.write(`[reelay-sourcemaps] ${msg}\n`);
+}
+function warn(msg) {
+  process.stderr.write(`[reelay-sourcemaps] WARN ${msg}\n`);
+}
+function fail(msg) {
+  process.stderr.write(`[reelay-sourcemaps] ERROR ${msg}\n`);
+  process.exit(1);
+}
+
+/** Deterministic UUIDv4-shaped id from content, so re-runs are idempotent. */
+function debugIdFromContent(buf) {
+  const h = createHash('sha256').update(buf).digest();
+  const b = Buffer.from(h.subarray(0, 16));
+  b[6] = (b[6] & 0x0f) | 0x40; // version 4
+  b[8] = (b[8] & 0x3f) | 0x80; // variant 10
+  const hex = b.toString('hex');
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+
+function walk(dir, out = []) {
+  for (const entry of readdirSync(dir)) {
+    const full = join(dir, entry);
+    const st = statSync(full);
+    if (st.isDirectory()) walk(full, out);
+    else out.push(full);
+  }
+  return out;
+}
+
+/** Resolves the map path for a JS file via its sourceMappingURL or `<js>.map`. */
+function mapPathFor(jsFile, jsText) {
+  const m = SOURCE_MAPPING_URL.exec(jsText);
+  if (m && m[1] && !m[1].startsWith('data:')) {
+    return resolve(dirname(jsFile), m[1]);
+  }
+  const sibling = `${jsFile}.map`;
+  try {
+    statSync(sibling);
+    return sibling;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Runtime snippet recording this chunk's debug id, keyed by a freshly-captured
+ * stack so the SDK can map script URL -> debug id. One physical line; we prepend
+ * exactly one `;` to the map's mappings to offset the inserted generated line.
+ */
+function injectionSnippet(debugId) {
+  return (
+    `;!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:` +
+    `"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},` +
+    `n=(new e.Error).stack;n&&(e._reelayDebugIds=e._reelayDebugIds||{},` +
+    `e._reelayDebugIds[n]="${debugId}")}catch(e){}}();`
+  );
+}
+
+function injectPair(jsFile, jsText) {
+  const existing = DEBUG_ID_COMMENT.exec(jsText);
+  const mapFile = mapPathFor(jsFile, jsText);
+  if (!mapFile) {
+    return { status: 'skipped', reason: 'no source map' };
+  }
+
+  let map;
+  try {
+    map = JSON.parse(readFileSync(mapFile, 'utf8'));
+  } catch {
+    return { status: 'skipped', reason: 'unparseable map' };
+  }
+  if (map.version !== 3 || typeof map.mappings !== 'string') {
+    // Indexed maps (sections) would need per-section offsetting; skip rather
+    // than risk corrupting the mapping.
+    return { status: 'skipped', reason: 'unsupported map (not flat v3)' };
+  }
+
+  // Idempotent: if already injected, just make sure the map carries the id.
+  if (existing) {
+    const debugId = existing[1];
+    if (map.debugId !== debugId || map.debug_id !== debugId) {
+      map.debugId = debugId;
+      map.debug_id = debugId;
+      writeFileSync(mapFile, JSON.stringify(map));
+    }
+    return { status: 'already', debugId, mapFile };
+  }
+
+  const debugId = debugIdFromContent(jsText);
+  const snippet = injectionSnippet(debugId);
+
+  // Prepend snippet as one full line; original code keeps its columns and moves
+  // down one generated line, which we offset with a single leading ';'.
+  let next = `${snippet}\n${jsText}`;
+  next = next.replace(/\s*$/, '');
+  next += `\n//# debugId=${debugId}\n`;
+  writeFileSync(jsFile, next);
+
+  map.mappings = `;${map.mappings}`;
+  map.debugId = debugId;
+  map.debug_id = debugId;
+  writeFileSync(mapFile, JSON.stringify(map));
+
+  return { status: 'injected', debugId, mapFile };
+}
+
+function cmdInject(dir) {
+  let injected = 0;
+  let already = 0;
+  for (const file of walk(dir)) {
+    if (!JS_EXT.test(file)) continue;
+    let jsText;
+    try {
+      jsText = readFileSync(file, 'utf8');
+    } catch {
+      continue;
+    }
+    const res = injectPair(file, jsText);
+    if (res.status === 'injected') {
+      injected++;
+      log(`injected ${res.debugId} -> ${basename(file)}`);
+    } else if (res.status === 'already') {
+      already++;
+    }
+  }
+  log(`inject complete: ${injected} injected, ${already} already done`);
+}
+
+async function uploadMap(opts, mapFile) {
+  let map;
+  try {
+    map = JSON.parse(readFileSync(mapFile, 'utf8'));
+  } catch {
+    warn(`skipping unreadable map ${mapFile}`);
+    return false;
+  }
+  const debugId = map.debugId || map.debug_id || '';
+  // Minified file the map belongs to: prefer the map's own `file`, else strip
+  // the .map suffix. Sent as the release+filename fallback key.
+  const file = basename(map.file || mapFile.replace(/\.map$/, ''));
+
+  if (!debugId && !opts.release) {
+    warn(`skipping ${basename(mapFile)}: no debug id and no --release to key on`);
+    return false;
+  }
+
+  const body = JSON.stringify({
+    release: opts.release || undefined,
+    debug_id: debugId || undefined,
+    file,
+    sourcemap: readFileSync(mapFile, 'utf8'),
+  });
+
+  const res = await fetch(`${opts.url.replace(/\/$/, '')}/api/ingest/sourcemaps`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json', 'X-Reelay-Token': opts.token },
+    body,
+  });
+  if (!res.ok) {
+    const text = await res.text().catch(() => '');
+    warn(`upload failed for ${basename(mapFile)}: ${res.status} ${text.slice(0, 200)}`);
+    return false;
+  }
+  log(`uploaded ${basename(mapFile)}${debugId ? ` (debugId ${debugId})` : ''}`);
+  if (opts.delete) rmSync(mapFile);
+  return true;
+}
+
+async function cmdUpload(dir, opts) {
+  if (!opts.url) fail('missing --url (or REELAY_URL)');
+  if (!opts.token) fail('missing --token (or REELAY_TOKEN)');
+
+  const maps = walk(dir).filter((f) => f.endsWith('.map'));
+  if (maps.length === 0) {
+    warn(`no .map files found under ${dir}`);
+    return;
+  }
+  let ok = 0;
+  for (const mapFile of maps) {
+    if (await uploadMap(opts, mapFile)) ok++;
+  }
+  log(`upload complete: ${ok}/${maps.length} maps stored`);
+}
+
+function parseArgs(argv) {
+  const opts = {
+    url: process.env.REELAY_URL || process.env.REELAY_ENDPOINT || '',
+    token: process.env.REELAY_TOKEN || '',
+    release: process.env.REELAY_RELEASE || '',
+    delete: false,
+    _: [],
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    switch (a) {
+      case '--url': opts.url = argv[++i]; break;
+      case '--token': opts.token = argv[++i]; break;
+      case '--release': opts.release = argv[++i]; break;
+      case '--delete': opts.delete = true; break;
+      default: opts._.push(a);
+    }
+  }
+  return opts;
+}
+
+async function main() {
+  const [, , command, ...rest] = process.argv;
+  const opts = parseArgs(rest);
+  const dir = opts._[0];
+
+  if (!command || command === '--help' || command === '-h') {
+    process.stdout.write(
+      'Usage:\n' +
+        '  reelay-sourcemaps inject <dir>\n' +
+        '  reelay-sourcemaps upload <dir> --url <u> --token <t> [--release <r>] [--delete]\n' +
+        '  reelay-sourcemaps inject-and-upload <dir> --url <u> --token <t> [--release <r>] [--delete]\n',
+    );
+    return;
+  }
+  if (!dir) fail('missing <dir> argument');
+  try {
+    statSync(dir);
+  } catch {
+    fail(`directory not found: ${dir}`);
+  }
+
+  switch (command) {
+    case 'inject':
+      cmdInject(dir);
+      break;
+    case 'upload':
+      await cmdUpload(dir, opts);
+      break;
+    case 'inject-and-upload':
+      cmdInject(dir);
+      await cmdUpload(dir, opts);
+      break;
+    default:
+      fail(`unknown command: ${command}`);
+  }
+}
+
+main().catch((err) => fail(err?.stack || String(err)));