@sphoro/bugcatch-web-sdk 0.13.1

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@sphoro/bugcatch-web-sdk",
+  "version": "0.13.1",
+  "description": "Drop-in browser SDK — report bugs with console, network and environment context, without the extension.",
+  "type": "module",
+  "main": "dist/bugcatch.es.js",
+  "module": "dist/bugcatch.es.js",
+  "browser": "dist/bugcatch.umd.js",
+  "unpkg": "dist/bugcatch.umd.js",
+  "jsdelivr": "dist/bugcatch.umd.js",
+  "types": "src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./dist/bugcatch.es.js",
+      "default": "./dist/bugcatch.es.js"
+    },
+    "./dist/bugcatch.umd.js": "./dist/bugcatch.umd.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "vite build",
+    "dev": "vite build --watch",
+    "prepublishOnly": "vite build"
+  },
+  "keywords": [
+    "bug-report",
+    "bug-tracking",
+    "error-reporting",
+    "console-capture",
+    "network-capture",
+    "feedback-widget",
+    "browser",
+    "sdk"
+  ],
+  "license": "MIT",
+  "homepage": "https://github.com/floki5G/sphoro.bugcatch/tree/main/bugcatch-sdk#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/floki5G/sphoro.bugcatch.git",
+    "directory": "bugcatch-sdk"
+  },
+  "bugs": {
+    "url": "https://github.com/floki5G/sphoro.bugcatch/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "vite": "^5.4.0"
+  }
+}

package/src/audio.js

