@sphoro/bugcatch-web-sdk 0.14.3 → 0.15.0

package/src/index.js

@@ -19,6 +19,7 @@ import {
 import { joinLiveCall, liveCallSupported, openMicrophone } from './live-call.js';
 import { showIncomingCall } from './incoming-call.js';
 import { referenceFields } from './references.js';
+import { normalizeUser, mergeContext, checkOptions, cleanApiBase } from './identity.js';
 
 // Replaced at build time from package.json. The guard is for anyone importing
 // src/ directly, where the define never runs.
@@ -78,6 +79,25 @@ const DEFAULTS = {
   // that can suppress a call the person can see ringing. Set `voice: false` to
   // switch the whole thing off.
   onIncomingCall: null,
+  // Called with { bugId, title, via: 'form' | 'call', result } once a report
+  // has been accepted — from the widget, from report(), or from pressing Call.
+  // The same thing is emitted as the 'report' event.
+  onReportSubmitted: null,
+  // Called with { bugId, phase, title, detail } when the AI assistant working
+  // a report moves: 'analyzing' → 'needs_info' | 'confirming' | 'reviewing' |
+  // 'resolving' | 'resolved'. Seen whenever the report is fetched — the widget
+  // does while it is open; myReport(id) does for an integration's own view.
+  onAssistantPhase: null,
+  // Called with { action, error } when something the SDK did on the page's
+  // behalf failed (a report that was refused, a listener that threw). Also the
+  // 'error' event.
+  onError: null,
+  // Business context for the screen the SDK starts on — see setContext().
+  context: null,
+  // Log what the SDK is doing (identify, context, each report's shape) to the
+  // console. Off in production; the warnings about misconfiguration are
+  // printed either way.
+  debug: false,
 };
 
 class BugCatchClient {
@@ -105,6 +125,40 @@ class BugCatchClient {
     // event -> Set<handler>. Several parts of a host app can listen without
     // having to share the single `onUpdate` config callback between them.
     this.listeners = new Map();
+    // What setContext() has said about the screen the reporter is on. Its own
+    // field rather than part of config, so init() — which rebuilds config —
+    // cannot wipe a context set before it ran.
+    this.context = {};
+    // Warnings already printed, so a misconfiguration in a render loop says so
+    // once rather than a thousand times.
+    this.warned = new Set();
+    // The last assistant phase seen per report, so onAssistantPhase fires on a
+    // change rather than on every poll.
+    this.phases = new Map();
+  }
+
+  /** A misconfiguration, said once. Always printed — it is what saves a day of guessing. */
+  warn(message) {
+    if (this.warned.has(message)) return;
+    this.warned.add(message);
+    // eslint-disable-next-line no-console
+    console.warn(`[BugCatch] ${message}`);
+  }
+
+  /** What the SDK is doing, for `debug: true`. */
+  debugLog(...args) {
+    // eslint-disable-next-line no-console
+    if (this.config.debug) console.info('[BugCatch]', ...args);
+  }
+
+  /** Call a host callback without letting it break the SDK. */
+  #callback(name, payload) {
+    const fn = this.config[name];
+    if (typeof fn !== 'function') return;
+    try { fn(payload); } catch (err) {
+      // eslint-disable-next-line no-console
+      console.error(`[BugCatch] your ${name} callback threw:`, err);
+    }
   }
 
   init(options = {}) {
@@ -112,10 +166,21 @@ class BugCatchClient {
       console.warn('[BugCatch] init() called twice — ignoring the second call.');
       return this;
     }
-    this.config = { ...DEFAULTS, ...options };
-
-    if (!this.config.apiKey) throw new Error('[BugCatch] apiKey is required.');
-    if (!this.config.projectId) throw new Error('[BugCatch] projectId is required.');
+    const { errors, warnings } = checkOptions(options, {
+      pageHost: typeof location !== 'undefined' ? location.hostname : '',
+    });
+    if (errors.length) throw new Error(`[BugCatch] ${errors[0]}`);
+    for (const w of warnings) this.warn(w);
+
+    // identify() and setContext() may run before init() — an app that knows its
+    // user before it has loaded its config is ordinary. Rebuilding config here
+    // used to throw that user away; it is carried over unless init names one.
+    const earlier = this.config.user;
+    this.config = { ...DEFAULTS, ...options, apiBase: cleanApiBase(options.apiBase ?? DEFAULTS.apiBase) };
+    this.config.user = options.user !== undefined
+      ? normalizeUser(options.user, (m) => this.warn(m.replace('identify()', 'init({ user })')))
+      : earlier || null;
+    if (options.context) this.setContext(options.context);
 
     this.consoleBuffer = createRingBuffer(this.config.consoleLimit);
     this.networkBuffer = createRingBuffer(this.config.networkLimit);
@@ -141,6 +206,10 @@ class BugCatchClient {
     }
 
     this.started = true;
+    this.debugLog('initialised', {
+      version: SDK_IDENTITY.version, apiBase: this.config.apiBase, projectId: this.config.projectId,
+      user: this.config.user, context: this.context,
+    });
     return this;
   }
 
@@ -223,7 +292,7 @@ class BugCatchClient {
       } catch (err) {
         // Someone else's handler, on someone else's page.
         // eslint-disable-next-line no-console
-        console.error('[BugCatch] an update listener threw:', err);
+        console.error(`[BugCatch] a '${event}' listener threw:`, err);
       }
     }
   }
