@sphoro/bugcatch-web-sdk 0.13.1 → 0.14.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sphoro/bugcatch-web-sdk",
-  "version": "0.13.1",
+  "version": "0.14.1",
   "description": "Drop-in browser SDK — report bugs with console, network and environment context, without the extension.",
   "type": "module",
   "main": "dist/bugcatch.es.js",

package/src/drafts.js

@@ -0,0 +1,32 @@
+// Drafts are scoped to the API, project and reporter. Never store credentials.
+const MAX_AGE = 7 * 24 * 60 * 60 * 1000;
+let database;
+function open() {
+  if (!database) database = new Promise((resolve, reject) => {
+    const request = indexedDB.open('bugcatch-drafts', 1);
+    request.onupgradeneeded = () => request.result.createObjectStore('drafts');
+    request.onsuccess = () => resolve(request.result);
+    request.onerror = () => reject(request.error);
+    request.onblocked = () => reject(new Error('Draft storage is blocked.'));
+  }).catch((err) => { database = null; throw err; });
+  return database;
+}
+export function draftKey(config, email) {
+  return JSON.stringify([config.apiBase, config.projectId, email || config.user?.email || config.user?.id || 'anonymous']);
+}
+export async function draftOperation(key, value) {
+  const db = await open();
+  return new Promise((resolve, reject) => {
+    const tx = db.transaction('drafts', value === undefined ? 'readonly' : 'readwrite');
+    const store = tx.objectStore('drafts');
+    const request = value === undefined ? store.get(key) : value === null ? store.delete(key) : store.put({ ...value, savedAt: Date.now() }, key);
+    tx.oncomplete = () => resolve(request.result);
+    tx.onerror = () => reject(tx.error);
+    tx.onabort = () => reject(tx.error || new Error('Draft was not saved.'));
+  });
+}
+export async function readDraft(key) {
+  const value = await draftOperation(key);
+  if (value && Date.now() - value.savedAt > MAX_AGE) { await draftOperation(key, null); return null; }
+  return value || null;
+}

package/src/index.d.ts

