@sphoro/bugcatch-web-sdk 0.13.1

package/src/index.js

@@ -0,0 +1,1217 @@
+import {
+  createRingBuffer, installConsoleCapture, installNetworkCapture,
+  installErrorCapture, collectEnvironment, collectEnvironmentSync,
+} from './collectors.js';
+import { mountWidget } from './widget.js';
+import { uploadAttachment, normalizeMime, REPORT_MIMES } from './capture.js';
+import {
+  watchUpdates, createUpdateNotifier, fetchMyReports, fetchReport, writeToken, readToken,
+  clearToken, sendMessage, callAvailable, callKindForProject, requestCall,
+  reportByCall, liveCallAvailable, requestLiveCall, giveUpLiveCall,
+  answerIncomingCall, declineIncomingCall,
+  readUnread, rememberUpdate, forgetUpdate, forgetReportUpdates, forgetAllUpdates,
+  fetchKnownIssues, matchKnownIssues, joinKnownIssue,
+  UNREAD_KEY,
+} from './updates.js';
+import {
+  loginState, startSignIn, confirmSignIn, endSignIn, readSession, clearSession,
+} from './session.js';
+import { startVoiceCall } from './voice.js';
+import { joinLiveCall, liveCallSupported, openMicrophone } from './live-call.js';
+import { showIncomingCall } from './incoming-call.js';
+
+// Replaced at build time from package.json. The guard is for anyone importing
+// src/ directly, where the define never runs.
+const SDK_IDENTITY = {
+  name: typeof __SDK_NAME__ === 'string' ? __SDK_NAME__ : '@sphoro/bugcatch-web-sdk',
+  version: typeof __SDK_VERSION__ === 'string' ? __SDK_VERSION__ : '0.0.0-dev',
+};
+
+const DEFAULTS = {
+  apiBase: 'http://localhost:3000',
+  apiKey: null,
+  projectId: null,
+  consoleLimit: 100,
+  networkLimit: 50,
+  captureConsole: true,
+  captureNetwork: true,
+  captureErrors: true,
+  // Shows the floating "Report a bug" button. Turn off to drive it yourself.
+  widget: true,
+  widgetPosition: 'bottom-right',
+  // 'auto' follows the visitor's system setting; 'light' / 'dark' pin it.
+  theme: 'auto',
+  accent: '#4F46E5',
+  // Screenshot / screen recording / file attach. Capture needs getDisplayMedia,
+  // so it is offered only where the browser has it — file attach always works.
+  attachments: true,
+  maxAttachments: 5,
+  maxAttachmentBytes: 25 * 1024 * 1024,
+  maxRecordingMs: 120_000,
+  // Called before send; return false to cancel, or mutate the payload to scrub.
+  beforeSend: null,
+  user: null,
+  // Tell the reporter when a bug they filed changes status — live, in your
+  // app, where they already are. Off means no connection is opened at all.
+  updates: true,
+  // Show the built-in notification when an update arrives. It stays until the
+  // reporter marks it read — including across a reload — so an update is not
+  // lost to whoever happened to be looking at the tab. Turn it off and drive
+  // the notification yourself from onUpdate and unreadUpdates().
+  updateToast: true,
+  // Called with { id, bugId, title, status, at } whenever one of this browser's
+  // reports moves. Runs whether or not the built-in notification is on; `id` is
+  // what markUpdateRead() takes.
+  onUpdate: null,
+  // Offer a voice call when a report is picked up, if the workspace has
+  // sphoro.voice configured. Nothing is dialled and no permission is asked for
+  // until somebody presses the button — see startCall().
+  voice: true,
+  // Called as a call moves: 'connecting', 'listening', 'speaking', 'ended',
+  // 'failed'. The SDK shows nothing of its own beyond the offer, so an
+  // integration that wants a call UI builds it from this and onCallTranscript.
+  onCallState: null,
+  // Called with { role, text, final } for each line, as it is recognised.
+  onCallTranscript: null,
+  // Called with { bugId, callId, from, project, reference, ringsUntil,
+  // recorded } when somebody on the team rings this page about a report filed
+  // from it. The SDK has already drawn the card by then — this is for a host
+  // application that wants to duck its own audio or pause a video, not a hook
+  // that can suppress a call the person can see ringing. Set `voice: false` to
+  // switch the whole thing off.
+  onIncomingCall: null,
+};
+
+class BugCatchClient {
+  constructor() {
+    this.config = { ...DEFAULTS };
+    this.started = false;
+    this.teardown = [];
+    this.consoleBuffer = createRingBuffer(DEFAULTS.consoleLimit);
+    this.networkBuffer = createRingBuffer(DEFAULTS.networkLimit);
+    this.stopWatching = null;
+    // The built-in notification stack, built on first use: an integration that
+    // renders its own never has one, and neither does a visitor who has nothing
+    // unread.
+    this.notifier = null;
+    // The call in progress, if any, and whether one is being connected. One at
+    // a time: a second would be two microphones on one page talking over each
+    // other.
+    this.call = null;
+    this.callStarting = false;
+    // The card on screen for a call the team is placing to this page, if any.
+    // Distinct from `call` above, which is a conversation in progress: this is
+    // a telephone that has not been picked up, and the two exist at different
+    // moments — a call cannot be ringing and connected at once.
+    this.ringing = null;
+    // 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();
+  }
+
+  init(options = {}) {
+    if (this.started) {
+      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.');
+
+    this.consoleBuffer = createRingBuffer(this.config.consoleLimit);
+    this.networkBuffer = createRingBuffer(this.config.networkLimit);
+
+    if (this.config.captureConsole) this.teardown.push(installConsoleCapture(this.consoleBuffer));
+    if (this.config.captureNetwork) this.teardown.push(installNetworkCapture(this.networkBuffer));
+    if (this.config.captureErrors) this.teardown.push(installErrorCapture(this.consoleBuffer));
+    if (this.config.widget) this.teardown.push(mountWidget(this));
+
+    // Only if this browser has actually filed something. A visitor who has
+    // never reported has nothing to be told about, and opening a connection
+    // for them would be a request on every page load that can never deliver.
+    if (this.config.updates && readToken()) {
+      this.startWatching();
+      // Whatever was still unread when they last closed the tab. The stream
+      // replays nothing on connect, so without this an update that arrived
+      // while somebody was away would be gone by the time they came back.
+      //
+      // A tick late, so the count reaches a listener registered on the line
+      // after init() — which is where every integration registers one, and
+      // where a synchronous emit would fire into an empty room.
+      queueMicrotask(() => this.#drawUnread());
+    }
+
+    this.started = true;
+    return this;
+  }
+
+  /**
+   * Open the update stream. Idempotent — init() and a first report both reach
+   * here, and a second connection would double every notification.
+   */
+  startWatching() {
+    if (this.stopWatching) return this;
+    this.stopWatching = watchUpdates({
+      apiBase: this.config.apiBase,
+      onUpdate: (event) => {
+        // A telephone, not an update — taken first and returned on, so it
+        // neither queues behind a status line nor lands in the unread store. A
+        // call is worthless thirty seconds after it is sent, and an unread
+        // badge that still says "someone called" tomorrow morning is a badge
+        // nobody trusts.
+        if (event?.incomingCall) { this.#ring(event); return; }
+        if (event?.callWithdrawn) { this.#stopRinging(event.callWithdrawn.callId); return; }
+
+        // Held before it is shown, and held until it is read. The card on
+        // screen is a view of this store rather than the notification itself,
+        // which is what lets a reload, a second tab, or the widget marking it
+        // read all agree about what is still outstanding.
+        const update = rememberUpdate(event);
+        if (typeof this.config.onUpdate === 'function') this.config.onUpdate(update);
+        // Listeners registered with on('update') get the same frame. The
+        // widget uses this to refresh a report the reader has open, so a
+        // change lands on screen rather than waiting for them to reopen it —
+        // and to mark it read, which is why this runs before the redraw.
+        this.emit('update', update);
+        this.#drawUnread();
+      },
+    });
+    this.teardown.push(() => this.stopWatching?.());
+    // And a card left ringing when the SDK is torn down is a card that rings
+    // forever: the stream that would withdraw it has just been closed.
+    this.teardown.push(() => this.#stopRinging());
+
+    // Another tab of the same app reads one. They share the store, so they
+    // share what is outstanding — without this, a card marked read in one tab
+    // sits there in the other, over an app that already knows about it.
+    const onStorage = (event) => {
+      // A null key is localStorage.clear(), which takes the store with it.
+      if (event.key === UNREAD_KEY || event.key === null) this.#drawUnread();
+    };
+    window.addEventListener('storage', onStorage);
+    this.teardown.push(() => window.removeEventListener('storage', onStorage));
+    return this;
+  }
+
+  /**
+   * Subscribe to updates on this browser's reports. Returns an unsubscribe.
+   *
+   *   const off = BugCatch.on('update', (u) => console.log(u.summary));
+   *
+   * Alongside the `onUpdate` config option rather than replacing it: that one
+   * is the single handler an integration sets at init, this one lets several
+   * parts of an app listen independently — a badge, a toast of your own, an
+   * open report view — without them having to agree on one callback.
+   */
+  on(event, handler) {
+    if (typeof handler !== 'function') return () => {};
+    const set = this.listeners.get(event) || new Set();
+    set.add(handler);
+    this.listeners.set(event, set);
+    return () => this.off(event, handler);
+  }
+
+  off(event, handler) {
+    this.listeners.get(event)?.delete(handler);
+    return this;
+  }
+
+  /** Notify listeners; one that throws must not stop the rest. */
+  emit(event, payload) {
+    for (const fn of this.listeners.get(event) || []) {
+      try {
+        fn(payload);
+      } 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);
+      }
+    }
+  }
+
+  /**
+   * Updates this browser has been told about and nobody has read yet, oldest
+   * first.
+   *
+   *   BugCatch.unreadUpdates().length   // a badge on your own bell
+   *
+   * Survives a reload: the stream replays nothing when it reconnects, so an
+   * update that arrived while the tab was closed would otherwise be gone.
+   * Each carries the `id` the mark-read calls take.
+   */
+  unreadUpdates() {
+    return readUnread();
+  }
+
+  /**
+   * Mark one update read. It stops being shown, here and on the next load.
+   *
+   *   BugCatch.on('update', (u) => myBell.add(u, () => BugCatch.markUpdateRead(u.id)));
+   *
+   * Read is something the reporter says, not something a timer decides — which
+   * is the whole reason these are held rather than shown for eight seconds and
+   * dropped. An integration rendering its own notifications is the one that
+   * knows when its reader has seen one, so it has to say.
+   */
+  markUpdateRead(id) {
+    forgetUpdate(id);
+    this.#drawUnread();
+    return this;
+  }
+
+  /**
+   * Mark everything about one report read.
+   *
+   * Opening the report is reading its updates, so the widget calls this when
+   * the thread opens; an integration with its own report view should too.
+   */
+  markReportRead(bugId) {
+    forgetReportUpdates(bugId);
+    this.#drawUnread();
+    return this;
+  }
+
+  /** Mark everything read. The "clear all" behind your own notification list. */
+  markUpdatesRead() {
+    forgetAllUpdates();
+    this.#drawUnread();
+    return this;
+  }
+
+  /**
+   * Redraw the built-in notifications, and tell anyone counting.
+   *
+   * The single path out of the unread store: every add and every mark-read ends
+   * here, so the cards on screen and a host app's own badge cannot disagree
+   * about what is outstanding.
+   */
+  #drawUnread() {
+    const unread = readUnread();
+    // Emitted whether or not the built-in cards are on — this is the number a
+    // host app puts on its own bell.
+    this.emit('unread', { count: unread.length, updates: unread });
+
+    if (!this.config.updateToast) return;
+    if (!this.notifier) {
+      if (!unread.length) return;
+      this.notifier = createUpdateNotifier({
+        accent: this.config.accent,
+        position: this.config.widgetPosition,
+        onRead: (id) => this.markUpdateRead(id),
+        onReadAll: () => this.markUpdatesRead(),
+        // The call button appears only where the API said the offer stands and
+        // this page has calling switched on. Pressing it reads the update —
+        // acting on a notification is the clearest way there is of having seen
+        // it — and `startCall` does the rest.
+        onCall: this.config.voice
+          ? (update) => {
+            this.markUpdateRead(update.id);
+            void this.startCall(update.bugId);
+          }
+          : null,
+      });
+      this.teardown.push(() => this.notifier?.destroy());
+    }
+    this.notifier.render(unread);
+  }
+
+  /**
+   * One report in full, with its timeline — every step from filing to now.
+   *
+   *   const report = await BugCatch.myReport(id);
+   *   report.timeline // [{ kind: 'filed' | 'status' | 'severity' | ... , summary, at }]
+   *
+   * Resolves to null when this browser cannot prove it filed that report.
+   */
+  myReport(bugId) {
+    return fetchReport({ apiBase: this.config.apiBase, bugId });
+  }
+
+  /**
+   * Write back on a report this browser filed.
+   *
+   *   const key = await BugCatch.uploadAttachment(file, file.type);
+   *   await BugCatch.replyToReport(id, {
+   *     body: 'Still happening on Safari',
+   *     attachments: [{ ...key, name: file.name, size: file.size }],
+   *   });
+   *
+   * The widget's own conversation view calls this; it is public so an
+   * integration rendering its own can too. Resolves to the stored message, so
+   * the caller renders what the server kept rather than what it hoped it sent.
+   */
+  replyToReport(bugId, { body, attachments } = {}) {
+    return sendMessage({ apiBase: this.config.apiBase, bugId, body, attachments });
+  }
+
+  /**
+   * Everything a report carries, however it was started.
+   *
+   * Shared by `report()` and by pressing Call, because the two file the same
+   * thing — the difference is only whether a person typed the title or the
+   * agent asks for it. Two 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 = [] }) {
+    return {
+      projectId: this.config.projectId,
+      ...(title ? { title } : {}),
+      description,
+      priority,
+      url: window.location.href,
+      reporterEmail: this.config.user?.email,
+      // Sent alongside the address so the dashboard can show a person rather
+      // than a mailbox, and so the resolution email can open with their name.
+      reporterName: this.config.user?.name,
+      metadata: {
+        ...(await collectEnvironment()),
+        ...metadata,
+        user: this.config.user || undefined,
+        sdk: SDK_IDENTITY,
+      },
+      logs: {
+        console: { entries: this.consoleBuffer.all() },
+        network: { entries: this.networkBuffer.all() },
+      },
+      // Omitted rather than sent empty: the field is optional server-side, and
+      // an empty array in every payload makes beforeSend hooks harder to read.
+      ...(media.length ? { attachments: media } : {}),
+    };
+  }
+
+  /**
+   * File a report because somebody pressed Call instead of filling the form in.
+   *
+   * Both kinds of call come through here — the triage agent and ringing the
+   * team — because filing is the half the two share, and it is the half that
+   * has to say who is filing. Held in one place after a session header went
+   * missing from this route while `report()` kept sending it: nothing looked
+   * wrong until a project switched sign-in on, and then a signed-in reporter
+   * pressing Call was told to sign in.
+   */
+  async #fileByCall() {
+    const session = readSession(this.config.projectId);
+
+    let filed;
+    try {
+      filed = await reportByCall({
+        apiBase: this.config.apiBase,
+        apiKey: this.config.apiKey,
+        token: session?.token,
+        payload: await this.#payload({}),
+      });
+    } catch (err) {
+      // A session the server no longer recognises, dropped exactly as
+      // `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);
+      throw err;
+    }
+
+    // The same token `report()` keeps, and for the same reason: it is what lets
+    // this browser hear what happens to the report afterwards.
+    if (filed.watchToken) {
+      writeToken(filed.watchToken);
+      if (this.config.updates) this.startWatching();
+    }
+    return filed;
+  }
+
+  /**
+   * Whether this visitor can report something by talking about it instead.
+   *
+   *   if (await BugCatch.canCallNow()) showYourOwnCallButton();
+   *
+   * Two conditions, and both have to hold before anything is drawn. The project
+   * has to have calling configured — false on most deployments — and this
+   * browser has to know who the visitor is, because a call with nobody to
+   * attribute it to has no watch token to follow it with and nobody to send the
+   * transcript to afterwards. That is the same limit every other follow-up
+   * feature in this SDK has: it all hangs off `identify()`.
+   */
+  async canCallNow() {
+    return Boolean(await this.callKind());
+  }
+
+  /**
+   * Which kind of call this visitor would get: 'agent', 'live', or null.
+   *
+   *   const kind = await BugCatch.callKind();
+   *   // 'agent' — a model answers and asks the questions the form did not
+   *   // 'live'  — the team's dashboards ring and a colleague picks up
+   *
+   * A deployment offers one or the other, never both: a sphoro.voice agent has
+   * exactly one mode. Worth asking rather than assuming, because the two are
+   * wholly different promises to make to somebody — and the wording next to the
+   * button has to match which one it is.
+   *
+   * The answer is remembered for the life of the page. It is a property of the
+   * deployment's configuration rather than of this visitor, and re-asking on
+   * every dialog open is a request per page view for something that changes
+   * about once a year.
+   */
+  async callKind() {
+    if (!this.config.voice) return null;
+    if (!this.config.user?.email) return null;
+    if (this.kind !== undefined) return this.kind;
+    this.kind = await callKindForProject({
+      apiBase: this.config.apiBase,
+      apiKey: this.config.apiKey,
+      projectId: this.config.projectId,
+    });
+    return this.kind;
+  }
+
+  /**
+   * Whether a report can be talked through right now.
+   *
+   *   if (await BugCatch.canCall(id)) showYourOwnButton();
+   *
+   * False on every deployment without sphoro.voice configured, on every
+   * workspace that has not switched calling on, and on a report that has had
+   * its allowance of calls — so an integration rendering its own affordance can
+   * ask rather than guess.
+   */
+  canCall(bugId) {
+    if (!this.config.voice) return Promise.resolve(false);
+    return callAvailable({ apiBase: this.config.apiBase, bugId });
+  }
+
+  /**
+   * Talk to the triage agent.
+   *
+   *   await BugCatch.startCall(id);   // about a report already filed
+   *   await BugCatch.startCall();     // instead of filling the form in
+   *
+   * With a report id, it talks about that report. With none, it files one first
+   * — carrying the console, network and environment this SDK is already holding
+   * — and then calls about that. The report is written before the call starts
+   * either way, so a call that drops still leaves the context behind; the
+   * handle carries `bugId` so the caller can say what it was filed as.
+   *
+   * Asks for the microphone, opens the call, and resolves once it is connected.
+   * What is said reaches the team as a message in the report's thread when the
+   * call ends — nobody from the team is on the line, and the agent says so.
+   *
+   * Rejects if the microphone is refused, if calling is not available, or if
+   * one is already running. There is deliberately no way to start a second: two
+   * microphones on one page talk over each other, and the second call would be
+   * transcribing the first. A rejection carrying `.filed` means the report was
+   * written and only the call failed.
+   */
+  async startCall(bugId) {
+    if (!this.config.voice) throw new Error('[BugCatch] calling is switched off.');
+    // Two checks, because there are two ways to already be on a call: one that
+    // has connected, and one still asking for the microphone. A double-click
+    // races past a check on `this.call` alone — the second press gets through
+    // while the first is still awaiting, and the page ends up with two sockets
+    // and two microphones transcribing each other.
+    if (this.call || this.callStarting) {
+      throw new Error('[BugCatch] a call is already running.');
+    }
+    this.callStarting = true;
+
+    try {
+      return await this.#connectCall(bugId);
+    } finally {
+      this.callStarting = false;
+    }
+  }
+
+  /** The body of startCall, so the in-flight flag is cleared on every path. */
+  async #connectCall(bugId) {
+    // Which kind of call this deployment actually offers, asked before anything
+    // is filed. `startCall` is the one entry point most integrations use — the
+    // widget's own button included — so it has to land on whichever kind the
+    // agent is, rather than on the one this method was originally written for.
+    //
+    // Without this the agent path ran against a person-to-person agent: the call
+    // came back *ringing*, the API refused it rather than connect a reporter to a
+    // rendezvous over the µ-law agent protocol, and all the reporter saw was a
+    // report they had not meant to file.
+    if (await this.callKind() === 'live') return this.#ringTheTeam(bugId);
+
+    let realtimeUrl;
+    let filed = null;
+
+    if (bugId) {
+      ({ realtime_url: realtimeUrl } = await requestCall({
+        apiBase: this.config.apiBase, bugId,
+      }));
+    } else {
+      // No report yet: this is somebody who pressed Call instead of filling the
+      // form in. One round trip files what the page was doing and starts the
+      // call about it, so a call that never connects still leaves the context
+      // behind.
+      filed = await this.#fileByCall();
+      bugId = filed.id;
+      realtimeUrl = filed.realtime_url;
+      if (!realtimeUrl) {
+        // Filed, but no call. Reported as such rather than thrown: the report
+        // exists and the caller has to be able to say so.
+        const err = new Error('[BugCatch] the report was filed, but no call could be started.');
+        err.filed = filed;
+        throw err;
+      }
+    }
+
+    const handle = await startVoiceCall({
+      realtimeUrl,
+      onState: (state, detail) => {
+        if (state === 'ended' || state === 'failed') this.call = null;
+        if (typeof this.config.onCallState === 'function') {
+          this.config.onCallState(state, { bugId, ...detail });
+        }
+        this.emit('call', { bugId, state, ...detail });
+      },
+      onTranscript: (line) => {
+        if (typeof this.config.onCallTranscript === 'function') {
+          this.config.onCallTranscript({ bugId, ...line });
+        }
+        this.emit('call-transcript', { bugId, ...line });
+      },
+    });
+
+    // Set after the await, not before: a call that never connected is not one
+    // this page is on, and leaving the slot taken would block the retry.
+    this.call = handle;
+    // `bugId` on the handle so a caller that did not name one — the Call
+    // button — can tell the reporter what their report is called.
+    return Object.assign(handle, { bugId, filed });
+  }
+
+  /**
+   * Talk to a person on the team.
+   *
+   *   await BugCatch.startLiveCall(id);
+   *
+   * The other kind of call. `startCall` reaches the triage agent, which answers
+   * instantly and asks the three questions the form did not; this rings the
+   * team, and whoever is free picks it up. What comes back is a conversation
+   * with a colleague — the audio travels directly between the two browsers over
+   * WebRTC and never reaches bugcatch or sphoro.voice, so it is not recorded and
+   * not transcribed. The thread gets a note saying it happened and who took it.
+   *
+   * Resolves once the call is *ringing*, not once somebody answers — the
+   * handle's `onState` is how the caller follows what happens next:
+   *
+   *   'ringing'    the team's dashboards are lighting up
+   *   'connecting' somebody answered; the two browsers are finding each other
+   *   'connected'  they can hear each other
+   *   'missed'     nobody picked up before the ringing stopped
+   *   'ended'      it is over
+   *
+   * A report id is required, unlike `startCall`. Ringing a room about a report
+   * nobody can read would ask somebody to answer a call they know nothing
+   * about — and the agent call's trick of filing first and taking a title from
+   * the transcript is not available here, because there is no transcript.
+   *
+   * Rejects if the microphone is refused, if live calling is not available on
+   * this report, or if a call of either kind is already running: this page has
+   * one microphone, and two calls on it would talk over each other.
+   */
+  async startLiveCall(bugId) {
+    if (!this.config.voice) throw new Error('[BugCatch] calling is switched off.');
+    if (!bugId) throw new Error('[BugCatch] startLiveCall needs the id of a filed report.');
+    if (!liveCallSupported()) {
+      throw new Error('[BugCatch] this browser cannot make live calls.');
+    }
+    // The same two checks `startCall` makes, against the same slot, because the
+    // two kinds of call compete for the same microphone — a live call started
+    // while the agent is mid-sentence would be two conversations in one room.
+    if (this.call || this.callStarting) {
+      throw new Error('[BugCatch] a call is already running.');
+    }
+    this.callStarting = true;
+
+    try {
+      return await this.#ringTheTeam(bugId);
+    } finally {
+      this.callStarting = false;
+    }
+  }
+
+  /** The body of startLiveCall, so the in-flight flag clears on every path. */
+  async #ringTheTeam(bugId) {
+    // 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
+    // be on. That ordering is why the report below is filed *after* the
+    // microphone too, even though filing it first is what the agent path does:
+    // on this kind of call, filing is what makes the phones ring.
+    if (!liveCallSupported()) {
+      throw new Error('[BugCatch] this browser cannot make live calls.');
+    }
+    const microphone = await openMicrophone();
+
+    let started;
+    let filed = null;
+    try {
+      if (bugId) {
+        started = await requestLiveCall({ apiBase: this.config.apiBase, bugId });
+      } else {
+        // Nobody filled the form in. One round trip writes what the page was
+        // doing and rings the team about it — the same trade the agent path
+        // makes, so a call nobody answers still leaves the context behind.
+        filed = await this.#fileByCall();
+        bugId = filed.id;
+        started = filed.live_call;
+        if (!started?.realtime_url) {
+          // Filed, but nobody rang. Reported as such rather than thrown, so the
+          // caller can say what the report is called instead of losing it.
+          const err = new Error('[BugCatch] the report was filed, but the team could not be rung.');
+          err.filed = filed;
+          throw err;
+        }
+      }
+    } catch (err) {
+      for (const track of microphone.getTracks()) track.stop();
+      throw err;
+    }
+
+    const handle = await joinLiveCall({
+      realtimeUrl: started.realtime_url,
+      stream: microphone,
+      ringsUntil: started.rings_until,
+      onState: (state, detail) => {
+        if (state === 'ended' || state === 'failed' || state === 'missed') this.call = null;
+        // Nobody picked up, as decided by the one client that was listening to
+        // it. Told to the API so the thread says so; the reporter has already
+        // been shown it, and nothing here waits for the answer.
+        if (state === 'missed') {
+          giveUpLiveCall({ apiBase: this.config.apiBase, bugId, callId: started.call_id });
+        }
+        if (typeof this.config.onCallState === 'function') {
+          this.config.onCallState(state, { bugId, live: true, ...detail });
+        }
+        this.emit('call', { bugId, live: true, state, ...detail });
+      },
+    });
+
+    // Set after the await, exactly as the agent path does: a call that never
+    // connected is not one this page is on, and leaving the slot taken would
+    // block the retry.
+    this.call = handle;
+    return Object.assign(handle, { bugId, callId: started.call_id, live: true, filed });
+  }
+
+  /**
+   * Whether this report can be talked through with a person.
+   *
+   * For a host application drawing its own button. The widget asks this itself.
+   */
+  canCallTeam(bugId) {
+    if (!this.config.voice) return Promise.resolve(false);
+    return liveCallAvailable({ apiBase: this.config.apiBase, bugId });
+  }
+
+  // --- being called ------------------------------------------------------------
+
+  /**
+   * Somebody on the team is ringing this page.
+   *
+   * The only thing in this SDK that starts without the person on the page
+   * asking for it, which is why what it does is so much narrower than what the
+   * outgoing calls do: it draws a card and makes a soft noise. No microphone is
+   * opened and nothing is connected until Answer is pressed, and if nothing is
+   * pressed the card takes itself away when the ringing stops.
+   *
+   * Silently ignored when calling is switched off in this integration's config
+   * or the browser cannot hold a peer connection. A host application that has
+   * said `voice: false` has said its customers are not to be rung, and a card
+   * offering a call this page could not join would be worse than none.
+   */
+  #ring(event) {
+    const call = event.incomingCall;
+    if (!this.config.voice || !liveCallSupported()) 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;
+    // One microphone on this page, so one call. Somebody already talking is not
+    // interrupted by a card offering them a second conversation.
+    if (this.call || this.callStarting) return;
+
+    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' });
+      },
+    });
+
+    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' });
+  }
+
+  /** Take the card away, whatever it is showing. */
+  #stopRinging(callId) {
+    if (!this.ringing) return;
+    if (callId && this.ringing.callId !== callId) return;
+    try { this.ringing.dismiss(); } catch { /* already gone */ }
+    this.ringing = null;
+  }
+
+  /**
+   * Answer it: microphone first, then the claim, then the socket.
+   *
+   * That order is the same one every other call in this file uses and it
+   * matters most here. The permission prompt takes as long as the person takes
+   * to read it, and claiming the call before they have answered it would put
+   * somebody on a conversation they may yet decline to be able to speak on —
+   * with a member of the team on the other end saying hello to a muted browser.
+   */
+  async #answer(bugId, call) {
+    this.ringing = null;
+    if (this.call || this.callStarting) return;
+    this.callStarting = true;
+
+    let microphone;
+    try {
+      microphone = await openMicrophone();
+    } catch (err) {
+      this.callStarting = false;
+      // Refused the prompt, or no microphone on this machine. The call is still
+      // ringing at the other end, so it is declined rather than left — the
+      // member calling should not wait out the deadline for somebody who
+      // cannot speak to them.
+      declineIncomingCall({ apiBase: this.config.apiBase, bugId, callId: call.callId });
+      this.emit('incoming-call', { bugId, callId: call.callId, state: 'failed', error: err });
+      return;
+    }
+
+    let answered;
+    try {
+      answered = await answerIncomingCall({
+        apiBase: this.config.apiBase, bugId, callId: call.callId,
+      });
+    } catch (err) {
+      for (const track of microphone.getTracks()) track.stop();
+      this.callStarting = false;
+      // 409 is the ordinary one: it stopped ringing while Answer was being
+      // pressed. Reported as a state rather than thrown, because nobody called
+      // this — the page did, on somebody's behalf, and there is no promise
+      // waiting to reject.
+      this.emit('incoming-call', { bugId, callId: call.callId, state: 'missed', error: err });
+      return;
+    }
+
+    try {
+      const handle = await joinLiveCall({
+        realtimeUrl: answered.realtime_url,
+        stream: microphone,
+        // No deadline on this side. The ringing is over — it ended when this
+        // browser claimed the call — and a countdown here would hang up on a
+        // conversation that has already started.
+        onState: (state, detail) => {
+          if (state === 'ended' || state === 'failed' || state === 'missed') this.call = null;
+          if (typeof this.config.onCallState === 'function') {
+            this.config.onCallState(state, { bugId, live: true, incoming: true, ...detail });
+          }
+          this.emit('call', { bugId, live: true, incoming: true, state, ...detail });
+        },
+      });
+      this.call = handle;
+      this.emit('incoming-call', { bugId, callId: call.callId, state: 'answered' });
+    } catch (err) {
+      for (const track of microphone.getTracks()) track.stop();
+      this.emit('incoming-call', { bugId, callId: call.callId, state: 'failed', error: err });
+    } finally {
+      this.callStarting = false;
+    }
+  }
+
+  /**
+   * End the call in progress, of either kind. Does nothing when there is not
+   * one — there is a single slot, because there is a single microphone.
+   */
+  endCall() {
+    this.call?.hangUp();
+    this.call = null;
+    return this;
+  }
+
+  /**
+   * Everything this browser has reported, newest first, with the status of
+   * each — the history a reporter normally has no way to see.
+   *
+   *   const { reports } = await BugCatch.myReports();
+   *   // [{ reference: '3F2A9B01', title, status, priority, createdAt, ... }]
+   *
+   * Resolves to an empty history rather than throwing when nothing has been
+   * filed from this browser, or when identify() supplied no email — there is
+   * nothing to look up in either case.
+   */
+  myReports() {
+    return fetchMyReports({ apiBase: this.config.apiBase });
+  }
+
+  /** True when this browser has filed something, so a "your reports" entry
+   *  point can be hidden until it would show anything. */
+  hasReports() {
+    return Boolean(readToken());
+  }
+
+  /**
+   * Forget this browser's reports — call on sign-out, or the next person at
+   * this machine inherits the previous one's notifications.
+   */
+  forgetReports() {
+    this.stopWatching?.();
+    this.stopWatching = null;
+    // Ended, not just forgotten. This is the sign-out path, and a call left
+    // running on it would keep a microphone open on behalf of somebody who has
+    // just left — and go on transcribing them into a report they can no longer
+    // prove is theirs.
+    this.endCall();
+    // Drops the unread notifications with the token — see clearToken — so the
+    // next person at a shared machine does not find the last one's bug reports
+    // stacked in the corner.
+    clearToken();
+    this.#drawUnread();
+    return this;
+  }
+
+  /**
+   * Attach the signed-in user so reports say who hit the bug.
+   *
+   * `email` is the field that matters beyond display: it threads every report
+   * from the same person together in the dashboard, and it is where the team's
+   * "your issue is resolved" email goes. Because your app has already
+   * authenticated this person, an address sent here is treated as reachable —
+   * unlike one typed into a public recording-link form, which stays unusable
+   * for outbound mail until the reporter answers a confirmation code.
+   *
+   *   BugCatch.identify({ id: 'u_42', email: 'alex@acme.com', name: 'Alex' });
+   *
+   * Pass null to forget them again on sign-out.
+   */
+  identify(user) {
+    this.config.user = user;
+    return this;
+  }
+
+  /**
+   * Upload a screenshot, recording or file and get back the storage key that
+   * `report({ attachments })` references.
+   *
+   * The blob goes straight to storage on a presigned URL — it never passes
+   * through the API — so this is also what you call when you drive the SDK
+   * yourself with `widget: false`.
+   */
+  async uploadAttachment(blob, mime, onProgress) {
+    if (!this.started) throw new Error('[BugCatch] call init() first.');
+    return uploadAttachment({
+      apiBase: this.config.apiBase,
+      apiKey: this.config.apiKey,
+      blob,
+      mime: mime || blob?.type,
+      onProgress,
+    });
+  }
+
+  /** File a bug with everything captured so far. */
+  async report({
+    title, description = '', priority = 'MEDIUM', metadata = {}, attachments = [],
+  } = {}) {
+    if (!this.started) throw new Error('[BugCatch] call init() first.');
+    if (!title || !title.trim()) throw new Error('[BugCatch] a title is required.');
+
+    // Drop anything the API would reject outright, so one bad entry can't cost
+    // the reporter the whole report.
+    const media = (attachments || [])
+      // REPORT_MIMES, not the full upload set: a report's attachments are typed
+      // SCREENSHOT or VIDEO, so a document reaching here would be filed as a
+      // screenshot. Documents and voice notes belong on a message.
+      .filter((a) => a?.storageKey && normalizeMime(a.mime, REPORT_MIMES))
+      .map((a) => ({
+        type: a.type === 'VIDEO' ? 'VIDEO' : 'SCREENSHOT',
+        storageKey: a.storageKey,
+        mime: normalizeMime(a.mime, REPORT_MIMES),
+      }));
+
+    let payload = await this.#payload({ title: title.trim(), description, priority, metadata, media });
+
+    if (typeof this.config.beforeSend === 'function') {
+      const result = this.config.beforeSend(payload);
+      if (result === false) return { cancelled: true };
+      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),
+    });
+
+    // 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
+    // the next report: the widget re-reads state every time it opens, so
+    // forgetting it now is what makes it draw the sign-in step instead.
+    if (res.status === 401 && session) clearSession(this.config.projectId);
+
+    if (!res.ok) {
+      let detail = '';
+      try {
+        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 : ''}`);
+    }
+
+    const result = await res.json();
+
+    // 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
+    // there is nobody to notify, and none comes back.
+    if (result.watchToken) {
+      writeToken(result.watchToken);
+      if (this.config.updates) this.startWatching();
+    }
+
+    return result;
+  }
+
+  /**
+   * What this project asks of the person reporting, and who this browser is
+   * signed in as right now.
+   *
+   *   const { mode, signedIn } = await BugCatch.loginState();
+   *   // mode: 'off' | 'optional' | 'required'
+   *
+   * The widget calls this itself every time it opens. It is here for
+   * integrations running with `widget: false`, which have to draw their own
+   * sign-in and need the same answer to know whether to draw one at all.
+   *
+   * The mode is the project's setting, changed in BugCatch under Project
+   * Settings → General, not in this config. A widget that could opt out of a
+   * required sign-in would not be a requirement.
+   */
+  loginState() {
+    return loginState({
+      apiBase: this.config.apiBase,
+      apiKey: this.config.apiKey,
+      projectId: this.config.projectId,
+      token: readSession(this.config.projectId)?.token,
+    });
+  }
+
+  /**
+   * Who this browser is signed in as on this project, from storage alone.
+   *
+   *   BugCatch.signedInAs()   // { email, name } | null
+   *
+   * Synchronous, and therefore only as current as the last round trip: a
+   * session ended elsewhere still reads as signed in here until something asks
+   * the server. Use loginState() where that matters.
+   */
+  signedInAs() {
+    const session = readSession(this.config.projectId);
+    return session ? { email: session.email, name: session.name } : null;
+  }
+
+  /**
+   * Step one of signing in: mail a code to any address.
+   *
+   *   await BugCatch.signIn('someone@example.com');
+   *   await BugCatch.confirmSignIn('someone@example.com', '481920');
+   *
+   * Any address, deliberately — there is no list of people who may report a
+   * bug in somebody's product, and asking for one would be asking the customer
+   * to maintain it. What the code proves is that whoever typed it can read the
+   * address, which is all a reply-to has ever needed to be worth.
+   */
+  signIn(email, { name } = {}) {
+    return startSignIn({
+      apiBase: this.config.apiBase,
+      apiKey: this.config.apiKey,
+      projectId: this.config.projectId,
+      email,
+      // The name the host app already knows beats asking for one again.
+      name: name ?? this.config.user?.name ?? null,
+    });
+  }
+
+  /**
+   * Step two: spend the code and hold the session.
+   *
+   * Signing in signs this address out of this project in every other browser —
+   * one live session per address per project. Somebody who signs in on their
+   * phone has signed their laptop out, on purpose.
+   */
+  async confirmSignIn(email, code) {
+    const session = await confirmSignIn({
+      apiBase: this.config.apiBase,
+      apiKey: this.config.apiKey,
+      projectId: this.config.projectId,
+      email,
+      code,
+    });
+
+    // A signed-in reporter is an identity, so reports carry it the same way
+    // identify() makes them — but never over one the host application set:
+    // that address is its own claim about its own user, and this SDK is not
+    // the thing that decides it was wrong.
+    if (!this.config.user?.email) {
+      this.config.user = { email: session.email, name: session.name || undefined };
+    }
+    this.emit('signin', { email: session.email, name: session.name });
+    return { email: session.email, name: session.name };
+  }
+
+  /**
+   * Sign out of this project.
+   *
+   * Ends the session on the server too, so the token cannot be replayed from a
+   * copy of this browser's storage. Local state goes whatever the network
+   * says — sign-out on a shared machine has to mean signed out on it.
+   */
+  async signOut() {
+    const session = readSession(this.config.projectId);
+    const result = await endSignIn({
+      apiBase: this.config.apiBase,
+      apiKey: this.config.apiKey,
+      projectId: this.config.projectId,
+      token: session?.token,
+    });
+    // Only the identity this session put there. One the host application set
+    // through identify() is theirs, and outlives a widget sign-out.
+    if (session?.email && this.config.user?.email === session.email) this.config.user = null;
+    this.emit('signout', { email: session?.email || null });
+    return result;
+  }
+
+  /** What would be sent right now — useful for debugging integrations. */
+  /**
+   * What this project is already known to be having trouble with.
+   *
+   * The widget asks this itself when it opens; it is public for a host
+   * application drawing its own help surface with `widget: false`. Resolves to
+   * an empty list on every project that has not switched the feature on, which
+   * is the default — draw nothing rather than an empty heading.
+   */
+  knownIssues() {
+    return fetchKnownIssues({
+      apiBase: this.config.apiBase,
+      apiKey: this.config.apiKey,
+      projectId: this.config.projectId,
+      sessionToken: readSession(this.config.projectId)?.token,
+    });
+  }
+
+  /**
+   * The known issues that look like a description somebody is writing.
+   *
+   * Pass an AbortSignal when calling this on a keystroke, or a fast typist gets
+   * the results of whichever request happens to return last.
+   */
+  matchKnownIssues(query, { signal } = {}) {
+    return matchKnownIssues({
+      apiBase: this.config.apiBase,
+      apiKey: this.config.apiKey,
+      projectId: this.config.projectId,
+      q: query || '',
+      sessionToken: readSession(this.config.projectId)?.token,
+      signal,
+    });
+  }
+
+  /**
+   * Say a known issue is happening to you too, instead of filing a second
+   * report about it.
+   *
+   * Sends the same capture a report would — this browser's console, network and
+   * environment — because that is what the team gets out of somebody joining
+   * rather than filing: one report with everybody's environment on it.
+   *
+   * Needs an address. A signed-in widget has one, and identify() supplies one
+   * otherwise; pass `email` for the case where neither did. Joining means "tell
+   * me when this is fixed", and there is no way to keep that promise to
+   * somebody anonymous.
+   */
+  async meToo(bugId, { email, name } = {}) {
+    const session = readSession(this.config.projectId);
+    const environment = await collectEnvironment();
+    return joinKnownIssue({
+      apiBase: this.config.apiBase,
+      apiKey: this.config.apiKey,
+      projectId: this.config.projectId,
+      bugId,
+      reporterEmail: email || this.config.user?.email,
+      reporterName: name || this.config.user?.name,
+      metadata: { ...environment, user: this.config.user || undefined, sdk: SDK_IDENTITY },
+      logs: {
+        console: { entries: this.consoleBuffer.all() },
+        network: { entries: this.networkBuffer.all() },
+      },
+      sessionToken: session?.token,
+    });
+  }
+
+  snapshot() {
+    return {
+      console: this.consoleBuffer.all(),
+      network: this.networkBuffer.all(),
+      environment: collectEnvironmentSync(),
+    };
+  }
+
+  clear() {
+    this.consoleBuffer.clear();
+    this.networkBuffer.clear();
+  }
+
+  /** Restore every patched global and remove the widget. */
+  destroy() {
+    // The call first. Everything else here is listeners and buffers; this one
+    // holds a live microphone, and a page that tore the SDK down without
+    // releasing it would keep the tab's recording indicator lit.
+    this.endCall();
+    this.teardown.forEach((fn) => { try { fn(); } catch { /* ignore */ } });
+    this.teardown = [];
+    // Torn down with everything else, so a later init() builds a fresh one
+    // rather than rendering into a stack that has been removed.
+    this.notifier = null;
+    this.started = false;
+  }
+}
+
+const BugCatch = new BugCatchClient();
+
+// Exposed on the singleton rather than as a second named export: with a UMD
+// 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;
+
+export default BugCatch;