@sphoro/bugcatch-web-sdk 0.17.0 → 0.18.0

package/src/index.js

@@ -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.
@@ -44,6 +50,11 @@ const DEFAULTS = {
   // 'auto' follows the visitor's system setting; 'light' / 'dark' pin it.
   theme: 'auto',
   accent: '#4F46E5',
+  // 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 +106,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 };
@@ -600,6 +633,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 +815,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 +916,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 +926,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 +1001,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 +1266,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 +1292,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 +1392,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;
+}

package/src/panel/call.js

@@ -0,0 +1,242 @@
+// Talking to the team instead of typing: the offer on the form, the screen
+// that replaces the form while the team is rung, and the bar that sits over a
+// report's thread during a call about it.
+//
+// Only what the reporter sees. Placing the call, the microphone and the
+// connection are the client's (startCall, startLiveCall in index.js), and their
+// code is fetched only when a call is actually placed.
+
+import * as ICONS from './icons.js';
+import { humanDuration } from '../capture.js';
+import { escapeHtml } from './render.js';
+
+export function mountCallOffer(ctx) {
+  const {
+    client, scrim, say, callBtn, close,
+  } = ctx;
+
+  // Asked once, when the dialog opens, and the button stays hidden unless the
+  // answer is yes. Doing it here rather than at init keeps one request off the
+  // page load of every site this SDK is on, for a button most of them will
+  // never show.
+  //
+  // The wording is fixed because there is one kind of call: it rings a room and
+  // may go unanswered. A button that said "talk to us" would have somebody
+  // expecting an instant answer sit through twenty seconds of ringing.
+  let callOffered = false;
+  function offerCall() {
+    client.callKind()
+      .then((kind) => {
+        if (!kind) return;
+        callOffered = true;
+        // Offered, so fetch what placing it needs now: the press should ring,
+        // not wait for code.
+        ctx.preloadCall();
+        // Never over a panel that is still asking who this is: the call would
+        // file a report, and on a project that requires sign-in that is the one
+        // thing this panel is holding back.
+        callBtn.hidden = ctx.mustSignIn();
+      })
+      .catch(() => { /* not available is the safe answer to every failure */ });
+  }
+  offerCall();
+
+  callBtn.addEventListener('click', async () => {
+    ctx.sending = true;
+    say('');
+    ctx.refreshSendState();
+    callBtn.disabled = true;
+    callBtn.innerHTML = '<span class="spinner"></span>Ringing…';
+
+    try {
+      // No id: this files the report from what the page was doing and rings the
+      // team about it, in one round trip.
+      const handle = await client.startCall();
+      showCall(handle);
+    } catch (err) {
+      ctx.sending = false;
+      callBtn.disabled = false;
+      callBtn.innerHTML = `${ICONS.phone}Talk to the team`;
+      ctx.refreshSendState();
+      // A report filed with no call is still a report. Saying "the call
+      // failed" and nothing else would leave the reporter thinking their
+      // context went nowhere, and pressing Send again would file it twice.
+      if (err.filed) ctx.succeed(err.filed, { callFailed: err.reason || 'The call could not be started.' });
+      else {
+        say(err.message.replace('[BugCatch] ', ''));
+        // The same follow-up the Send button does, because a call can fail for
+        // the same reason a report can: this browser was signed out while the
+        // panel sat open. Without it the message says sign in while the row
+        // under it still names who signed in, which reads as a broken widget.
+        ctx.recheckSignIn();
+      }
+    }
+  });
+
+  /**
+   * The call, once the team is being rung.
+   *
+   * Replaces the panel for the same reason the history view does: it is the
+   * same dialog answering a different question, and the reporter got here from
+   * one launcher. There is no way back to the form — the report has already
+   * been filed, and a Cancel that implied otherwise would be a lie.
+   */
+  function showCall(handle) {
+    const panel = scrim.querySelector('.panel');
+    const ref = handle?.bugId ? String(handle.bugId).slice(0, 8) : null;
+
+    panel.innerHTML = `
+      <div class="call">
+        <div class="call-head">
+          <span class="call-dot" aria-hidden="true"></span>
+          <strong class="call-state">Ringing…</strong>
+        </div>
+        <p class="call-note">
+          We're ringing the team now. Someone will pick up if they're free — your report${
+            ref ? ` <code>${escapeHtml(ref)}</code>` : ''} is already filed either way, so nothing is lost if nobody answers.
+        </p>
+        <div class="foot">
+          <span class="spacer"></span>
+          <button class="primary" type="button" data-act="hangup">Cancel</button>
+        </div>
+      </div>`;
+
+    const stateEl = panel.querySelector('.call-state');
+    const dot = panel.querySelector('.call-dot');
+
+    // A call spends its first twenty seconds ringing, and can end by nobody
+    // picking up — which is not a failure and must not read as one.
+    const WORDING = {
+      ringing: 'Ringing the team…',
+      connecting: 'Someone answered — connecting…',
+      connected: 'Connected',
+      missed: 'Nobody was free',
+      ended: 'Call ended',
+      failed: 'The call dropped',
+    };
+
+    // `missed` is over too, and is the ordinary way a live call ends when the
+    // team is busy. Left out of this list it would leave the dialog showing
+    // "Nobody was free" above a Cancel button for a call that has already
+    // stopped.
+    const OVER = ['ended', 'failed', 'missed'];
+
+    const offState = client.on('call', ({ state }) => {
+      stateEl.textContent = WORDING[state] || state;
+      dot.classList.toggle('off', OVER.includes(state));
+      if (OVER.includes(state)) {
+        panel.querySelector('[data-act="hangup"]').textContent = 'Close';
+        if (state === 'missed') {
+          // Said plainly, and said as the non-event it is. The report is filed
+          // and the thread already says the call went unanswered, so the one
+          // thing left to tell them is that they have not lost anything.
+          const note = panel.querySelector('.call-note');
+          if (note) {
+            note.textContent = 'Nobody was free to pick up just now. Your report is filed '
+              + 'and the team will reply in the chat.';
+          }
+        }
+      }
+    });
+
+    panel.querySelector('[data-act="hangup"]').addEventListener('click', () => {
+      offState();
+      client.endCall();
+      close();
+    });
+  }
+
+  /**
+   * The call, on top of the report it is about.
+   *
+   * A bar rather than a screen of its own, unlike the one the composer's button
+   * opens — and for a reason that only applies here. A call has nothing to show
+   * while it runs, because nobody is listening to it but the person on the
+   * other end, so what is worth looking at is the report both people are
+   * talking about.
+   */
+  function showLiveCall(body, thread, handle) {
+    const bar = document.createElement('div');
+    bar.className = 'livecall';
+    bar.innerHTML = `
+      <span class="call-dot" aria-hidden="true"></span>
+      <span class="who" role="status" aria-live="polite">Calling the team…</span>
+      <span class="secs" hidden></span>
+      ${handle?.recorded ? '<span class="call-kept">This call is recorded.</span>' : ''}
+      <button class="act" type="button" data-act="mute" hidden>Mute</button>
+      <button class="act danger" type="button" data-act="hangup">Cancel</button>`;
+    body.insertBefore(bar, thread);
+
+    const who = bar.querySelector('.who');
+    const secs = bar.querySelector('.secs');
+    const dot = bar.querySelector('.call-dot');
+    const muteBtn = bar.querySelector('[data-act="mute"]');
+    const hangBtn = bar.querySelector('[data-act="hangup"]');
+
+    let ticker = null;
+    const stopTicking = () => { if (ticker) { clearInterval(ticker); ticker = null; } };
+
+    /** Left up rather than removed, so somebody who looked away can see how it
+     *  ended — and dismissed by hand, or by the next call replacing it. */
+    const settle = (text) => {
+      stopTicking();
+      dot.classList.add('off');
+      bar.classList.add('over');
+      who.textContent = text;
+      secs.hidden = true;
+      muteBtn.hidden = true;
+      hangBtn.textContent = 'Dismiss';
+      hangBtn.classList.remove('danger');
+    };
+
+    const off = client.on('call', ({ state }) => {
+      if (state === 'ringing') who.textContent = 'Calling the team…';
+
+      if (state === 'connecting') {
+        who.textContent = 'Someone answered — connecting…';
+      }
+
+      if (state === 'connected') {
+        who.textContent = "You're on a call with the team";
+        muteBtn.hidden = false;
+        secs.hidden = false;
+        const from = Date.now();
+        stopTicking();
+        // Started on connect rather than on answer: the seconds a person is
+        // charged for looking at are the ones they could hear.
+        ticker = setInterval(() => {
+          secs.textContent = humanDuration(Math.floor((Date.now() - from) / 1000));
+        }, 1000);
+        secs.textContent = '0s';
+      }
+
+      if (state === 'missed') {
+        settle('Nobody was free. Send a message instead and the team will pick it up.');
+      }
+      if (state === 'ended') settle('Call ended.');
+      if (state === 'failed') settle('The call dropped.');
+    });
+
+    muteBtn.addEventListener('click', () => {
+      const muted = handle.setMuted(!handle.isMuted());
+      muteBtn.textContent = muted ? 'Unmute' : 'Mute';
+      // Announced rather than only shown: somebody who muted by accident finds
+      // out when the other person stops replying, which is a long way in.
+      who.textContent = muted ? "You're muted" : "You're on a call with the team";
+    });
+
+    hangBtn.addEventListener('click', () => {
+      off();
+      stopTicking();
+      client.endCall();
+      bar.remove();
+      // The note about the call lands in the thread a moment after it ends, and
+      // the reporter is looking straight at where it goes.
+      ctx.refreshThread(ctx.openReportId());
+    });
+  }
+
+  ctx.offerCall = offerCall;
+  ctx.callOffered = () => callOffered;
+  ctx.showLiveCall = showLiveCall;
+}