@lightworkai.official/debug-capture 0.6.0

package/src/capture/cause.ts

@@ -0,0 +1,49 @@
+// Derives the "smoking gun" summary from the captured buffers: failed requests,
+// uncaught errors, and errored React Query keys. Surfaced at the top of the
+// report so a developer sees the likely cause immediately.
+
+import type {
+  CapturedConsoleEntry,
+  CapturedRequest,
+  CauseSummary,
+  ErroredQuery,
+} from '../types';
+
+const MAX_ITEMS = 20;
+
+export function computeCause(
+  network: CapturedRequest[],
+  consoleLog: CapturedConsoleEntry[],
+  erroredQueries: ErroredQuery[],
+): CauseSummary {
+  const failedRequests = network
+    .filter((req) => Boolean(req.error) || (req.status != null && req.status >= 400))
+    .slice(-MAX_ITEMS)
+    .map((req) => ({
+      method: req.method,
+      url: req.url,
+      status: req.status,
+      error: req.error,
+      at: req.startedAt,
+    }));
+
+  const errors = consoleLog
+    .filter(
+      (entry) =>
+        entry.level === 'error' ||
+        entry.level === 'exception' ||
+        entry.level === 'unhandledrejection',
+    )
+    .slice(-MAX_ITEMS)
+    .map((entry) => entry.message);
+
+  return {
+    failedRequests,
+    errors,
+    erroredQueries: erroredQueries.slice(0, MAX_ITEMS),
+  };
+}
+
+export function causeCount(cause: CauseSummary): number {
+  return cause.failedRequests.length + cause.errors.length + cause.erroredQueries.length;
+}

package/src/capture/consoleBuffer.ts

@@ -0,0 +1,80 @@
+// Rolling console + error capture. Patches console methods and the global
+// error/unhandledrejection events into a bounded ring buffer, so when the user
+// reports an issue we have the recent log tail that led up to it.
+
+import { captureOption } from '../config';
+import type { CapturedConsoleEntry, ConsoleEntryKind, ConsoleLevel } from '../types';
+
+const MAX_MSG_LEN = 2000;
+
+let buffer: CapturedConsoleEntry[] = [];
+let counter = 0;
+let installed = false;
+
+function push(level: ConsoleEntryKind, message: string): void {
+  counter += 1;
+  buffer.push({
+    id: `log_${counter}`,
+    at: new Date().toISOString(),
+    level,
+    message: message.length > MAX_MSG_LEN ? `${message.slice(0, MAX_MSG_LEN)}…` : message,
+  });
+  while (buffer.length > captureOption('maxConsoleEntries')) buffer.shift();
+}
+
+function safeReplacer(): (key: string, value: unknown) => unknown {
+  const seen = new WeakSet<object>();
+  return (_key, value) => {
+    if (typeof value === 'object' && value !== null) {
+      if (seen.has(value)) return '[Circular]';
+      seen.add(value);
+    }
+    if (typeof value === 'bigint') return value.toString();
+    return value;
+  };
+}
+
+function stringifyArg(arg: unknown): string {
+  if (typeof arg === 'string') return arg;
+  if (arg instanceof Error) return `${arg.name}: ${arg.message}`;
+  try {
+    return JSON.stringify(arg, safeReplacer()) ?? String(arg);
+  } catch {
+    return String(arg);
+  }
+}
+
+export function installConsoleCapture(): void {
+  if (installed || typeof window === 'undefined') return;
+  installed = true;
+
+  const levels: ConsoleLevel[] = ['log', 'info', 'warn', 'error', 'debug'];
+  for (const level of levels) {
+    const original = console[level].bind(console) as (...args: unknown[]) => void;
+    console[level] = ((...args: unknown[]) => {
+      push(level, args.map(stringifyArg).join(' '));
+      original(...args);
+    }) as Console[ConsoleLevel];
+  }
+
+  window.addEventListener('error', (event: ErrorEvent) => {
+    const where = event.filename ? ` (${event.filename}:${event.lineno}:${event.colno})` : '';
+    push('exception', `${event.message}${where}`);
+  });
+
+  window.addEventListener('unhandledrejection', (event: PromiseRejectionEvent) => {
+    const reason =
+      event.reason instanceof Error
+        ? `${event.reason.name}: ${event.reason.message}`
+        : stringifyArg(event.reason);
+    push('unhandledrejection', reason);
+  });
+}
+
+export function getConsoleLog(): CapturedConsoleEntry[] {
+  return buffer.map((entry) => ({ ...entry }));
+}
+
+export function clearConsoleLog(): void {
+  buffer = [];
+}