@@ -327,8 +396,44 @@ class BugCatchClient {
     return verifyFix({ apiBase: this.config.apiBase, bugId, result, resolvedAt, note, metadata: context.metadata, logs: context.logs });
   }
 
-  myReport(bugId) {
-    return fetchReport({ apiBase: this.config.apiBase, bugId });
+  async myReport(bugId) {
+    const report = await fetchReport({ apiBase: this.config.apiBase, bugId });
+    this.#notePhase(bugId, report?.assistant);
+    return report;
+  }
+
+  /**
+   * Tell the host app the assistant moved, once per change.
+   *
+   * The phase is only known when a report is fetched, which the widget does
+   * every few seconds while its thread is open and an integration does through
+   * myReport(). The first sighting counts as a change: a host that has just
+   * opened a report wants to know it is being analysed.
+   */
+  #notePhase(bugId, assistant) {
+    const phase = assistant?.phase;
+    if (!bugId || typeof phase !== 'string') return;
+    if (this.phases.get(bugId) === phase) return;
+    this.phases.set(bugId, phase);
+    const detail = { bugId, phase, title: assistant.title ?? null, detail: assistant.detail ?? null };
+    this.debugLog('assistant', detail);
+    this.#callback('onAssistantPhase', detail);
+    this.emit('assistant', detail);
+  }
+
+  /** A report was accepted: tell the host app, however it was filed. */
+  #submitted(result, { title, via }) {
+    if (!result?.id) return;
+    const detail = { bugId: result.id, title: title ?? null, via, result };
+    this.debugLog('report accepted', detail);
+    this.#callback('onReportSubmitted', detail);
+    this.emit('report', detail);
+  }
+
+  /** Something done on the page's behalf failed. */
+  #failed(action, error) {
+    this.#callback('onError', { action, error });
+    this.emit('error', { action, error });
   }
 
   /**
@@ -356,7 +461,9 @@ class BugCatchClient {
    * copies of this would drift, and the half that drifted would be the one that
    * stopped attaching the console.
    */
