@sphoro/bugcatch-web-sdk 0.17.0 → 0.19.0

package/src/index.d.ts

@@ -117,6 +117,31 @@ export interface JoinedIssue {
   watchToken?: string | null;
 }
 
+/**
+ * Something the project's team is telling the people using its widget, written
+ * on the Widget announcements settings page. Already narrowed to the visitor's
+ * own day and to what this browser has not closed.
+ */
+export interface Announcement {
+  id: string;
+  /** Bumped by "Show it again", which is what reopens it for people who closed it. */
+  revision: number;
+  title: string;
+  /** '' when there is none. */
+  body: string;
+  /** Picks the colour and the icon; the site's accent is 'info'. */
+  tone: 'info' | 'success' | 'warning' | 'critical';
+  /** Both, or both ''. A path is a page on your own site. */
+  ctaLabel: string;
+  ctaHref: string;
+  /** 'launcher' is also shown beside the button, and is always dismissible. */
+  placement: 'panel' | 'launcher';
+  dismissible: boolean;
+  /** YYYY-MM-DD, inclusive, or ''. */
+  startsOn: string;
+  endsOn: string;
+}
+
 export interface BugCatchConfig {
   /**
    * Log what the SDK does — identify, context, each report's shape — to the
@@ -137,6 +162,16 @@ export interface BugCatchConfig {
   onError?: ((event: BugCatchErrorEvent) => void) | null;
   /** Recover unfinished widget reports on this device for seven days. Default true. */
   drafts?: boolean;
+  /**
+   * Where the script-tag build fetches the rest of itself from: the folder
+   * holding bugcatch-panel.umd.js and bugcatch-call.umd.js, which it loads the
+   * first time the report panel opens or a call is placed. By default the
+   * folder bugcatch.umd.js itself was loaded from — set this only when that
+   * cannot be told (the bundle inlined into the page, or its dist/ files served
+   * from somewhere else). A relative URL is read against the page. Ignored by
+   * the ES build, whose chunks are the bundler's to place.
+   */
+  chunkBase?: string | null;
   /** Your app's version, attached to every report. */
   release?: string;
   /** e.g. 'production' / 'staging', attached to every report. */
@@ -161,8 +196,12 @@ export interface BugCatchConfig {
   widgetPosition?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
   /** 'auto' follows the visitor's system setting. Default 'auto'. */
   theme?: 'auto' | 'light' | 'dark';
-  /** Any CSS colour. Default '#4F46E5'. */
-  accent?: string;
+  /**
+   * Any CSS colour, for the launcher, the buttons and the assistant's orb. The
+   * words on it are white or near-black, whichever reads. Default null: ink,
+   * which is a black button on light and a white one on dark.
+   */
+  accent?: string | null;
   /** Offer screenshot / recording / file attach in the widget. Default true. */
   attachments?: boolean;
   /**
@@ -172,6 +211,13 @@ export interface BugCatchConfig {
    * the feature on and somebody lists an individual report.
    */
   knownIssues?: boolean;
+  /**
+   * Draw what the project's team is telling visitors: at the top of the panel,
+   * and beside the button for the ones written for that. Default true — and
+   * nothing is drawn until the project publishes one. false draws nothing;
+   * announcements() still answers, for a site that shows them its own way.
+   */
+  announcements?: boolean;
   /** Default 5. */
   maxAttachments?: number;
   /** Default 25 MB. */
@@ -420,6 +466,25 @@ export interface MyReport {
   project: string;
   workspace: string;
   attachments: number;
+  /** Their score for how it was handled, 1–5, or null when they have not rated it. */
+  rating: number | null;
+  /** Settled, on a project that asks for ratings — so a list can say "rate it". */
+  ratingAsked: boolean;
+}
+
+/**
+ * A reporter's own rating of how a settled report was handled.
+ *
+ * `current` is false when the report has been reopened and settled again since
+ * it was given — the rating stands, but it was for an earlier fix.
+ */
+export interface ReportRating {
+  /** 1–5, five best. */
+  score: number;
+  comment: string | null;
+  ratedAt: string;
+  via: 'widget' | 'portal' | 'email';
+  current: boolean;
 }
 
 /** A report of this browser's changed status. */
@@ -510,6 +575,18 @@ export interface ReportDetail {
   attachments: { type: string; mime: string; createdAt: string; url: string | null }[];
   /** Every step from filing to now, oldest first, both sides' messages included. */
   timeline: ReportTimelineEntry[];
+  /** When it was last settled, or null while it is open. */
+  resolvedAt: string | null;
+  /** Their answer to "does the fix work?", or null when they have not given one. */
+  verification: 'CONFIRMED' | 'STILL_HAPPENING' | null;
+  /** Their rating of how it was handled, or null. See rate(). */
+  rating: ReportRating | null;
+  /**
+   * Whether a rating is being asked for: the report is settled and the project
+   * has not switched ratings off. The widget draws its stars only when this is
+   * true; an integration's own view should do the same.
+   */
+  ratingAsked: boolean;
   /**
    * The same figure they were given when they filed it, so coming back to check
    * is not a worse experience than not checking. Null on a settled report — the
@@ -745,6 +822,12 @@ export declare class BugCatchClient {
   endCall(): this;
   /** 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 }>;
+  /**
+   * Rate how a settled report was handled, 1–5, five best. Rating again
+   * replaces the earlier score. Rejects while the report is open, or on a
+   * project that does not ask for ratings (`ratingAsked` is false).
+   */
+  rate(bugId: string, rating: { score: 1 | 2 | 3 | 4 | 5; comment?: string }): Promise<ReportRating>;
   /** One report with its full timeline, or null if this browser cannot prove it filed it. */
   myReport(bugId: string): Promise<ReportDetail | null>;
   /**
@@ -813,6 +896,14 @@ export declare class BugCatchClient {
    * draw nothing rather than an empty heading.
    */
   knownIssues(): Promise<KnownIssue[]>;
+  /**
+   * What this project's team is telling the people using its widget, for a
+   * site drawing its own UI (`widget: false` or `announcements: false`). A
+   * browser asks at most every five minutes. Empty on every failure.
+   */
+  announcements(): Promise<Announcement[]>;
+  /** Stop showing one in this browser until the team uses "Show it again". */
+  dismissAnnouncement(announcement: Announcement): void;
   /**
    * The known issues that look like what somebody is describing.
    *

package/src/index.js

@@ -6,7 +6,7 @@ import { mountWidget } from './widget.js';
 import { uploadAttachment, normalizeMime, REPORT_MIMES } from './capture.js';
 import {
   watchUpdates, createUpdateNotifier, fetchMyReports, fetchReport, writeToken, readToken,
-  clearToken, scopeReports, sendMessage, verifyFix, callKindsForProject,
+  clearToken, scopeReports, sendMessage, verifyFix, rateReport, callKindsForProject,
   reportByCall, liveCallAvailable, requestLiveCall, giveUpLiveCall,
   answerIncomingCall, declineIncomingCall,
   readUnread, rememberUpdate, forgetUpdate, forgetReportUpdates, forgetAllUpdates,
@@ -16,11 +16,17 @@ import {
 import {
   loginState, startSignIn, confirmSignIn, endSignIn, readSession, clearSession,
 } from './session.js';
-import { joinLiveCall, liveCallSupported, openMicrophone } from './live-call.js';
-import { showIncomingCall } from './incoming-call.js';
+// Not live-call.js and incoming-call.js: the call code is fetched when a call
+// is placed or rings, not with every page (see lazy.js).
+import { loadCall } from './lazy.js';
+import { pageTouched } from './gesture.js';
 import { referenceFields } from './references.js';
 import { fetchAgentIssues } from './agent-issues.js';
+import {
+  fetchAnnouncements, visibleAnnouncements, dismissAnnouncement as rememberDismissed,
+} from './announcements.js';
 import { normalizeUser, mergeContext, checkOptions, cleanApiBase } from './identity.js';
+import { tooManyMessage } from './busy.js';
 
 // Replaced at build time from package.json. The guard is for anyone importing
 // src/ directly, where the define never runs.
@@ -43,7 +49,14 @@ const DEFAULTS = {
   widgetPosition: 'bottom-right',
   // 'auto' follows the visitor's system setting; 'light' / 'dark' pin it.
   theme: 'auto',
-  accent: '#4F46E5',
+  // null is ink: black buttons on light, white on dark (accent.js). Any CSS
+  // colour makes the buttons, the launcher and the assistant's orb that colour.
+  accent: null,
+  // Draw what the project's team is telling visitors — written on the Widget
+  // announcements settings page — in the panel, and beside the button for the
+  // ones written for that. false draws nothing; announcements() still answers,
+  // for a site that shows them its own way.
+  announcements: true,
   // Screenshot / screen recording / file attach. Capture needs getDisplayMedia,
   // so it is offered only where the browser has it — file attach always works.
   attachments: true,
@@ -95,12 +108,34 @@ const DEFAULTS = {
   onError: null,
   // Business context for the screen the SDK starts on — see setContext().
   context: null,
+  // The script-tag build fetches the report panel and the call code when they
+  // are first needed, from the folder it was itself loaded from. Set this to
+  // that folder's URL when it cannot tell — a copy of the bundle inlined into
+  // the page, or served from somewhere other than beside its dist/ siblings.
+  // The ES build ignores it: the bundler decides where its chunks live.
+  chunkBase: 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,
 };
 
+/**
+ * A report's body, plus the watch token this browser already holds for this
+ * project.
+ *
+ * The token that comes back from filing names the reports this browser filed —
+ * not every report ever filed under the address it sent, which anybody holding
+ * the public key could claim. Sending the held one back is what makes the new
+ * token cover the earlier reports too, so "Your reports" keeps its history
+ * without anybody signing in. Added after beforeSend, which has no business
+ * with it, and absent when there is nothing held.
+ */
+function withHeldToken(payload) {
+  const held = readToken();
+  return held ? { ...payload, watchToken: held } : payload;
+}
+
 class BugCatchClient {
   constructor() {
     this.config = { ...DEFAULTS };
@@ -423,6 +458,28 @@ class BugCatchClient {
     this.notifier.render(unread);
   }
 
+  /**
+   * Tell the team whether their fix worked. STILL_HAPPENING reopens the report
+   * and re-sends this browser's context with it.
+   */
+  async verifyFix(bugId, { result, resolvedAt, note }) {
+    const context = result === 'STILL_HAPPENING' ? await this.#payload({}) : {};
+    return verifyFix({ apiBase: this.config.apiBase, bugId, result, resolvedAt, note, metadata: context.metadata, logs: context.logs });
+  }
+
+  /**
+   * Rate how a settled report was handled, 1 to 5, five best.
+   *
+   *   await BugCatch.rate(report.id, { score: 4, comment: 'Quick, thanks' });
+   *
+   * Only once the report is RESOLVED or CLOSED, on a project that asks for
+   * ratings — `myReport(id).ratingAsked` says whether it does. Rating again
+   * replaces the earlier score rather than adding a second one.
+   */
+  async rate(bugId, { score, comment } = {}) {
+    return rateReport({ apiBase: this.config.apiBase, bugId, score, comment });
+  }
+
   /**
    * One report in full, with its timeline — every step from filing to now.
    *
@@ -431,11 +488,6 @@ class BugCatchClient {
    *
    * Resolves to null when this browser cannot prove it filed that report.
    */
-  async verifyFix(bugId, { result, resolvedAt, note }) {
-    const context = result === 'STILL_HAPPENING' ? await this.#payload({}) : {};
-    return verifyFix({ apiBase: this.config.apiBase, bugId, result, resolvedAt, note, metadata: context.metadata, logs: context.logs });
-  }
-
   async myReport(bugId) {
     const report = await fetchReport({ apiBase: this.config.apiBase, bugId });
     this.#notePhase(bugId, report?.assistant);
@@ -600,6 +652,9 @@ class BugCatchClient {
         apiKey: this.config.apiKey,
         token: session?.token,
         payload,
+        // See report(): the token this browser holds, so the one that comes
+        // back still covers what it covered.
+        watchToken: readToken(),
       });
     } catch (err) {
       // A session the server no longer recognises, dropped exactly as
@@ -779,6 +834,11 @@ class BugCatchClient {
 
   /** The body of startCall, so the in-flight flag clears on every path. */
   async #ringTheTeam(bugId) {
+    // The call code first: fetched now, when somebody has asked for a call,
+    // rather than on every page load for the few that ever place one. A failure
+    // here rejects before anything is asked for or filed.
+    const { joinLiveCall, liveCallSupported, openMicrophone } = await loadCall(this.config.chunkBase);
+
     // Before the call is placed, not after. A permission prompt takes as long
     // as the person takes to read it, and asking afterwards would have a room
     // full of dashboards ringing about a call its own caller may yet refuse to
@@ -875,7 +935,7 @@ class BugCatchClient {
    */
   #ring(event) {
     const call = event.incomingCall;
-    if (!this.config.voice || !liveCallSupported()) return;
+    if (!this.config.voice) return;
     // Already ringing about this one — a reconnect replaying the frame, or a
     // second delivery. One card either way.
     if (this.ringing?.callId === call.callId) return;
@@ -885,36 +945,56 @@ class BugCatchClient {
 
     this.#stopRinging();
 
-    const dismiss = showIncomingCall({
-      call,
-      accent: this.config.accent,
-      position: this.config.widgetPosition,
-      onAnswer: () => { void this.#answer(event.bugId, call); },
-      onDecline: () => {
-        this.ringing = null;
-        declineIncomingCall({
-          apiBase: this.config.apiBase, bugId: event.bugId, callId: call.callId,
-        });
-        this.emit('incoming-call', { bugId: event.bugId, callId: call.callId, state: 'declined' });
-      },
-      // Nothing is reported here. The member who placed it is watching it ring
-      // on their own screen and their browser tells the API when it stops —
-      // the same rule as the other direction, where whoever placed the call is
-      // the one that reports nobody answered.
-      onExpire: () => {
-        this.ringing = null;
-        this.emit('incoming-call', { bugId: event.bugId, callId: call.callId, state: 'missed' });
-      },
-    });
+    // The card's code is fetched now, the first time anything rings. The slot
+    // is held while it arrives, so a second delivery of this frame finds it,
+    // and a withdrawal or a teardown that lands first takes it away before any
+    // card is drawn.
+    const pending = { callId: call.callId, dismiss: () => {} };
+    this.ringing = pending;
+    loadCall(this.config.chunkBase).then(({ liveCallSupported, showIncomingCall }) => {
+      if (this.ringing !== pending) return;
+      this.ringing = null;
+      if (!liveCallSupported()) return;
+      if (this.call || this.callStarting) return;
+
+      const dismiss = showIncomingCall({
+        call,
+        accent: this.config.accent,
+        position: this.config.widgetPosition,
+        // Whether the page has been touched, which is when the card may ring
+        // out loud — tracked since load, which the card's own code cannot be.
+        touched: pageTouched,
+        onAnswer: () => { void this.#answer(event.bugId, call); },
+        onDecline: () => {
+          this.ringing = null;
+          declineIncomingCall({
+            apiBase: this.config.apiBase, bugId: event.bugId, callId: call.callId,
+          });
+          this.emit('incoming-call', { bugId: event.bugId, callId: call.callId, state: 'declined' });
+        },
+        // Nothing is reported here. The member who placed it is watching it ring
+        // on their own screen and their browser tells the API when it stops —
+        // the same rule as the other direction, where whoever placed the call is
+        // the one that reports nobody answered.
+        onExpire: () => {
+          this.ringing = null;
+          this.emit('incoming-call', { bugId: event.bugId, callId: call.callId, state: 'missed' });
+        },
+      });
 
-    this.ringing = { callId: call.callId, dismiss };
-    if (typeof this.config.onIncomingCall === 'function') {
-      // After the card, not instead of it. This is for a host application that
-      // wants to know — to duck its own audio, to pause a video — and not a
-      // hook that can suppress a call the person can see ringing.
-      try { this.config.onIncomingCall({ bugId: event.bugId, ...call }); } catch { /* theirs */ }
-    }
-    this.emit('incoming-call', { bugId: event.bugId, callId: call.callId, state: 'ringing' });
+      this.ringing = { callId: call.callId, dismiss };
+      if (typeof this.config.onIncomingCall === 'function') {
+        // After the card, not instead of it. This is for a host application that
+        // wants to know — to duck its own audio, to pause a video — and not a
+        // hook that can suppress a call the person can see ringing.
+        try { this.config.onIncomingCall({ bugId: event.bugId, ...call }); } catch { /* theirs */ }
+      }
+      this.emit('incoming-call', { bugId: event.bugId, callId: call.callId, state: 'ringing' });
+    }, () => {
+      // No card can be drawn without its code. chunkUnavailable has said why in
+      // the console; the member ringing sees it go unanswered.
+      if (this.ringing === pending) this.ringing = null;
+    });
   }
 
   /** Take the card away, whatever it is showing. */
@@ -940,8 +1020,12 @@ class BugCatchClient {
     this.callStarting = true;
 
     let microphone;
+    let joinLiveCall;
     try {
-      microphone = await openMicrophone();
+      // Already here: the card that was answered was drawn by this code.
+      const calling = await loadCall(this.config.chunkBase);
+      joinLiveCall = calling.joinLiveCall;
+      microphone = await calling.openMicrophone();
     } catch (err) {
       this.callStarting = false;
       // Refused the prompt, or no microphone on this machine. The call is still
@@ -1201,7 +1285,7 @@ class BugCatchClient {
           // reporter would undo the requirement.
           ...(session?.token ? { 'X-BugCatch-Session': session.token } : {}),
         },
-        body: JSON.stringify(payload),
+        body: JSON.stringify(withHeldToken(payload)),
       });
     } catch (cause) {
       // No response at all: the wrong apiBase, the API down, or CORS refusing
@@ -1227,7 +1311,13 @@ class BugCatchClient {
       // 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 : ''}`);
+      // Too many, too fast: the one refusal that is nobody's mistake and that
+      // waiting fixes. Said as a sentence, because the widget puts this string
+      // in front of the person reporting, and "report failed (HTTP 429)" reads
+      // as though they broke something.
+      const err = res.status === 429
+        ? new Error(`[BugCatch] ${tooManyMessage(detail)}`)
+        : new Error(`[BugCatch] report failed (HTTP ${res.status})${detail ? ': ' + detail : ''}`);
       err.status = res.status;
       this.#failed('report', err);
       throw err;
@@ -1321,6 +1411,38 @@ class BugCatchClient {
     return this.agentIssueList;
   }
 
+  /**
+   * What this project's team is telling the people using its widget, narrowed
+   * to the visitor's own day and to what this browser has not closed.
+   *
+   *   const notices = await BugCatch.announcements();
+   *   // [{ id, title, body, tone: 'info' | 'success' | 'warning' | 'critical',
+   *   //    ctaLabel, ctaHref, placement: 'panel' | 'launcher', dismissible }]
+   *   BugCatch.dismissAnnouncement(notices[0]);
+   *
+   * Written and changed on the project's settings page, with no redeploy here;
+   * a browser asks at most every five minutes, so a change reaches visitors
+   * within that. The widget draws them itself — this is for a site running
+   * `widget: false` or `announcements: false`. Empty on every failure.
+   */
+  async announcements() {
+    const list = await fetchAnnouncements({
+      apiBase: this.config.apiBase,
+      apiKey: this.config.apiKey,
+      projectId: this.config.projectId,
+    });
+    return visibleAnnouncements(list);
+  }
+
+  /**
+   * Stop showing an announcement in this browser, until the team uses "Show it
+   * again". Takes one of announcements()' results; one that may not be closed
+   * is left alone.
+   */
+  dismissAnnouncement(announcement) {
+    rememberDismissed(announcement);
+  }
+
   /**
    * Who this browser is signed in as on this project, from storage alone.
    *

package/src/lazy.js

@@ -0,0 +1,23 @@
+// Where the parts of the SDK that most pages never use come from.
+//
+// Two parts are left out of the script every page loads: the report panel
+// (panel/), fetched the first time the launcher is pressed — or a little
+// before, see widget.js — and the call code (call.js), fetched when a call is
+// offered, placed, or rings.
+//
+// This is the ES build's way of fetching them: import(), which the host app's
+// bundler turns into chunks of its own and loads from wherever it put them.
+// The script-tag build has no bundler behind it and gets umd/lazy.js in this
+// file's place, with the same exports — see vite.config.js.
+//
+// Each resolves to the part's exports, and to the same promise every time once
+// it has arrived. `chunkBase` is the script-tag build's; a bundler decides for
+// itself where its chunks live.
+
+import { chunkUnavailable, once } from './chunks.js';
+
+export const loadPanel = once(() => import('./panel/index.js')
+  .catch((cause) => { throw chunkUnavailable('the report panel could not be loaded.', cause); }));
+
+export const loadCall = once(() => import('./call.js')
+  .catch((cause) => { throw chunkUnavailable('the calling code could not be loaded.', cause); }));

package/src/notice.js

@@ -0,0 +1,68 @@
+// One announcement as a card: beside the launcher, or at the top of the panel.
+// The rules for it are in the launcher's sheet (widget.js), because the card
+// beside the button is drawn before the panel's code exists.
+//
+// Built from nodes rather than markup. Every word on it was typed into a
+// settings page and lands on somebody else's site, and textContent cannot be
+// talked into being HTML.
+
+import * as ICONS from './icons.js';
+
+const TONE_ICON = {
+  info: ICONS.info, success: ICONS.check, warning: ICONS.warn, critical: ICONS.alert,
+};
+
+/**
+ * `where` is 'launcher' or 'panel'. `onDismiss` is called with the
+ * announcement when its × is pressed; a notice that may not be closed has none.
+ */
+export function noticeNode(a, { where, onDismiss }) {
+  const card = document.createElement('div');
+  card.className = `notice tone-${a.tone} at-${where}`;
+  // A status, not an alert: it is news the visitor did not ask for, and a
+  // screen reader should get to it when it is done with what they were doing.
+  card.setAttribute('role', 'status');
+
+  const ico = document.createElement('span');
+  ico.className = 'notice-ico';
+  ico.setAttribute('aria-hidden', 'true');
+  ico.innerHTML = TONE_ICON[a.tone] || ICONS.info;
+
+  const text = document.createElement('div');
+  text.className = 'notice-text';
+  const title = document.createElement('strong');
+  title.textContent = a.title;
+  text.append(title);
+  if (a.body) {
+    const body = document.createElement('p');
+    body.textContent = a.body;
+    text.append(body);
+  }
+  if (a.ctaHref && a.ctaLabel) {
+    const link = document.createElement('a');
+    link.className = 'notice-cta';
+    link.href = a.ctaHref;
+    link.textContent = a.ctaLabel;
+    // A path is a page on this site and opens here, like any other link on
+    // it. An address is somewhere else, and leaving the page for it would
+    // take a half-written report with it.
+    if (/^https?:/i.test(a.ctaHref)) {
+      link.target = '_blank';
+      link.rel = 'noopener noreferrer';
+    }
+    text.append(link);
+  }
+
+  card.append(ico, text);
+
+  if (a.dismissible && onDismiss) {
+    const close = document.createElement('button');
+    close.type = 'button';
+    close.className = 'notice-x';
+    close.setAttribute('aria-label', 'Dismiss this notice');
+    close.innerHTML = ICONS.close;
+    close.addEventListener('click', () => onDismiss(a));
+    card.append(close);
+  }
+  return card;
+}