package/src/capture/crashWatcher.ts

@@ -0,0 +1,61 @@
+// Auto-catch uncaught runtime errors and promise rejections, and announce them
+// on the crash channel so the host can invite the user to file a report. This
+// catches bugs users would otherwise never mention.
+
+import { emitCrash } from '../reporter';
+import type { DebugReason } from '../types';
+
+const THROTTLE_MS = 15000;
+
+// Benign / noisy errors that shouldn't nag the user.
+const IGNORED = [
+  'ResizeObserver loop',
+  'Script error.',
+  'Non-Error promise rejection captured',
+];
+
+let installed = false;
+let lastPromptAt = 0;
+
+function isIgnored(message: string): boolean {
+  return IGNORED.some((needle) => message.includes(needle));
+}
+
+function promptReport(reason: DebugReason): void {
+  const message = reason.message ?? '';
+  if (!message || isIgnored(message)) return;
+  // Manual throttle (Date.now avoided elsewhere, but fine in app code).
+  const now = Date.now();
+  if (now - lastPromptAt < THROTTLE_MS) return;
+  lastPromptAt = now;
+
+  // Announce it and stop. Whether that becomes a toast, a banner or nothing is
+  // the host's call — and it must NOT open the reporter by itself: screen
+  // capture needs a real click behind it.
+  emitCrash({ ...reason, message });
+}
+
+export function installCrashWatcher(): void {
+  if (installed || typeof window === 'undefined') return;
+  installed = true;
+
+  window.addEventListener('error', (event: ErrorEvent) => {
+    // Resource-load errors (img/script) have no message/error — ignore them.
+    if (!event.message && !event.error) return;
+    const error = event.error instanceof Error ? event.error : null;
+    promptReport({
+      type: 'runtime-error',
+      message: event.message || (error ? error.message : 'Unknown error'),
+      stack: error?.stack,
+    });
+  });
+
+  window.addEventListener('unhandledrejection', (event: PromiseRejectionEvent) => {
+    const reason = event.reason;
+    promptReport({
+      type: 'unhandledrejection',
+      message: reason instanceof Error ? reason.message : String(reason),
+      stack: reason instanceof Error ? reason.stack : undefined,
+    });
+  });
+}

package/src/capture/networkBuffer.ts