-  async #payload({ title, description = '', priority = 'MEDIUM', metadata = {}, media = [], references = [] }) {
+  async #payload({ title, description = '', priority = 'MEDIUM', metadata = {}, media = [], references = [], context = null }) {
+    // This report's own context over the screen's, without keeping it.
+    const ctx = context ? mergeContext(this.context, context, (m) => this.warn(m.replace('setContext()', 'report({ context })'))) : this.context;
     return {
       projectId: this.config.projectId,
       ...(title ? { title } : {}),
@@ -373,7 +480,13 @@ class BugCatchClient {
         environment: this.config.environment,
         buildId: this.config.buildId,
         ...metadata,
+        // Who is signed in, as identify() shaped it: `id`, `email` and `phone`
+        // are where the API and the ownership check read them, and `loanId`,
+        // `applicationId`, `customerNumber` become trusted lookup keys.
         user: this.config.user || undefined,
+        // The screen the report came from — setContext(). Its identifiers
+        // outrank the same kind on `user`.
+        ...(Object.keys(ctx).length ? { context: ctx } : {}),
         sdk: SDK_IDENTITY,
       },
       logs: {
@@ -417,8 +530,10 @@ class BugCatchClient {
       // `report()` drops it: the widget re-reads state every time it opens, so
       // forgetting it now is what makes it draw the sign-in step instead.
       if (err.status === 401 && session) clearSession(this.config.projectId);
+      this.#failed('call', err);
       throw err;
     }
+    this.#submitted(filed, { title: null, via: 'call' });
 
     // The same token `report()` keeps, and for the same reason: it is what lets
     // this browser hear what happens to the report afterwards.
@@ -864,10 +979,64 @@ class BugCatchClient {
    * Pass null to forget them again on sign-out.
    */
   identify(user) {
-    this.config.user = user;
+    const shaped = normalizeUser(user, (m) => this.warn(m));
+    // Anything but null/undefined that yielded nothing usable is a mistake, not
+    // a sign-out: keep who was there rather than silently forgetting them.
+    if (user !== null && user !== undefined && !shaped) return this;
+    this.config.user = shaped;
+    this.debugLog('identify', shaped);
+    return this;
+  }
+
+  /**
+   * Say what the reporter is looking at — the loan, application or customer on
+   * this screen — so every report filed from it carries that record.
+   *
+   *   BugCatch.setContext({ loanId: 'L26090028459', screen: 'repayment' });
+   *   BugCatch.setContext({ loanId: null });   // left the loan screen
+   *   BugCatch.setContext(null);               // clear everything
+   *
+   * Merged over what was set before and kept until changed — for the life of
+   * the page, not across reloads. `loanId`, `applicationId` and
+   * `customerNumber` are read by bugcatch as identifiers your app asserted, and
+   * outrank the same field on identify(); anything else is readable metadata.
+   */
+  setContext(context) {
+    this.context = mergeContext(this.context, context, (m) => this.warn(m));
+    this.debugLog('context', this.context);
     return this;
   }
 
+  /** What setContext() currently holds (a copy). */
+  getContext() {
+    return { ...this.context };
+  }
+
+  /**
+   * Open the report panel, as if the floating button had been pressed — for a
+   * "Report a problem" item in your own menu.
+   *
+   * Needs the built-in widget (`widget: true`, the default). With `widget:
+   * false` there is no panel to open: draw your own form and call report().
+   */
+  open() {
+    if (!this.started) { this.warn('open() was called before init() — nothing to open yet.'); return this; }
+    if (!this.widgetControls) { this.warn('open() needs the built-in widget; it was turned off with widget: false.'); return this; }
+    this.widgetControls.open();
+    return this;
+  }
+
+  /** Close the report panel if it is open. */
+  close() {
+    this.widgetControls?.close();
+    return this;
+  }
+
+  /** Whether the report panel is open. */
+  isOpen() {
+    return Boolean(this.widgetControls?.isOpen());
+  }
+
   /**
    * Upload a screenshot, recording or file and get back the storage key that
    * `report({ attachments })` references.
@@ -890,10 +1059,14 @@ class BugCatchClient {
   /** File a bug with everything captured so far. */
   async report({
     title, description = '', priority = 'MEDIUM', metadata = {}, attachments = [],
-    references = [],
+    references = [], context = null,
   } = {}) {
     if (!this.started) throw new Error('[BugCatch] call init() first.');
-    if (!title || !title.trim()) throw new Error('[BugCatch] a title is required.');
+    if (typeof title !== 'string' || !title.trim()) throw new Error('[BugCatch] a title is required.');
+    if (!['LOW', 'MEDIUM', 'HIGH', 'CRITICAL'].includes(String(priority).toUpperCase())) {
+      this.warn(`priority "${priority}" is not one of LOW, MEDIUM, HIGH, CRITICAL — sent as MEDIUM.`);
+      priority = 'MEDIUM';
+    }
 
     // Drop anything the API would reject outright, so one bad entry can't cost
     // the reporter the whole report.
@@ -908,8 +1081,19 @@ class BugCatchClient {
         mime: normalizeMime(a.mime, REPORT_MIMES),
       }));
 
+    // Only well-formed entries: one malformed reference must not cost the
+    // reporter the report (the API refuses the whole body on a bad one).
+    const refs = (Array.isArray(references) ? references : [])
+      .filter((r) => r && typeof r.key === 'string' && r.key && (typeof r.value === 'string' || typeof r.value === 'number'))
+      .map((r) => ({ key: r.key.slice(0, 64), value: String(r.value).trim().slice(0, 120) }))
+      .filter((r) => r.value);
+    if (Array.isArray(references) && refs.length < references.length) {
+      this.warn('report({ references }) takes [{ key, value }] with string values; malformed entries were dropped.');
+    }
+
     let payload = await this.#payload({
-      title: title.trim(), description, priority, metadata, media, references,
+      title: title.trim(), description: typeof description === 'string' ? description : String(description ?? ''),
+      priority: String(priority).toUpperCase(), metadata, media, references: refs, context,
     });
 
     if (typeof this.config.beforeSend === 'function') {
@@ -918,20 +1102,35 @@ class BugCatchClient {
       if (result && typeof result === 'object') payload = result;
     }
 
-    const session = readSession(this.config.projectId);
-    const res = await fetch(`${this.config.apiBase}/ingest/bugs`, {
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-        'X-BugCatch-Key': this.config.apiKey,
-        // Present only where the reporter signed in. The server takes the
-        // address from here rather than from the payload when it is — on a
-        // project that requires sign-in, letting the page name a different
-        // reporter would undo the requirement.
-        ...(session?.token ? { 'X-BugCatch-Session': session.token } : {}),
-      },
-      body: JSON.stringify(payload),
+    this.debugLog('sending report', {
+      title: payload.title, user: payload.metadata?.user, context: payload.metadata?.context,
+      references: payload.references, console: payload.logs?.console?.entries?.length,
+      network: payload.logs?.network?.entries?.length,
     });
+    const session = readSession(this.config.projectId);
+    let res;
+    try {
+      res = await fetch(`${this.config.apiBase}/ingest/bugs`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'X-BugCatch-Key': this.config.apiKey,
+          // Present only where the reporter signed in. The server takes the
+          // address from here rather than from the payload when it is — on a
+          // project that requires sign-in, letting the page name a different
+          // reporter would undo the requirement.
+          ...(session?.token ? { 'X-BugCatch-Session': session.token } : {}),
+        },
+        body: JSON.stringify(payload),
+      });
+    } catch (cause) {
+      // No response at all: the wrong apiBase, the API down, or CORS refusing
+      // this origin. The browser's own "Failed to fetch" names none of them.
+      const err = new Error(`[BugCatch] could not reach ${this.config.apiBase} — check apiBase, and that this site's origin is allowed by the API.`);
+      err.cause = cause;
+      this.#failed('report', err);
+      throw err;
+    }
 
     // A session the server no longer recognises — expired, or ended by a
     // sign-in somewhere else. Dropped here rather than left to fail again on
