@sphoro/bugcatch-web-sdk 0.16.0 → 0.18.0

package/src/panel/thread.js

@@ -0,0 +1,384 @@
+// What happens to a report once it is filed: the confirmation, the
+// reporter's list of everything they have filed, and one report as a
+// conversation — with the assistant's live card over it, the "does the fix
+// work" question under it, and the reply box at the bottom (composer.js).
+
+import * as ICONS from './icons.js';
+import { threadHtml, typingHtml } from './messages.js';
+import {
+  headHtml, emptyHtml, skeletonRows, skeletonBubbles, escapeHtml, statusWord, relativeDay,
+  atLatest, scrollToLatest,
+} from './render.js';
+import { mountComposer } from './composer.js';
+
+// What each open thread was last drawn from, so a poll that brings nothing new
+// leaves the DOM (and the reader's place in it) alone.
+const threadDrawn = new WeakMap();
+
+export function mountThread(ctx) {
+  const {
+    client, scrim, close,
+  } = ctx;
+
+  // The report currently open, if any. A live update for a different report
+  // must not redraw the one being read.
+  let openReportId = null;
+
+  /**
+   * The confirmation, and the one answer somebody actually wants from it.
+   *
+   * "How long will this take" is the first thing anybody thinks after reporting
+   * a bug, and until now the answer was nothing at all — so the honest reading
+   * of a confirmation screen was "into the void". The API computes the figure
+   * on the same request that files the report, precisely so it can be said
+   * here: an estimate that needed a second call would arrive after this panel
+   * had closed itself.
+   *
+   * Absent whenever the project has decided not to tell reporters, or has
+   * nothing to base a figure on. Nothing is drawn in that case — no "unknown",
+   * no placeholder — because a confirmation that admits it cannot answer is
+   * worse than one that does not raise the question.
+   *
+   * The dwell is longer when there is something to read. Two seconds is right
+   * for one line and is not enough for two, and a panel that closes over the
+   * sentence somebody started reading is the reason they open it again.
+   */
+  function succeed(res, { callFailed = null } = {}) {
+    // The assistant: straight into the report's conversation, where the
+    // investigation shows itself working ("Analyzing the issue…") and asks
+    // what it needs. The plain "Thanks" below stays for when that view cannot
+    // load — a report filed without a way to follow it.
+    if (res?.id && !callFailed) {
+      showReport(res.id, { fresh: true }).then((ok) => { if (!ok) doneScreen(res, { callFailed }); });
+      return;
+    }
+    doneScreen(res, { callFailed });
+  }
+
+  function doneScreen(res, { callFailed = null } = {}) {
+    const ref = res?.id ? String(res.id).slice(0, 8) : null;
+    const eta = res?.estimate?.label ? String(res.estimate.label) : null;
+    // A press of Call that filed the report and then could not ring anybody.
+    // Shown as a plain "Thanks" it read as a call that had quietly worked, and
+    // the reporter sat waiting for a phone that was never going to ring.
+    const failed = callFailed
+      ? `<p class="eta">${escapeHtml(callFailed)} Your report is filed, and the team will reply in the chat.</p>`
+      : '';
+    scrim.querySelector('.panel').innerHTML = `
+      <div class="done">
+        <div class="tick">${ICONS.check}</div>
+        <h3>Thanks — that's on its way.</h3>
+        <p>${ref ? `Filed as <code>${escapeHtml(ref)}</code>.` : 'The team has what they need to reproduce it.'}</p>
+        ${failed}
+        ${eta ? `<p class="eta">Reports like this usually take <strong>${escapeHtml(eta)}</strong>. We'll let you know when it moves.</p>` : ''}
+      </div>`;
+    setTimeout(close, failed ? 6000 : eta ? 4000 : 2000);
+  }
+
+  /**
+   * The reporter's own history: what they have filed and where each one got to.
+   *
+   * Replaces the panel rather than opening a second surface — it is the same
+   * dialog answering a different question, and the reporter came here from one
+   * launcher.
+   */
+  async function showHistory() {
+    const panel = scrim.querySelector('.panel');
+    clearTimeout(assistantTimer);
+    openReportId = null;
+    panel.classList.remove('is-chat');
+    panel.innerHTML = `
+      ${headHtml({ title: 'Your reports', sub: "Everything you've reported, and where each one got to." })}
+      <div class="history" aria-busy="true">${skeletonRows(3)}</div>`;
+
+    panel.querySelector('[data-act="close"]').addEventListener('click', close);
+
+    let reports = [];
+    try {
+      ({ reports } = await client.myReports());
+    } catch {
+      const failed = panel.querySelector('.history');
+      if (failed) failed.innerHTML = emptyHtml('Couldn\'t load your reports just now.', ICONS.alert);
+      return;
+    }
+
+    // The panel can be closed while the request is in flight.
+    const list = panel.querySelector('.history');
+    if (!list) return;
+
+    list.removeAttribute('aria-busy');
+    list.innerHTML = reports.length
+      ? reports.map((r, i) => `
+        <button class="row" type="button" data-report="${escapeHtml(r.id)}" style="animation-delay:${Math.min(i, 8) * 30}ms">
+          <span class="row-ico" aria-hidden="true">${ICONS.chat}</span>
+          <span class="who">
+            <span class="ttl">${escapeHtml(r.title)}</span>
+            <span class="sub">${escapeHtml(r.reference)} · ${escapeHtml(relativeDay(r.createdAt))}</span>
+          </span>
+          <span class="pill ${escapeHtml(String(r.status).toLowerCase())}">${escapeHtml(statusWord(r.status))}</span>
+          <span class="chev" aria-hidden="true">${ICONS.chevronRight}</span>
+        </button>`).join('')
+      : emptyHtml('You haven\'t reported anything yet.', ICONS.inbox);
+
+    for (const row of list.querySelectorAll('[data-report]')) {
+      row.addEventListener('click', () => showReport(row.dataset.report));
+    }
+  }
+
+  /**
+   * One report as a conversation.
+   *
+   * This screen used to be a timeline: everything that had happened, read-only,
+   * newest first. It answered "what happened to my report" and nothing else —
+   * so when the team's reply was a question ("which browser?"), the person best
+   * placed to answer it was looking straight at it with no way to.
+   *
+   * Now it is a thread. Status changes still appear, as the quiet centred lines
+   * that mark events in any chat; the messages between the two sides are
+   * bubbles either side of them; and there is a box at the bottom. Oldest at
+   * the top, because that is the direction a conversation is read.
+   */
+  async function showReport(bugId, { fresh = false } = {}) {
+    const panel = scrim.querySelector('.panel');
+    clearTimeout(assistantTimer);
+    panel.classList.add('is-chat');
+    panel.innerHTML = `
+      ${headHtml({
+        back: true,
+        title: fresh ? 'Looking into it' : 'Your report',
+        sub: fresh ? 'Our assistant is on it — it may ask you a question here.' : 'Everything that has happened, and a way to answer.',
+      })}
+      <div class="history chatting" aria-busy="true"><div class="thread">${skeletonBubbles()}</div></div>`;
+
+    panel.querySelector('[data-act="close"]').addEventListener('click', close);
+    panel.querySelector('[data-act="back"]').addEventListener('click', showHistory);
+
+    let report = null;
+    try {
+      report = await client.myReport(bugId);
+    } catch {
+      report = null;
+    }
+
+    const body = panel.querySelector('.history');
+    // The panel can be closed, or navigated away from, while this is in flight.
+    if (!body || !panel.querySelector('[data-act="back"]')) return false;
+
+    if (!report) {
+      if (fresh) { panel.classList.remove('is-chat'); return false; }
+      body.removeAttribute('aria-busy');
+      body.innerHTML = emptyHtml('Couldn\'t load that report just now.', ICONS.alert);
+      return false;
+    }
+
+    openReportId = bugId;
+    // Reading the report is reading its updates. Leaving a "your report was
+    // fixed" card up over the screen where they are reading that it was fixed
+    // would be the notification arguing with itself.
+    client.markReportRead(bugId);
+    const drawn = threadHtml(report.timeline);
+    body.classList.add('chatting');
+    body.removeAttribute('aria-busy');
+    body.innerHTML = `
+      <div class="report-head">
+        <span class="ttl">${escapeHtml(report.title)}</span>
+        <span class="sub">${escapeHtml(report.reference)} · ${escapeHtml(report.project || '')}</span>
+        <span class="pill ${escapeHtml(String(report.status).toLowerCase())}">${escapeHtml(statusWord(report.status))}</span>
+        ${report.estimate?.label
+          // The same figure they were given when they filed it, so coming back
+          // to check is not a worse experience than not checking. Absent on a
+          // report that has already been settled — the API stops sending it —
+          // because a prediction beside a finished report is either redundant
+          // or an argument.
+          ? `<span class="eta-line">Usually takes ${escapeHtml(String(report.estimate.label))}</span>`
+          : ''}
+      </div>
+      <div class="thread" role="log" aria-live="polite" aria-label="Conversation">${drawn}</div>`;
+
+    const thread = body.querySelector('.thread');
+    threadDrawn.set(thread, drawn);
+    scrollToLatest(thread);
+    mountVerification(body, report);
+    if (report.canReply) mountComposer(ctx, body, thread, bugId);
+    mountAssistant(body, report, bugId);
+    // Again, now the cards above it have taken their share of the height: the
+    // latest message — and any quick answers under it — is what they came for.
+    scrollToLatest(thread);
+    return true;
+  }
+
+  /**
+   * The assistant's live card: where the investigation is, and a gentle
+   * refresh while it works. Analyzing polls every few seconds until the
+   * outcome lands — a question, a found cause, or a hand-off — so the
+   * reporter watches it happen rather than wondering whether anything is.
+   */
+  let assistantTimer = null;
+  function mountAssistant(body, report, bugId) {
+    clearTimeout(assistantTimer);
+    const a = report.assistant;
+    const thread = body.querySelector('.thread');
+    let card = body.querySelector('.assistant');
+    if (!a) {
+      card?.remove();
+      thread?.querySelector('.typing-row')?.remove();
+      return;
+    }
+
+    // Updated in place rather than rebuilt: the card is polled every few
+    // seconds while the assistant works, and a card that re-entered on every
+    // poll would flicker — and re-announce itself to a screen reader — for
+    // nothing. It only animates when the phase actually moves.
+    const previous = card?.dataset.phase || null;
+    if (!card) {
+      card = document.createElement('div');
+      card.setAttribute('role', 'status');
+      card.setAttribute('aria-live', 'polite');
+      body.querySelector('.report-head')?.after(card);
+    }
+    card.className = `assistant ${escapeHtml(a.phase)}`;
+    card.dataset.phase = a.phase;
+
+    const steps = a.steps || [];
+    const done = steps.filter((st) => st.state === 'done').length;
+    const active = steps.some((st) => st.state === 'active') ? 0.5 : 0;
+    const pct = steps.length ? Math.round(((done + active) / steps.length) * 100) : 0;
+    const content = `
+      <div class="as-body${previous && previous !== a.phase ? ' entering' : ''}">
+        <div class="as-top">
+          <span class="as-orb" aria-hidden="true">${a.phase === 'analyzing' ? '<span class="as-spin"></span>'
+            : a.phase === 'calling' ? ICONS.phone
+              : a.phase === 'resolved' ? ICONS.check : ICONS.sparkle}</span>
+          <div class="as-text">
+            <div class="as-title">${escapeHtml(a.title)}</div>
+            <div class="as-detail">${escapeHtml(a.detail)}</div>
+          </div>
+        </div>
+      </div>
+      ${steps.length ? `
+      <div class="as-progress" role="progressbar" aria-label="Progress" aria-valuemin="0" aria-valuemax="100" aria-valuenow="${pct}"><i style="width:${pct}%"></i></div>
+      <ol class="as-steps">${steps.map((st) => `<li class="${escapeHtml(st.state)}"${st.state === 'active' ? ' aria-current="step"' : ''}><span class="dot"></span><span class="lbl">${escapeHtml(st.label)}</span></li>`).join('')}</ol>` : ''}`;
+    const key = JSON.stringify([a.phase, a.title, a.detail, steps]);
+    if (card.dataset.key !== key) {
+      const bar = card.querySelector('.as-progress i');
+      const from = bar?.style.width;
+      card.innerHTML = content;
+      card.dataset.key = key;
+      // Let the bar travel from where it was to where it is now.
+      const next = card.querySelector('.as-progress i');
+      if (next && from) {
+        next.style.width = from;
+        requestAnimationFrame(() => { next.style.width = `${pct}%`; });
+      }
+    }
+
+    // While it works, a "thinking" bubble sits where its next message will land.
+    // Never during a call: somebody is on the phone about this report, nothing
+    // is being analysed (the analysis waits for the transcript), and a bubble
+    // typing away underneath a live call is the assistant talking over them.
+    if (thread) {
+      const pinned = atLatest(thread);
+      const typing = thread.querySelector('.typing-row');
+      if (a.phase !== 'analyzing') typing?.remove();
+      else if (!typing || typing !== thread.lastElementChild) {
+        typing?.remove();
+        thread.insertAdjacentHTML('beforeend', typingHtml());
+        if (pinned) scrollToLatest(thread);
+      }
+    }
+
+    if (a.phase === 'analyzing') {
+      assistantTimer = setTimeout(() => refreshThread(bugId), 3000);
+    } else if (a.phase === 'calling') {
+      // Slower: the call's own card is what the reporter is watching, and this
+      // only has to notice when the call ends and the analysis begins.
+      assistantTimer = setTimeout(() => refreshThread(bugId), 10000);
+    } else if (a.phase === 'needs_info' && previous !== 'needs_info') {
+      body.querySelector('.composer textarea')?.focus();
+    }
+  }
+
+  function mountVerification(body, report) {
+    body.querySelector('.fix-verification')?.remove();
+    if (!report.resolvedAt || !['RESOLVED', 'CLOSED'].includes(report.status)) return;
+    const box = document.createElement('div'); box.className = 'fix-verification';
+    if (report.verification) { box.textContent = report.verification === 'CONFIRMED' ? 'You confirmed that this fix works.' : 'Your feedback was recorded.'; }
+    else {
+      box.innerHTML = '<p>Does the fix work for you?</p><textarea maxlength="4000" aria-label="Fix feedback" placeholder="What happens when you try again? (optional)"></textarea><button type="button" data-result="CONFIRMED">It works now</button> <button type="button" data-result="STILL_HAPPENING">Still happening</button><p class="feedback-status" role="status"></p>';
+      box.querySelectorAll('[data-result]').forEach((btn) => { btn.onclick = async () => {
+        box.querySelectorAll('button').forEach((b) => { b.disabled = true; });
+        try { await client.verifyFix(report.id, { result: btn.dataset.result, resolvedAt: report.resolvedAt, note: box.querySelector('textarea').value }); await showReport(report.id); }
+        catch (err) { box.querySelector('.feedback-status').textContent = err.message; box.querySelectorAll('button').forEach((b) => { b.disabled = false; }); }
+      }; });
+    }
+    body.querySelector('.report-head')?.after(box);
+  }
+
+  /**
+   * Redraw the open thread in place, keeping whatever is half-typed.
+   *
+   * Rebuilding the whole screen on every incoming message would be simpler and
+   * would also throw away a draft, a staged file and the scroll position — for
+   * someone mid-sentence, a reply arriving would look like the widget crashed.
+   */
+  async function refreshThread(bugId) {
+    const body = scrim.querySelector('.history.chatting');
+    const thread = body?.querySelector('.thread');
+    if (!thread || openReportId !== bugId) return;
+
+    let report = null;
+    try {
+      report = await client.myReport(bugId);
+    } catch { /* a failed refresh leaves what is on screen, which is not wrong */ }
+    // Closed while it was asking: nothing to draw, and no next poll to set.
+    if (ctx.closed || !report || openReportId !== bugId) return;
+
+    mountVerification(body, report);
+    const pinned = atLatest(thread);
+    const html = threadHtml(report.timeline);
+    // Only rewritten when something changed, so a poll that brings nothing new
+    // does not replay every bubble's entrance or re-announce the log.
+    if (threadDrawn.get(thread) !== html) {
+      thread.innerHTML = html;
+      threadDrawn.set(thread, html);
+    }
+    mountAssistant(body, report, bugId);
+    // Only follow the conversation down if they were already at the bottom.
+    // Yanking someone back from something they scrolled up to read is worse
+    // than making them scroll.
+    if (pinned) scrollToLatest(thread);
+
+    const pill = body.querySelector('.report-head .pill');
+    if (pill) {
+      pill.className = `pill ${String(report.status).toLowerCase()}`;
+      pill.textContent = statusWord(report.status);
+    }
+  }
+
+  // Re-read the open thread when something happens to it. Without this the
+  // reader is looking at a conversation that stopped being true while they read
+  // it — the very screen where a stale view is most obvious, and now the screen
+  // where the other side may be typing.
+  const stopListening = client.on('update', (event) => {
+    if (!openReportId || event?.bugId !== openReportId) return;
+    // Already on screen, so already read — and marking it here, before the
+    // client draws its notifications, is what keeps a card from appearing over
+    // the thread that is about to show the same thing.
+    client.markReportRead(openReportId);
+    refreshThread(openReportId);
+  });
+  // Stopped with the panel: a frame arriving after it has gone would redraw a
+  // panel that is no longer on the page. The assistant's poll too — it reads
+  // the thread out of the detached panel, finds it still there, and would go
+  // on asking every three seconds for as long as the analysis ran.
+  ctx.onDestroy(() => {
+    stopListening();
+    clearTimeout(assistantTimer);
+  });
+
+  scrim.querySelector('[data-act="history"]')?.addEventListener('click', showHistory);
+
+  ctx.succeed = succeed;
+  ctx.refreshThread = refreshThread;
+  ctx.openReportId = () => openReportId;
+}

package/src/session.js

@@ -22,6 +22,8 @@
 // mounts two projects' widgets is two independent sign-ins, and signing out of
 // one leaves the other alone.
 
+import { tooManyMessage } from './busy.js';
+
 const KEY_PREFIX = 'bugcatch.session.';
 
 const storageKey = (projectId) => `${KEY_PREFIX}${projectId}`;
@@ -91,12 +93,15 @@ function headers({ apiKey, token }) {
 }
 
 async function readError(res) {
+  let message = '';
   try {
     const body = await res.json();
-    const message = Array.isArray(body.message) ? body.message.join(', ') : body.message;
-    if (message) return message;
+    message = Array.isArray(body.message) ? body.message.join(', ') : body.message || '';
   } catch { /* non-JSON error */ }
-  return `Request failed (HTTP ${res.status})`;
+  // Asking for codes too fast. The server's sentence says so; a proxy's page
+  // would not, and "Request failed (HTTP 429)" reads as a broken form.
+  if (res.status === 429) return tooManyMessage(message);
+  return message || `Request failed (HTTP ${res.status})`;
 }
 
 /**

package/src/umd/call.js

@@ -0,0 +1,6 @@
+// The call code as a script of its own, for the script-tag build: run, it
+// hands its exports to the loader that added it (lazy.js beside this file).
+import * as call from '../call.js';
+import { registerChunk } from '../chunks.js';
+
+registerChunk('call', call);

package/src/umd/lazy.js

@@ -0,0 +1,98 @@
+// The script-tag build's loader: ../lazy.js's exports, fetched with <script> tags
+// from the place this script itself was loaded from.
+//
+// Vite cannot split a UMD bundle, so the parts are built as scripts of their
+// own — bugcatch-panel.umd.js and bugcatch-call.umd.js, see vite.config.js —
+// that register their exports when they run (panel.js and call.js beside
+// this file, through ../chunks.js). This adds the script, waits for it to
+// load, and reads them back.
+//
+// # From where
+//
+// Beside this file, found while it is still running: document.currentScript is
+// only set during a script's first run, so it is read here, at the top, and
+// never again. That covers the CDN, which serves dist/ as a directory, and a
+// copy of dist/ on the site's own server. It cannot cover a copy with no
+// address of its own — the bundle pasted into an inline <script>, or
+// concatenated into one of the site's files — and there init({ chunkBase })
+// says where the parts are.
+
+import {
+  registeredChunk, chunkUnavailable, once, CHUNK_VERSION,
+} from '../chunks.js';
+
+const self = typeof document !== 'undefined' ? document.currentScript : null;
+const loadedFrom = self?.src || null;
+// Carried over to the scripts this adds, so a page that let this one in lets
+// them in the same way: its CSP nonce, and the CORS and referrer settings the
+// page chose for this tag.
+const nonce = self?.nonce || '';
+const crossOrigin = self?.getAttribute('crossorigin') ?? null;
+const referrerPolicy = self?.referrerPolicy || '';
+
+/**
+ * The folder the parts are in, with a trailing slash — or null when there is
+ * no way to know. `loadedFrom` is this script's own address; `baseURI` the
+ * page's, which a relative `chunkBase` is read against.
+ *
+ * A bare package address, https://unpkg.com/@sphoro/bugcatch-web-sdk@0.17.0,
+ * is answered by the CDN with this file but names no folder to be beside, so
+ * its parts are looked for under dist/, which is where that file lives.
+ */
+export function chunkFolder({ chunkBase, loadedFrom: from, baseURI }) {
+  if (chunkBase) return new URL(String(chunkBase).replace(/\/*$/, '/'), baseURI).href;
+  if (!from) return null;
+  const url = new URL(from);
+  if (!/\.js$/i.test(url.pathname)) return new URL(`${url.pathname.replace(/\/*$/, '/')}dist/`, url).href;
+  return new URL('.', url).href;
+}
+
+function loadScript(name, chunkBase) {
+  const arrived = registeredChunk(name);
+  if (arrived) return Promise.resolve(arrived);
+
+  const folder = chunkFolder({ chunkBase, loadedFrom, baseURI: document.baseURI });
+  if (!folder) {
+    return Promise.reject(chunkUnavailable(`bugcatch-${name}.umd.js could not be loaded: this copy of `
+      + 'the SDK was not loaded from an address, so there is nowhere to look for it. Set '
+      + 'init({ chunkBase }) to the folder that holds it.'));
+  }
+  // The version in the address as well as in the registry: a file cached from
+  // an older release, under an address that does not change between releases,
+  // is fetched afresh rather than found stale.
+  const src = `${folder}bugcatch-${name}.umd.js?v=${encodeURIComponent(CHUNK_VERSION)}`;
+
+  return new Promise((resolve, reject) => {
+    const script = document.createElement('script');
+    script.src = src;
+    script.async = true;
+    if (nonce) script.nonce = nonce;
+    if (crossOrigin !== null) script.crossOrigin = crossOrigin;
+    if (referrerPolicy) script.referrerPolicy = referrerPolicy;
+    const settle = () => {
+      script.onload = null;
+      script.onerror = null;
+      script.remove();
+    };
+    script.onload = () => {
+      settle();
+      const exports = registeredChunk(name);
+      if (exports) resolve(exports);
+      else {
+        reject(chunkUnavailable(`${src} loaded, but not as version ${CHUNK_VERSION} of the SDK — `
+          + 'serve every file in dist/ from the same release.'));
+      }
+    };
+    script.onerror = () => {
+      settle();
+      reject(chunkUnavailable(`could not load ${src}. The files in dist/ are served together: `
+        + 'a self-hosted copy needs all of them (or init({ chunkBase }) pointing at them), and a '
+        + 'Content-Security-Policy has to allow them in script-src.'));
+    };
+    (document.head || document.documentElement).appendChild(script);
+  });
+}
+
+export const loadPanel = once((chunkBase) => loadScript('panel', chunkBase));
+
+export const loadCall = once((chunkBase) => loadScript('call', chunkBase));

package/src/umd/panel.js

@@ -0,0 +1,6 @@
+// The report panel as a script of its own, for the script-tag build: run, it
+// hands its exports to the loader that added it (lazy.js beside this file).
+import * as panel from '../panel/index.js';
+import { registerChunk } from '../chunks.js';
+
+registerChunk('panel', panel);

package/src/updates.js

@@ -11,6 +11,8 @@
 // let anyone read anyone's reports. Holding this token is proof of having
 // filed them.
 
+import { tooManyMessage } from './busy.js';
+
 const TOKEN_KEY = 'bugcatch.watch';
 const BACKOFF_MS = [2000, 5000, 15000, 30000, 60000];
 
@@ -308,6 +310,7 @@ export async function sendMessage({ apiBase, bugId, body, attachments }) {
       const problem = await res.json();
       detail = Array.isArray(problem.message) ? problem.message.join(', ') : problem.message || '';
     } catch { /* non-JSON error */ }
+    if (res.status === 429) throw new Error(tooManyMessage(detail));
     throw new Error(detail || `[BugCatch] could not send that (HTTP ${res.status}).`);
   }
   return res.json();
@@ -384,7 +387,7 @@ export async function callKindsForProject({ apiBase, apiKey, projectId }) {
  * call could be placed — which is a success for the report and a failure only
  * for the call, and the caller is expected to tell them apart.
  */
-export async function reportByCall({ apiBase, apiKey, token, payload }) {
+export async function reportByCall({ apiBase, apiKey, token, payload, watchToken }) {
   const res = await fetch(`${apiBase}/ingest/calls`, {
     method: 'POST',
     headers: {
@@ -396,7 +399,9 @@ export async function reportByCall({ apiBase, apiKey, token, payload }) {
       // is saying, an inch below the message, who they are signed in as.
       ...(token ? { 'X-BugCatch-Session': token } : {}),
     },
-    body: JSON.stringify(payload),
+    // The watch token this browser holds, so the one filing hands back covers
+    // the reports it already could — see withHeldToken in index.js.
+    body: JSON.stringify(watchToken ? { ...payload, watchToken } : payload),
   });
 
   if (!res.ok) {
@@ -406,7 +411,8 @@ export async function reportByCall({ apiBase, apiKey, token, payload }) {
       detail = Array.isArray(problem.message) ? problem.message.join(', ') : problem.message || '';
     } catch { /* non-JSON error */ }
     const err = new Error(
-      detail || `[BugCatch] the call could not be started (HTTP ${res.status}).`,
+      res.status === 429 ? tooManyMessage(detail)
+        : detail || `[BugCatch] the call could not be started (HTTP ${res.status}).`,
     );
     // Carried so a session the server has stopped recognising can be told from
     // every other refusal and forgotten, rather than pressing Call into the
@@ -1020,12 +1026,18 @@ export async function matchKnownIssues({ apiBase, apiKey, projectId, q, sessionT
 export async function joinKnownIssue({
   apiBase, apiKey, projectId, bugId, reporterEmail, reporterName, metadata, logs, sessionToken,
 }) {
+  // The token this browser already holds goes back with the join, so the one
+  // that comes back still covers the reports it filed as well as this issue.
+  const held = readToken();
   const res = await fetch(
     `${apiBase}/ingest/known-issues/${encodeURIComponent(bugId)}/join`,
     {
       method: 'POST',
       headers: knownIssueHeaders(apiKey, sessionToken),
-      body: JSON.stringify({ projectId, reporterEmail, reporterName, metadata, logs }),
+      body: JSON.stringify({
+        projectId, reporterEmail, reporterName, metadata, logs,
+        ...(held ? { watchToken: held } : {}),
+      }),
     },
   );
   if (!res.ok) throw new Error(await readJoinError(res));
@@ -1043,12 +1055,13 @@ function knownIssueHeaders(apiKey, sessionToken) {
 }
 
 async function readJoinError(res) {
+  let message = '';
   try {
     const body = await res.json();
-    const message = Array.isArray(body.message) ? body.message.join(', ') : body.message;
-    if (message) return message;
+    message = Array.isArray(body.message) ? body.message.join(', ') : body.message || '';
   } catch { /* non-JSON error */ }
-  return `Could not add you to this issue (HTTP ${res.status})`;
+  if (res.status === 429) return tooManyMessage(message);
+  return message || `Could not add you to this issue (HTTP ${res.status})`;
 }
 
 export async function verifyFix({ apiBase, bugId, ...feedback }) {