@sphoro/bugcatch-web-sdk 0.13.1

package/src/collectors.js

@@ -0,0 +1,213 @@
+// Ring-buffered capture of the things you wish you had when a bug comes in:
+// console output, failed/slow requests, unhandled errors, and the environment.
+//
+// Everything is bounded — a long-lived page must not grow memory without limit.
+
+import { redactUrl, redactText } from './redact.js';
+
+export function createRingBuffer(limit) {
+  const items = [];
+  return {
+    push(item) {
+      items.push(item);
+      if (items.length > limit) items.splice(0, items.length - limit);
+    },
+    all: () => items.slice(),
+    clear: () => { items.length = 0; },
+    get size() { return items.length; },
+  };
+}
+
+const LEVELS = ['log', 'info', 'warn', 'error', 'debug'];
+
+/** Wraps console.* and records what goes through, then calls the original. */
+export function installConsoleCapture(buffer, { levels = ['warn', 'error', 'log', 'info'] } = {}) {
+  const originals = {};
+  for (const level of LEVELS) {
+    originals[level] = console[level];
+    if (!levels.includes(level)) continue;
+    console[level] = (...args) => {
+      try {
+        buffer.push({
+          level,
+          text: args.map(stringify).join(' ').slice(0, 2000),
+          at: new Date().toISOString(),
+        });
+      } catch { /* capture must never break the page */ }
+      originals[level].apply(console, args);
+    };
+  }
+  return () => { for (const level of LEVELS) console[level] = originals[level]; };
+}
+
+/**
+ * Records fetch + XHR: url, method, status, duration. Bodies are never read,
+ * which leaves the URL as the only place a credential can arrive — so every
+ * entry goes through redact.js on the way into the buffer.
+ */
+export function installNetworkCapture(buffer, { slowMs = 2000 } = {}) {
+  const originalFetch = window.fetch;
+  const originalOpen = XMLHttpRequest.prototype.open;
+  const originalSend = XMLHttpRequest.prototype.send;
+
+  if (originalFetch) {
+    window.fetch = async function patchedFetch(...args) {
+      const started = performance.now();
+      const url = typeof args[0] === 'string' ? args[0] : args[0]?.url;
+      const method = args[1]?.method || (typeof args[0] === 'object' ? args[0]?.method : 'GET') || 'GET';
+      try {
+        const res = await originalFetch.apply(this, args);
+        record(buffer, { url, method, status: res.status, ms: Math.round(performance.now() - started), slowMs });
+        return res;
+      } catch (err) {
+        record(buffer, { url, method, status: 0, error: String(err?.message || err), ms: Math.round(performance.now() - started), slowMs });
+        throw err;
+      }
+    };
+  }
+
+  XMLHttpRequest.prototype.open = function patchedOpen(method, url, ...rest) {
+    this.__bc = { method, url, started: 0 };
+    return originalOpen.call(this, method, url, ...rest);
+  };
+  XMLHttpRequest.prototype.send = function patchedSend(...args) {
+    if (this.__bc) {
+      this.__bc.started = performance.now();
+      this.addEventListener('loadend', () => {
+        record(buffer, {
+          url: this.__bc.url,
+          method: this.__bc.method,
+          status: this.status,
+          ms: Math.round(performance.now() - this.__bc.started),
+          slowMs,
+        });
+      });
+    }
+    return originalSend.apply(this, args);
+  };
+
+  return () => {
+    if (originalFetch) window.fetch = originalFetch;
+    XMLHttpRequest.prototype.open = originalOpen;
+    XMLHttpRequest.prototype.send = originalSend;
+  };
+}
+
+function record(buffer, { url, method, status, ms, error, slowMs }) {
+  try {
+    buffer.push({
+      // Scrubbed before it is buffered, not before it is sent: a credential
+      // that never enters the ring buffer cannot leave with a report, and
+      // cannot be read back out of memory by the page either. Redact first,
+      // then truncate — truncating first would split a token into something
+      // no pattern recognises, and the fragment would still be a fragment of
+      // a live credential.
+      url: redactUrl(String(url)).slice(0, 500),
+      method,
+      status,
+      ms,
+      error: error === undefined ? undefined : redactText(error),
+      // Flagged so triage can spot the interesting rows without reading everything.
+      failed: status === 0 || status >= 400,
+      slow: ms >= slowMs,
+      at: new Date().toISOString(),
+    });
+  } catch { /* ignore */ }
+}
+
+/** Unhandled errors and rejections, appended to the console buffer. */
+export function installErrorCapture(buffer) {
+  const onError = (event) => {
+    // Browsers already prefix event.message with "Uncaught" — don't say it twice.
+    const message = String(event.message || 'Error');
+    const where = event.filename ? ` (${event.filename}:${event.lineno}:${event.colno})` : '';
+    buffer.push({
+      level: 'error',
+      text: (/^uncaught/i.test(message) ? message : `Uncaught ${message}`) + where,
+      at: new Date().toISOString(),
+    });
+  };
+  const onRejection = (event) => {
+    buffer.push({
+      level: 'error',
+      text: `Unhandled rejection: ${stringify(event.reason)}`,
+      at: new Date().toISOString(),
+    });
+  };
+  window.addEventListener('error', onError);
+  window.addEventListener('unhandledrejection', onRejection);
+  return () => {
+    window.removeEventListener('error', onError);
+    window.removeEventListener('unhandledrejection', onRejection);
+  };
+}
+
+/**
+ * Battery needs the async Battery Status API, so environment collection is
+ * async now. Unsupported browsers (Safari, Firefox) simply omit the fields.
+ */
+export async function collectEnvironment() {
+  const base = collectEnvironmentSync();
+  try {
+    if (navigator.getBattery) {
+      const b = await navigator.getBattery();
+      base.battery = Math.round(b.level * 100);
+      base.charging = b.charging;
+    }
+  } catch { /* not available — leave the fields out */ }
+  return base;
+}
+
+export function collectEnvironmentSync() {
+  const nav = window.navigator || {};
+  return {
+    userAgent: nav.userAgent,
+    platform: nav.platform,
+    language: nav.language,
+    languages: nav.languages ? [...nav.languages] : null,
+    online: nav.onLine,
+    cookieEnabled: nav.cookieEnabled,
+    maxTouchPoints: nav.maxTouchPoints ?? null,
+    viewport: { width: window.innerWidth, height: window.innerHeight },
+    screen: {
+      width: window.screen?.width,
+      height: window.screen?.height,
+      availWidth: window.screen?.availWidth,
+      availHeight: window.screen?.availHeight,
+      colorDepth: window.screen?.colorDepth,
+      orientation: window.screen?.orientation?.type || null,
+    },
+    devicePixelRatio: window.devicePixelRatio,
+    referrer: document.referrer || null,
+    title: document.title,
+    capturedAt: new Date().toISOString(),
+    timezone: Intl.DateTimeFormat().resolvedOptions().timeZone,
+    timezoneOffsetMinutes: new Date().getTimezoneOffset(),
+    // A hint, not a guarantee: `webdriver` is the only broadly-available signal
+    // that something other than a person is driving the page.
+    browserMode: nav.webdriver ? 'Automated' : 'Normal',
+    doNotTrack: nav.doNotTrack || null,
+    hardwareConcurrency: nav.hardwareConcurrency ?? null,
+    deviceMemory: nav.deviceMemory ?? null,
+    connection: nav.connection
+      ? {
+          effectiveType: nav.connection.effectiveType,
+          downlink: nav.connection.downlink,
+          rtt: nav.connection.rtt,
+          saveData: nav.connection.saveData,
+        }
+      : null,
+    prefersColorScheme: window.matchMedia?.('(prefers-color-scheme: dark)').matches ? 'dark' : 'light',
+    prefersReducedMotion: window.matchMedia?.('(prefers-reduced-motion: reduce)').matches || false,
+  };
+}
+
+function stringify(value) {
+  if (typeof value === 'string') return value;
+  if (value instanceof Error) return `${value.name}: ${value.message}`;
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return String(value);
+  }
+}