@@ -0,0 +1,315 @@
+// Rolling network capture. The app has no axios — every API call funnels
+// through native `fetch` (a custom client) and a few integrations use `fetch`
+// directly, so patching `window.fetch` (plus XHR for completeness) is the one
+// chokepoint that records everything. Entries land in a bounded ring buffer;
+// headers/urls/bodies are redacted at capture time.
+
+import { captureOption, mayCaptureBody } from '../config';
+import { redactBody, redactHeaders, redactUrl } from './redact';
+import type { CapturedRequest } from '../types';
+
+
+const MAX_REQ_BODY = 4000;
+// Per-response body cap — generous enough to store virtually any API response in
+// FULL (most are < 100 KB), so the developer reads the whole body, not a snippet.
+// Skip reading responses larger than this (by Content-Length) to bound memory.
+const MAX_RES_BYTES = 1_000_000; // 1 MB
+// Total budget across ALL captured response bodies, enforced at snapshot time
+// (getNetworkLog). The whole bundle ships as ONE multipart part capped at 15 MB
+// by the backend — keep well under it so a report never fails to submit. Newest
+// responses keep their full body; once the budget is spent, older bodies are
+// replaced with a small marker.
+const MAX_TOTAL_RES_BYTES = 10_000_000; // 10 MB
+
+let buffer: CapturedRequest[] = [];
+let counter = 0;
+let installed = false;
+
+function push(entry: CapturedRequest): void {
+  buffer.push(entry);
+  while (buffer.length > captureOption('maxRequests')) buffer.shift();
+}
+
+function nextId(): string {
+  counter += 1;
+  return `req_${counter}`;
+}
+
+function headersToObject(input: HeadersInit | undefined): Record<string, string> {
+  const out: Record<string, string> = {};
+  if (!input) return out;
+  if (input instanceof Headers) {
+    input.forEach((value, key) => {
+      out[key] = value;
+    });
+  } else if (Array.isArray(input)) {
+    for (const [key, value] of input) out[key] = value;
+  } else {
+    Object.assign(out, input);
+  }
+  return out;
+}
+
+function responseHeadersToObject(headers: Headers): Record<string, string> {
+  const out: Record<string, string> = {};
+  headers.forEach((value, key) => {
+    out[key] = value;
+  });
+  return out;
+}
+
+function bodyToString(body: BodyInit | null | undefined): string | null {
+  if (body == null) return null;
+  if (typeof body === 'string') return body;
+  if (body instanceof URLSearchParams) return body.toString();
+  if (typeof FormData !== 'undefined' && body instanceof FormData) {
+    return `[FormData: ${Array.from(body.keys()).join(', ')}]`;
+  }
+  if (typeof Blob !== 'undefined' && body instanceof Blob) return `[Blob ${body.size} bytes]`;
+  if (body instanceof ArrayBuffer) return `[ArrayBuffer ${body.byteLength} bytes]`;
+  return '[binary]';
+}
+
+function resolveRequestMeta(
+  input: RequestInfo | URL,
+  init?: RequestInit,
+): { method: string; url: string; headers: Record<string, string>; body: string | null } {
+  let url = '';
+  let method = 'GET';
+  let headers: Record<string, string> = {};
+  let body: string | null = null;
+
+  if (typeof input === 'string') {
+    url = input;
+  } else if (input instanceof URL) {
+    url = input.toString();
+  } else {
+    // Request object
+    url = input.url;
+    method = input.method || method;
+    headers = headersToObject(input.headers);
+  }
+  if (init) {
+    if (init.method) method = init.method;
+    if (init.headers) headers = { ...headers, ...headersToObject(init.headers) };
+    if (init.body !== undefined) body = bodyToString(init.body);
+  }
+  return { method: method.toUpperCase(), url, headers, body };
+}
+
+/**
+ * Endpoints whose response BODY must never be stored.
+ *
+ * A support ticket's row carries the whole debug bundle, so capturing the
+ * ticket API's responses makes every report contain the previous reports. A
+ * widget's own `/ingest/*` calls are this library talking to itself, and a
+ * third party's body is not ours to collect unless the host named its origin.
+ *
+ * NOT the support host's whole origin — see `mayCaptureBody`. Excluding that
+ * left a self-hosted support app unable to capture any body at all.
+ *
+ * Only the body is dropped. Method, URL, status and duration are still
+ * recorded, so the request remains visible in the timeline and still counts
+ * toward a step's correlation — the part a reader actually uses.
+ */
+function bodyExcluded(url: string): boolean {
+  return !mayCaptureBody(url);
+}
+
+function captureResponseSnippet(response: Response, entry: CapturedRequest): void {
+  if (bodyExcluded(entry.url)) {
+    entry.responseSnippet = '[body not captured for this origin]';
+    return;
+  }
+  const contentType = response.headers.get('content-type') ?? '';
+  const contentLength = Number(response.headers.get('content-length') ?? '0');
+  const sizeNote = contentLength ? `, ~${contentLength} bytes` : '';
+  // Binary bodies (pdf/images/blobs): record a descriptor, don't read bytes.
+  if (!/json|text|xml|html|javascript|urlencoded/i.test(contentType)) {
+    entry.responseSnippet = `[binary ${contentType || 'unknown'}${sizeNote}]`;
+    return;
+  }
+  if (contentLength > MAX_RES_BYTES) {
+    entry.responseSnippet = `[response ${contentType || 'text'}${sizeNote} — omitted]`;
+    return;
+  }
+  try {
+    // Fire-and-forget on a clone so we never delay or consume the app's body.
+    response
+      .clone()
+      .text()
+      .then((text) => {
+        entry.responseSnippet = redactBody(text, captureOption('maxBodyChars'));
+      })
+      .catch(() => {
+        /* ignore — best effort */
+      });
+  } catch {
+    /* clone can throw if the body was already read — ignore */
+  }
+}
+
+// Next.js App Router runs client navigation + <Link> prefetching through
+// `fetch` — every such request carries a `_rsc` cache-busting query param and/or
+// `RSC` / `Next-Router-Prefetch` request headers, and returns an RSC flight
+// payload (not JSON the app consumes). It's framework chatter, not the app's
+// API calls: it buries the real Fetch/XHR and, worse, evicts genuine API calls
+// from the bounded ring buffer. Skip it at the source.
+function isFrameworkNoise(url: string, headers: Record<string, string>): boolean {
+  if (/[?&]_rsc=/.test(url)) return true;
+  for (const key of Object.keys(headers)) {
+    const k = key.toLowerCase();
+    if (k === 'rsc' || k === 'next-router-prefetch' || k === 'next-router-state-tree') {
+      return true;
+    }
+  }
+  return false;
+}
+
+function installFetch(): void {
+  if (typeof window === 'undefined' || typeof window.fetch !== 'function') return;
+  const original = window.fetch.bind(window);
+
+  // Object.assign keeps whatever statics the platform hangs off fetch
+  // (`preconnect` in newer runtimes). Replacing it with a bare function drops
+  // them, and something else on the page may be relying on one.
+  window.fetch = Object.assign(async (input: RequestInfo | URL, init?: RequestInit): Promise<Response> => {
+    const meta = resolveRequestMeta(input, init);
+    // Don't record Next.js RSC navigation/prefetch — capture real requests only.
+    if (isFrameworkNoise(meta.url, meta.headers)) return original(input, init);
+    const entry: CapturedRequest = {
+      id: nextId(),
+      startedAt: new Date().toISOString(),
+      method: meta.method,
+      url: redactUrl(meta.url),
+      requestHeaders: redactHeaders(meta.headers),
+      requestBody: redactBody(meta.body, MAX_REQ_BODY),
+      status: null,
+      statusText: null,
+      durationMs: null,
+      via: 'fetch',
+    };
+    push(entry);
+
+    const start = performance.now();
+    try {
+      const response = await original(input, init);
+      entry.status = response.status;
+      entry.statusText = response.statusText;
+      entry.durationMs = Math.round(performance.now() - start);
+      entry.responseHeaders = redactHeaders(responseHeadersToObject(response.headers));
+      captureResponseSnippet(response, entry);
+      return response;
+    } catch (err) {
+      entry.durationMs = Math.round(performance.now() - start);
+      entry.error = err instanceof Error ? `${err.name}: ${err.message}` : String(err);
+      throw err;
+    }
+  }, original);
+}
+
+interface PatchedXhr extends XMLHttpRequest {
+  __cibEntry?: CapturedRequest;
+  __cibStart?: number;
+}
+
+function installXhr(): void {
+  if (typeof window === 'undefined' || typeof window.XMLHttpRequest !== 'function') return;
+  const proto = XMLHttpRequest.prototype;
+  const originalOpen = proto.open;
+  const originalSend = proto.send;
+
+  const patchedOpen = function (this: PatchedXhr, method: string, url: string | URL): void {
+    const urlStr = typeof url === 'string' ? url : url.toString();
+    // Skip framework chatter (headers aren't set yet at open() — URL is enough).
+    this.__cibEntry = isFrameworkNoise(urlStr, {})
+      ? undefined
+      : {
+          id: nextId(),
+          startedAt: '',
+          method: (method || 'GET').toUpperCase(),
+          url: redactUrl(urlStr),
+          requestHeaders: {},
+          requestBody: null,
+          status: null,
+          statusText: null,
+          durationMs: null,
+          via: 'xhr',
+        };
+    // eslint-disable-next-line prefer-rest-params
+    return originalOpen.apply(this, arguments as unknown as Parameters<typeof originalOpen>);
+  };
+
+  const patchedSend = function (
+    this: PatchedXhr,
+    body?: Document | XMLHttpRequestBodyInit | null,
+  ): void {
+    const entry = this.__cibEntry;
+    if (entry) {
+      entry.startedAt = new Date().toISOString();
+      entry.requestBody =
+        typeof body === 'string'
+          ? redactBody(body, MAX_REQ_BODY)
+          : body == null
+            ? null
+            : '[non-string body]';
+      const start = performance.now();
+      push(entry);
+      this.addEventListener('loadend', () => {
+        entry.status = this.status || null;
+        entry.statusText = this.statusText || null;
+        entry.durationMs = Math.round(performance.now() - start);
+        // Only string responseText is readable ('' / 'text' response types);
+        // for blob/arraybuffer/json response types record a descriptor.
+        if (bodyExcluded(entry.url)) {
+          entry.responseSnippet = '[body not captured for this origin]';
+        } else if (this.responseType === '' || this.responseType === 'text') {
+          try {
+            entry.responseSnippet = redactBody(this.responseText || '', captureOption('maxBodyChars'));
+          } catch {
+            /* responseText may throw for some response types — ignore */
+          }
+        } else {
+          const ct = this.getResponseHeader('content-type') ?? this.responseType;
+          entry.responseSnippet = `[binary ${ct}]`;
+        }
+      });
+    }
+    // eslint-disable-next-line prefer-rest-params
+    return originalSend.apply(this, arguments as unknown as Parameters<typeof originalSend>);
+  };
+
+  proto.open = patchedOpen as typeof proto.open;
+  proto.send = patchedSend as typeof proto.send;
+}
+
+export function installNetworkCapture(): void {
+  if (installed) return;
+  installed = true;
+  installFetch();
+  installXhr();
+}
+
+export function getNetworkLog(): CapturedRequest[] {
+  // Shallow clones so consumers can't mutate the live buffer.
+  const clones = buffer.map((entry) => ({ ...entry }));
+  // Enforce the total response-body budget newest-first: keep full bodies until
+  // the budget is spent, then replace older ones with a marker so the assembled
+  // report stays comfortably under the backend's 15 MB multipart part cap.
+  let used = 0;
+  for (let i = clones.length - 1; i >= 0; i -= 1) {
+    const clone = clones[i];
+    const body = clone?.responseSnippet;
+    if (!clone || typeof body !== 'string' || body.length === 0) continue;
+    if (used + body.length > MAX_TOTAL_RES_BYTES) {
+      clone.responseSnippet = `[response omitted — report size budget reached (${body.length.toLocaleString()} chars)]`;
+    } else {
+      used += body.length;
+    }
+  }
+  return clones;
+}
+
+export function clearNetworkLog(): void {
+  buffer = [];
+}

