@sphoro/bugcatch-web-sdk 0.17.0 → 0.18.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.18.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.
@@ -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"?`).
@@ -406,6 +423,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 +451,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
@@ -815,6 +834,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 +1015,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 +1034,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.