@sphoro/bugcatch-web-sdk 0.13.1 → 0.14.0

package/README.md

@@ -60,9 +60,8 @@ doing gets attached to the report.
 | `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 voice call when a report is picked up, where the workspace has one 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` | — | `('connecting' \| 'listening' \| 'speaking' \| 'ended' \| 'failed', { bugId })` as a call moves. |
-| `onCallTranscript` | — | `{ bugId, role, text, final }` for each line, as it is recognised. |
+| `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. |
 
 ## Screenshots, recordings and files
 
@@ -127,13 +126,13 @@ await BugCatch.matchKnownIssues(q, { signal });  // the ones matching what they
 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 call about it
+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);          // talk an existing report through
-await BugCatch.canCallTeam(bugId);        // may they reach a person about it?
-await BugCatch.startLiveCall(bugId);      // ring the team about an existing report
+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, either kind
+BugCatch.endCall();                       // hang up
 ```
 
 ### Telling BugCatch who is reporting
@@ -506,104 +505,76 @@ a description: the question it answers is "is this the thing I came here about".
 
 ## Talking a report through
 
-Where the workspace has sphoro.voice configured, a reporter can talk instead of
-type. There are two ways in.
+Where the workspace has sphoro.voice configured, a reporter can talk to the team
+instead of typing. There are two ways in.
 
-**Instead of the form.** A **Talk to us** button appears next to *Send report*.
-Pressing it files the report immediately — carrying the console, network and
-environment the SDK is already holding — and puts the reporter straight on a
-call about it. The report exists before the call starts, so a call that drops
+**Instead of the form.** A **Talk to the team** button appears next to *Send
+report*. Pressing it asks for the microphone, files the report — carrying the
+console, network and environment the SDK is already holding — and rings the team
+about it. The report is written before the phones ring, so a call nobody answers
 still leaves the context behind, and it opens unassigned: whoever takes it in
-the dashboard owns it. Nobody typed a title, so it takes one from the first
-thing the reporter actually says.
+the dashboard owns it.
 
 **After somebody picks it up.** When a report is assigned, its reporter is
-offered a call about it. The agent asks the three questions the form did not,
-and what it learns lands in the report's thread.
+offered a call about it, and the open report's composer grows a phone button.
 
-Either way the other end is an automated agent, not a colleague — the widget
-says so before the first word — and the team reads the transcript rather than
-answering a phone.
+The other end is a colleague, not software. The audio travels directly between
+the two browsers over WebRTC and never reaches BugCatch or sphoro.voice, so
+there is no transcript — the report's thread gets a note saying the call
+happened, who took it and how long it lasted. It goes both ways: the team can
+ring back, which is the section after this one.
 
 ```js
 BugCatch.init({
   apiBase: '…', apiKey: '…', projectId: '…',
-  onCallState: (state) => setStatus(state),
-  onCallTranscript: ({ role, text }) => appendLine(role, text),
+  onCallState: (state) => setStatus(state),   // 'ringing' → 'connected' → 'ended'
 });
 ```
 
-Both affordances are built in: the **Talk to us** button on the composer, and —
-with `updateToast` on, the default — a **Talk it through** button on the update
-card when a report is picked up (pressing it marks that update read: acting on a
-notification is the clearest way there is of having seen it). To render your own instead:
+Both affordances are built in: the **Talk to the team** button on the composer,
+and — with `updateToast` on, the default — a **Talk it through** button on the
+update card when a report is picked up (pressing it marks that update read:
+acting on a notification is the clearest way there is of having seen it). To
+render your own instead:
 
 ```js
-// Instead of the form: files a report and calls about it.
+// Instead of the form: files a report and rings the team about it.
 if (await BugCatch.canCallNow()) {
-  const call = await BugCatch.startCall();
+  const call = await BugCatch.startCall();   // resolves once it is *ringing*
   call.bugId;   // what it was filed as
+  call.setMuted(true);
+  call.hangUp();
 }
 
 // About a report already filed.
 if (await BugCatch.canCall(bugId)) {
   await BugCatch.startCall(bugId);
 }
-```
-
-`startCall()` with no id rejects with `.filed` set when the report was written
-but no call could be placed — the report still exists, and telling the reporter
-otherwise would have them file it twice.
-
-Three things are worth being explicit about, because they are what people ask:
-
-- **Nobody from the team is on the line.** The agent is software, it says so,
-  and the team reads the transcript afterwards. Nothing rings anywhere. (Unless
-  it is a *live* call — see below, which is the other feature entirely.)
-- **The microphone is asked for on the press, never before.** An offer that
-  raised a permission prompt on arrival would be a page listening to somebody
-  who walked away from it.
-- **One call at a time**, and `destroy()` ends it. Two microphones on one page
-  transcribe each other.
-
-### Calling a person instead
 
-The other kind of call. `startCall` reaches the triage agent; `startLiveCall`
-rings the team, and whoever is free picks it up. It goes both ways — the team
-can ring back, which is the section after this one.
-
-```js
-if (await BugCatch.canCallTeam(bugId)) {
-  const call = await BugCatch.startLiveCall(bugId);   // resolves once it is *ringing*
-  call.setMuted(true);
-  call.hangUp();
-}
-
-BugCatch.on('call', ({ live, state }) => {
-  if (!live) return;
+BugCatch.on('call', ({ state }) => {
   // 'ringing' → 'connecting' → 'connected' → 'ended'
   // or 'ringing' → 'missed', when nobody picked up in about twenty seconds.
 });
 ```
 
-The widget renders this itself: a phone button on an open report's composer,
-shown only where the workspace has switched live calling on — which most have
-not.
+`startCall()` with no id rejects with `.filed` set when the report was written
+but nobody could be rung — the report still exists, and telling the reporter
+otherwise would have them file it twice. `startLiveCall()` is the same call
+under its older name, from when this was one of two kinds.
 
-What is different about it, and worth telling a customer:
+Four things are worth being explicit about, because they are what people ask:
 
 - **It is a real person, and it is not recorded.** The audio goes directly
-  between the two browsers over WebRTC and never reaches BugCatch or
-  sphoro.voice, so there is no transcript. The report's thread gets a note
-  saying the call happened, who took it and how long it lasted.
+  between the two browsers, so there is no transcript for the team to read
+  instead of answering. The thread gets a note saying the call happened.
 - **It can go unanswered.** It rings everybody who can see the report for about
   twenty seconds; if nobody is free, the state is `missed` and the reporter is
   pointed back at the chat.
-- **A report id is required.** Unlike `startCall()`, there is no file-and-call
-  path: ringing a room about a report nobody can read would ask somebody to
-  answer a call they know nothing about.
-- **One microphone.** A live call and an agent call share the slot, so
-  `endCall()` ends whichever is running and neither can start over the other.
+- **The microphone is asked for on the press, never before.** An offer that
+  raised a permission prompt on arrival would be a page listening to somebody
+  who walked away from it.
+- **One call at a time**, and `destroy()` ends it. Two microphones on one page
+  talk over each other.
 
 ### Being called
 
@@ -679,8 +650,7 @@ deployment without sphoro.voice and any workspace that has not switched calling
 on, which is most of them. `canCallNow` additionally needs `identify()` to have
 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 (about 1.5 kB gzipped, most of it the G.711 codec a browser
-does not ship), but nothing runs.
+still in the bundle, but nothing runs.
 
 ## What is captured