@sphoro/bugcatch-web-sdk 0.14.4 → 0.16.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sphoro/bugcatch-web-sdk",
-  "version": "0.14.4",
+  "version": "0.16.0",
   "description": "Drop-in browser SDK — report bugs with console, network and environment context, without the extension.",
   "type": "module",
   "main": "dist/bugcatch.es.js",

package/src/identity.js

@@ -0,0 +1,277 @@
+/**
+ * Who is reporting, what they are looking at, and whether init() was given
+ * something that can work — shaped here, before anything is sent.
+ *
+ * Pure and import-free so the unit tests load it directly. Every function takes
+ * a `warn(message)` callback instead of calling console itself: the client
+ * decides whether (and how often) a warning is printed, and the tests collect
+ * them.
+ *
+ * WHY THE BUSINESS IDS HAVE NAMES. A lending app knows exactly which customer is
+ * signed in and which loan is on screen. Passed as `loanId`, `applicationId` or
+ * `customerNumber`, the API reads them as identifiers the app itself asserted
+ * (reference source `identify`), which is what lets bugcatch look the customer
+ * up in the lender's own system over MCP without asking the reporter — and lets
+ * that lookup count as a trusted join. Passed under any other name they are
+ * still sent, but only as metadata a person can read.
+ *
+ * WHERE THEY GO. The signed-in user's fields travel as `metadata.user`, which is
+ * where the API has always read `id` and where the ownership check reads `phone`
+ * and `email`. The current screen travels as `metadata.context`. Both shapes are
+ * mirrored by bugcatch-api/src/settings/reference-extract.ts identifyReferences.
+ */
+
+/** Longest identifier the API keeps; anything longer is dropped there too. */
+export const MAX_ID_CHARS = 120;
+/** Longest free-form string value kept on user or context. */
+export const MAX_TEXT_CHARS = 500;
+/** Most extra (non-standard) keys kept on user or context. */
+export const MAX_EXTRA_KEYS = 30;
+/** Largest nested object or array kept, as JSON. */
+const MAX_NESTED_JSON = 1000;
+
+/**
+ * The identifier fields bugcatch understands, and the names each accepts.
+ * The first name is canonical; the rest are accepted and rewritten to it so the
+ * API sees one spelling.
+ */
+export const ID_FIELDS = {
+  loanId: ['loanId', 'loanNumber'],
+  applicationId: ['applicationId'],
+  customerNumber: ['customerNumber', 'customerId'],
+};
+
+const CONTROL = /[\u0000-\u001f\u007f]/;
+
+/** An identifier: a non-empty string or finite number, as a trimmed string, or null. */
+export function idValue(raw) {
+  if (typeof raw === 'number') return Number.isFinite(raw) ? String(raw) : null;
+  if (typeof raw !== 'string') return null;
+  const v = raw.trim();
+  if (!v || v.length > MAX_ID_CHARS || CONTROL.test(v)) return null;
+  return v;
+}
+
+function describe(v) {
+  if (v === null) return 'null';
+  if (Array.isArray(v)) return 'an array';
+  return typeof v === 'object' ? 'an object' : `a ${typeof v}`;
+}
+
+/** Read one identifier field (under any of its names) off `src`, warning on a bad value. */
+function readId(src, canonical, names, where, warn) {
+  for (const name of names) {
+    if (!(name in src) || src[name] === undefined || src[name] === null || src[name] === '') continue;
+    const v = idValue(src[name]);
+    if (v) return v;
+    const raw = src[name];
+    warn(typeof raw === 'string' && raw.trim().length > MAX_ID_CHARS
+      ? `${where}.${name} is longer than ${MAX_ID_CHARS} characters and was dropped — pass the identifier itself, not a sentence or a URL.`
+      : `${where}.${name} should be a string or number, got ${describe(raw)} — it was dropped.`);
+  }
+  return null;
+}
+
+/** An extra field worth keeping: a primitive, or a small plain object / array. */
+function extraValue(v) {
+  if (v === null || typeof v === 'boolean') return { ok: true, value: v };
+  if (typeof v === 'number') return Number.isFinite(v) ? { ok: true, value: v } : { ok: false };
+  if (typeof v === 'string') return { ok: true, value: v.slice(0, MAX_TEXT_CHARS) };
+  if (typeof v === 'object') {
+    try {
+      const json = JSON.stringify(v);
+      if (json && json.length <= MAX_NESTED_JSON) return { ok: true, value: JSON.parse(json) };
+    } catch { /* cyclic or otherwise unserialisable */ }
+  }
+  return { ok: false };
+}
+
+const USER_TEXT = ['email', 'name', 'phone'];
+const RESERVED_USER = new Set(['id', 'userId', ...USER_TEXT, ...Object.values(ID_FIELDS).flat()]);
+
+/**
+ * identify()'s argument, as it will be sent under `metadata.user`.
+ *
+ * Returns null for null/undefined (sign-out) and for anything that is not a
+ * plain object, with a warning for the latter. Never throws.
+ *
+ *   id              string | number   the customer's own account id in your system
+ *   email           string            threads their reports; where "resolved" mail goes
+ *   name            string
+ *   phone           string | number   used, with email, to confirm the reporter owns
+ *                                     the record bugcatch looked up
+ *   loanId          string | number   (alias loanNumber)
+ *   applicationId   string | number
+ *   customerNumber  string | number   (alias customerId)
+ *
+ * Anything else is kept as readable metadata, within limits.
+ */
+export function normalizeUser(user, warn = () => {}) {
+  if (user === null || user === undefined) return null;
+  if (typeof user !== 'object' || Array.isArray(user)) {
+    warn(`identify() takes an object like { id, email, name } or null, got ${describe(user)} — ignored.`);
+    return null;
+  }
+  const out = {};
+  try {
+    const id = readId(user, 'id', ['id', 'userId'], 'identify()', warn);
+    if (id) out.id = id;
+    for (const field of USER_TEXT) {
+      const raw = user[field];
+      if (raw === undefined || raw === null || raw === '') continue;
+      if (field === 'phone' && typeof raw === 'number' && Number.isFinite(raw)) { out.phone = String(raw); continue; }
+      if (typeof raw !== 'string') {
+        warn(`identify().${field} should be a string, got ${describe(raw)} — it was dropped.`);
+        continue;
+      }
+      const v = raw.trim().slice(0, field === 'name' ? 200 : MAX_ID_CHARS);
+      if (!v) continue;
+      if (field === 'email' && !v.includes('@')) {
+        warn(`identify().email "${v}" does not look like an email address — reports cannot be threaded or followed up without one.`);
+      }
+      out[field] = v;
+    }
+    for (const [canonical, names] of Object.entries(ID_FIELDS)) {
+      const v = readId(user, canonical, names, 'identify()', warn);
+      if (v) out[canonical] = v;
+    }
+    let extras = 0;
+    for (const [key, raw] of Object.entries(user)) {
+      if (RESERVED_USER.has(key) || raw === undefined || typeof raw === 'function') continue;
+      if (extras >= MAX_EXTRA_KEYS) { warn(`identify() was given more than ${MAX_EXTRA_KEYS} extra fields; the rest were dropped.`); break; }
+      const kept = extraValue(raw);
+      if (!kept.ok) { warn(`identify().${key} could not be sent (${describe(raw)} too large or not serialisable) — dropped.`); continue; }
+      out[key] = kept.value;
+      extras += 1;
+    }
+  } catch {
+    // A getter that throws, a proxy — whatever it was, the report goes out with
+    // what was read before it.
+  }
+  if (!out.id && !out.email) {
+    warn('identify() was called without an id or email — reports will not be attributed to anyone, and nothing can be looked up by user.');
+  }
+  return out;
+}
+
+/**
+ * setContext()'s argument merged over what was already set, as it will be sent
+ * under `metadata.context`.
+ *
+ * `null` for the patch clears everything; a key set to null/undefined removes
+ * that key. Identifier fields are validated exactly as identify()'s are and
+ * rewritten to their canonical names; everything else (screen, route, feature
+ * flag…) is kept within limits. Never throws.
+ */
+export function mergeContext(prev, patch, warn = () => {}) {
+  if (patch === null) return {};
+  const out = { ...(prev || {}) };
+  if (patch === undefined) return out;
+  if (typeof patch !== 'object' || Array.isArray(patch)) {
+    warn(`setContext() takes an object like { loanId, screen } or null, got ${describe(patch)} — ignored.`);
+    return out;
+  }
+  try {
+    const aliases = new Map();
+    for (const [canonical, names] of Object.entries(ID_FIELDS)) for (const n of names) aliases.set(n, canonical);
+    for (const [key, raw] of Object.entries(patch)) {
+      const canonical = aliases.get(key);
+      if (raw === null || raw === undefined) { delete out[canonical || key]; continue; }
+      if (canonical) {
+        const v = readId({ [key]: raw }, canonical, [key], 'setContext()', warn);
+        if (v) out[canonical] = v; else delete out[canonical];
+        continue;
+      }
+      if (typeof raw === 'function') continue;
+      if (!(key in out) && Object.keys(out).length >= MAX_EXTRA_KEYS) {
+        warn(`setContext() holds at most ${MAX_EXTRA_KEYS} keys; "${key}" was dropped.`);
+        continue;
+      }
+      const kept = extraValue(raw);
+      if (!kept.ok) { warn(`setContext().${key} could not be sent (${describe(raw)} too large or not serialisable) — dropped.`); continue; }
+      out[key] = kept.value;
+    }
+  } catch { /* keep what was merged so far */ }
+  return out;
+}
+
+/** Every init() option this SDK reads. Anything else is probably a typo. */
+export const KNOWN_OPTIONS = [
+  'apiBase', 'apiKey', 'projectId', 'consoleLimit', 'networkLimit', 'captureConsole',
+  'captureNetwork', 'captureErrors', 'widget', 'widgetPosition', 'theme', 'accent',
+  'attachments', 'maxAttachments', 'maxAttachmentBytes', 'maxRecordingMs', 'beforeSend',
+  'user', 'context', 'updates', 'updateToast', 'onUpdate', 'voice', 'onCallState',
+  'onIncomingCall', 'onReportSubmitted', 'onAssistantPhase', 'onError', 'debug',
+  'drafts', 'knownIssues', 'release', 'environment', 'buildId',
+];
+
+const CALLBACK_OPTIONS = [
+  'beforeSend', 'onUpdate', 'onCallState', 'onIncomingCall', 'onReportSubmitted',
+  'onAssistantPhase', 'onError',
+];
+
+/** The closest known option to a misspelt one, when it is close enough to suggest. */
+function suggest(name) {
+  const lower = name.toLowerCase().replace(/[-_]/g, '');
+  return KNOWN_OPTIONS.find((k) => k.toLowerCase() === lower) || null;
+}
+
+const PLACEHOLDER = /^(your[_-]|<|xxx|todo|changeme)/i;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/**
+ * What is wrong with init()'s options, as two lists: `errors` stop init (it
+ * throws the first), `warnings` are printed and init carries on.
+ *
+ * `pageHost` is the page's hostname, passed in so this stays pure; it is what
+ * tells a production page still pointed at the localhost default apart from a
+ * developer's machine.
+ */
+export function checkOptions(options, { pageHost = '' } = {}) {
+  const errors = [];
+  const warnings = [];
+  if (!options || typeof options !== 'object') {
+    errors.push('init() takes an options object: BugCatch.init({ apiBase, apiKey, projectId }).');
+    return { errors, warnings };
+  }
+  const { apiKey, projectId, apiBase } = options;
+
+  if (!apiKey) errors.push('apiKey is required — create one under Workspace Settings → API Keys.');
+  else if (typeof apiKey !== 'string') errors.push(`apiKey must be a string, got ${describe(apiKey)}.`);
+  else if (PLACEHOLDER.test(apiKey)) errors.push(`apiKey is still the placeholder "${apiKey}" — paste the key you saved when you created it.`);
+  else if (UUID.test(apiKey)) warnings.push('apiKey looks like a project id — did you swap apiKey and projectId?');
+  else if (!apiKey.startsWith('bc_')) warnings.push('apiKey does not look like a BugCatch key (they start with "bc_live_") — reports will be refused with HTTP 401.');
+
+  if (!projectId) errors.push('projectId is required — copy it from Project Settings → Web SDK.');
+  else if (typeof projectId !== 'string') errors.push(`projectId must be a string, got ${describe(projectId)}.`);
+  else if (PLACEHOLDER.test(projectId)) errors.push(`projectId is still the placeholder "${projectId}".`);
+  else if (projectId.startsWith('bc_')) warnings.push('projectId looks like an API key — did you swap apiKey and projectId?');
+  else if (/\s/.test(projectId)) warnings.push('projectId contains whitespace — check it was copied cleanly.');
+
+  if (apiBase === undefined || apiBase === null) {
+    const local = !pageHost || /^(localhost|127\.|0\.0\.0\.0|\[::1\])/.test(pageHost);
+    if (!local) warnings.push('apiBase is not set, so reports go to http://localhost:3000 — set apiBase to your BugCatch API URL.');
+  } else if (typeof apiBase !== 'string' || !/^https?:\/\//.test(apiBase)) {
+    warnings.push(`apiBase should be an absolute http(s) URL, got ${JSON.stringify(apiBase)}.`);
+  }
+
+  for (const key of Object.keys(options)) {
+    if (KNOWN_OPTIONS.includes(key)) continue;
+    const near = suggest(key);
+    warnings.push(near
+      ? `unknown option "${key}" — did you mean "${near}"?`
+      : `unknown option "${key}" is ignored.`);
+  }
+  for (const key of CALLBACK_OPTIONS) {
+    const v = options[key];
+    if (v !== undefined && v !== null && typeof v !== 'function') {
+      warnings.push(`${key} should be a function, got ${describe(v)} — it will not be called.`);
+    }
+  }
+  return { errors, warnings };
+}
+
+/** Drop a trailing slash so `${apiBase}/ingest/bugs` never has two. */
+export function cleanApiBase(apiBase) {
+  return typeof apiBase === 'string' ? apiBase.replace(/\/+$/, '') : apiBase;
+}

