@sphoro/bugcatch-web-sdk 0.14.4 → 0.16.0

package/README.md

@@ -1,11 +1,38 @@
 # @sphoro/bugcatch-web-sdk
 
-A ~4 kB browser SDK that reports bugs from your site with the context you'd otherwise
-have to ask for: console output, network activity, unhandled errors and environment.
+A browser SDK that lets your customers report a problem from inside your app, and
+attaches what you'd otherwise have to ask them for: console output, network
+activity, unhandled errors, the environment, and — when you tell it — who the
+customer is and which loan, application or account they were looking at.
+
+No extension, no dependencies. The widget renders in a shadow root, so its CSS and
+yours never collide.
+
+- [Quick start](#quick-start)
+- [Tell BugCatch who the customer is](#tell-bugcatch-who-the-customer-is) — with loan / customer IDs
+- [Context for the current screen](#context-for-the-current-screen)
+- [A lending app, end to end](#a-lending-app-end-to-end)
+- [Events](#events)
+- [Reporting and opening from your own UI](#reporting-and-opening-from-your-own-ui)
+- [The AI assistant](#the-ai-assistant)
+- [Privacy: what is captured and what is not](#privacy-what-is-captured-and-what-is-not)
+- [Options](#options)
+- [API at a glance](#api-at-a-glance)
+- [Troubleshooting](#troubleshooting)
+- [Reference](#reference) — attachments, sign-in, live updates, replies, known issues, calls
+
+## Quick start
+
+You need two values from BugCatch:
+
+| Value | Where to find it |
+|---|---|
+| `apiKey` | Workspace Settings → API Keys (`bc_live_…`; shown once when created) |
+| `projectId` | Project Settings → Web SDK (the snippet there is pre-filled) |
 
-No extension required. No dependencies.
+and the URL of your BugCatch API (`apiBase`).
 
-## Install
+**npm / bundler**
 
 ```bash
 npm install @sphoro/bugcatch-web-sdk
@@ -15,55 +42,380 @@ npm install @sphoro/bugcatch-web-sdk
 import BugCatch from '@sphoro/bugcatch-web-sdk';
 
 BugCatch.init({
-  apiBase: 'https://api.yourdomain.com',
-  apiKey: 'bc_live_…',       // Workspace Settings → API Keys
-  projectId: '…',            // Project Settings → General
+  apiBase: 'https://api.bugcatch.yourdomain.com',
+  apiKey: 'bc_live_…',
+  projectId: '…',
+  release: '4.12.0',           // optional, shown on every report
+  environment: 'production',   // optional
 });
 ```
 
-Or with a script tag:
+**Script tag**
 
 ```html
 <!-- Pin the version. Without one the CDN serves whatever is latest, so a
      future release changes behaviour on a site nobody redeployed. -->
-<script src="https://unpkg.com/@sphoro/bugcatch-web-sdk@0.13.1/dist/bugcatch.umd.js"></script>
+<script src="https://unpkg.com/@sphoro/bugcatch-web-sdk@0.16.0/dist/bugcatch.umd.js"></script>
 <script>
-  BugCatch.init({ apiBase: '…', apiKey: '…', projectId: '…' });
+  BugCatch.init({ apiBase: '…', apiKey: 'bc_live_…', projectId: '…' });
 </script>
 ```
 
-That's it — a floating **Report a bug** button appears, and whatever the page was
-doing gets attached to the report.
+A floating **Report a bug** button appears, and whatever the page was doing is
+attached to each report. Types ship with the package (`src/index.d.ts`), so
+editors autocomplete every option and method below.
+
+Call `init()` once, as early as you can — console and network capture start at
+`init()`, so anything before it is not recorded. `identify()` and `setContext()`
+may be called before or after it.
+
+## Tell BugCatch who the customer is
+
+```js
+BugCatch.identify({
+  id: customer.id,                  // your customer's own account id
+  email: customer.email,
+  name: customer.fullName,
+  phone: customer.mobile,           // include the country code: '+919876543210'
+  customerNumber: customer.number,  // your customer / client number
+  loanId: customer.activeLoanId,    // a loan they hold
+  applicationId: customer.appId,    // a loan application
+});
+
+// On sign-out
+BugCatch.identify(null);
+BugCatch.setContext(null);
+BugCatch.forgetReports();   // so the next person on this device doesn't see their updates
+```
+
+Every field is optional; send what you have. What each one does:
+
+| Field | Type | What BugCatch does with it |
+|---|---|---|
+| `id` | string \| number | The customer's account id in **your** system. Used to look them up in your connected data source (as `userId`). Never pass a staff or agent id here. |
+| `email` | string | Threads their reports together in the dashboard, and is where the "your issue is resolved" email goes. Treated as reachable because your app authenticated them. Needed for live updates and calls. |
+| `name` | string | Shown instead of a bare address. |
+| `phone` | string \| number | With `email`, compared against the record BugCatch looked up, to confirm the reporter really is that customer before anything is done on their behalf. |
+| `loanId` | string \| number | Looked up as a **loan** (`loanId`). Alias: `loanNumber`. |
+| `applicationId` | string \| number | Looked up as a **loan application** (`loanId`). |
+| `customerNumber` | string \| number | Looked up as a **customer** (`customerNumber`). Alias: `customerId`. |
+| anything else | primitive or small object | Kept as readable metadata on the report. Not used for lookups. |
+
+**Why the IDs matter.** When your project has a data source connected (MCP), the
+AI assistant looks the customer up *before* it reasons about the report. IDs your
+app passes are **trusted identifiers**: your application asserted them, so the
+assistant uses them directly instead of asking the customer "what is your loan
+number?", and a record found by one of them counts as belonging to the reporter.
+IDs a customer types into the report are still read — but as hints, not facts.
+
+Rules the SDK enforces (with a console warning, never an exception):
+
+- Identifiers must be strings or numbers, at most 120 characters, with no control
+  characters. Anything else is dropped — a truncated loan number is a different loan.
+- An object, array or function passed as an identifier is dropped.
+- `identify('u_42')` (not an object) is ignored and keeps the previous user.
+  Only `identify(null)` signs out.
+- Extra fields: up to 30, strings capped at 500 characters, nested objects at 1 kB of JSON.
+
+## Context for the current screen
+
+`identify()` says who the customer is. `setContext()` says what they are looking
+at — so a report filed from the repayment screen of one loan carries that loan,
+even when the customer holds three.
+
+```js
+// Entering a loan's screen
+BugCatch.setContext({ loanId: loan.id, screen: 'repayment' });
+
+// Leaving it — null removes one key
+BugCatch.setContext({ loanId: null });
+
+// Clear everything
+BugCatch.setContext(null);
+
+BugCatch.getContext();   // { screen: 'repayment' }
+```
+
+- Merged over what was set before, and kept until changed, for the life of the
+  page (not across reloads — call it again when the screen mounts).
+- `loanId`, `applicationId` and `customerNumber` are validated and trusted exactly
+  as on `identify()`, and **outrank** the same field there: if the customer holds
+  loan A but files from loan B's screen, B is what gets looked up.
+- Anything else (`screen`, `step`, `route`, a feature flag) is readable metadata.
+- For a single report, pass `context` to `report()` instead — it is merged for
+  that report only and does not change what `setContext()` holds.
+
+In a single-page app, the natural place is your router:
+
+```js
+router.afterEach((to) => {
+  BugCatch.setContext({
+    screen: to.name,
+    loanId: to.params.loanId ?? null,
+    applicationId: to.params.applicationId ?? null,
+  });
+});
+```
+
+## A lending app, end to end
+
+```js
+import BugCatch from '@sphoro/bugcatch-web-sdk';
+
+BugCatch.init({
+  apiBase: 'https://bugcatch-api.example.com',
+  apiKey: 'bc_live_…',
+  projectId: '…',
+  release: APP_VERSION,
+  environment: 'production',
+  onReportSubmitted: ({ bugId }) => analytics.track('bug_reported', { bugId }),
+  onAssistantPhase: ({ phase }) => {
+    if (phase === 'needs_info') showBadge('We need one more detail from you');
+  },
+});
+
+auth.onSignIn((customer) => {
+  BugCatch.identify({
+    id: customer.userId,               // e.g. 'dc046b84-3314-46ae-9b8f-526d3e50bc50'
+    email: customer.email,
+    name: customer.name,
+    phone: customer.mobile,            // '+919876543210'
+    customerNumber: customer.customerNumber,   // e.g. 'C1234567'
+  });
+});
+
+auth.onSignOut(() => {
+  BugCatch.identify(null);
+  BugCatch.setContext(null);
+  BugCatch.forgetReports();
+});
+
+// Loan details / repayment / EMI screens
+function onLoanScreen(loan) {
+  BugCatch.setContext({ loanId: loan.formattedLoanId, screen: 'loan-details' });   // 'L26090028459'
+}
+```
+
+**How the IDs travel.**
+
+1. The SDK sends `identify()` fields as `metadata.user` and `setContext()` as
+   `metadata.context` on every report (and on "me too" joins).
+2. The API reads them — only on the SDK's authenticated route, never from a public
+   recording link — and stores them as references with source `identify`:
+   `id` → `identify_user_id`, `loanId` → `auto_loan`, `applicationId` →
+   `auto_application`, `customerNumber` → `auto_customer`.
+3. The analysis looks each one up as what it is (`loanId`, `customerNumber`,
+   `userId`, loans first) through your data source's tools, and marks the join
+   trusted only when the record it found came from one of these IDs.
+4. `phone` and `email` from `identify()` are what the ownership check compares
+   with the record, before the assistant acts for the customer.
+
+## Events
+
+Every event is available two ways: as a single callback in `init()`, or through
+`on()`, which several parts of your app can use independently. `on()` returns an
+unsubscribe function. A handler that throws is logged and never breaks the SDK.
+
+| `on(…)` event | `init` option | Payload | When |
+|---|---|---|---|
+| `'report'` | `onReportSubmitted` | `{ bugId, title, via: 'form' \| 'call', result }` | A report was accepted — from the widget, `report()`, or pressing Call. |
+| `'assistant'` | `onAssistantPhase` | `{ bugId, phase, title, detail }` | The AI assistant working a report changed phase — see [The AI assistant](#the-ai-assistant). |
+| `'error'` | `onError` | `{ action: 'report' \| 'call', error }` | A report or call failed. `error.status` is set for an HTTP refusal. |
+| `'update'` | `onUpdate` | `ReportUpdate` | A report filed from this browser changed (status, reply, …). |
+| `'unread'` | — | `{ count, updates }` | The unread count changed — for your own bell. |
+| `'call'` | `onCallState` | `{ bugId, state, … }` | A call moved: `ringing`, `connecting`, `connected`, `missed`, `ended`, `failed`. |
+| `'incoming-call'` | `onIncomingCall` | `{ bugId, callId, state }` | The team is ringing this page. |
+| `'signin'` / `'signout'` | — | `{ email, name }` | The reporter signed in or out through the widget. |
+
+```js
+const off = BugCatch.on('report', ({ bugId, via }) => {
+  console.log(`filed ${bugId} via ${via}`);
+});
+off();   // stop listening
+```
+
+## Reporting and opening from your own UI
+
+Open the built-in panel from your own menu item:
+
+```js
+helpMenu.onReportProblem = () => BugCatch.open();
+BugCatch.close();
+BugCatch.isOpen();
+```
+
+Or turn the widget off and file reports yourself — everything captured is still
+attached:
+
+```js
+BugCatch.init({ apiKey, projectId, apiBase, widget: false });
+
+const result = await BugCatch.report({
+  title: 'EMI paid but still showing due',   // required
+  description: 'Paid ₹4,210 by UPI this morning',
+  priority: 'HIGH',                          // LOW | MEDIUM | HIGH | CRITICAL
+  context: { loanId: 'L26090028459' },       // this report only
+  references: [{ key: 'utr', value: '4321…' }],   // what the customer typed, if you asked
+  metadata: { paymentMethod: 'upi' },
+});
+// → { id, redactionsApplied, watchToken?, estimate? }  or { cancelled: true } from beforeSend
+```
+
+`report()` rejects with an `Error` whose message says what went wrong
+(`[BugCatch] report failed (HTTP 401): the apiKey was not accepted`), and emits
+`'error'`. Malformed `references` entries are dropped rather than failing the report.
+
+## The AI assistant
+
+When your workspace has AI analysis on, every report is investigated as soon as
+it arrives: the assistant reads the report, the captured logs and — with a
+connected data source — the customer's own records, looked up by the IDs above.
+After a report is filed, the widget opens its conversation, where the reporter
+watches progress and answers questions.
+
+| Phase | What the reporter sees |
+|---|---|
+| `analyzing` | "Analyzing the issue…" — reading the report, the account and the logs. |
+| `needs_info` | It asked a question (often: which loan?) and is waiting for the reporter's reply. |
+| `confirming` | It found the likely cause and asks the reporter to confirm. |
+| `resolving` | The cause is confirmed, or it is being handled. |
+| `reviewing` | Handed to your team, who will reply in the thread. |
+| `resolved` | Settled. |
+
+The phase is known when a report is fetched: the widget does this every few
+seconds while its thread is open, and `BugCatch.myReport(bugId)` does it for your
+own view (it also returns `report.assistant`). Each change fires
+`onAssistantPhase` / `'assistant'` once.
+
+**Passing IDs is the biggest thing you can do for it.** Without them, the first
+thing the assistant usually has to do is ask the customer which account or loan
+they mean — the `needs_info` step — and wait for an answer.
+
+## Privacy: what is captured and what is not
+
+Captured, and only after `init()`:
+
+- **Console** — the last 100 entries (level, message, time), plus uncaught errors
+  and unhandled promise rejections. Whatever your app logs is captured, so do not
+  log tokens or personal data — or drop those entries in `beforeSend`.
+- **Network** — the last 50 `fetch`/XHR calls: URL, method, status, duration.
+  **Request and response bodies are never read.** Credentials in URLs (API keys,
+  tokens, signatures, JWTs, `user:password@`) are replaced with `[REDACTED]` before
+  the entry is even buffered.
+- **Environment** — browser, OS, language, viewport and screen, timezone,
+  connection type, page title and referrer.
+- **The page URL** when the report is filed (credential-scrubbed the same way).
+- **Only what you pass** to `identify()`, `setContext()` and `report({ metadata })`.
+  The SDK never reads your cookies, your app's storage or what is typed into your forms.
+- **Screenshots and recordings** only when the reporter chooses to take one; the
+  browser always shows its own permission prompt.
+
+On top of that:
+
+- `beforeSend(payload)` runs in the browser before anything leaves it — mutate the
+  payload or return `false` to cancel.
+- Your workspace's redaction rules (Workspace Settings → Security) run again on the
+  server before anything is stored; encrypted workspaces seal it at rest.
+- `captureConsole`, `captureNetwork` and `captureErrors` can each be switched off.
+- The SDK stores in the reporter's own browser only: a watch token for their reports,
+  unread update notices, unfinished drafts (7 days), and a widget sign-in if used.
+  `forgetReports()` clears the first two.
 
 ## Options
 
 | Option | Default | What it does |
 |---|---|---|
-| `apiKey` | *required* | Workspace API key. |
-| `projectId` | *required* | Project the bugs land in. |
-| `apiBase` | `http://localhost:3000` | Where the API lives. |
-| `widget` | `true` | Floating launcher. Set `false` to drive it from your own UI. |
+| `apiKey` | *required* | Workspace API key (`bc_live_…`). |
+| `projectId` | *required* | Project the reports land in. |
+| `apiBase` | `http://localhost:3000` | Your BugCatch API URL. **Set it everywhere except local development.** A trailing slash is removed. |
+| `user` | `null` | Same as calling `identify()` right after `init()`. |
+| `context` | `null` | Same as calling `setContext()` right after `init()`. |
+| `release` / `environment` / `buildId` | — | Attached to every report. |
+| `debug` | `false` | Log identify, context and each report's shape to the console. |
+| `onReportSubmitted` | — | See [Events](#events). |
+| `onAssistantPhase` | — | See [Events](#events). |
+| `onError` | — | See [Events](#events). |
+| `widget` | `true` | Floating launcher and panel. `false` to drive everything from your own UI. |
 | `widgetPosition` | `'bottom-right'` | `bottom-left`, `top-right`, `top-left`. |
-| `captureConsole` | `true` | Wrap `console.*`. |
-| `captureNetwork` | `true` | Wrap `fetch` and `XMLHttpRequest`. |
-| `captureErrors` | `true` | Listen for `error` and `unhandledrejection`. |
-| `consoleLimit` | `100` | Console entries retained. |
-| `networkLimit` | `50` | Network entries retained. |
-| `theme` | `'auto'` | Starting theme: `auto` follows the visitor's system setting; `light` / `dark` pin it. A light/dark/auto switch sits above the launcher, and once the visitor uses it their choice is remembered in `localStorage` and wins over this value on later visits. |
-| `accent` | `'#4F46E5'` | Any CSS colour. Used for the launcher, focus rings and the primary button. |
-| `attachments` | `true` | Offer screenshot, screen recording and file attach. |
-| `knownIssues` | `true` | Show what this project already knows is broken above the form, and offer "this is happening to me too" instead of a second report. Draws nothing until the project switches the feature on and somebody lists an individual report — see [What is already known](#what-is-already-known). |
-| `maxAttachments` | `5` | Per report. |
-| `maxAttachmentBytes` | `25 MB` | Per file. |
-| `maxRecordingMs` | `120000` | Hard cap on a single recording. |
+| `theme` | `'auto'` | `auto` follows the system; `light` / `dark` pin it. A visitor's own choice in the widget wins on later visits. |
+| `accent` | `'#4F46E5'` | Any CSS colour. |
+| `captureConsole` / `captureNetwork` / `captureErrors` | `true` | Each capture can be switched off. |
+| `consoleLimit` / `networkLimit` | `100` / `50` | Entries retained. |
+| `attachments` | `true` | Offer screenshot, recording and file attach. |
+| `maxAttachments` / `maxAttachmentBytes` / `maxRecordingMs` | `5` / `25 MB` / `120000` | Attachment limits. |
+| `drafts` | `true` | Recover an unfinished report on this device for seven days. |
+| `knownIssues` | `true` | Show what this project already knows is broken, with "me too". Draws nothing until the project turns it on. |
 | `beforeSend` | — | Mutate the payload, or return `false` to cancel. |
-| `updates` | `true` | Tell the reporter, live, when a bug they filed moves. Connects only once this browser has filed something. |
-| `updateToast` | `true` | Show the built-in notification. It stays until the reporter marks it read — a reload included. Set `false` to render your own. |
-| `onUpdate` | — | `{ id, bugId, title, kind, summary, at }` on every update, whether or not the built-in notification is shown. |
-| `voice` | `true` | Offer a call to the team when a report is picked up, where the workspace has calling configured. Nothing is dialled and no microphone is asked for until the reporter presses the button — see [Talking a report through](#talking-a-report-through). |
-| `onCallState` | — | `('ringing' \| 'connecting' \| 'connected' \| 'missed' \| 'ended' \| 'failed', { bugId })` as a call moves. |
+| `updates` | `true` | Tell the reporter live when a report they filed moves. |
+| `updateToast` | `true` | Show the built-in notification; `false` to render your own from `'update'` / `'unread'`. |
+| `onUpdate` | — | Called on every update. |
+| `voice` | `true` | Offer calls where the workspace has calling configured. `false` switches calls off in both directions. |
+| `onCallState` / `onIncomingCall` | — | See [Talking a report through](#talking-a-report-through). |
+
+An option the SDK does not know is reported in the console with a suggestion
+(`unknown option "projectID" — did you mean "projectId"?`).
+
+## API at a glance
+
+```js
+BugCatch.init(options);                   // once
+BugCatch.identify({ id, email, name, phone, loanId, applicationId, customerNumber });
+BugCatch.identify(null);                  // sign-out
+BugCatch.setContext({ loanId, screen });  // merge; null value removes a key
+BugCatch.setContext(null);                // clear
+BugCatch.getContext();
+
+BugCatch.open(); BugCatch.close(); BugCatch.isOpen();
+await BugCatch.report({ title, description, priority, context, references, metadata, attachments });
+await BugCatch.uploadAttachment(blob, mime, onProgress);
+
+const off = BugCatch.on('report' | 'assistant' | 'error' | 'update' | 'unread' | 'call'
+  | 'incoming-call' | 'signin' | 'signout', handler);
+BugCatch.off(event, handler);
+
+await BugCatch.myReports();               // everything filed from this browser
+await BugCatch.myReport(bugId);           // one report, with timeline and assistant phase
+await BugCatch.replyToReport(bugId, { body, attachments });
+BugCatch.unreadUpdates(); BugCatch.markUpdateRead(id); BugCatch.markReportRead(bugId); BugCatch.markUpdatesRead();
+BugCatch.hasReports(); BugCatch.forgetReports();
+
+await BugCatch.loginState(); BugCatch.signedInAs();
+await BugCatch.signIn(email); await BugCatch.confirmSignIn(email, code); await BugCatch.signOut();
+await BugCatch.referenceFields();         // the identifier question this project asks
+
+await BugCatch.knownIssues(); await BugCatch.matchKnownIssues(q, { signal }); await BugCatch.meToo(bugId);
+
+await BugCatch.canCallNow(); await BugCatch.startCall(bugId?); BugCatch.endCall();
 
-## Screenshots, recordings and files
+BugCatch.snapshot();                      // what would be sent right now (user, context, logs)
+BugCatch.clear();                         // empty the capture buffers
+BugCatch.destroy();                       // restore patched globals, remove the widget
+BugCatch.version;                         // the SDK version, for support tickets
+```
+
+## Troubleshooting
+
+Turn on `debug: true` first: the console then shows what `init()` received, every
+`identify()` / `setContext()` and the shape of each report as it is sent.
+
+| Symptom | Likely cause |
+|---|---|
+| `[BugCatch] apiKey is required` / `projectId is required` thrown | The option is missing or still the snippet placeholder. |
+| Warning: *apiBase is not set, so reports go to http://localhost:3000* | Set `apiBase` to your BugCatch API URL. |
+| Warning: *apiKey looks like a project id* | `apiKey` and `projectId` are swapped. |
+| `report failed (HTTP 401): the apiKey was not accepted` | Revoked or mistyped key — keys are shown once; create a new one. |
+| `report failed (HTTP 403)` | The key belongs to a different workspace than `projectId`. |
+| `could not reach https://…` | Wrong `apiBase`, the API is down, or the API's CORS does not allow your site's origin. |
+| `This project needs something to look the report up by — …` | The project requires an identifier. Pass `loanId` / `customerNumber` via `identify()` or `setContext()`, or let the widget ask. |
+| The assistant keeps asking customers for their loan number | Pass the IDs through `identify()` / `setContext()`; check `BugCatch.snapshot().user` and `.context` show them. |
+| `identify()` "did nothing" | It was called with a non-object (ignored with a warning), or an identifier was an object/array/too long. See the console. |
+| Reports are not attributed / no resolution email / no live updates / no Call button | `identify()` has no `email`. |
+| The panel will not open with `open()` | `widget: false` — there is no built-in panel; use `report()`. |
+| Nothing is captured from before a certain point | Capture starts at `init()`. Call it as early as possible. |
+
+## Reference
+
+### Screenshots, recordings and files
 
 The widget can attach a screenshot, a screen recording, or a file the reporter
 picks. Capture goes through `getDisplayMedia`, so **the browser always shows its
@@ -98,68 +450,6 @@ off.
 >     "MaxAgeSeconds":86400}]}'
 > ```
 
-## API
-
-```js
-BugCatch.identify({ id, email, name });   // attach the signed-in user
-await BugCatch.report({ title, description, priority, metadata, attachments });
-await BugCatch.uploadAttachment(blob, mime, onProgress);
-BugCatch.snapshot();                      // what would be sent right now
-BugCatch.clear();                         // empty the buffers
-BugCatch.destroy();                       // restore every patched global
-
-const off = BugCatch.on('update', fn);    // live updates on this browser's reports
-await BugCatch.myReports();               // everything filed here
-await BugCatch.myReport(bugId);           // one report, with its full timeline
-await BugCatch.replyToReport(bugId, { body, attachments });  // write back
-BugCatch.hasReports();                    // has this browser filed anything?
-BugCatch.forgetReports();                 // drop the subscription (call on sign-out)
-
-await BugCatch.loginState();              // what this project asks, and who is signed in
-BugCatch.signedInAs();                    // { email, name } | null, from storage
-await BugCatch.signIn(email);             // step one: mail a code to any address
-await BugCatch.confirmSignIn(email, code);// step two: spend it
-await BugCatch.signOut();                 // end the session, here and on the server
-
-await BugCatch.knownIssues();             // what this project says is already broken
-await BugCatch.matchKnownIssues(q, { signal });  // the ones matching what they are typing
-await BugCatch.meToo(bugId, { email });   // join a report instead of filing a second
-
-await BugCatch.canCallNow();              // may this visitor call instead of typing?
-await BugCatch.startCall();               // file a report and ring the team about it
-await BugCatch.canCall(bugId);            // may this report be talked through?
-await BugCatch.startCall(bugId);          // ring the team about an existing report
-await BugCatch.canCallTeam(bugId);        // the same question, under the widget's name
-await BugCatch.startLiveCall(bugId);      // the same call, under its older name
-BugCatch.on('incoming-call', fn);         // the team ringing *them* — the SDK draws the card
-BugCatch.endCall();                       // hang up
-```
-
-### Telling BugCatch who is reporting
-
-```js
-BugCatch.identify({ id: 'u_42', email: 'alex@example.com', name: 'Alex' });
-
-// On sign-out
-BugCatch.identify(null);
-```
-
-`email` is the field with behaviour attached. It does three things:
-
-- **Threads their reports together.** Every report from that address belongs to
-  one person in the dashboard, with a count and a last-seen — so "this user
-  keeps hitting things" is visible rather than something you have to notice.
-- **Closes the loop.** When someone marks the bug resolved, that person gets
-  the project's resolution email. Nobody has to remember to tell them.
-- **Is trusted, because you authenticated them.** An address typed into a
-  public recording-link form is unusable for outbound mail until the reporter
-  answers a confirmation code. One that arrives through `identify()` is not,
-  because your app already knows who they are. Only send addresses you have
-  actually signed in.
-
-Calling `identify()` is optional; without it reports are filed anonymously and
-nobody gets a resolution email.
-
 ### Letting them sign in themselves
 
 `identify()` is your application vouching for its own user. Some projects want
@@ -457,7 +747,7 @@ parameters — `?page=2`, `?sort=created_at`, `?code=US` — are left alone.
 The API applies the same scrubbing on intake and again when a report is read back, so
 reports captured by older SDK versions are covered too.
 
-## What is already known
+### What is already known
 
 The widget opens with the reports this project has chosen to say are already
 broken, above the form rather than after it, and offers **Me too** beside each
@@ -503,7 +793,7 @@ this on, which is the default — draw nothing rather than an empty heading. Wha
 comes back is a title, a state and a count, and never a severity, an assignee or
 a description: the question it answers is "is this the thing I came here about".
 
-## Talking a report through
+### Talking a report through
 
 Where the workspace has sphoro.voice configured, a reporter can talk to the team
 instead of typing. There are two ways in.
@@ -576,7 +866,7 @@ Four things are worth being explicit about, because they are what people ask:
 - **One call at a time**, and `destroy()` ends it. Two microphones on one page
   talk over each other.
 
-### Being called
+#### Being called
 
 The same live call, placed from the other end. Somebody on the team reads a
 report an hour after it was filed, has one question whose answer is thirty
@@ -652,22 +942,7 @@ supplied an email: a call with nobody to attribute has no way to tell the
 reporter what happened next. Set `voice: false` to opt out entirely; the code is
 still in the bundle, but nothing runs.
 
-## What is captured
-
-- **Console** — last N entries with level and timestamp, plus uncaught errors and
-  unhandled promise rejections.
-- **Network** — last N `fetch`/XHR calls: URL, method, status, duration, and flags for
-  failed or slow. **Request and response bodies are never read**, and **credentials are
-  stripped out of the URL before it is buffered** — see below.
-- **Environment** — user agent, platform, language(s), viewport, screen (size, available
-  size, colour depth, orientation), DPR, timezone and offset, connection type, CPU cores,
-  device memory, touch points, battery level and charging state, colour-scheme and
-  reduced-motion preferences, Do Not Track, online state, referrer, page title.
-- **Page URL** at the moment of reporting.
-
-Both buffers are ring buffers, so a long-lived page won't grow memory without bound.
-
-## Notes
+### Notes
 
 - The widget renders in a shadow root, so your CSS and its CSS can't collide.
 - Capture never throws into your page: every hook is wrapped, and originals are always