package/src/capture/redact.ts

@@ -0,0 +1,117 @@
+// Redaction — strips secrets before anything is shown, copied, or downloaded.
+// A debug bundle is meant to be pasted into a chat / ticket, so tokens,
+// cookies, and credentials must never survive into it.
+//
+// The built-in lists cover what is standard. They cannot cover what is not:
+// every app has a header or a body key that is a credential only there, so a
+// consumer extends these through `redact` in the config. A library that only
+// knew Authorization and Cookie would be a library that leaks.
+
+import { getRedactOptions } from '../config';
+
+export const REDACTED = '‹redacted›';
+
+const SENSITIVE_HEADER_RE =
+  /^(authorization|proxy-authorization|cookie|set-cookie|x-[a-z-]*token|x-csrf[a-z-]*|x-xsrf[a-z-]*)$/i;
+
+const SENSITIVE_QUERY_KEYS = new Set([
+  'access_token',
+  'token',
+  'id_token',
+  'refresh_token',
+  'code',
+  'secret',
+  'client_secret',
+  'password',
+  'apikey',
+  'api_key',
+  'signature',
+  'x-amz-signature',
+  'x-amz-credential',
+]);
+
+const SENSITIVE_BODY_KEY_RE =
+  /(password|passwd|token|secret|authorization|refresh|client_secret|otp|pin)/i;
+
+// PII patterns for action-trail LABELS (visible UI text captured from clicks /
+// field names). Conservative on purpose — only high-confidence identifiers, so
+// meaningful labels ("2 รายการ", "16:35", "2569") are never masked:
+//   • email addresses
+//   • long digit runs (≥9) — phone / national-id / account numbers (allowing
+//     spaces or dashes as separators, e.g. "081-234-5678", "1 2345 67890 12 3")
+const EMAIL_RE = /[\w.+-]+@[\w-]+\.[\w.-]+/g;
+const LONG_NUMBER_RE = /\d(?:[\d\s-]{7,})\d/g;
+
+/** Strip likely PII (emails, phone/ID number runs) from a captured UI label.
+ *  Labels come from visible text, so they rarely hold secrets — but a container's
+ *  text can carry a reporter's name/number, and tickets are shown to admins. */
+export function redactLabel(text: string): string {
+  return text.replace(EMAIL_RE, REDACTED).replace(LONG_NUMBER_RE, REDACTED);
+}
+
+function isSensitiveHeader(key: string): boolean {
+  if (SENSITIVE_HEADER_RE.test(key)) return true;
+  const extra = getRedactOptions().headers;
+  return extra.some((name) => name.toLowerCase() === key.toLowerCase());
+}
+
+export function redactHeaders(headers: Record<string, string>): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [key, value] of Object.entries(headers)) {
+    out[key] = isSensitiveHeader(key) ? REDACTED : value;
+  }
+  return out;
+}
+
+export function redactUrl(rawUrl: string): string {
+  try {
+    const isAbsolute = /^https?:\/\//i.test(rawUrl);
+    // Relative URLs need a base to parse; the placeholder origin is discarded
+    // on output so we return the original relative shape.
+    const url = new URL(rawUrl, isAbsolute ? undefined : 'http://local.invalid');
+    let changed = false;
+    url.searchParams.forEach((_value, key) => {
+      if (SENSITIVE_QUERY_KEYS.has(key.toLowerCase()) || getRedactOptions().queryKeys.includes(key.toLowerCase())) {
+        url.searchParams.set(key, REDACTED);
+        changed = true;
+      }
+    });
+    if (!changed) return rawUrl;
+    return isAbsolute ? url.toString() : `${url.pathname}${url.search}`;
+  } catch {
+    return rawUrl;
+  }
+}
+
+/** Deep-redact object values whose keys look sensitive. Returns a new value. */
+function redactValue(value: unknown, depth: number): unknown {
+  if (depth > 6 || value === null || typeof value !== 'object') return value;
+  if (Array.isArray(value)) return value.map((item) => redactValue(item, depth + 1));
+  const out: Record<string, unknown> = {};
+  for (const [key, val] of Object.entries(value as Record<string, unknown>)) {
+    const sensitive =
+      SENSITIVE_BODY_KEY_RE.test(key) ||
+      getRedactOptions().bodyKeys.some((needle) => key.toLowerCase().includes(needle));
+    out[key] = sensitive ? REDACTED : redactValue(val, depth + 1);
+  }
+  return out;
+}
+
+/** Redact + truncate a request/response body string. */
+export function redactBody(body: string | null, maxLen: number): string | null {
+  if (body == null) return null;
+  let text = body;
+  const trimmed = body.trim();
+  if (trimmed.startsWith('{') || trimmed.startsWith('[')) {
+    try {
+      const parsed: unknown = JSON.parse(trimmed);
+      text = JSON.stringify(redactValue(parsed, 0));
+    } catch {
+      // Not JSON — keep the raw text (still truncated below).
+    }
+  }
+  if (text.length > maxLen) {
+    return `${text.slice(0, maxLen)}… [truncated ${text.length - maxLen} chars]`;
+  }
+  return text;
+}