@@ -945,10 +1144,17 @@ class BugCatchClient {
         const body = await res.json();
         detail = Array.isArray(body.message) ? body.message.join(', ') : body.message || '';
       } catch { /* non-JSON error */ }
-      throw new Error(`[BugCatch] report failed (HTTP ${res.status})${detail ? ': ' + detail : ''}`);
+      // The two refusals an integrator hits first, said in their terms.
+      if (res.status === 401 && !session) detail ||= 'the apiKey was not accepted';
+      if (res.status === 403) detail ||= 'the apiKey is not allowed to report to this projectId';
+      const err = new Error(`[BugCatch] report failed (HTTP ${res.status})${detail ? ': ' + detail : ''}`);
+      err.status = res.status;
+      this.#failed('report', err);
+      throw err;
     }
 
     const result = await res.json();
+    this.#submitted(result, { title: payload.title ?? title.trim(), via: 'form' });
 
     // The API returns a watch token only when it could attribute the report to
     // someone — which means identify() was called with an email. Without one
@@ -1095,7 +1301,6 @@ class BugCatchClient {
     return result;
   }
 
-  /** What would be sent right now — useful for debugging integrations. */
   /**
    * What this project is already known to be having trouble with.
    *
@@ -1153,7 +1358,12 @@ class BugCatchClient {
       bugId,
       reporterEmail: email || this.config.user?.email,
       reporterName: name || this.config.user?.name,
-      metadata: { ...environment, user: this.config.user || undefined, sdk: SDK_IDENTITY },
+      metadata: {
+        ...environment,
+        user: this.config.user || undefined,
+        ...(Object.keys(this.context).length ? { context: this.context } : {}),
+        sdk: SDK_IDENTITY,
+      },
       logs: {
         console: { entries: this.consoleBuffer.all() },
         network: { entries: this.networkBuffer.all() },
@@ -1162,8 +1372,11 @@ class BugCatchClient {
     });
   }
 
+  /** What would be sent right now — useful for debugging integrations. */
   snapshot() {
     return {
+      user: this.config.user || null,
+      context: { ...this.context },
       console: this.consoleBuffer.all(),
       network: this.networkBuffer.all(),
       environment: collectEnvironmentSync(),
@@ -1196,5 +1409,7 @@ const BugCatch = new BugCatchClient();
 // build, a named export alongside the default turns `window.BugCatch` into a
 // namespace object, so `BugCatch.init(...)` from a <script> tag would break.
 BugCatch.Client = BugCatchClient;
+// For support tickets and `console.log(BugCatch.version)`.
+BugCatch.version = SDK_IDENTITY.version;
 
 export default BugCatch;