@sphoro/bugcatch-web-sdk 0.17.0 → 0.19.0

package/README.md

@@ -55,7 +55,7 @@ BugCatch.init({
 ```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.17.0/dist/bugcatch.umd.js"></script>
+<script src="https://unpkg.com/@sphoro/bugcatch-web-sdk@0.19.0/dist/bugcatch.umd.js"></script>
 <script>
   BugCatch.init({ apiBase: '…', apiKey: 'bc_live_…', projectId: '…' });
 </script>
@@ -65,6 +65,21 @@ 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.
 
+The script is the launcher and the capture, and nothing more. The report panel
+and the call code are separate files in `dist/` — `bugcatch-panel.umd.js` and
+`bugcatch-call.umd.js` — fetched from the folder the script was loaded from the
+first time they are needed: the panel once the page has settled (or when the
+button is pressed, if that comes first), the call code when a call is offered.
+From a bundler, the same two parts are `import()`ed and your bundler splits them.
+
+- **Content-Security-Policy:** allow the host in `script-src`, not the one file.
+  A `nonce` on the script tag is carried over to the parts it loads.
+- **Hosting it yourself:** copy every `dist/bugcatch*.umd.js` into one folder
+  and load `bugcatch.umd.js` from it. If the script cannot know its own address
+  — pasted inline, or concatenated into one of your files — point it at the
+  folder with `init({ chunkBase: '/vendor/bugcatch/' })`, or serve
+  `dist/bugcatch.standalone.umd.js`, which is all of it in one file.
+
 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.
@@ -357,8 +372,8 @@ On top of that:
 | `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`. |
-| `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. |
+| `theme` | `'auto'` | `auto` follows the system; `light` / `dark` pin it. Visitors can change it from the panel's header, and their choice wins on later visits. |
+| `accent` | `null` | Any CSS colour, for the launcher, buttons and the assistant's orb. Text on it is white or near-black, whichever reads. `null` is ink: black on light, white on dark. |
 | `captureConsole` / `captureNetwork` / `captureErrors` | `true` | Each capture can be switched off. |
 | `consoleLimit` / `networkLimit` | `100` / `50` | Entries retained. |
 | `attachments` | `true` | Offer screenshot, recording and file attach. |
@@ -366,12 +381,14 @@ On top of that:
 | `drafts` | `true` | Recover an unfinished report on this device for seven days. |
 | `agentIssues` | `true` | Show the one-tap questions the assistant answers by itself. Draws nothing until the project turns the agent on. |
 | `knownIssues` | `true` | Show what this project already knows is broken, with "me too". Draws nothing until the project turns it on. |
+| `announcements` | `true` | Show what your team publishes under Settings → Project → Widget announcements, in the panel and beside the button. Draws nothing until one is published. `false` to show them your own way with `announcements()`. |
 | `beforeSend` | — | Mutate the payload, or return `false` to cancel. |
 | `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). |
+| `chunkBase` | the script's own folder | Script tag only: where the panel and call code are fetched from. Set it when the bundle is inlined or its `dist/` files are served elsewhere. |
 
 An option the SDK does not know is reported in the console with a suggestion
 (`unknown option "projectID" — did you mean "projectId"?`).
@@ -397,6 +414,8 @@ 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 });
+await BugCatch.verifyFix(bugId, { result, resolvedAt, note }); // 'CONFIRMED' | 'STILL_HAPPENING'
+await BugCatch.rate(bugId, { score, comment });                 // 1–5, once it is settled
 BugCatch.unreadUpdates(); BugCatch.markUpdateRead(id); BugCatch.markReportRead(bugId); BugCatch.markUpdatesRead();
 BugCatch.hasReports(); BugCatch.forgetReports();
 
@@ -406,6 +425,7 @@ await BugCatch.referenceFields();         // the identifier question this projec
 await BugCatch.agentIssues();             // one-tap questions the assistant answers and closes
 
 await BugCatch.knownIssues(); await BugCatch.matchKnownIssues(q, { signal }); await BugCatch.meToo(bugId);
+await BugCatch.announcements(); BugCatch.dismissAnnouncement(a);  // what your team is telling visitors
 
 await BugCatch.canCallNow(); await BugCatch.startCall(bugId?); BugCatch.endCall();
 
@@ -433,6 +453,7 @@ Turn on `debug: true` first: the console then shows what `init()` received, ever
 | `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()`. |
+| *The report form didn't load* above the launcher | `bugcatch-panel.umd.js` could not be fetched from beside `bugcatch.umd.js` — the console names the address. Serve `dist/` together, allow it in `script-src`, or set `chunkBase`. |
 | Nothing is captured from before a certain point | Capture starts at `init()`. Call it as early as possible. |
 
 ## Reference
@@ -697,6 +718,37 @@ attachments stay images and video, because they are typed `SCREENSHOT` or
 `report.canReply` says whether this reader can write back; the widget hides its
 composer when it is false rather than offering a box that would fail on send.
 
+### Asking how it went
+
+Once a report is resolved or closed, the widget asks the reporter **How did we
+do?** under it: five stars, one tap to send, and a box for a note after the
+tap rather than before — a form that asks for a sentence first is a form people
+close. Their list of reports says **Rate it** against the settled ones still
+waiting for a rating, and shows the score on the ones that have one.
+
+The same rating is asked for on the reporter's own page and in the email that
+tells them it was fixed, so whichever they answer is the one that counts.
+Rating again replaces the earlier score. Whether a project asks at all is
+**Project Settings → Resolutions → Ask the reporter to rate it**, on by default.
+
+To drive it from your own UI:
+
+```js
+const report = await BugCatch.myReport(id);
+
+if (report.ratingAsked) {
+  // report.rating is null until they rate, then
+  // { score: 4, comment: 'Quick, thanks', ratedAt, via: 'widget', current: true }
+  await BugCatch.rate(id, { score: 4, comment: 'Quick, thanks' });
+}
+```
+
+`ratingAsked` is true only for a settled report on a project that asks; `rate()`
+rejects otherwise. `rating.current` is false when the report was reopened and
+fixed again after the rating was given — the rating stands, but it was about an
+earlier fix. In `myReports()`, each row carries `rating` (the score, or null)
+and `ratingAsked`.
+
 ### Reporting from your own UI
 
 ```js
@@ -815,6 +867,41 @@ 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".
 
+### Telling visitors something
+
+Your team can put a notice in the widget from the dashboard, and change it or
+take it down there, without redeploying your site: **Settings → Project → Widget
+announcements**. "UPI payments are delayed today — we're on it, no need to
+report it" is the reason it exists: said where people come to report, before
+they type it out.
+
+Each one picks where it appears:
+
+- **In the widget**: at the top of the report panel, when somebody opens it.
+- **Next to the button, too**: also as a small card beside the launcher on
+  every page, for people who came to do something else. Always closable.
+
+A tone (info, success, warning, critical) picks the colour and the icon; info
+wears your `accent`. A link is optional — a path like `/status` is a page on
+your site, a full `https://` address opens a tab. Each runs between two days,
+inclusive, on the visitor's own calendar, and the last day is required.
+Closing one is remembered in that browser until somebody presses **Show it
+again**; editing the wording does not reopen it.
+
+A browser asks at most every five minutes, so a change reaches visitors within
+that, and a project with nothing published costs one small request per browser
+per five minutes.
+
+```js
+// widget: false, or announcements: false — draw them your own way
+const notices = await BugCatch.announcements();
+// [{ id, title, body, tone, ctaLabel, ctaHref, placement, dismissible, ... }]
+BugCatch.dismissAnnouncement(notices[0]);
+```
+
+`announcements()` is already narrowed to the visitor's day and to what this
+browser has not closed, and resolves to an empty list on every failure.
+
 ### Talking a report through
 
 Where the workspace has sphoro.voice configured, a reporter can talk to the team
@@ -961,8 +1048,8 @@ call, and if both are open, the first to answer gets it.
 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, but nothing runs.
+reporter what happened next. Set `voice: false` to opt out entirely; the call
+code is then never fetched, and nothing runs.
 
 ### Notes
 
@@ -980,5 +1067,16 @@ still in the bundle, but nothing runs.
 
 ```bash
 npm install
-npm run build     # dist/bugcatch.es.js + dist/bugcatch.umd.js
+npm run build     # every file below, into dist/ (scripts/build.mjs; the builds are in vite.config.js)
+npm run dev       # the same, rebuilt on change
 ```
+
+| File | For |
+|---|---|
+| `bugcatch.es.js` (+ `bugcatch-core.es.js`, `bugcatch-panel.es.js`, `bugcatch-call.es.js`) | Bundlers. The panel and call code are `import()`ed, so they split off. |
+| `bugcatch.umd.js` | A `<script>` tag; `window.BugCatch`. Fetches the two below from beside itself. |
+| `bugcatch-panel.umd.js`, `bugcatch-call.umd.js` | Those parts, as scripts that register themselves with it. |
+| `bugcatch.standalone.umd.js` | All of it in one file, for a page that cannot load a second one. |
+
+The build fails if the main script ends up containing either part, or if a part
+carries its own copy of something whose state belongs to the main script.