@@ -0,0 +1,191 @@
+// Microphone to µ-law, and back.
+//
+// sphoro.voice speaks G.711 µ-law at 8 kHz in both directions — the format a
+// telephone carrier hands it, which is what makes a browser call and a phone
+// call indistinguishable to everything downstream. A browser has neither: it
+// captures 32-bit floats at whatever rate the sound card runs at. The gap
+// between those two is a codec and a resampler, and neither is available from
+// the platform, so both are here.
+//
+// This file exists rather than the two callers each having a copy. The agent
+// call sends µ-law because that is the whole conversation; a live call sends it
+// because sphoro.voice cannot record or transcribe a conversation it is not in
+// the middle of, and asks each browser for a copy of its own microphone. Two
+// implementations of G.711 in one package would be one implementation and one
+// that is subtly wrong on the day somebody fixes only the first.
+//
+// Nothing is imported to do it. The SDK runs on someone else's page and has no
+// dependencies, and that rule does not bend for audio.
+
+/** The wire's sample rate. Not negotiable — see the note above. */
+export const WIRE_RATE = 8000;
+
+/**
+ * An audio context, at the wire's rate where the browser will give us one.
+ *
+ * Asking for 8 kHz outright makes the resampler below dead code on most
+ * machines. Some browsers refuse a rate their hardware does not like, so the
+ * fallback is an ordinary context and the manual path.
+ */
+export function createContext(rate = WIRE_RATE) {
+  const Ctor = window.AudioContext || window.webkitAudioContext;
+  try {
+    return new Ctor({ sampleRate: rate });
+  } catch {
+    return new Ctor();
+  }
+}
+
+/**
+ * Start a context that the browser has parked, if it will let us.
+ *
+ * Resolves either way. There is nothing useful to do with the rejection: it
+ * means this browser wants a user gesture we are not inside, and the call is
+ * still worth attempting — a context that stays suspended is a silent call,
+ * which is what the caller finds out about from the states it is already being
+ * sent.
+ */
+export async function resumeContext(context) {
+  if (context.state !== 'suspended') return;
+  try {
+    await context.resume();
+  } catch { /* no activation to spend */ }
+}
+
+/**
+ * Drop a signal to the wire rate by averaging each source window.
+ *
+ * Exported for its own test: the browsers that refuse an 8 kHz context are the
+ * ones that need this, and they are exactly the browsers a developer is least
+ * likely to be looking at when they change it.
+ *
+ * Averaging rather than picking every nth sample: plain decimation aliases
+ * everything above 4 kHz down into the speech band, and consonants are exactly
+ * what lives up there. This is a crude low-pass, but it is the difference
+ * between "sixty" and "sixteen" surviving the trip.
+ */
+export function downsample(input, fromRate, toRate) {
+  const ratio = fromRate / toRate;
+  const out = new Float32Array(Math.floor(input.length / ratio));
+  for (let i = 0; i < out.length; i++) {
+    const start = Math.floor(i * ratio);
+    const end = Math.min(Math.floor((i + 1) * ratio), input.length);
+    let sum = 0;
+    for (let j = start; j < end; j++) sum += input[j];
+    out[i] = end > start ? sum / (end - start) : 0;
+  }
+  return out;
+}
+
+/** G.711 µ-law: the bias and clip the standard specifies. */
+const MU_BIAS = 0x84;
+const MU_CLIP = 32635;
+
+/**
+ * Float samples to µ-law bytes, ready to put on the wire.
+ *
+ * Exported for the codec test rather than for callers: this file is not the
+ * package's entry point, and a hand-rolled G.711 that nothing checks is a
+ * silent call nobody can debug from the outside.
+ */
+export function encodeMuLaw(samples) {
+  const out = new Uint8Array(samples.length);
+  for (let i = 0; i < samples.length; i++) {
+    // Clamped before scaling: a float outside [-1, 1] is legal in Web Audio and
+    // would wrap round to the opposite sign as an integer.
+    const clamped = Math.max(-1, Math.min(1, samples[i]));
+    let sample = Math.round(clamped * 32767);
+
+    const sign = sample < 0 ? 0x80 : 0;
+    if (sign) sample = -sample;
+    if (sample > MU_CLIP) sample = MU_CLIP;
+    sample += MU_BIAS;
+
+    let exponent = 7;
+    for (let mask = 0x4000; (sample & mask) === 0 && exponent > 0; exponent--, mask >>= 1);
+    const mantissa = (sample >> (exponent + 3)) & 0x0F;
+    out[i] = ~(sign | (exponent << 4) | mantissa) & 0xFF;
+  }
+  return out;
+}
+
+/** µ-law bytes back to float samples, ready for an AudioBuffer. */
+export function decodeMuLaw(bytes) {
+  const out = new Float32Array(bytes.length);
+  for (let i = 0; i < bytes.length; i++) {
+    const byte = ~bytes[i] & 0xFF;
+    const sign = byte & 0x80;
+    const exponent = (byte >> 4) & 0x07;
+    const mantissa = byte & 0x0F;
+    const magnitude = (((mantissa << 3) + MU_BIAS) << exponent) - MU_BIAS;
+    out[i] = (sign ? -magnitude : magnitude) / 32768;
+  }
+  return out;
+}
+
+/**
+ * How much audio rides in one frame.
+ *
+ * Measured in samples, and the context above runs at 8 kHz wherever the browser
+ * allows it — so this is 64 ms of speech, not the 20-odd it would be at
+ * hardware rate. That distinction is the whole reason for the number: at 2048
+ * the same code sends a quarter of a second per frame, which is a quarter of a
+ * second added to the start of every turn and to every barge-in, and it sounds
+ * exactly like an agent that is slow to notice you talking.
+ *
+ * Not smaller than this. ScriptProcessorNode runs on the main thread, and a
+ * block it cannot fill in time is a block it drops — which is a gap in the
+ * middle of a word rather than a delay before one. Powers of two only.
+ */
+export const CAPTURE_BLOCK = 512;
+
+/**
+ * Tap a microphone and hand each block over as µ-law bytes.
+ *
+ * ScriptProcessorNode is deprecated in favour of AudioWorklet, and is used
+ * anyway. A worklet's processor has to be loaded from a URL, which on this SDK
+ * means a blob: URL — and a blob: worklet is refused outright by the
+ * Content-Security-Policy of a great many of the sites this code runs on. A
+ * deprecated node that works on a customer's page beats a modern one that is
+ * blocked by their headers.
+ *
+ * Returns a `stop` that lets go of the whole chain. The microphone track is
+ * deliberately *not* stopped by it: on a live call the same track is carrying
+ * the conversation, and stopping it to end a recording would end the call.
+ *
+ * @param {AudioContext} context
+ * @param {MediaStream} stream
+ * @param {(bytes: Uint8Array) => void} onFrame
+ * @param {number} [wireRate]
+ * @returns {{stop: () => void}}
+ */
+export function tapMicrophone(context, stream, onFrame, wireRate = WIRE_RATE) {
+  const source = context.createMediaStreamSource(stream);
+  const capture = context.createScriptProcessor(CAPTURE_BLOCK, 1, 1);
+
+  capture.onaudioprocess = (event) => {
+    const input = event.inputBuffer.getChannelData(0);
+    const frames = context.sampleRate === wireRate
+      ? input
+      : downsample(input, context.sampleRate, wireRate);
+    onFrame(encodeMuLaw(frames));
+  };
+
+  source.connect(capture);
+  // A ScriptProcessorNode does not run unless it is connected to a destination,
+  // even when nothing is meant to come out of it. Zero gain is what keeps the
+  // speaker from hearing their own voice played back at them.
+  const mute = context.createGain();
+  mute.gain.value = 0;
+  capture.connect(mute);
+  mute.connect(context.destination);
+
+  return {
+    stop() {
+      capture.onaudioprocess = null;
+      try { source.disconnect(); } catch { /* already gone */ }
+      try { capture.disconnect(); } catch { /* already gone */ }
+      try { mute.disconnect(); } catch { /* already gone */ }
+    },
+  };
+}