package/src/index.d.ts

@@ -1,8 +1,73 @@
 /**
- * Who is using your app. `email` is the one field with behaviour attached —
- * see identify().
+ * Who is using your app, as identify() takes it.
+ *
+ * `id`, `email` and `phone` have behaviour attached; so do the three business
+ * identifiers, which bugcatch reads as identifiers *your app* asserted — trusted
+ * join keys it uses to look the customer up in your own system (over MCP)
+ * without asking the reporter. Anything else is kept as readable metadata.
+ */
+export interface BugCatchUser {
+  /** The customer's own account id in your system — never a staff or agent id. */
+  id?: string | number;
+  /** Threads their reports together; where "your issue is resolved" mail goes. */
+  email?: string;
+  name?: string;
+  /**
+   * With `email`, what bugcatch compares against the record it looked up to
+   * confirm the reporter owns it. Include the country code.
+   */
+  phone?: string | number;
+  /** A loan this customer holds. Looked up as a loan. Alias: `loanNumber`. */
+  loanId?: string | number;
+  /** A loan application. Looked up as a loan. */
+  applicationId?: string | number;
+  /** Your customer / client number. Looked up as a customer. Alias: `customerId`. */
+  customerNumber?: string | number;
+  /** @deprecated alias of `customerNumber`. */
+  customerId?: string | number;
+  /** @deprecated alias of `loanId`. */
+  loanNumber?: string | number;
+  /** Extra fields: strings, numbers, booleans or small objects, sent as metadata. */
+  [extra: string]: unknown;
+}
+
+/**
+ * What the reporter is looking at, as setContext() takes it. The three
+ * identifier fields are read exactly as on identify() and outrank them; set one
+ * to null to remove it.
  */