package/src/incoming-call.js

@@ -0,0 +1,324 @@
+// The reporter's telephone.
+//
+// Everything else this SDK draws is a consequence of something the person on
+// the page did: they pressed the widget, they filed a report, they asked to
+// talk it through. This is the one thing that arrives unasked — a member of the
+// team has a question about a report and is ringing to ask it — and that makes
+// it the piece with the most rules around it.
+//
+// # What it is allowed to do
+//
+// Appear, and make a noise. That is the whole of it. No microphone is opened,
+// no audio moves and nothing is connected until the person presses Answer, and
+// if they press nothing at all it takes itself away when the ringing stops. The
+// card is an offer; the SDK does not put a customer on a call because somebody
+// at the vendor clicked a button.
+//
+// # And what it says
+//
+// A name, a product and what the call is about, because a card that says
+// "someone is calling about a report" is indistinguishable from the thing every
+// bank tells people to hang up on. And whether the call would be recorded,
+// stated before Answer rather than after — on a peer-to-peer call the copy that
+// gets kept is uplinked by this browser, so telling somebody afterwards is
+// telling them about something that already happened.
+//
+// # The noise
+//
+// Synthesised, for the reason the dashboard's is: a ringtone as an audio file
+// is a binary in a bundle that runs on somebody else's site, an extra request
+// on their page, and a thing that can go missing behind a cache header. Four
+// oscillators and a table of numbers cost none of that.
+//
+// It is also softer and shorter than the dashboard's. A phone on a support
+// desk is meant to interrupt; this one is ringing in the middle of a stranger's
+// shopping cart, and a page that suddenly plays a loud telephone at somebody is
+// a page they close. If the browser refuses to play it at all — no interaction
+// yet, which is its rule and not ours — the card rings silently rather than not
+// appearing.
+
+/**
+ * A quiet double-pulse, once every three seconds.
+ *
+ * Two notes rather than one so it reads as a telephone rather than as an alert,
+ * and a fifth apart because that interval is the one people hear as "ringing"
+ * across every phone system anybody has used.
+ */
+const RING = {
+  cycleMs: 3000,
+  peak: 0.045,
+  bursts: [
+    { at: 0, seconds: 0.4, hz: [440, 660] },
+    { at: 0.55, seconds: 0.4, hz: [440, 660] },
+  ],
+};
+
+/**
+ * Whether anybody has touched this page yet.
+ *
+ * Tracked rather than asked, because there is nothing to ask: a browser will
+ * tell you an AudioContext is suspended, but only after you have built one —
+ * and building one on a page with no interaction is what writes
+ *
+ *     The AudioContext was not allowed to start. It must be resumed (or
+ *     created) after a user gesture on the page.
+ *
+ * into the console. This SDK runs on somebody else's site, and that console
+ * belongs to whoever is trying to debug their own product. A warning we cannot
+ * act on, for a sound that was never going to play, is not ours to put there.
+ */
+let touched = false;
+if (typeof window !== 'undefined' && window.addEventListener) {
+  for (const evt of ['pointerdown', 'keydown', 'touchstart']) {
+    // Capture, and it matters more here than it would in our own app: this runs
+    // on somebody else's page, whose handlers we have never seen and one of
+    // which may well stop a click before it reaches the window.
+    window.addEventListener(evt, () => { touched = true; }, {
+      once: true, capture: true, passive: true,
+    });
+  }
+}
+
+/**
+ * The same question asked of the browser rather than of ourselves.
+ *
+ * Chrome and Edge implement this and are the browsers that enforce the policy
+ * in the first place, so where it matters it answers. It is the recovery for a
+ * host page that swallowed every gesture before we saw it — better to make a
+ * quiet noise the person expects than to stay silent because of somebody else's
+ * event handler.
+ */
+function activatedByBrowser() {
+  try {
+    return Boolean(navigator.userActivation?.hasBeenActive);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Start ringing, and give back the way to stop.
+ *
+ * Returns a no-op teardown on every browser that will not do it, which is a
+ * real and ordinary case: a page nobody has clicked on yet has no audio
+ * permission, and the correct behaviour there is a card that appears in silence
+ * rather than no card.
+ */
+function startRinging() {
+  if (!touched && !activatedByBrowser()) return () => {};
+
+  const Ctx = typeof window !== 'undefined' && (window.AudioContext || window.webkitAudioContext);
+  if (!Ctx) return () => {};
+
+  let context;
+  try {
+    context = new Ctx();
+  } catch {
+    return () => {};
+  }
+
+  let stopped = false;
+  let timer = null;
+  const voices = [];
+
+  const burst = ({ at, seconds, hz }) => {
+    const start = context.currentTime + at;
+    const gain = context.createGain();
+    gain.connect(context.destination);
+    // Shaped rather than switched. A square edge on a sine is a click, and a
+    // click every three seconds is more irritating than the tone it introduces.
+    gain.gain.setValueAtTime(0, start);
+    gain.gain.linearRampToValueAtTime(RING.peak, start + 0.02);
+    gain.gain.setValueAtTime(RING.peak, start + seconds - 0.06);
+    gain.gain.linearRampToValueAtTime(0, start + seconds);
+
+    for (const frequency of hz) {
+      const osc = context.createOscillator();
+      osc.type = 'sine';
+      osc.frequency.value = frequency;
+      osc.connect(gain);
+      osc.start(start);
+      osc.stop(start + seconds + 0.02);
+      voices.push(osc);
+    }
+  };
+
+  const cycle = () => {
+    if (stopped) return;
+    try {
+      RING.bursts.forEach(burst);
+    } catch { /* the card is still on screen, which is the part that matters */ }
+  };
+
+  const begin = () => {
+    if (stopped) return;
+    cycle();
+    timer = setInterval(cycle, RING.cycleMs);
+  };
+
+  if (context.state === 'running') begin();
+  else context.resume().then(begin).catch(() => {});
+
+  return () => {
+    stopped = true;
+    if (timer) clearInterval(timer);
+    // Stopped rather than left to finish. Answered, this is cut off by the
+    // microphone opening a fraction of a second later, and a ring still sounding
+    // over the first word of a conversation is the thing people apologise for.
+    for (const osc of voices) {
+      try { osc.stop(); } catch { /* already stopped on its own schedule */ }
+    }
+    try { context.close(); } catch { /* nothing left to close */ }
+  };
+}
+
+/** Seconds left until a deadline, floored at zero. */
+function secondsLeft(ringsUntil) {
+  const until = Date.parse(ringsUntil || '');
+  if (Number.isNaN(until)) return 0;
+  return Math.max(0, Math.round((until - Date.now()) / 1000));
+}
+
+const BUTTON = [
+  'flex:1',
+  'padding:9px 12px',
+  'border:0',
+  'border-radius:8px',
+  'font:600 13px/1.4 inherit',
+  'cursor:pointer',
+].join(';');
+
+/**
+ * Put the card on screen and ring until something happens to it.
+ *
+ * @param {object} opts
+ * @param {object} opts.call  The `incomingCall` object off the update stream —
+ *   `callId`, `from`, `project`, `reference`, `ringsUntil`, `recorded`.
+ * @param {string} opts.accent  The integration's own colour, for Answer.
+ * @param {string} [opts.position]  Same two words the toast takes.
+ * @param {() => void} opts.onAnswer   Pressed Answer.
+ * @param {() => void} opts.onDecline  Pressed Decline.
+ * @param {() => void} [opts.onExpire] Nobody pressed anything in time.
+ * @returns {(reason?: string) => void} Take it away. Called with no reason on
+ *   an ordinary dismissal; the caller passes one only for its own logging.
+ */
+export function showIncomingCall({
+  call, accent = '#5b6ef5', position = 'bottom-right',
+  onAnswer, onDecline, onExpire,
+}) {
+  if (typeof document === 'undefined' || !document.body) return () => {};
+
+  const [vertical, horizontal] = String(position).split('-');
+  const el = document.createElement('div');
+  el.setAttribute('role', 'alertdialog');
+  el.setAttribute('aria-live', 'assertive');
+  el.setAttribute('aria-label', `${call.from || 'Support'} is calling about ${call.reference}`);
+  el.style.cssText = [
+    'position:fixed',
+    `${vertical === 'top' ? 'top' : 'bottom'}:20px`,
+    `${horizontal === 'left' ? 'left' : 'right'}:20px`,
+    // Above the update toast, which uses the maximum and may be on screen at
+    // the same moment — a status line must not sit on top of a ringing phone.
+    'z-index:2147483647',
+    'width:300px',
+    'max-width:calc(100vw - 40px)',
+    'padding:14px',
+    'border-radius:12px',
+    'background:#1b1e26',
+    'color:#eceef2',
+    'font:13px/1.5 -apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif',
+    'box-shadow:0 18px 44px rgba(0,0,0,0.5)',
+    `border:1px solid ${accent}`,
+    'opacity:0',
+    'transform:translateY(8px)',
+    'transition:opacity .2s ease,transform .2s ease',
+  ].join(';');
+
+  const heading = document.createElement('div');
+  heading.style.cssText = 'font-weight:600;font-size:14px;margin-bottom:2px';
+  // textContent throughout: every string on this card came from a person typing
+  // it, and it is being written into somebody else's page.
+  heading.textContent = `${call.from || 'Support'} is calling`;
+
+  const about = document.createElement('div');
+  about.style.cssText = 'color:#a4abba;margin-bottom:10px';
+  about.textContent = call.project
+    ? `About your report ${call.reference} · ${call.project}`
+    : `About your report ${call.reference}`;
+
+  const countdown = document.createElement('div');
+  countdown.style.cssText = 'color:#7d8598;font-size:12px;margin-bottom:10px';
+
+  const answer = document.createElement('button');
+  answer.type = 'button';
+  answer.textContent = 'Answer';
+  answer.style.cssText = `${BUTTON};background:${accent};color:#fff`;
+
+  const decline = document.createElement('button');
+  decline.type = 'button';
+  decline.textContent = 'Not now';
+  decline.style.cssText = `${BUTTON};background:#2b2f3a;color:#c8cedb`;
+
+  const actions = document.createElement('div');
+  actions.style.cssText = 'display:flex;gap:8px';
+  actions.append(answer, decline);
+
+  el.append(heading, about, countdown);
+  if (call.recorded) {
+    const kept = document.createElement('div');
+    kept.style.cssText = 'color:#7d8598;font-size:12px;margin-bottom:10px';
+    kept.textContent = 'This call will be recorded.';
+    el.append(kept);
+  }
+  el.append(actions);
+  document.body.appendChild(el);
+
+  const stopRinging = startRinging();
+  let closed = false;
+  let ticker = null;
+
+  const close = () => {
+    if (closed) return;
+    closed = true;
+    if (ticker) clearInterval(ticker);
+    stopRinging();
+    el.style.opacity = '0';
+    el.style.transform = 'translateY(8px)';
+    setTimeout(() => el.remove(), 250);
+  };
+
+  const tick = () => {
+    const left = secondsLeft(call.ringsUntil);
+    countdown.textContent = left
+      ? `Ringing — ${left}s`
+      : 'The call has stopped ringing.';
+    if (left) return;
+    // The deadline is the server's, not this browser's arithmetic, for the
+    // reason the API writes it down: two clocks disagreeing about when a phone
+    // stopped ringing is how somebody gets cut off mid-answer.
+    close();
+    try { onExpire?.(); } catch { /* theirs */ }
+  };
+  tick();
+  ticker = setInterval(tick, 1000);
+
+  answer.addEventListener('click', () => {
+    // Stopped before the handler runs, not after: opening a microphone takes a
+    // moment, and a phone still ringing during it sounds like the button
+    // did nothing.
+    close();
+    try { onAnswer?.(); } catch { /* theirs */ }
+  });
+
+  decline.addEventListener('click', () => {
+    close();
+    try { onDecline?.(); } catch { /* theirs */ }
+  });
+
+  requestAnimationFrame(() => {
+    el.style.opacity = '1';
+    el.style.transform = 'translateY(0)';
+  });
+
+  return close;
+}