@sphoro/bugcatch-web-sdk 0.13.1 → 0.14.0

package/src/index.js

@@ -6,7 +6,7 @@ import { mountWidget } from './widget.js';
 import { uploadAttachment, normalizeMime, REPORT_MIMES } from './capture.js';
 import {
   watchUpdates, createUpdateNotifier, fetchMyReports, fetchReport, writeToken, readToken,
-  clearToken, sendMessage, callAvailable, callKindForProject, requestCall,
+  clearToken, sendMessage, verifyFix, callKindsForProject,
   reportByCall, liveCallAvailable, requestLiveCall, giveUpLiveCall,
   answerIncomingCall, declineIncomingCall,
   readUnread, rememberUpdate, forgetUpdate, forgetReportUpdates, forgetAllUpdates,
@@ -16,9 +16,9 @@ import {
 import {
   loginState, startSignIn, confirmSignIn, endSignIn, readSession, clearSession,
 } from './session.js';
-import { startVoiceCall } from './voice.js';
 import { joinLiveCall, liveCallSupported, openMicrophone } from './live-call.js';
 import { showIncomingCall } from './incoming-call.js';
+import { referenceFields } from './references.js';
 
 // Replaced at build time from package.json. The guard is for anyone importing
 // src/ directly, where the define never runs.
@@ -63,16 +63,14 @@ const DEFAULTS = {
   // reports moves. Runs whether or not the built-in notification is on; `id` is
   // what markUpdateRead() takes.
   onUpdate: null,
-  // Offer a voice call when a report is picked up, if the workspace has
+  // Offer a call to the team when a report is picked up, if the workspace has
   // sphoro.voice configured. Nothing is dialled and no permission is asked for
   // until somebody presses the button — see startCall().
   voice: true,
-  // Called as a call moves: 'connecting', 'listening', 'speaking', 'ended',
-  // 'failed'. The SDK shows nothing of its own beyond the offer, so an
-  // integration that wants a call UI builds it from this and onCallTranscript.
+  // Called as a call moves: 'ringing', 'connecting', 'connected', 'missed',
+  // 'ended', 'failed'. The SDK shows nothing of its own beyond the offer, so an
+  // integration that wants a call UI builds it from this.
   onCallState: null,
-  // Called with { role, text, final } for each line, as it is recognised.
-  onCallTranscript: null,
   // Called with { bugId, callId, from, project, reference, ringsUntil,
   // recorded } when somebody on the team rings this page about a report filed
   // from it. The SDK has already drawn the card by then — this is for a host
@@ -324,6 +322,11 @@ class BugCatchClient {
    *
    * Resolves to null when this browser cannot prove it filed that report.
    */
+  async verifyFix(bugId, { result, resolvedAt, note }) {
+    const context = result === 'STILL_HAPPENING' ? await this.#payload({}) : {};
+    return verifyFix({ apiBase: this.config.apiBase, bugId, result, resolvedAt, note, metadata: context.metadata, logs: context.logs });
+  }
+
   myReport(bugId) {
     return fetchReport({ apiBase: this.config.apiBase, bugId });
   }
@@ -349,11 +352,11 @@ class BugCatchClient {
    * Everything a report carries, however it was started.
    *
    * Shared by `report()` and by pressing Call, because the two file the same
-   * thing — the difference is only whether a person typed the title or the
-   * agent asks for it. Two copies of this would drift, and the half that
-   * drifted would be the one that stopped attaching the console.
+   * thing — the difference is only whether a person typed a title first. Two
+   * copies of this would drift, and the half that drifted would be the one that
+   * stopped attaching the console.
    */
-  async #payload({ title, description = '', priority = 'MEDIUM', metadata = {}, media = [] }) {
+  async #payload({ title, description = '', priority = 'MEDIUM', metadata = {}, media = [], references = [] }) {
     return {
       projectId: this.config.projectId,
       ...(title ? { title } : {}),
@@ -366,6 +369,9 @@ class BugCatchClient {
       reporterName: this.config.user?.name,
       metadata: {
         ...(await collectEnvironment()),
+        release: this.config.release,
+        environment: this.config.environment,
+        buildId: this.config.buildId,
         ...metadata,
         user: this.config.user || undefined,
         sdk: SDK_IDENTITY,
@@ -377,18 +383,23 @@ class BugCatchClient {
       // Omitted rather than sent empty: the field is optional server-side, and
       // an empty array in every payload makes beforeSend hooks harder to read.
       ...(media.length ? { attachments: media } : {}),
+      // What the reporter answered when asked which record this is about. Only
+      // ever what they typed into the box — never what this browser matched in
+      // their own text, which the API reads for itself out of the title and
+      // description it is being sent anyway. A payload is a claim, and there is
+      // no reason to make the join key one when the source text is right here.
+      ...(references.length ? { references } : {}),
     };
   }
 
   /**
    * File a report because somebody pressed Call instead of filling the form in.
    *
-   * Both kinds of call come through here — the triage agent and ringing the
-   * team — because filing is the half the two share, and it is the half that
-   * has to say who is filing. Held in one place after a session header went
-   * missing from this route while `report()` kept sending it: nothing looked
-   * wrong until a project switched sign-in on, and then a signed-in reporter
-   * pressing Call was told to sign in.
+   * Filing is the half a call shares with the form, and it is the half that has
+   * to say who is filing. Held in one place after a session header went missing
+   * from this route while `report()` kept sending it: nothing looked wrong until
+   * a project switched sign-in on, and then a signed-in reporter pressing Call
+   * was told to sign in.
    */
   async #fileByCall() {
     const session = readSession(this.config.projectId);
@@ -426,25 +437,23 @@ class BugCatchClient {
    * Two conditions, and both have to hold before anything is drawn. The project
    * has to have calling configured — false on most deployments — and this
    * browser has to know who the visitor is, because a call with nobody to
-   * attribute it to has no watch token to follow it with and nobody to send the
-   * transcript to afterwards. That is the same limit every other follow-up
-   * feature in this SDK has: it all hangs off `identify()`.
+   * attribute it to has no watch token to follow it with and nobody to tell
+   * afterwards what happened to the report. That is the same limit every other
+   * follow-up feature in this SDK has: it all hangs off `identify()`.
    */
   async canCallNow() {
     return Boolean(await this.callKind());
   }
 
   /**
-   * Which kind of call this visitor would get: 'agent', 'live', or null.
+   * Which kind of call this visitor would get: 'live', or null for none.
    *
    *   const kind = await BugCatch.callKind();
-   *   // 'agent' — a model answers and asks the questions the form did not
-   *   // 'live'  — the team's dashboards ring and a colleague picks up
+   *   // 'live' — the team's dashboards ring and a colleague picks up
    *
-   * A deployment offers one or the other, never both: a sphoro.voice agent has
-   * exactly one mode. Worth asking rather than assuming, because the two are
-   * wholly different promises to make to somebody — and the wording next to the
-   * button has to match which one it is.
+   * One kind, and this says whether it is on offer. It is still worth asking
+   * rather than assuming: on most deployments the answer is null, and a button
+   * promising a call nobody can place is worse than no button.
    *
    * The answer is remembered for the life of the page. It is a property of the
    * deployment's configuration rather than of this visitor, and re-asking on
@@ -452,15 +461,36 @@ class BugCatchClient {
    * about once a year.
    */
   async callKind() {
-    if (!this.config.voice) return null;
-    if (!this.config.user?.email) return null;
-    if (this.kind !== undefined) return this.kind;
-    this.kind = await callKindForProject({
+    const kinds = await this.callKinds();
+    return kinds.live ? 'live' : null;
+  }
+
+  /**
+   * The same answer as booleans: `{ agent, live }`.
+   *
+   *   const { live } = await BugCatch.callKinds();
+   *   if (live) drawCallTheTeam();
+   *
+   * `agent` is always false. It was a triage agent that answered instantly
+   * instead of a person, it is gone, and the key stays only so an integration
+   * that reads it does not get `undefined` and draw a button on it.
+   *
+   * Same round trip and same page-lifetime cache as `callKind()`. False on a
+   * deployment without sphoro.voice, on a workspace that has switched calling
+   * off, and on a visitor this SDK has no address for — a call needs somebody
+   * to attribute it to.
+   */
+  async callKinds() {
+    const none = { agent: false, live: false };
+    if (!this.config.voice) return none;
+    if (!this.config.user?.email) return none;
+    if (this.kinds !== undefined) return this.kinds;
+    this.kinds = await callKindsForProject({
       apiBase: this.config.apiBase,
       apiKey: this.config.apiKey,
       projectId: this.config.projectId,
     });
-    return this.kind;
+    return this.kinds;
   }
 
   /**
@@ -472,174 +502,98 @@ class BugCatchClient {
    * workspace that has not switched calling on, and on a report that has had
    * its allowance of calls — so an integration rendering its own affordance can
    * ask rather than guess.
+   *
+   * The same question as `canCallTeam`, which is the name the widget uses. Both
+   * are kept because both are documented, and there is one kind of call left
+   * for either of them to be asking about.
    */
   canCall(bugId) {
     if (!this.config.voice) return Promise.resolve(false);
-    return callAvailable({ apiBase: this.config.apiBase, bugId });
+    return liveCallAvailable({ apiBase: this.config.apiBase, bugId });
   }
 
   /**
-   * Talk to the triage agent.
+   * Ring the team.
    *
    *   await BugCatch.startCall(id);   // about a report already filed
    *   await BugCatch.startCall();     // instead of filling the form in
    *
-   * With a report id, it talks about that report. With none, it files one first
+   * With a report id, it rings about that report. With none, it files one first
    * — carrying the console, network and environment this SDK is already holding
-   * — and then calls about that. The report is written before the call starts
-   * either way, so a call that drops still leaves the context behind; the
-   * handle carries `bugId` so the caller can say what it was filed as.
+   * — and rings about that. The report is written before the phones ring either
+   * way, so a call nobody answers still leaves the context behind; the handle
+   * carries `bugId` so the caller can say what it was filed as.
    *
-   * Asks for the microphone, opens the call, and resolves once it is connected.
-   * What is said reaches the team as a message in the report's thread when the
-   * call ends — nobody from the team is on the line, and the agent says so.
+   * Asks for the microphone, places the call, and resolves once it is
+   * *ringing* — not once somebody answers. The handle's `onState` is how the
+   * caller follows what happens after that:
+   *
+   *   'ringing'    the team's dashboards are lighting up
+   *   'connecting' somebody answered; the two browsers are finding each other
+   *   'connected'  they can hear each other
+   *   'missed'     nobody picked up before the ringing stopped
+   *   'ended'      it is over
+   *
+   * What comes back is a conversation with a colleague: the audio travels
+   * directly between the two browsers over WebRTC and never reaches bugcatch or
+   * sphoro.voice, so it is not transcribed. The thread gets a note saying the
+   * call happened and who took it.
    *
    * Rejects if the microphone is refused, if calling is not available, or if
    * one is already running. There is deliberately no way to start a second: two
-   * microphones on one page talk over each other, and the second call would be
-   * transcribing the first. A rejection carrying `.filed` means the report was
-   * written and only the call failed.
+   * microphones on one page talk over each other. A rejection carrying `.filed`
+   * means the report was written and only the call failed.
    */
   async startCall(bugId) {
     if (!this.config.voice) throw new Error('[BugCatch] calling is switched off.');
     // Two checks, because there are two ways to already be on a call: one that
     // has connected, and one still asking for the microphone. A double-click
     // races past a check on `this.call` alone — the second press gets through
-    // while the first is still awaiting, and the page ends up with two sockets
-    // and two microphones transcribing each other.
+    // while the first is still awaiting, and the page ends up with two
+    // microphones in one conversation.
     if (this.call || this.callStarting) {
       throw new Error('[BugCatch] a call is already running.');
     }
     this.callStarting = true;
 
     try {
-      return await this.#connectCall(bugId);
+      // Whether this deployment can place a call at all, asked before the
+      // microphone prompt and before anything is filed. Without it a press from
+      // a visitor with no address, or on a project with calling off, filed a
+      // report anyway — and the reporter, promised a call, got a ticket and a
+      // phone that never rang.
+      if (!await this.callKind()) {
+        throw new Error(this.config.user?.email
+          ? '[BugCatch] calling is not available on this project.'
+          : '[BugCatch] a call needs to know who is calling — call identify() with an email first.');
+      }
+      return await this.#ringTheTeam(bugId);
     } finally {
       this.callStarting = false;
     }
   }
 
-  /** The body of startCall, so the in-flight flag is cleared on every path. */
-  async #connectCall(bugId) {
-    // Which kind of call this deployment actually offers, asked before anything
-    // is filed. `startCall` is the one entry point most integrations use — the
-    // widget's own button included — so it has to land on whichever kind the
-    // agent is, rather than on the one this method was originally written for.
-    //
-    // Without this the agent path ran against a person-to-person agent: the call
-    // came back *ringing*, the API refused it rather than connect a reporter to a
-    // rendezvous over the µ-law agent protocol, and all the reporter saw was a
-    // report they had not meant to file.
-    if (await this.callKind() === 'live') return this.#ringTheTeam(bugId);
-
-    let realtimeUrl;
-    let filed = null;
-
-    if (bugId) {
-      ({ realtime_url: realtimeUrl } = await requestCall({
-        apiBase: this.config.apiBase, bugId,
-      }));
-    } else {
-      // No report yet: this is somebody who pressed Call instead of filling the
-      // form in. One round trip files what the page was doing and starts the
-      // call about it, so a call that never connects still leaves the context
-      // behind.
-      filed = await this.#fileByCall();
-      bugId = filed.id;
-      realtimeUrl = filed.realtime_url;
-      if (!realtimeUrl) {
-        // Filed, but no call. Reported as such rather than thrown: the report
-        // exists and the caller has to be able to say so.
-        const err = new Error('[BugCatch] the report was filed, but no call could be started.');
-        err.filed = filed;
-        throw err;
-      }
-    }
-
-    const handle = await startVoiceCall({
-      realtimeUrl,
-      onState: (state, detail) => {
-        if (state === 'ended' || state === 'failed') this.call = null;
-        if (typeof this.config.onCallState === 'function') {
-          this.config.onCallState(state, { bugId, ...detail });
-        }
-        this.emit('call', { bugId, state, ...detail });
-      },
-      onTranscript: (line) => {
-        if (typeof this.config.onCallTranscript === 'function') {
-          this.config.onCallTranscript({ bugId, ...line });
-        }
-        this.emit('call-transcript', { bugId, ...line });
-      },
-    });
-
-    // Set after the await, not before: a call that never connected is not one
-    // this page is on, and leaving the slot taken would block the retry.
-    this.call = handle;
-    // `bugId` on the handle so a caller that did not name one — the Call
-    // button — can tell the reporter what their report is called.
-    return Object.assign(handle, { bugId, filed });
-  }
-
   /**
-   * Talk to a person on the team.
+   * Ring the team, under the name an integration may already be calling.
    *
    *   await BugCatch.startLiveCall(id);
    *
-   * The other kind of call. `startCall` reaches the triage agent, which answers
-   * instantly and asks the three questions the form did not; this rings the
-   * team, and whoever is free picks it up. What comes back is a conversation
-   * with a colleague — the audio travels directly between the two browsers over
-   * WebRTC and never reaches bugcatch or sphoro.voice, so it is not recorded and
-   * not transcribed. The thread gets a note saying it happened and who took it.
-   *
-   * Resolves once the call is *ringing*, not once somebody answers — the
-   * handle's `onState` is how the caller follows what happens next:
-   *
-   *   'ringing'    the team's dashboards are lighting up
-   *   'connecting' somebody answered; the two browsers are finding each other
-   *   'connected'  they can hear each other
-   *   'missed'     nobody picked up before the ringing stopped
-   *   'ended'      it is over
-   *
-   * 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
-   * about — and the agent call's trick of filing first and taking a title from
-   * the transcript is not available here, because there is no transcript.
-   *
-   * 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, and two calls on it would talk over each other.
+   * Exactly `startCall`, which is now the only call there is. The id is
+   * optional here too: it was required while this was one of two kinds, because
+   * the other one was the only way to call without a report to call about.
    */
-  async startLiveCall(bugId) {
-    if (!this.config.voice) throw new Error('[BugCatch] calling is switched off.');
-    if (!bugId) throw new Error('[BugCatch] startLiveCall needs the id of a filed report.');
-    if (!liveCallSupported()) {
-      throw new Error('[BugCatch] this browser cannot make live calls.');
-    }
-    // The same two checks `startCall` makes, against the same slot, because the
-    // two kinds of call compete for the same microphone — a live call started
-    // while the agent is mid-sentence would be two conversations in one room.
-    if (this.call || this.callStarting) {
-      throw new Error('[BugCatch] a call is already running.');
-    }
-    this.callStarting = true;
-
-    try {
-      return await this.#ringTheTeam(bugId);
-    } finally {
-      this.callStarting = false;
-    }
+  startLiveCall(bugId) {
+    return this.startCall(bugId);
   }
 
-  /** The body of startLiveCall, so the in-flight flag clears on every path. */
+  /** The body of startCall, so the in-flight flag clears on every path. */
   async #ringTheTeam(bugId) {
     // Before the call is placed, not after. A permission prompt takes as long
     // as the person takes to read it, and asking afterwards would have a room
     // full of dashboards ringing about a call its own caller may yet refuse to
     // be on. That ordering is why the report below is filed *after* the
-    // microphone too, even though filing it first is what the agent path does:
-    // on this kind of call, filing is what makes the phones ring.
+    // microphone too, rather than first as the form does: filing is what makes
+    // the phones ring.
     if (!liveCallSupported()) {
       throw new Error('[BugCatch] this browser cannot make live calls.');
     }
@@ -652,16 +606,18 @@ class BugCatchClient {
         started = await requestLiveCall({ apiBase: this.config.apiBase, bugId });
       } else {
         // Nobody filled the form in. One round trip writes what the page was
-        // doing and rings the team about it — the same trade the agent path
-        // makes, so a call nobody answers still leaves the context behind.
+        // doing and rings the team about it, so a call nobody answers still
+        // leaves the context behind.
         filed = await this.#fileByCall();
         bugId = filed.id;
         started = filed.live_call;
         if (!started?.realtime_url) {
           // Filed, but nobody rang. Reported as such rather than thrown, so the
           // caller can say what the report is called instead of losing it.
-          const err = new Error('[BugCatch] the report was filed, but the team could not be rung.');
+          const err = new Error(`[BugCatch] the report was filed, but the team could not be rung${
+            filed.call_error ? `: ${filed.call_error}` : '.'}`);
           err.filed = filed;
+          err.reason = filed.call_error || null;
           throw err;
         }
       }
@@ -689,9 +645,8 @@ class BugCatchClient {
       },
     });
 
-    // Set after the await, exactly as the agent path does: a call that never
-    // connected is not one this page is on, and leaving the slot taken would
-    // block the retry.
+    // Set after the await, not before: a call that never connected is not one
+    // this page is on, and leaving the slot taken would block the retry.
     this.call = handle;
     return Object.assign(handle, { bugId, callId: started.call_id, live: true, filed });
   }
@@ -935,6 +890,7 @@ class BugCatchClient {
   /** File a bug with everything captured so far. */
   async report({
     title, description = '', priority = 'MEDIUM', metadata = {}, attachments = [],
+    references = [],
   } = {}) {
     if (!this.started) throw new Error('[BugCatch] call init() first.');
     if (!title || !title.trim()) throw new Error('[BugCatch] a title is required.');
@@ -952,7 +908,9 @@ class BugCatchClient {
         mime: normalizeMime(a.mime, REPORT_MIMES),
       }));
 
-    let payload = await this.#payload({ title: title.trim(), description, priority, metadata, media });
+    let payload = await this.#payload({
+      title: title.trim(), description, priority, metadata, media, references,
+    });
 
     if (typeof this.config.beforeSend === 'function') {
       const result = this.config.beforeSend(payload);
@@ -1027,6 +985,31 @@ class BugCatchClient {
     });
   }
 
+  /**
+   * What this project needs in order to look a report up, and how it asks.
+   *
+   *   const { policy, fields } = await BugCatch.referenceFields();
+   *   // policy: 'off' | 'optional' | 'required'
+   *
+   * The widget calls this itself when it opens, and caches the answer for the
+   * life of the page: unlike the sign-in state, this cannot change underneath a
+   * reporter in a way that matters — an admin editing the field list mid-report
+   * costs one stale question, not a failed send.
+   *
+   * Here for the same reason loginState() is: an integration running with
+   * `widget: false` draws its own form and needs the same answer to know
+   * whether that form should have an identifier box on it.
+   */
+  referenceFields() {
+    if (this.refFields) return this.refFields;
+    this.refFields = referenceFields({
+      apiBase: this.config.apiBase,
+      apiKey: this.config.apiKey,
+      projectId: this.config.projectId,
+    });
+    return this.refFields;
+  }
+
   /**
    * Who this browser is signed in as on this project, from storage alone.
    *

package/src/references.js

@@ -0,0 +1,172 @@
+/**
+ * Reading the reporter's own text for something that identifies their record.
+ *
+ * A browser-side twin of bugcatch-api/src/settings/reference-extract.ts, and
+ * deliberately only the half this side needs. The server does the extraction
+ * that counts — what a payload claims it found is not evidence, and the value
+ * an investigation eventually joins on is the one the API read out of the text
+ * it stored. This copy exists to answer one question, locally and instantly:
+ *
+ *   does what this person has already typed contain an identifier, or do we
+ *   have to interrupt them for one?
+ *
+ * Getting that wrong in the lenient direction costs an unnecessary question.
+ * Getting it wrong in the strict direction means asking a reporter who has
+ * already told us, in the sentence above the box, which is the fastest way to
+ * make somebody close a bug reporter and not come back. So the matching rule
+ * here is the same rule, run over the same patterns, which the API ships with
+ * the field list precisely so that both sides can agree.
+ *
+ * The patterns arrive over the wire and are compiled here. That is a thing to
+ * be deliberate about rather than nervous about: they are shapes, not secrets —
+ * "a loan number looks like LN- followed by digits" is not a fact worth hiding
+ * from somebody already looking at their own loan number — and the alternative
+ * is a round trip per keystroke or a question for everybody.
+ */
+
+const MAX_SCAN_CHARS = 20000;
+const MAX_VALUE_CHARS = 120;
+const MAX_MATCHES = 200;
+
+/**
+ * Compile, or null.
+ *
+ * Null on anything that will not compile, which in a browser is a real case
+ * rather than a defensive one: a regex feature one engine lacks throws here
+ * rather than failing to match. A field that cannot be compiled is simply not
+ * scanned, the reporter gets asked, and the server — which compiled it fine —
+ * still reads the text. Degrading to the question is the whole design.
+ */
+function compile(source) {
+  if (typeof source !== 'string' || !source.trim() || source.length > 400) return null;
+  try {
+    return new RegExp(source.trim(), 'gi');
+  } catch {
+    return null;
+  }
+}
+
+const tidy = (value) => String(value).replace(/\s+/g, ' ').trim().slice(0, MAX_VALUE_CHARS);
+
+/** Group 1 where the pattern has one, the whole match otherwise. */
+function valueOf(match) {
+  const raw = match.length > 1 && match[1] !== undefined ? match[1] : match[0];
+  if (typeof raw !== 'string' || !raw.trim()) return null;
+  // The span claimed is the whole match, never the capture: a labelled rule has
+  // eaten the words in front of the value too, and leaving them unclaimed lets
+  // a later field match them again.
+  return { value: tidy(raw), start: match.index, end: match.index + match[0].length };
+}
+
+/**
+ * Every configured identifier found in the given text.
+ *
+ * Fields are taken in the order the project arranged them and a span an earlier
+ * field claimed is not offered to a later one — which is what keeps the rule for
+ * "alternate number" and the rule for "mobile number", which match the same ten
+ * digits, from both claiming it.
+ */
+export function matchReferences(fields, texts) {
+  const found = [];
+  const seen = new Set();
+
+  for (const block of texts || []) {
+    const text = typeof block === 'string' ? block.slice(0, MAX_SCAN_CHARS) : '';
+    if (!text) continue;
+
+    const claimed = [];
+    const overlaps = (a, b) => claimed.some(([s, e]) => a < e && b > s);
+
+    for (const field of fields || []) {
+      if (!field || field.scan === false) continue;
+      const re = compile(field.pattern);
+      if (!re) continue;
+
+      let match;
+      let guard = 0;
+      re.lastIndex = 0;
+      while ((match = re.exec(text)) !== null) {
+        if (++guard > MAX_MATCHES) break;
+        // exec does not advance past a zero-width match, so this would spin.
+        if (match[0] === '') { re.lastIndex += 1; continue; }
+
+        const hit = valueOf(match);
+        if (hit && !overlaps(hit.start, hit.end)) {
+          claimed.push([hit.start, hit.end]);
+          const dedupe = `${field.key}:${hit.value.toLowerCase()}`;
+          if (!seen.has(dedupe)) {
+            seen.add(dedupe);
+            found.push({ key: field.key, label: field.label, value: hit.value });
+          }
+        }
+      }
+    }
+  }
+
+  return found;
+}
+
+/**
+ * Whether what somebody typed into the box is the shape that field asks for.
+ *
+ * Anchored, unlike the scan above: reading prose means finding a value inside a
+ * sentence, and checking an answer means the answer *is* the value. `valuePattern`
+ * where the field has one — a rule that finds "alternate number: 98…" in prose
+ * needs the words, and a box already headed "Alternate number" will not have
+ * them typed into it again.
+ *
+ * Returns the tidied value, or null. Advisory only: the widget uses it to say
+ * "that does not look like a loan number" before sending, and the API keeps a
+ * value that fails it rather than dropping what the reporter believes is their
+ * reference.
+ */
+export function validateReference(field, raw) {
+  const value = typeof raw === 'string' ? raw.trim() : '';
+  if (!value || value.length > MAX_VALUE_CHARS) return null;
+
+  const re = compile(field && (field.valuePattern || field.pattern));
+  if (!re) return null;
+
+  let match;
+  let guard = 0;
+  re.lastIndex = 0;
+  while ((match = re.exec(value)) !== null) {
+    if (++guard > MAX_MATCHES) break;
+    if (match[0] === '') { re.lastIndex += 1; continue; }
+    // One character of slack at the front and only there, for a pattern whose
+    // left boundary consumes rather than looks behind — see the phone rule,
+    // written that way so it compiles in older Safari.
+    const toEnd = match.index + match[0].length === value.length;
+    const atEdge = match.index === 0 || match.index === 1;
+    if (toEnd && atEdge) {
+      const hit = valueOf(match);
+      if (hit) return hit.value;
+    }
+  }
+  return null;
+}
+
+/**
+ * What this project needs in order to look a report up.
+ *
+ * Every failure answers `{ policy: 'off', fields: [] }`, which is the answer
+ * that draws nothing. A widget that could not reach this route must not be a
+ * widget that refuses to send a report — the whole feature is a help, and the
+ * server reads the text either way.
+ */
+export async function referenceFields({ apiBase, apiKey, projectId }) {
+  const off = { policy: 'off', fields: [] };
+  try {
+    const res = await fetch(
+      `${apiBase}/ingest/reference-fields?projectId=${encodeURIComponent(projectId)}`,
+      { headers: { 'X-BugCatch-Key': apiKey } },
+    );
+    if (!res.ok) return off;
+    const body = await res.json();
+    const policy = body.policy === 'optional' || body.policy === 'required' ? body.policy : 'off';
+    const fields = Array.isArray(body.fields) ? body.fields : [];
+    return fields.length ? { policy, fields } : off;
+  } catch {
+    return off;
+  }
+}