-export interface BugCatchUser { id?: string; email?: string; name?: string; }
+export interface BugCatchContext {
+  loanId?: string | number | null;
+  applicationId?: string | number | null;
+  customerNumber?: string | number | null;
+  /** Anything else — screen, route, step, a feature flag. Readable metadata only. */
+  [extra: string]: unknown;
+}
+
+/** Where the AI assistant working a report has got to. */
+export type AssistantPhase =
+  | 'analyzing' | 'needs_info' | 'confirming' | 'reviewing' | 'resolving' | 'resolved';
+
+export interface AssistantPhaseEvent {
+  bugId: string;
+  phase: AssistantPhase;
+  /** A short heading written for the reporter, e.g. "Root cause found". */
+  title: string | null;
+  detail: string | null;
+}
+
+export interface ReportSubmittedEvent {
+  bugId: string;
+  /** Null for a report filed by pressing Call — it is titled from the call. */
+  title: string | null;
+  via: 'form' | 'call';
+  result: ReportResult;
+}
+
+export interface BugCatchErrorEvent {
+  action: 'report' | 'call';
+  error: Error & { status?: number };
+}
 
 /**
  * What a bug *report* may carry. Narrower than what may be uploaded: a report's
@@ -53,13 +118,39 @@ export interface JoinedIssue {
 }
 
 export interface BugCatchConfig {
+  /**
+   * Log what the SDK does — identify, context, each report's shape — to the
+   * console. Default false. Misconfiguration warnings print either way.
+   */
+  debug?: boolean;
+  /** Context for the first screen; the same as calling setContext() after init. */
+  context?: BugCatchContext | null;
+  /** A report was accepted (widget, report() or Call). Also the 'report' event. */
+  onReportSubmitted?: ((event: ReportSubmittedEvent) => void) | null;
+  /**
+   * The AI assistant working a report moved phase. Seen whenever the report is
+   * fetched: by the widget while its thread is open, or by myReport(). Also the
+   * 'assistant' event.
+   */
+  onAssistantPhase?: ((event: AssistantPhaseEvent) => void) | null;
+  /** A report or call the SDK filed failed. Also the 'error' event. */
+  onError?: ((event: BugCatchErrorEvent) => void) | null;
   /** Recover unfinished widget reports on this device for seven days. Default true. */
   drafts?: boolean;
