@lightworkai.official/debug-capture 0.6.0

package/src/types.ts

@@ -0,0 +1,169 @@
+/**
+ * The shape of a debug bundle.
+ *
+ * A bundle is a redacted, client-side snapshot of what the user was doing when
+ * something went wrong — recent network requests, console output, the trail of
+ * actions that led there, page/session context, a cause summary, and a
+ * screenshot. It is assembled entirely in the browser so support can reproduce
+ * an issue without a round of "what were you clicking".
+ *
+ * What changed on the way out of the original in-app reporter: anything that
+ * described ONE app — a Thai unit hierarchy, a permission-bypass dev flag, a
+ * fixed module vocabulary — is gone. Those arrive through config now, because a
+ * library that ships another company's org chart is not a library.
+ */
+
+export type CaptureVia = "fetch" | "xhr";
+
+export interface CapturedRequest {
+  id: string;
+  /** ISO timestamp when the request started. */
+  startedAt: string;
+  method: string;
+  /** Redacted URL (sensitive query params masked). */
+  url: string;
+  /** Redacted request headers. */
+  requestHeaders: Record<string, string>;
+  /** Redacted + truncated request body (JSON string / marker / null). */
+  requestBody: string | null;
+  status: number | null;
+  statusText: string | null;
+  /** Redacted response headers. */
+  responseHeaders?: Record<string, string>;
+  /**
+   * Redacted response body, in full up to a per-response cap — not a snippet.
+   * Only captured for origins the consumer allowed: see `capture.bodyOrigins`.
+   */
+  responseSnippet?: string | null;
+  durationMs: number | null;
+  /** Populated when the request rejected (network error / abort). */
+  error?: string;
+  via: CaptureVia;
+}
+
+export type ConsoleLevel = "log" | "info" | "warn" | "error" | "debug";
+export type ConsoleEntryKind = ConsoleLevel | "exception" | "unhandledrejection";
+
+export interface CapturedConsoleEntry {
+  id: string;
+  at: string;
+  level: ConsoleEntryKind;
+  /** Human-readable, truncated message. */
+  message: string;
+}
+
+export type ActionKind = "click" | "input" | "navigate" | "submit" | "ui";
+
+export interface ActionTrailEntry {
+  id: string;
+  at: string;
+  kind: ActionKind;
+  /** Human-readable description, e.g. `click ปุ่ม "บันทึกร่าง"`. */
+  detail: string;
+  /** Consecutive identical actions are collapsed; this is how many. */
+  count?: number;
+  /** Where a click leads — from the link's href or the nearest click target. */
+  source?: string;
+  /**
+   * A small, sanitized+redacted `outerHTML` of the clicked element, so a reader
+   * can see the ACTUAL control rather than a text label. Omitted when too large.
+   *
+   * MUST be re-sanitized before rendering. It is attacker-influenced markup that
+   * has travelled between origins.
+   */
+  html?: string;
+  /**
+   * The same control a moment later, once it visibly changed — disabled, busy,
+   * relabelled, or gone. A button's resting state says what was pressed; this
+   * says what pressing it DID, which is the half that was missing.
+   */
+  afterHtml?: string;
+  /** One-line summary of that change, present even if `afterHtml` was dropped. */
+  afterNote?: string;
+}
+
+export type DebugReasonType = "manual" | "runtime-error" | "unhandledrejection" | "framework-error";
+
+export interface DebugReason {
+  type: DebugReasonType;
+  message?: string;
+  stack?: string;
+}
+
+/** A failed data-layer query the host chose to report (react-query, Apollo, …). */
+export interface ErroredQuery {
+  key: string;
+  error: string;
+}
+
+export interface FailedRequestSummary {
+  method: string;
+  url: string;
+  status: number | null;
+  error?: string;
+  at: string;
+}
+
+/** The "smoking gun" — surfaced at the top of the report. */
+export interface CauseSummary {
+  failedRequests: FailedRequestSummary[];
+  errors: string[];
+  erroredQueries: ErroredQuery[];
+}
+
+/**
+ * Who was using the app. Every field optional: the library cannot know what a
+ * host knows about its users, and a half-filled identity is worth more than a
+ * shape the host has to lie to satisfy.
+ */
+export interface DebugUser {
+  id?: string | null;
+  email?: string | null;
+  fullName?: string | null;
+  /** Department / unit / team — whatever the host calls the thing. */
+  unit?: string | null;
+  roles?: string[];
+}
+
+export interface DebugContext {
+  capturedAt: string;
+  route: { href: string; pathname: string; search: string };
+  /** Which part of the app this was, when the host declares one. */
+  module: { key: string; label: string } | null;
+  user: DebugUser;
+  /** Host-supplied request headers, redacted. Acting-as context and the like. */
+  apiHeaders: Record<string, string>;
+  app: { name: string; version: string; environment: string };
+  client: {
+    userAgent: string;
+    language: string;
+    platform: string;
+    online: boolean;
+    viewport: { width: number; height: number; dpr: number };
+    screen: { width: number; height: number };
+  };
+  performance: {
+    memoryUsedMb: number | null;
+    memoryLimitMb: number | null;
+    domContentLoadedMs: number | null;
+    loadEventMs: number | null;
+  };
+  /** Anything else the host wants on the record — feature flags, build id, … */
+  extra: Record<string, unknown>;
+}
+
+export type ScreenshotMethod = "display-media" | "html-to-image" | "none" | "cancelled";
+
+export interface DebugBundle {
+  context: DebugContext;
+  reason: DebugReason;
+  note: string;
+  cause: CauseSummary;
+  actionTrail: ActionTrailEntry[];
+  network: CapturedRequest[];
+  console: CapturedConsoleEntry[];
+  /** PNG data URL, or null if capture failed / was skipped. */
+  screenshotDataUrl: string | null;
+  screenshotMethod: ScreenshotMethod;
+  meta: { generatedBy: string; schemaVersion: number };
+}