@@ -53,6 +53,11 @@ export interface JoinedIssue {
 }
 
 export interface BugCatchConfig {
+  /** Recover unfinished widget reports on this device for seven days. Default true. */
+  drafts?: boolean;
+  release?: string;
+  environment?: string;
+  buildId?: string;
   apiBase?: string;
   apiKey: string;
   projectId: string;
@@ -116,15 +121,13 @@ export interface BugCatchConfig {
    */
   voice?: boolean;
   /**
-   * Called as a call of either kind moves between states. `detail.live` marks
-   * the ones about a call to a person; their states come from LiveCallState.
+   * Called as a call moves between states. `detail.incoming` marks a call the
+   * team placed to this page rather than one started from it.
    */
   onCallState?: ((
-    state: CallState | LiveCallState,
-    detail: { bugId: string; live?: boolean; reason?: string },
+    state: LiveCallState,
+    detail: { bugId: string; live?: boolean; incoming?: boolean; reason?: string },
   ) => void) | null;
-  /** Called with each line of a call, as it is recognised. */
-  onCallTranscript?: ((line: CallTranscriptLine) => void) | null;
   /**
    * Called when somebody on the team rings this page about a report filed from
    * it — the one call this SDK does not start.
@@ -171,43 +174,18 @@ export type IncomingCallState =
   'ringing' | 'answered' | 'declined' | 'missed' | 'failed';
 
 /**
- * Where a call is. `listening` means the reporter's turn, `speaking` the
- * agent's; `ended` and `failed` are both final and release the microphone.
- */
-export type CallState = 'connecting' | 'listening' | 'speaking' | 'ended' | 'failed';
-
-/**
- * Where a *live* call is — one to a person on the team rather than to the
- * agent. A separate vocabulary because the two have almost nothing in common:
- * an agent call is never `ringing` because a model does not keep anybody
- * waiting, and a live call is never `listening` or `speaking`, because nobody
- * is transcribing it to know whose turn it is.
+ * Where a call is.
  *
- * `missed` is final and ordinary: the ringing stopped before anybody picked up.
+ * It starts `ringing`, because a call reaches a room of people rather than
+ * something that answers instantly. `missed` means the ringing stopped before
+ * anybody picked up — final, and ordinary rather than a failure. `ended`,
+ * `missed` and `failed` all release the microphone.
  */
 export type LiveCallState =
   'ringing' | 'connecting' | 'connected' | 'ended' | 'missed' | 'failed';
 
-export interface CallTranscriptLine {
-  bugId: string;
-  /** Who said it. `agent` lines arrive as deltas; `final` marks the end of a turn. */
-  role: 'reporter' | 'agent';
-  text: string;
-  final: boolean;
-}
-
-/** A call in progress. */
-/** Which kind of call a deployment offers. One agent has one mode, so never both. */
-export type CallKind = 'agent' | 'live';
-
-export interface CallHandle {
-  /** End it. Safe to call twice, and after it has already ended. */
-  hangUp(): void;
-  /** The report this call is about, whether it was named or filed on the way in. */
-  bugId: string;
-  /** What was filed, when the call is the reason the report exists. */
-  filed?: { id: string; watchToken?: string } | null;
-}
+/** Which kind of call a deployment offers. One kind: a person on the team. */
+export type CallKind = 'live';
 
 export interface LiveCallHandle {
   /** End it. Safe to call twice, and after it has already ended. */
@@ -221,11 +199,13 @@ export interface LiveCallHandle {
    */
   setMuted(muted: boolean): boolean;
   isMuted(): boolean;
-  /** The report this call is about. */
+  /** The report this call is about, whether it was named or filed on the way in. */
   bugId: string;
   /** sphoro.voice's id for the call, as the team's dashboard also knows it. */
   callId: string;
   live: true;
+  /** What was filed, when the call is the reason the report exists. */
+  filed?: { id: string; watchToken?: string } | null;
 }
 
 export interface Attachment {
@@ -241,6 +221,56 @@ export interface ReportInput {
   metadata?: Record<string, any>;
   /** Already uploaded via uploadAttachment(). Entries without a key are dropped. */
   attachments?: Attachment[];
+  /**
+   * What identifies the record this report is about — a loan number, a customer
+   * id, the mobile number the account is registered under.
+   *
+   * `key` names one of the kinds this project has configured; see
+   * `referenceFields()`. Only supply what the person actually told you: the API
+   * reads the title and description for identifiers itself, and does so on its
+   * own side rather than trusting what a page claims to have found.
+   *
+   * The built-in widget fills this in from the question it asks at Send. It is
+   * here for integrations running with `widget: false`, which draw their own
+   * form and must ask their own version of that question.
+   */
+  references?: ReportReference[];
+}
+
+export interface ReportReference {
+  key: string;
+  value: string;
+}
+
+/** How a project asks reporters to identify the record a report is about. */
+export type ReferencePolicy = 'off' | 'optional' | 'required';
+
+/**
+ * One kind of identifier this project recognises.
+ *
+ * `pattern` is a regex source with no delimiters and no flags, matched
+ * case-insensitively. Where it has a capture group, group 1 is the value; where
+ * it has none, the whole match is. `valuePattern`, when present, is the shape of
+ * the value on its own — used to check something typed into a box rather than
+ * found in a sentence.
+ */
+export interface ReferenceField {
+  key: string;
+  label: string;
+  hint: string;
+  placeholder: string;
+  inputMode: 'text' | 'email' | 'tel' | 'numeric';
+  pattern: string;
+  valuePattern: string | null;
+  /** Whether this kind may be read out of the report's own text. */
+  scan: boolean;
+  /** Whether this is one of the kinds that satisfies a `required` policy. */
+  required: boolean;
+}
+
+export interface ReferenceConfig {
+  policy: ReferencePolicy;
+  fields: ReferenceField[];
 }
 
 /**
@@ -434,10 +464,9 @@ export declare class BugCatchClient {
   on(
     event: 'call',
     handler: (detail: {
-      bugId: string; state: CallState | LiveCallState; live?: boolean; reason?: string;
+      bugId: string; state: LiveCallState; live?: boolean; incoming?: boolean; reason?: string;
     }) => void,
   ): () => void;
-  on(event: 'call-transcript', handler: (line: CallTranscriptLine) => void): () => void;
   /**
    * A call the team placed to this page, as it moves. Separate from `call`,
    * which is the conversation once one is connected — this is the telephone
@@ -466,7 +495,7 @@ export declare class BugCatchClient {
   on(event: 'signout', handler: (who: { email: string | null }) => void): () => void;
   off(event: 'update', handler: (update: ReportUpdate) => void): this;
   off(
-    event: 'call' | 'call-transcript' | 'unread' | 'incoming-call' | 'signin' | 'signout',
+    event: 'call' | 'unread' | 'incoming-call' | 'signin' | 'signout',
     handler: (payload: any) => void,
   ): this;
   /**
@@ -475,6 +504,17 @@ export declare class BugCatchClient {
    * for integrations running with `widget: false`.
    */
   loginState(): Promise<SdkLoginState>;
+  /**
+   * What this project needs in order to look a report up, and how it asks.
+   *
+   * `{ policy: 'off', fields: [] }` on every project that has not configured
+   * this, and on every failure to reach the API — a widget that cannot ask the
+   * question must never be a widget that refuses to send the report.
+   *
+   * Cached for the life of the page. The built-in widget calls this itself; it
+   * is here for integrations running with `widget: false`.
+   */
+  referenceFields(): Promise<ReferenceConfig>;
   /**
    * Who this browser is signed in as, from storage alone — no request, and
    * therefore only as current as the last one. A session ended elsewhere still
@@ -533,66 +573,65 @@ export declare class BugCatchClient {
   /**
    * Which kind of call this visitor would get, or null for none.
    *
-   * `'agent'` is the triage agent: a model answers instantly and asks the
-   * questions the form did not. `'live'` rings the team and a colleague picks
-   * up. A deployment offers one or the other and never both — the agent behind
-   * it has exactly one mode — so this is what to word a button from.
+   * `'live'` rings the team and a colleague picks up, which is the only kind
+   * there is. Null on most deployments, which is what to hide a button on.
    *
    * Remembered for the life of the page: it describes the deployment's
    * configuration, not this visitor.
    */
   callKind(): Promise<CallKind | null>;
   /**
-   * Talk a report through. Asks for the microphone, places the call, and
-   * resolves once it is up.
+   * The same answer as booleans.
+   *
+   * `agent` is always false: it was a triage agent that answered instead of a
+   * person, and it is gone. The key stays so an integration reading it gets
+   * `false` rather than `undefined`.
+   *
+   * Same round trip and same page-lifetime cache as `callKind()`.
+   */
+  callKinds(): Promise<{ agent: false; live: boolean }>;
+  /**
+   * Ring the team about a report. Asks for the microphone, places the call, and
+   * resolves once it is *ringing* — not once somebody answers. Follow the rest
+   * through `onCallState` or the `call` event.
    *
-   * Lands on whichever kind of call this deployment offers, which is decided by
-   * the mode of its agent rather than by the method you called: against a
-   * person-to-person agent this rings the team, and the handle comes back with
-   * `live: true`. Ask `callKind()` first if the wording around your own button
-   * has to say which.
+   * The audio goes directly between the two browsers over WebRTC, so a call is
+   * not transcribed; the report's thread gets a note saying it happened.
    *
    * Rejects if the microphone is refused, if calling is not available on this
    * report, or if a call is already running — there is deliberately no way to
    * start a second.
    */
-  startCall(bugId: string): Promise<CallHandle | LiveCallHandle>;
+  startCall(bugId: string): Promise<LiveCallHandle>;
   /**
-   * The same, with no report yet: files one from the captured context and calls
-   * about it. The handle carries the id it was filed as. A rejection with
-   * `.filed` set means the report was written and only the call failed.
+   * The same, with no report yet: files one from the captured context and rings
+   * the team about it. The handle carries the id it was filed as. A rejection
+   * with `.filed` set means the report was written and only the call failed.
    */
-  startCall(): Promise<CallHandle | LiveCallHandle>;
+  startCall(): Promise<LiveCallHandle>;
   /**
    * Whether this report can be talked through with a person on the team.
    *
-   * Never true at the same time as `canCall`: one agent has one mode, so a
-   * deployment answers for the triage agent or for a live call, not both.
+   * The same question as `canCall`, under the name the widget uses: there is
+   * one kind of call, so there is one answer.
    */
   canCallTeam(bugId: string): Promise<boolean>;
   /**
-   * Ring the team about a report, and hand back the call.
+   * Ring the team — exactly `startCall`, under the name an integration written
+   * when there were two kinds of call is already using.
    *
-   * Resolves once it is *ringing*, not once somebody answers — follow the rest
-   * through `onCallState` or the `call` event. The audio goes directly between
-   * the two browsers over WebRTC, so a live call is not recorded and not
-   * transcribed; the report's thread gets a note saying it happened.
-   *
-   * A report id is required, unlike `startCall`: ringing a room about a report
-   * nobody can read would ask somebody to answer a call they know nothing
+   * The id is optional here too. It was required while this was one of two
+   * kinds, because the other was the only way to call with no report to call
    * about.
-   *
-   * Rejects if the microphone is refused, if live calling is not available on
-   * this report, or if a call of either kind is already running — this page has
-   * one microphone.
    */
-  startLiveCall(bugId: string): Promise<LiveCallHandle>;
+  startLiveCall(bugId?: string): Promise<LiveCallHandle>;
   /**
-   * End the call in progress, of either kind. Does nothing when there is not
-   * one — there is a single slot, because there is a single microphone.
+   * End the call in progress. Does nothing when there is not one — there is a
+   * single slot, because there is a single microphone.
    */
   endCall(): this;
   /** One report with its full timeline, or null if this browser cannot prove it filed it. */
+  verifyFix(bugId: string, feedback: { result: 'CONFIRMED' | 'STILL_HAPPENING'; resolvedAt: string; note?: string }): Promise<{ verification: string; status: string }>;
   myReport(bugId: string): Promise<ReportDetail | null>;
   /**
    * Write back on a report this browser filed. The widget's own conversation