package/src/capture.js

@@ -0,0 +1,300 @@
+// Screenshots, screen recordings and file attachments.
+//
+// Capture always goes through getDisplayMedia, so the browser shows its own
+// picker and permission prompt — nothing leaves the page without the person
+// explicitly choosing what to share. There is no DOM-rasterising fallback on
+// purpose: it would need a heavy dependency and would still silently miss
+// cross-origin iframes, canvas and video, which is worse than not offering it.
+
+/**
+ * Pristine references, taken at module-evaluation time — which happens on
+ * import, before init() patches anything.
+ *
+ * Uploads must not be recorded by our own network capture: a report would
+ * otherwise describe its own attachment upload, and a retry would append to a
+ * buffer that is already being serialised.
+ */
+const nativeFetch = typeof window !== 'undefined' && window.fetch
+  ? window.fetch.bind(window)
+  : null;
+const nativeXhrOpen = typeof XMLHttpRequest !== 'undefined'
+  ? XMLHttpRequest.prototype.open
+  : null;
+const nativeXhrSend = typeof XMLHttpRequest !== 'undefined'
+  ? XMLHttpRequest.prototype.send
+  : null;
+
+/**
+ * What the API will presign. Anything else is rejected before we ask.
+ *
+ * Mirrors UPLOAD_MIMES in the API's storage.service.ts. The two are checked
+ * independently — this one to fail early with a message the person can act on,
+ * that one because a browser is not a place to enforce anything.
+ */
+export const UPLOAD_MIMES = [
+  'image/png', 'image/jpeg', 'image/webp', 'image/gif', 'video/webm', 'video/mp4',
+  'audio/webm', 'audio/ogg', 'audio/mpeg', 'audio/mp4', 'audio/wav',
+  'application/pdf', 'text/plain', 'text/csv', 'application/json', 'application/zip',
+  'application/msword',
+  'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+  'application/vnd.ms-excel',
+  'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+];
+
+/**
+ * What a *bug report* may carry, which is narrower than what may be uploaded.
+ *
+ * A report's attachments are evidence of the bug — what the screen looked like,
+ * what the session did — and the API types them SCREENSHOT or VIDEO. A document
+ * has no honest value there: filed as a SCREENSHOT it would render as a broken
+ * image in the dashboard's media viewer.
+ *
+ * Documents and voice notes belong on a *message*, where the type is derived
+ * from the mime and the reader gets a player or a download.
+ */
+export const REPORT_MIMES = [
+  'image/png', 'image/jpeg', 'image/webp', 'video/webm', 'video/mp4',
+];
+
+export const voiceSupported = () =>
+  Boolean(navigator?.mediaDevices?.getUserMedia && typeof MediaRecorder !== 'undefined');
+
+export const captureSupported = () =>
+  Boolean(navigator?.mediaDevices?.getDisplayMedia && typeof MediaRecorder !== 'undefined');
+
+export const screenshotSupported = () =>
+  Boolean(navigator?.mediaDevices?.getDisplayMedia);
+
+/**
+ * MediaRecorder reports `video/webm;codecs=vp9`, but the presign signature
+ * binds an exact Content-Type and the API only allows the base types. Strip
+ * the codec parameter so the type we sign, the header we send and the type the
+ * API stored all agree.
+ */
+export function normalizeMime(mime, allowed = UPLOAD_MIMES) {
+  const base = String(mime || '').split(';')[0].trim().toLowerCase();
+  return allowed.includes(base) ? base : null;
+}
+
+/** Grab a single frame of a chosen screen/window/tab as a PNG blob. */
+export async function captureScreenshot() {
+  const stream = await navigator.mediaDevices.getDisplayMedia({
+    video: { frameRate: 1 },
+    audio: false,
+  });
+  try {
+    const track = stream.getVideoTracks()[0];
+    const video = document.createElement('video');
+    video.srcObject = stream;
+    video.muted = true;
+    video.playsInline = true;
+    await video.play();
+
+    // Wait one frame so the first paint isn't blank.
+    await new Promise((resolve) => requestAnimationFrame(() => requestAnimationFrame(resolve)));
+
+    const { width, height } = track.getSettings();
+    const canvas = document.createElement('canvas');
+    canvas.width = width || video.videoWidth;
+    canvas.height = height || video.videoHeight;
+    canvas.getContext('2d').drawImage(video, 0, 0, canvas.width, canvas.height);
+
+    const blob = await new Promise((res) => canvas.toBlob(res, 'image/png'));
+    if (!blob) throw new Error('The browser returned an empty screenshot.');
+    return { blob, mime: 'image/png', kind: 'SCREENSHOT' };
+  } finally {
+    // Always release the capture, including on failure — otherwise the browser
+    // keeps showing "sharing your screen".
+    stream.getTracks().forEach((t) => t.stop());
+  }
+}
+
+/**
+ * Start recording a chosen screen/window/tab. Returns a handle with stop() and
+ * cancel(); the caller decides which. Recording ends on its own if the user
+ * clicks the browser's "Stop sharing" button or the cap is reached.
+ */
+export async function startRecording({ maxMs = 120_000, onTick, onAutoStop } = {}) {
+  const stream = await navigator.mediaDevices.getDisplayMedia({
+    video: { frameRate: 15 },
+    audio: false,
+  });
+
+  const mime = ['video/webm;codecs=vp9', 'video/webm;codecs=vp8', 'video/webm']
+    .find((t) => MediaRecorder.isTypeSupported(t)) || 'video/webm';
+
+  const recorder = new MediaRecorder(stream, { mimeType: mime, videoBitsPerSecond: 2_500_000 });
+  const chunks = [];
+  recorder.ondataavailable = (e) => { if (e.data.size) chunks.push(e.data); };
+  recorder.start(1000);
+
+  const startedAt = Date.now();
+  const timer = setInterval(() => onTick?.(Math.floor((Date.now() - startedAt) / 1000)), 500);
+
+  const cleanup = () => {
+    clearInterval(timer);
+    clearTimeout(capTimer);
+    stream.getTracks().forEach((t) => t.stop());
+  };
+
+  const finished = new Promise((resolve) => {
+    recorder.onstop = () => {
+      cleanup();
+      resolve(new Blob(chunks, { type: mime }));
+    };
+  });
+
+  const endEarly = () => {
+    if (recorder.state !== 'inactive') recorder.stop();
+    onAutoStop?.();
+  };
+
+  // The user can stop sharing from the browser's own UI; treat that as "done".
+  stream.getVideoTracks()[0].addEventListener('ended', endEarly);
+
+  // Hard cap so a forgotten recording can't grow without bound.
+  const capTimer = setTimeout(endEarly, maxMs);
+
+  return {
+    mime,
+    maxMs,
+    async stop() {
+      clearTimeout(capTimer);
+      if (recorder.state !== 'inactive') recorder.stop();
+      return { blob: await finished, mime, kind: 'VIDEO' };
+    },
+    cancel() {
+      cleanup();
+      if (recorder.state !== 'inactive') recorder.stop();
+    },
+  };
+}
+
+/**
+ * Record a voice note from the microphone. Returns a handle with stop() and
+ * cancel(), like startRecording() above.
+ *
+ * Audio only, and from getUserMedia rather than getDisplayMedia: this is
+ * somebody talking into their laptop to explain a bug, not a capture of the
+ * screen. The browser shows its own microphone prompt, so nothing is recorded
+ * without an explicit grant.
+ *
+ * The container is whichever the browser will give us — Chromium and Firefox
+ * produce webm/opus, Safari mp4/aac — because MediaRecorder cannot be made to
+ * agree on one, and the API allows both.
+ */
+export async function startVoiceNote({ maxMs = 120_000, onTick, onAutoStop } = {}) {
+  const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
+
+  const mime = ['audio/webm;codecs=opus', 'audio/webm', 'audio/mp4', 'audio/ogg']
+    .find((t) => MediaRecorder.isTypeSupported(t)) || '';
+
+  const recorder = new MediaRecorder(stream, mime ? { mimeType: mime } : undefined);
+  const chunks = [];
+  recorder.ondataavailable = (e) => { if (e.data.size) chunks.push(e.data); };
+  recorder.start(1000);
+
+  const startedAt = Date.now();
+  const timer = setInterval(() => onTick?.(Math.floor((Date.now() - startedAt) / 1000)), 500);
+
+  const cleanup = () => {
+    clearInterval(timer);
+    clearTimeout(capTimer);
+    stream.getTracks().forEach((t) => t.stop());
+  };
+
+  const finished = new Promise((resolve) => {
+    recorder.onstop = () => {
+      cleanup();
+      resolve(new Blob(chunks, { type: recorder.mimeType || mime }));
+    };
+  });
+
+  const endEarly = () => {
+    if (recorder.state !== 'inactive') recorder.stop();
+    onAutoStop?.();
+  };
+
+  // A hard cap, as for screen recording: a forgotten open microphone is worse
+  // than a truncated note.
+  const capTimer = setTimeout(endEarly, maxMs);
+
+  return {
+    mime: recorder.mimeType || mime,
+    maxMs,
+    async stop() {
+      clearTimeout(capTimer);
+      if (recorder.state !== 'inactive') recorder.stop();
+      const blob = await finished;
+      return { blob, mime: blob.type || recorder.mimeType || mime, kind: 'AUDIO' };
+    },
+    cancel() {
+      cleanup();
+      if (recorder.state !== 'inactive') recorder.stop();
+    },
+  };
+}
+
+/**
+ * Ask the API for a presigned URL and PUT the blob straight at it, so media
+ * never passes through the API request path.
+ *
+ * Resolves to the storage key, which is what a report references.
+ */
+export async function uploadAttachment({ apiBase, apiKey, blob, mime, onProgress }) {
+  const type = normalizeMime(mime || blob.type);
+  if (!type) {
+    throw new Error(`[BugCatch] ${mime || blob.type || 'that file'} can't be attached.`);
+  }
+
+  const res = await nativeFetch(`${apiBase}/ingest/presign`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json', 'X-BugCatch-Key': apiKey },
+    body: JSON.stringify({ mime: type }),
+  });
+  if (!res.ok) throw new Error(`[BugCatch] could not start the upload (HTTP ${res.status}).`);
+  const { key, uploadUrl } = await res.json();
+
+  await put(uploadUrl, blob, type, onProgress);
+  return { storageKey: key, mime: type };
+}
+
+/**
+ * XHR rather than fetch purely for upload progress — a recording is megabytes,
+ * and a progress bar is the difference between "working" and "frozen".
+ */
+function put(uploadUrl, blob, mime, onProgress) {
+  return new Promise((resolve, reject) => {
+    const xhr = new XMLHttpRequest();
+    nativeXhrOpen.call(xhr, 'PUT', uploadUrl, true);
+    xhr.setRequestHeader('Content-Type', mime);
+    xhr.upload.onprogress = (e) => {
+      if (e.lengthComputable) onProgress?.(e.loaded / e.total);
+    };
+    xhr.onload = () => {
+      if (xhr.status >= 200 && xhr.status < 300) resolve();
+      else reject(new Error(`[BugCatch] upload failed (HTTP ${xhr.status}).`));
+    };
+    // The PUT goes to the bucket, not to the API, so a missing bucket CORS
+    // policy arrives here as a bare network error with no status. Reporting it
+    // as "network error" sends people to read API logs that are perfectly clean.
+    xhr.onerror = () => reject(new Error(
+      '[BugCatch] the browser blocked the upload to storage. If this is a new '
+      + 'environment, the media bucket is probably missing its CORS policy.',
+    ));
+    xhr.onabort = () => reject(new Error('[BugCatch] upload cancelled.'));
+    nativeXhrSend.call(xhr, blob);
+  });
+}
+
+export function humanSize(bytes) {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(0)} KB`;
+  return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
+}
+
+export function humanDuration(seconds) {
+  const m = Math.floor(seconds / 60);
+  const s = seconds % 60;
+  return `${m}:${String(s).padStart(2, '0')}`;
+}