@sphoro/bugcatch-web-sdk 0.13.1

package/src/updates.js

@@ -0,0 +1,1062 @@
+// Live status changes on the reports this browser has filed.
+//
+// The person who reported a bug is the one person a tracker usually forgets to
+// tell. They are already in your app, so this is where they hear about it —
+// not in an email they may not read, and not on a page they have to remember
+// to visit.
+//
+// Authentication is the token handed back when the report was filed, kept in
+// localStorage. Deliberately not the API key: that is publishable and sits in
+// your page source, so a key-authenticated feed keyed on an email address would
+// let anyone read anyone's reports. Holding this token is proof of having
+// filed them.
+
+const TOKEN_KEY = 'bugcatch.watch';
+const BACKOFF_MS = [2000, 5000, 15000, 30000, 60000];
+
+/**
+ * How long a stream has to survive before it counts as having worked.
+ *
+ * The backoff above is only a backoff if "it failed" and "it worked" are told
+ * apart by more than the response arriving, and they were not: the counter
+ * reset the moment the headers landed. A server that accepts the connection and
+ * ends it immediately therefore reset the backoff every time, so the delay
+ * never left its first rung and the retry became a two-second loop that no
+ * amount of failing could slow down.
+ *
+ * That is not hypothetical here. An expired watch token used to be answered
+ * with a 200 whose body closed at once — the status could not be set, because
+ * an SSE response has already begun by the time the token is opened — and this
+ * client only treats a 401 as fatal. Prod on 2026-08-31: 6,001 of 6,012
+ * requests to the stream aborted under 10ms, ~50/min, for hours. The server
+ * sends a real 401 now (see WatchTokenGuard in the API), and this is the other
+ * half: a stream that ends the instant it opens must cost a longer wait than
+ * the one before it, whatever the reason.
+ *
+ * Comfortably over the connect-and-die case and well under the 25s server
+ * heartbeat, so a stream genuinely carrying traffic always qualifies.
+ */
+const STABLE_MS = 5000;
+
+/** Where the watch token lives. Storage can throw in private modes — never fatal. */
+export function readToken() {
+  try {
+    return window.localStorage?.getItem(TOKEN_KEY) || null;
+  } catch {
+    return null;
+  }
+}
+
+export function writeToken(token) {
+  if (!token) return;
+  try {
+    window.localStorage?.setItem(TOKEN_KEY, token);
+  } catch { /* storage unavailable — updates just won't survive a reload */ }
+}
+
+export function clearToken() {
+  try {
+    window.localStorage?.removeItem(TOKEN_KEY);
+  } catch { /* ignore */ }
+  // Anything still waiting to be read goes with it. Unread updates are about
+  // reports this browser can no longer prove it filed — and on the sign-out
+  // path, about somebody who has left a machine the next person will use.
+  forgetAllUpdates();
+}
+
+/* ---------------------------------------------------------------------------
+ * Unread updates.
+ *
+ * An update used to be shown for eight seconds and then dropped on the floor.
+ * Somebody switching tabs, reading something else on the page, or away from
+ * the keyboard when their bug was fixed simply never found out — the one
+ * notification they were waiting for was the one most likely to be missed.
+ *
+ * So an update is now held until it has been read, and "read" is something the
+ * reporter says rather than something a timer decides. The store below is what
+ * remembers that across a reload: the stream replays nothing on reconnect, so
+ * an unread notification that lived only in a variable would not survive the
+ * reporter pressing refresh.
+ *
+ * Kept beside the watch token, and dropped with it — a browser that can no
+ * longer prove it filed anything has no reports to be told about.
+ * ------------------------------------------------------------------------ */
+
+export const UNREAD_KEY = 'bugcatch.unread';
+// Enough that a fortnight away does not lose anything, small enough that the
+// store stays a notification list rather than a history. The full record of
+// what happened lives on the report itself.
+const UNREAD_LIMIT = 20;
+
+/**
+ * A stable id for an update, so the same one is not shown twice and so a host
+ * app can say which one it has read.
+ *
+ * Built from the frame rather than generated, because it has to survive a
+ * reload: the server sends no id of its own, and a random one would make every
+ * restored notification a new notification.
+ */
+export function updateId(event) {
+  return [event?.bugId || 'report', event?.kind || 'status', event?.at || ''].join('|');
+}
+
+/** Unread updates, oldest first. Never throws — a corrupt store reads as empty. */
+export function readUnread() {
+  try {
+    const raw = window.localStorage?.getItem(UNREAD_KEY);
+    const list = raw ? JSON.parse(raw) : [];
+    return Array.isArray(list) ? list.filter((u) => u && typeof u.id === 'string') : [];
+  } catch {
+    return [];
+  }
+}
+
+function writeUnread(list) {
+  try {
+    if (list.length) window.localStorage?.setItem(UNREAD_KEY, JSON.stringify(list));
+    else window.localStorage?.removeItem(UNREAD_KEY);
+  } catch { /* storage unavailable — unread then lasts only for this page */ }
+}
+
+/**
+ * Hold an update until it is read. Returns the stored record, which is the
+ * frame the API sent plus the id everything else refers to it by.
+ *
+ * Re-delivery of one already held replaces it in place rather than stacking a
+ * second copy: a reconnect that repeats a frame must not double the badge.
+ */
+export function rememberUpdate(event) {
+  const record = { ...event, id: updateId(event) };
+  const list = readUnread().filter((u) => u.id !== record.id);
+  list.push(record);
+  writeUnread(list.slice(-UNREAD_LIMIT));
+  return record;
+}
+
+/** Read. Returns what is still unread. */
+export function forgetUpdate(id) {
+  const list = readUnread().filter((u) => u.id !== id);
+  writeUnread(list);
+  return list;
+}
+
+/**
+ * Everything about one report, read.
+ *
+ * Opening the report *is* reading its updates — the widget calls this when the
+ * thread opens — and 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.
+ */
+export function forgetReportUpdates(bugId) {
+  const list = readUnread().filter((u) => u.bugId !== bugId);
+  writeUnread(list);
+  return list;
+}
+
+/** All read. */
+export function forgetAllUpdates() {
+  writeUnread([]);
+  return [];
+}
+
+/**
+ * Pull complete SSE frames out of a growing buffer, returning the partial one
+ * left over. Frames are separated by a blank line and one can span several
+ * `data:` lines, so this cannot split on newlines — a payload cut in half by
+ * the network would parse as garbage.
+ */
+function drain(buffer, onFrame) {
+  let rest = buffer;
+  let split = rest.indexOf('\n\n');
+  while (split !== -1) {
+    const frame = rest.slice(0, split);
+    rest = rest.slice(split + 2);
+
+    const data = frame
+      .split('\n')
+      .filter((line) => line.startsWith('data:'))
+      .map((line) => line.slice(5).trim())
+      .join('\n');
+
+    if (data) {
+      try {
+        onFrame(JSON.parse(data));
+      } catch { /* a malformed frame is skipped, never fatal to the stream */ }
+    }
+    split = rest.indexOf('\n\n');
+  }
+  return rest;
+}
+
+/**
+ * Everything this browser has reported, with where each one got to.
+ *
+ * Same credential as the stream: the token handed back when a report was
+ * filed. Returns an empty history rather than throwing when nothing has been
+ * filed here — "you have not reported anything" is an answer, not an error.
+ */
+export async function fetchMyReports({ apiBase }) {
+  const token = readToken();
+  if (!token) return { reporter: null, reports: [] };
+
+  const res = await fetch(`${apiBase}/ingest/watch/reports`, {
+    headers: { Authorization: `Bearer ${token}` },
+  });
+
+  // Expired or revoked. Drop it so a later report can replace it, and answer
+  // as though nothing had been filed — which, as far as this browser can now
+  // prove, is true.
+  if (res.status === 401) {
+    clearToken();
+    return { reporter: null, reports: [] };
+  }
+  if (!res.ok) throw new Error(`[BugCatch] could not load your reports (HTTP ${res.status})`);
+  return res.json();
+}
+
+/**
+ * One report in full, including how it got to where it is.
+ *
+ * The list endpoint answers "what have I reported and where is each one"; this
+ * one answers "what has actually happened to this", which is the question
+ * somebody opening a report is asking. Same credential as the rest.
+ */
+export async function fetchReport({ apiBase, bugId }) {
+  const token = readToken();
+  if (!token) return null;
+
+  const res = await fetch(`${apiBase}/ingest/watch/reports/${encodeURIComponent(bugId)}`, {
+    headers: { Authorization: `Bearer ${token}` },
+  });
+  if (res.status === 401) {
+    clearToken();
+    return null;
+  }
+  if (res.status === 404) return null;
+  if (!res.ok) throw new Error(`[BugCatch] could not load that report (HTTP ${res.status})`);
+  return res.json();
+}
+
+/**
+ * Write back on a report this browser filed.
+ *
+ * The other half of the feed. Everything above tells the reporter what happened
+ * to their report; this is how they answer — "still broken on Safari", "here is
+ * the file that breaks it" — without leaving the app they hit the bug in.
+ *
+ * Same credential as the rest: the watch token, which is proof of having filed
+ * this. Resolves to the stored message, so the caller can render exactly what
+ * the server kept rather than what it hoped it sent.
+ */
+export async function sendMessage({ apiBase, bugId, body, attachments }) {
+  const token = readToken();
+  if (!token) throw new Error('[BugCatch] nothing filed from this browser yet.');
+
+  const res = await fetch(
+    `${apiBase}/ingest/watch/reports/${encodeURIComponent(bugId)}/messages`,
+    {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${token}` },
+      body: JSON.stringify({
+        ...(body ? { body } : {}),
+        ...(attachments?.length ? { attachments } : {}),
+      }),
+    },
+  );
+
+  if (res.status === 401) {
+    clearToken();
+    throw new Error('[BugCatch] this browser can no longer prove it filed that report.');
+  }
+  if (!res.ok) {
+    // The API's own message is worth surfacing — "Unsupported file type" and
+    // "Write something, or attach a file" are both things the sender can fix,
+    // and an HTTP code is not.
+    let detail = '';
+    try {
+      const problem = await res.json();
+      detail = Array.isArray(problem.message) ? problem.message.join(', ') : problem.message || '';
+    } catch { /* non-JSON error */ }
+    throw new Error(detail || `[BugCatch] could not send that (HTTP ${res.status}).`);
+  }
+  return res.json();
+}
+
+/**
+ * Whether this project can take a call instead of a form.
+ *
+ * Asked before anything has been filed, so this one is authenticated by the
+ * publishable API key rather than by a watch token — there is no report yet to
+ * hold a token for. It answers a fact about the project's configuration and
+ * nothing about any report, which is all a publishable key should ever be able
+ * to learn.
+ */
+export async function callAvailableForProject({ apiBase, apiKey, projectId }) {
+  return Boolean(await callKindForProject({ apiBase, apiKey, projectId }));
+}
+
+/**
+ * Which kind of call this project can take: 'agent', 'live', or null for none.
+ *
+ * The same round trip as above, answering the question that actually matters.
+ * A deployment offers one or the other and never both — a sphoro.voice agent has
+ * exactly one mode, and it is either a model that answers or a rendezvous that
+ * rings the team. Asking only "can it call" is what drew a triage button on a
+ * deployment whose agent had been switched to person-to-person: pressing it filed
+ * the report and then failed the call, so the reporter got a ticket they had not
+ * asked for and nobody's dashboard rang.
+ *
+ * Null for every failure, and for an older API that answers without `kind` but
+ * says it is available — that deployment is on the agent, because live calling
+ * did not exist before the field did.
+ */
+export async function callKindForProject({ apiBase, apiKey, projectId }) {
+  try {
+    const res = await fetch(
+      `${apiBase}/ingest/calls?projectId=${encodeURIComponent(projectId)}`,
+      { headers: { 'X-BugCatch-Key': apiKey } },
+    );
+    if (!res.ok) return null;
+    const body = await res.json();
+    if (!body?.available) return null;
+    return body.kind === 'live' || body.kind === 'agent' ? body.kind : 'agent';
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * File a report by calling about it, and get back the socket to talk on.
+ *
+ * The report is written before the call starts rather than after it ends, so
+ * whatever this page was doing survives a call that drops or a reporter who
+ * changes their mind. `realtime_url` is null when the report was filed but no
+ * 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 }) {
+  const res = await fetch(`${apiBase}/ingest/calls`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'X-BugCatch-Key': apiKey,
+      // The same header `report()` sends, and for the same reason: this route
+      // files a report too. Without it a project that requires sign-in refuses
+      // the call outright — and the reporter is told to sign in by a panel that
+      // is saying, an inch below the message, who they are signed in as.
+      ...(token ? { 'X-BugCatch-Session': token } : {}),
+    },
+    body: JSON.stringify(payload),
+  });
+
+  if (!res.ok) {
+    let detail = '';
+    try {
+      const problem = await res.json();
+      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}).`,
+    );
+    // Carried so a session the server has stopped recognising can be told from
+    // every other refusal and forgotten, rather than pressing Call into the
+    // same 401 again.
+    err.status = res.status;
+    throw err;
+  }
+  return res.json();
+}
+
+/**
+ * Whether this report can be talked through with the triage agent.
+ *
+ * Asked before anything is rendered, so a button never appears on a deployment
+ * with no sphoro.voice configured, on a workspace that has not switched calling
+ * on, or on a report that has already had its allowance. False for every
+ * failure too: a call is an extra, and an extra that cannot be offered quietly
+ * is better than an error about a feature nobody asked for.
+ */
+export async function callAvailable({ apiBase, bugId }) {
+  const token = readToken();
+  if (!token) return false;
+
+  try {
+    const res = await fetch(
+      `${apiBase}/ingest/watch/reports/${encodeURIComponent(bugId)}/voice-call`,
+      { headers: { Authorization: `Bearer ${token}` } },
+    );
+    if (!res.ok) return false;
+    const body = await res.json();
+    return Boolean(body?.offered);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Ask for a call, and get back the socket to hold it on.
+ *
+ * The response carries a URL with a short-lived credential in it and nothing
+ * else — no key ever reaches this page. Which is also why the URL is passed
+ * straight to the caller and never logged or stored.
+ */
+export async function requestCall({ apiBase, bugId }) {
+  const token = readToken();
+  if (!token) throw new Error('[BugCatch] nothing filed from this browser yet.');
+
+  const res = await fetch(
+    `${apiBase}/ingest/watch/reports/${encodeURIComponent(bugId)}/voice-call`,
+    { method: 'POST', headers: { Authorization: `Bearer ${token}` } },
+  );
+
+  if (res.status === 401) {
+    clearToken();
+    throw new Error('[BugCatch] this browser can no longer prove it filed that report.');
+  }
+  if (!res.ok) {
+    // The API's own message is the one worth showing: "you have already talked
+    // this report through" is something the reader can act on, and a status
+    // code is not.
+    let detail = '';
+    try {
+      const problem = await res.json();
+      detail = Array.isArray(problem.message) ? problem.message.join(', ') : problem.message || '';
+    } catch { /* non-JSON error */ }
+    throw new Error(detail || `[BugCatch] the call could not be started (HTTP ${res.status}).`);
+  }
+  return res.json();
+}
+
+/**
+ * Whether this report can be talked through with a *person*.
+ *
+ * A separate question from `callAvailable` and separately switched on, so the
+ * widget cannot infer either answer from the other: a workspace may run the
+ * triage agent, or a live line to its team, or both, or neither — and neither
+ * is the common case.
+ */
+export async function liveCallAvailable({ apiBase, bugId }) {
+  const token = readToken();
+  if (!token) return false;
+
+  try {
+    const res = await fetch(
+      `${apiBase}/ingest/watch/reports/${encodeURIComponent(bugId)}/live-call`,
+      { headers: { Authorization: `Bearer ${token}` } },
+    );
+    if (!res.ok) return false;
+    const body = await res.json();
+    return Boolean(body?.offered);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Ring the team, and get back the socket to wait on.
+ *
+ * Carries `rings_until` as well as the socket, because the browser is what
+ * decides the ringing is over — it is the one client guaranteed to still be
+ * listening at that moment, and a server-side timer would have to guess whether
+ * anybody was still there to hear it stop.
+ */
+export async function requestLiveCall({ apiBase, bugId }) {
+  const token = readToken();
+  if (!token) throw new Error('[BugCatch] nothing filed from this browser yet.');
+
+  const res = await fetch(
+    `${apiBase}/ingest/watch/reports/${encodeURIComponent(bugId)}/live-call`,
+    { method: 'POST', headers: { Authorization: `Bearer ${token}` } },
+  );
+
+  if (res.status === 401) {
+    clearToken();
+    throw new Error('[BugCatch] this browser can no longer prove it filed that report.');
+  }
+  if (!res.ok) {
+    // The API's own message is the one worth showing: "there is already a call
+    // in progress about this report" is something the reader can act on, and a
+    // status code is not.
+    let detail = '';
+    try {
+      const problem = await res.json();
+      detail = Array.isArray(problem.message) ? problem.message.join(', ') : problem.message || '';
+    } catch { /* non-JSON error */ }
+    throw new Error(detail || `[BugCatch] the call could not be started (HTTP ${res.status}).`);
+  }
+  return res.json();
+}
+
+/**
+ * Say that nobody picked up.
+ *
+ * Best-effort and deliberately unreported: the reporter's call is over either
+ * way, and the only thing this changes is what the team's thread says about it
+ * afterwards. sphoro.voice refuses it while the call is genuinely still
+ * ringing, so a browser with a fast clock cannot hang up on somebody halfway
+ * through answering.
+ */
+export async function giveUpLiveCall({ apiBase, bugId, callId }) {
+  const token = readToken();
+  if (!token) return;
+
+  try {
+    await fetch(
+      `${apiBase}/ingest/watch/reports/${encodeURIComponent(bugId)}`
+      + `/live-call/${encodeURIComponent(callId)}/give-up`,
+      { method: 'POST', headers: { Authorization: `Bearer ${token}` } },
+    );
+  } catch { /* the call is over regardless */ }
+}
+
+/**
+ * Take a call the team placed, and get back the socket to hold it on.
+ *
+ * The other direction, and the only call this SDK does not start. A member
+ * pressed a button on the report and the update stream put a card on screen;
+ * this is what happens when the person reading it presses Answer, and nothing
+ * connects — and no microphone opens — until they do.
+ *
+ * 409 is an ordinary outcome and says so plainly: the ringing stopped while the
+ * button was being pressed, or this is a second tab losing to the one the
+ * person actually answered in.
+ */
+export async function answerIncomingCall({ apiBase, bugId, callId }) {
+  const token = readToken();
+  if (!token) throw new Error('[BugCatch] nothing filed from this browser yet.');
+
+  const res = await fetch(
+    `${apiBase}/ingest/watch/reports/${encodeURIComponent(bugId)}`
+    + `/live-call/${encodeURIComponent(callId)}/answer`,
+    { method: 'POST', headers: { Authorization: `Bearer ${token}` } },
+  );
+
+  if (res.status === 401) {
+    clearToken();
+    throw new Error('[BugCatch] this browser can no longer prove it filed that report.');
+  }
+  if (res.status === 409) {
+    throw new Error('[BugCatch] that call is no longer ringing.');
+  }
+  if (!res.ok) {
+    let detail = '';
+    try {
+      const problem = await res.json();
+      detail = Array.isArray(problem.message) ? problem.message.join(', ') : problem.message || '';
+    } catch { /* non-JSON error */ }
+    throw new Error(detail || `[BugCatch] the call could not be answered (HTTP ${res.status}).`);
+  }
+  return res.json();
+}
+
+/**
+ * Or don't.
+ *
+ * Sent rather than left to time out, because the two are different facts on the
+ * report: somebody who was not at the screen invites being rung again in ten
+ * minutes and somebody who declined does not. Best-effort and unreported — the
+ * card is going away either way, and there is nothing the reader could do about
+ * a failure here.
+ */
+export async function declineIncomingCall({ apiBase, bugId, callId }) {
+  const token = readToken();
+  if (!token) return;
+
+  try {
+    await fetch(
+      `${apiBase}/ingest/watch/reports/${encodeURIComponent(bugId)}`
+      + `/live-call/${encodeURIComponent(callId)}/decline`,
+      { method: 'POST', headers: { Authorization: `Bearer ${token}` } },
+    );
+  } catch { /* they have declined; nothing here can change that */ }
+}
+
+/**
+ * Watch for updates until stopped. Returns a stop function.
+ *
+ * Reconnects with backoff, which starts slower than the dashboard's: this runs
+ * on someone else's site, and a tight retry loop against their network is not
+ * ours to spend.
+ */
+export function watchUpdates({ apiBase, onUpdate }) {
+  let running = true;
+  let attempt = 0;
+  let controller = null;
+
+  async function connect() {
+    const token = readToken();
+    if (!token) throw new Error('nothing filed from this browser yet');
+
+    controller = new AbortController();
+    const res = await fetch(`${apiBase}/ingest/watch/stream`, {
+      headers: { Authorization: `Bearer ${token}`, Accept: 'text/event-stream' },
+      signal: controller.signal,
+    });
+
+    // The token expired or was revoked. Retrying cannot fix that, and the
+    // stale token is dropped so a later report can replace it.
+    if (res.status === 401) {
+      running = false;
+      clearToken();
+      throw new Error('subscription no longer valid');
+    }
+    if (!res.ok || !res.body) throw new Error(`stream failed (${res.status})`);
+
+    const openedAt = Date.now();
+    const reader = res.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = '';
+
+    try {
+      for (;;) {
+        const { value, done } = await reader.read();
+        if (done) break;
+        buffer += decoder.decode(value, { stream: true });
+        buffer = drain(buffer, (event) => {
+          if (event.type !== 'ping') {
+            try {
+              onUpdate(event);
+            } catch { /* a host handler that throws must not kill the stream */ }
+          }
+        });
+      }
+    } finally {
+      // In a `finally` so a stream that ends by throwing is judged the same way
+      // as one that ends cleanly — both have to earn the reset by lasting.
+      if (Date.now() - openedAt >= STABLE_MS) attempt = 0;
+    }
+  }
+
+  (async () => {
+    while (running) {
+      try {
+        await connect();
+      } catch (err) {
+        if (err?.name === 'AbortError') return;
+      }
+      if (!running) return;
+      const wait = BACKOFF_MS[Math.min(attempt, BACKOFF_MS.length - 1)];
+      attempt += 1;
+      await new Promise((resolve) => setTimeout(resolve, wait));
+    }
+  })();
+
+  return () => {
+    running = false;
+    controller?.abort();
+    controller = null;
+  };
+}
+
+const STATUS_COPY = {
+  OPEN: 'is open',
+  IN_PROGRESS: 'is being worked on',
+  RESOLVED: 'has been fixed',
+  CLOSED: 'has been closed',
+};
+
+/**
+ * The colour each kind of update wears, so a fix and a severity change are not
+ * the same anonymous grey card. Keyed on the update kind the API sends.
+ */
+const KIND_ACCENT = {
+  status: null,        // falls back to the host's configured accent
+  severity: '#e8912a',
+  assignment: '#4da3ff',
+  reply: '#35b87f',
+};
+
+/**
+ * The headline for an update.
+ *
+ * The API writes this line — it knows what changed and phrases it for the
+ * person who reported it, and one copy of that wording serves the toast, the
+ * timeline and the portal. `summary` is preferred for exactly that reason; the
+ * status fallback below is only for a page still talking to an older API.
+ */
+export function updateHeadline(event) {
+  if (event?.summary) return event.summary;
+  return `Your report ${STATUS_COPY[event?.status] || 'was updated'}`;
+}
+
+/** The second line: a shared reply reads as the reply, everything else names the report. */
+function updateDetail(event) {
+  if (event?.kind === 'reply' && event.reply?.body) {
+    const who = event.reply.author ? `${event.reply.author}: ` : '';
+    return `${who}${event.reply.body}`;
+  }
+  return event?.title || '';
+}
+
+/** How long ago, in the fewest words. Persisted cards outlive the moment. */
+function agoLabel(at) {
+  const then = Date.parse(at || '');
+  if (!Number.isFinite(then)) return '';
+  const mins = Math.round((Date.now() - then) / 60000);
+  if (mins < 1) return 'just now';
+  if (mins < 60) return `${mins}m ago`;
+  const hours = Math.round(mins / 60);
+  if (hours < 24) return `${hours}h ago`;
+  const days = Math.round(hours / 24);
+  return days === 1 ? 'yesterday' : `${days}d ago`;
+}
+
+// At most this many cards on screen at once; the rest are counted on a line
+// under them. Somebody who has been away for a week should find a corner they
+// can still see their app through.
+const MAX_CARDS = 3;
+
+/**
+ * How far above the corner to start, so the stack clears the widget's launcher
+ * rather than sitting on it. Measured rather than assumed: the dock is a
+ * launcher, sometimes with a theme switch above it, and its height is the only
+ * honest source for how much room it takes.
+ */
+function dockOffset() {
+  try {
+    const host = document.querySelector('[data-bugcatch="widget"]');
+    const dock = host?.shadowRoot?.querySelector('.dock');
+    const height = dock?.getBoundingClientRect().height || 0;
+    return height ? Math.round(height) + 12 : 0;
+  } catch {
+    return 0;
+  }
+}
+
+/**
+ * The built-in notifications, for integrations that do not want to render their
+ * own.
+ *
+ * A card per unread update, stacked in the same corner as the widget and
+ * staying there until the reporter marks it read. Nothing here is on a timer:
+ * the whole point of telling somebody their bug was fixed is that they find
+ * out, and a card that removes itself after eight seconds only reaches the
+ * people who happened to be looking.
+ *
+ * Everything is inline-styled and scoped to elements this owns: the SDK runs on
+ * someone else's page and must not depend on, or contribute to, their CSS. It
+ * sits *below* the widget's own layers, so an open report panel covers it
+ * instead of a notification floating over the report it is about.
+ */
+export function createUpdateNotifier({
+  accent = '#4F46E5',
+  position = 'bottom-right',
+  onRead = null,
+  onReadAll = null,
+  onCall = null,
+} = {}) {
+  const [vertical, horizontal] = String(position).split('-');
+  const atTop = vertical === 'top';
+  const atLeft = horizontal === 'left';
+  // id -> card element, so an update already on screen is left alone. Rebuilding
+  // the stack on every frame would restart the animations and take the button
+  // out from under a finger already on its way to it.
+  const cards = new Map();
+  let stack = null;
+  let more = null;
+
+  function ensureStack() {
+    if (stack?.isConnected) return stack;
+    stack = document.createElement('div');
+    stack.setAttribute('data-bugcatch', 'updates');
+    stack.style.cssText = [
+      'position:fixed',
+      `${atTop ? 'top' : 'bottom'}:${20 + dockOffset()}px`,
+      `${atLeft ? 'left' : 'right'}:20px`,
+      // Under the widget's dock and its panel scrim, both of which are higher.
+      // A notification is worth interrupting a page for, not the report being
+      // read on top of it.
+      'z-index:2147482998',
+      'display:flex',
+      'flex-direction:column',
+      'gap:10px',
+      `align-items:${atLeft ? 'flex-start' : 'flex-end'}`,
+      'width:min(320px,calc(100vw - 40px))',
+      // The gaps between cards belong to the page underneath.
+      'pointer-events:none',
+    ].join(';');
+    document.body.appendChild(stack);
+    return stack;
+  }
+
+  /** Fade out and go. Instant for a card that has not been painted yet. */
+  function drop(el) {
+    if (!el._bcShown) { el.remove(); return; }
+    el.style.opacity = '0';
+    el.style.transform = `translateY(${atTop ? -8 : 8}px)`;
+    setTimeout(() => el.remove(), 250);
+  }
+
+  function button(label, primary) {
+    const el = document.createElement('button');
+    el.type = 'button';
+    el.textContent = label;
+    el.style.cssText = [
+      'padding:5px 11px',
+      `border:${primary ? '0' : '1px solid rgba(236,238,242,.24)'}`,
+      'border-radius:6px',
+      `background:${primary ? accent : 'transparent'}`,
+      `color:${primary ? '#fff' : '#eceef2'}`,
+      'font:600 12px/1.4 inherit',
+      'cursor:pointer',
+      'white-space:nowrap',
+    ].join(';');
+    return el;
+  }
+
+  function card(record) {
+    const el = document.createElement('div');
+    el.setAttribute('role', 'status');
+    el.style.cssText = [
+      'box-sizing:border-box',
+      'width:100%',
+      'padding:12px 14px',
+      'border-radius:10px',
+      'background:#1b1e26',
+      'color:#eceef2',
+      'font:13px/1.5 -apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif',
+      'box-shadow:0 12px 30px rgba(0,0,0,0.45)',
+      `border-left:3px solid ${KIND_ACCENT[record?.kind] || accent}`,
+      'opacity:0',
+      `transform:translateY(${atTop ? -8 : 8}px)`,
+      'transition:opacity .2s ease,transform .2s ease',
+      'pointer-events:auto',
+    ].join(';');
+
+    const title = document.createElement('div');
+    title.style.cssText = 'font-weight:600;margin-bottom:2px';
+    title.textContent = updateHeadline(record);
+
+    const body = document.createElement('div');
+    // A reply is the one kind whose detail is worth more room than a title, and
+    // it is the only text here the team wrote rather than the reporter.
+    body.style.cssText = record?.kind === 'reply'
+      ? 'color:#a4abba;display:-webkit-box;-webkit-line-clamp:3;-webkit-box-orient:vertical;overflow:hidden'
+      : 'color:#a4abba';
+    // textContent, not innerHTML: this is text a person typed, being written
+    // back into somebody else's page.
+    body.textContent = updateDetail(record);
+
+    const actions = document.createElement('div');
+    actions.style.cssText =
+      'display:flex;align-items:center;gap:8px;margin-top:10px;flex-wrap:wrap';
+
+    const when = document.createElement('span');
+    when.style.cssText = 'color:#7b8394;font-size:11px;margin-right:auto';
+    when.textContent = agoLabel(record?.at);
+
+    const read = button('Mark as read', false);
+    read.setAttribute('aria-label', `Mark as read: ${updateHeadline(record)}`);
+    read.addEventListener('click', () => onRead?.(record.id));
+
+    actions.append(when, read);
+
+    // The call offer, when there is one. A button rather than a call: a page
+    // somebody may have walked away from must not raise a microphone prompt by
+    // itself, and a reporter who would rather type has lost nothing by ignoring
+    // this.
+    if (record?.call?.offered && typeof onCall === 'function') {
+      const talk = button('Talk it through', true);
+      talk.addEventListener('click', () => onCall(record));
+      actions.insertBefore(talk, read);
+    }
+
+    el.append(title, body, actions);
+    return el;
+  }
+
+  /** The line under the stack when there is more unread than fits. */
+  function moreRow(count) {
+    const el = document.createElement('div');
+    el.style.cssText = [
+      'box-sizing:border-box',
+      'width:100%',
+      'display:flex',
+      'align-items:center',
+      'gap:8px',
+      'padding:8px 12px',
+      'border-radius:10px',
+      'background:#1b1e26',
+      'color:#a4abba',
+      'font:12px/1.4 -apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif',
+      'box-shadow:0 12px 30px rgba(0,0,0,0.45)',
+      'pointer-events:auto',
+    ].join(';');
+
+    const label = document.createElement('span');
+    label.style.cssText = 'margin-right:auto';
+    label.textContent = `${count} more update${count === 1 ? '' : 's'}`;
+
+    const all = button('Mark all as read', false);
+    all.style.cssText += ';padding:4px 9px';
+    all.addEventListener('click', () => onReadAll?.());
+
+    el.append(label, all);
+    return el;
+  }
+
+  return {
+    /**
+     * Draw what is unread, oldest first.
+     *
+     * The newest card sits nearest the corner the widget is in, which is the
+     * corner the reporter's eye is already trained on — so the stack grows away
+     * from the launcher rather than over it.
+     */
+    render(list) {
+      const unread = Array.isArray(list) ? list : [];
+      if (!unread.length) {
+        for (const el of cards.values()) drop(el);
+        cards.clear();
+        more?.remove();
+        more = null;
+        // The container goes too: an empty fixed element in someone else's page
+        // is one more thing for their own layout debugging to trip over.
+        stack?.remove();
+        stack = null;
+        return;
+      }
+
+      const visible = unread.slice(-MAX_CARDS);
+      const shown = new Set(visible.map((u) => u.id));
+      const root = ensureStack();
+
+      for (const [id, el] of cards) {
+        if (!shown.has(id)) { drop(el); cards.delete(id); }
+      }
+
+      const fresh = [];
+      for (const record of visible) {
+        if (cards.has(record.id)) continue;
+        const el = card(record);
+        cards.set(record.id, el);
+        fresh.push(el);
+      }
+
+      // Nearest the corner is the newest, so a top-anchored stack is drawn in
+      // the opposite order to a bottom-anchored one.
+      const ordered = atTop ? [...visible].reverse() : visible;
+      for (const record of ordered) root.appendChild(cards.get(record.id));
+
+      const hidden = unread.length - visible.length;
+      if (hidden > 0) {
+        more?.remove();
+        more = moreRow(hidden);
+        // Furthest from the corner, past the oldest card on screen.
+        if (atTop) root.appendChild(more);
+        else root.insertBefore(more, root.firstChild);
+      } else {
+        more?.remove();
+        more = null;
+      }
+
+      // One frame later, so the transition has a start to run from. Cards read
+      // as unpainted until this fires, which is what lets an update marked read
+      // in the same tick — by the widget, with the report already open — leave
+      // without a card flashing up and fading out behind it.
+      requestAnimationFrame(() => {
+        for (const el of fresh) {
+          if (!el.isConnected) continue;
+          el._bcShown = true;
+          el.style.opacity = '1';
+          el.style.transform = 'translateY(0)';
+        }
+      });
+    },
+
+    destroy() {
+      cards.clear();
+      more = null;
+      stack?.remove();
+      stack = null;
+    },
+  };
+}
+
+/**
+ * What this project is willing to say is already broken.
+ *
+ * Asked when the widget opens, before anything is typed. Failure is silent and
+ * answers an empty list: this is a help panel in front of a form, and a page
+ * that cannot reach the API still has to let somebody report the thing they
+ * came to report.
+ */
+export async function fetchKnownIssues({ apiBase, apiKey, projectId, sessionToken }) {
+  try {
+    const res = await fetch(
+      `${apiBase}/ingest/known-issues?projectId=${encodeURIComponent(projectId)}`,
+      { headers: knownIssueHeaders(apiKey, sessionToken) },
+    );
+    if (!res.ok) return [];
+    const body = await res.json();
+    return Array.isArray(body?.issues) ? body.issues : [];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * The listed issues that look like what somebody is typing.
+ *
+ * Takes an AbortSignal because it runs on a keystroke debounce: without one, a
+ * fast typist has six of these in flight and the panel renders whichever
+ * happens to land last, which is not necessarily the one matching what is now
+ * in the box.
+ */
+export async function matchKnownIssues({ apiBase, apiKey, projectId, q, sessionToken, signal }) {
+  try {
+    const url = `${apiBase}/ingest/known-issues/match`
+      + `?projectId=${encodeURIComponent(projectId)}&q=${encodeURIComponent(q)}`;
+    const res = await fetch(url, { headers: knownIssueHeaders(apiKey, sessionToken), signal });
+    if (!res.ok) return [];
+    const body = await res.json();
+    return Array.isArray(body?.issues) ? body.issues : [];
+  } catch {
+    // Includes the AbortError of a superseded keystroke, which is the ordinary
+    // case rather than a failure.
+    return [];
+  }
+}
+
+/**
+ * Say an existing report is happening to you too.
+ *
+ * Throws, unlike the two reads above: this one is a button somebody pressed,
+ * and a press that silently does nothing is worse than an error they can read.
+ * The watch token comes back for the same reason it does on a filed report —
+ * it is what lets this browser hear that the bug was fixed.
+ */
+export async function joinKnownIssue({
+  apiBase, apiKey, projectId, bugId, reporterEmail, reporterName, metadata, logs, sessionToken,
+}) {
+  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 }),
+    },
+  );
+  if (!res.ok) throw new Error(await readJoinError(res));
+  const body = await res.json();
+  if (body?.watchToken) writeToken(body.watchToken);
+  return body;
+}
+
+function knownIssueHeaders(apiKey, sessionToken) {
+  return {
+    'Content-Type': 'application/json',
+    'X-BugCatch-Key': apiKey,
+    ...(sessionToken ? { 'X-BugCatch-Session': sessionToken } : {}),
+  };
+}
+
+async function readJoinError(res) {
+  try {
+    const body = await res.json();
+    const message = Array.isArray(body.message) ? body.message.join(', ') : body.message;
+    if (message) return message;
+  } catch { /* non-JSON error */ }
+  return `Could not add you to this issue (HTTP ${res.status})`;
+}