+  /** Your app's version, attached to every report. */
   release?: string;
+  /** e.g. 'production' / 'staging', attached to every report. */
   environment?: string;
   buildId?: string;
+  /**
+   * Your BugCatch API URL, e.g. 'https://api.bugcatch.example'. Default
+   * 'http://localhost:3000' — set it anywhere but local development. A trailing
+   * slash is removed.
+   */
   apiBase?: string;
+  /** A workspace API key (bc_live_…), from Workspace Settings → API Keys. */
   apiKey: string;
+  /** The project reports land in, from Project Settings → Web SDK. */
   projectId: string;
   consoleLimit?: number;
   networkLimit?: number;
@@ -235,6 +326,11 @@ export interface ReportInput {
    * form and must ask their own version of that question.
    */
   references?: ReportReference[];
+  /**
+   * Context for this report only, merged over setContext()'s without changing
+   * it — e.g. the loan a "report a problem with this loan" button belongs to.
+   */
+  context?: BugCatchContext;
 }
 
 export interface ReportReference {
@@ -426,6 +522,17 @@ export interface ReportDetail {
    * whose send button would fail.
    */
   canReply: boolean;
+  /**
+   * Where the AI assistant is on this report, written for the reporter. Null
+   * when no assistant is working it. Fetching a report also fires
+   * onAssistantPhase / the 'assistant' event when the phase has changed.
+   */
+  assistant?: {
+    phase: AssistantPhase;
+    title: string;
+    detail: string;
+    steps: { label: string; state: string }[];
+  } | null;
 }
 
 /**
@@ -461,6 +568,12 @@ export declare class BugCatchClient {
    * Several listeners can coexist, unlike the single `onUpdate` config hook.
    */
   on(event: 'update', handler: (update: ReportUpdate) => void): () => void;
+  /** A report was accepted — from the widget, report(), or pressing Call. */
+  on(event: 'report', handler: (event: ReportSubmittedEvent) => void): () => void;
+  /** The AI assistant working a report moved phase (seen when the report is fetched). */
+  on(event: 'assistant', handler: (event: AssistantPhaseEvent) => void): () => void;
+  /** A report or call the SDK filed failed. */
+  on(event: 'error', handler: (event: BugCatchErrorEvent) => void): () => void;
   on(
     event: 'call',
     handler: (detail: {
@@ -495,7 +608,7 @@ export declare class BugCatchClient {
   on(event: 'signout', handler: (who: { email: string | null }) => void): () => void;
   off(event: 'update', handler: (update: ReportUpdate) => void): this;
   off(
-    event: 'call' | 'unread' | 'incoming-call' | 'signin' | 'signout',
+    event: 'call' | 'unread' | 'incoming-call' | 'signin' | 'signout' | 'report' | 'assistant' | 'error',
     handler: (payload: any) => void,
   ): this;
   /**
@@ -630,8 +743,9 @@ export declare class BugCatchClient {
    * single slot, because there is a single microphone.
    */
   endCall(): this;
-  /** One report with its full timeline, or null if this browser cannot prove it filed it. */
+  /** Tell the team whether their fix worked. STILL_HAPPENING re-sends this browser's context. */
   verifyFix(bugId: string, feedback: { result: 'CONFIRMED' | 'STILL_HAPPENING'; resolvedAt: string; note?: string }): Promise<{ verification: string; status: string }>;
+  /** One report with its full timeline, or null if this browser cannot prove it filed it. */
   myReport(bugId: string): Promise<ReportDetail | null>;
   /**
    * Write back on a report this browser filed. The widget's own conversation
@@ -664,6 +778,24 @@ export declare class BugCatchClient {
    * Pass null on sign-out.
    */
   identify(user: BugCatchUser | null): this;
+  /**
+   * Say what the reporter is looking at — the loan, application or customer on
+   * this screen. Merged over what was set before and kept for the life of the
+   * page; a key set to null is removed, and `setContext(null)` clears it all.
+   */
+  setContext(context: BugCatchContext | null): this;
+  /** A copy of what setContext() holds. */
+  getContext(): BugCatchContext;
+  /** Open the built-in report panel (needs `widget: true`). */
+  open(): this;
+  /** Close the report panel if it is open. */
+  close(): this;
+  isOpen(): boolean;
+  /**
+   * File a report with everything captured so far. Rejects with an Error
+   * (carrying `.status` for an HTTP refusal) and emits 'error'; resolves to
+   * `{ cancelled: true }` when beforeSend returned false.
+   */
   report(input: ReportInput): Promise<ReportResult | { cancelled: true }>;
   /** Uploads straight to storage and resolves the key a report references. */
   uploadAttachment(
@@ -703,7 +835,13 @@ export declare class BugCatchClient {
    * neither did. Rejects when there is none.
    */
   meToo(bugId: string, who?: { email?: string; name?: string }): Promise<JoinedIssue>;
-  snapshot(): { console: any[]; network: any[]; environment: Record<string, any> };
+  snapshot(): {
+    user: BugCatchUser | null;
+    context: BugCatchContext;
+    console: any[];
+    network: any[];
+    environment: Record<string, any>;
+  };
   /**
    * Everything this browser has reported, newest first, with each one's
    * status. Resolves to an empty history when nothing has been filed here.
@@ -719,5 +857,5 @@ export declare class BugCatchClient {
   destroy(): void;
 }
 
-declare const BugCatch: BugCatchClient & { Client: typeof BugCatchClient };
+declare const BugCatch: BugCatchClient & { Client: typeof BugCatchClient; version: string };
 export default BugCatch;