@lightworkai.official/debug-capture 0.14.3 → 0.15.0

package/src/config.ts

@@ -149,6 +149,18 @@ export interface DebugCaptureConfig {
   /** UI language. Only affects the built-in reporter's own strings. */
   locale?: "th" | "en";
 
+  /**
+   * The ring for a call from the support team. Default true.
+   *
+   * With `identity` set and calls switched on for the desk, the reporter's own
+   * live connection to the support host is held here — the one their portal
+   * tab holds, proven with the same signed token — so a call from the team
+   * rings in this app, as a card, and opens the reporter's request on the
+   * support host to answer it (the call itself happens there). `false` leaves
+   * calls to the support host and the invitation the team sends.
+   */
+  ring?: boolean;
+
   /**
    * Where this library's own notifications go.
    *

package/src/index.ts

@@ -42,6 +42,8 @@ export { redactBody, redactHeaders, redactLabel, redactUrl, REDACTED } from "./c
 // `defineReporterElement()` builds it in the browser, where it exists.
 export { defineReporterElement, setErroredQueriesSource, REPORTER_TAG } from "./ui/element";
 export { showToast } from "./ui/toast";
+// A call from the support team, rung in the host app — started by install; a host that renders its own UI may start or stop it.
+export { startLiveRing, stopLiveRing } from "./live";
 
 /*
  * The annotator ENGINE, shared by every framework package.

package/src/install.ts

@@ -14,6 +14,7 @@ import { strings } from "./ui/strings";
 import { showToast } from "./ui/toast";
 import { defineReporterElement, REPORTER_TAG } from "./ui/element";
 import { loadRequestTypes } from "./requests";
+import { startLiveRing } from "./live";
 
 let armed = false;
 
@@ -69,4 +70,12 @@ export function installDebugCapture(options: InstallOptions = {}): void {
   const idle = (window as Window & { requestIdleCallback?: (cb: () => void, o?: { timeout: number }) => number }).requestIdleCallback;
   if (idle) idle(() => void loadRequestTypes(), { timeout: 5000 });
   else setTimeout(() => void loadRequestTypes(), 2000);
+
+  /*
+   * A call from the support team rings here (live.ts) — when the host vouches
+   * for who is signed in and the desk has calls on. Late, like the request
+   * types: the page came for something else.
+   */
+  if (idle) idle(() => startLiveRing(), { timeout: 8000 });
+  else setTimeout(() => startLiveRing(), 3000);
 }

package/src/live.ts

@@ -0,0 +1,227 @@
+/**
+ * The ring for a call from the support team, in the host app.
+ *
+ * A reporter lives in the app they report from, not on the support host; a
+ * call from the team used to reach them only by the invitation in their
+ * email. So, when the host vouches for who is signed in (`identity`) and the
+ * desk has calls switched on, the widget holds the reporter's OWN live
+ * connection to the support host — the one their portal tab holds, traded
+ * for the host's signed token at `/ingest/live-ticket`, told about their own
+ * requests and calls and nothing else — and a call rings here as a card.
+ *
+ * Answering happens on the support host, where the call's media lives: the
+ * card's button opens the reporter's request there, signed in by the same
+ * hand-off the portal button uses — a tab opened INSIDE the press (a browser
+ * allows nothing later), its address set once the token is in hand.
+ *
+ * Quiet by design. No identity, calls off, a support host older than this
+ * package, a token refused: no socket, no card, nothing in the console — the
+ * widget does exactly what it did before.
+ */
+import { getConfig } from "./config";
+import { preparePortalUrl } from "./portal";
+import { hideRing, ringOpened, ringShownFor, showRing } from "./ui/ring";
+
+export interface RingingCall {
+  id: string;
+  ticketId: string;
+  ticketKey: string;
+  ticketTitle: string;
+  status: string;
+  ringUntil: string;
+  side?: string | null;
+}
+
+const RETRY_MS = [2000, 5000, 15_000, 30_000, 60_000];
+const PING_MS = 20_000;
+
+let started = false;
+let stopped = false;
+/** Asked for a token and got none — nobody signed in yet. A few slow tries, then quiet: never a request a minute forever. */
+let tokenless = 0;
+const TOKENLESS_MAX = 5;
+let socket: WebSocket | null = null;
+let retry = 0;
+let pinger: ReturnType<typeof setInterval> | undefined;
+let reconnectTimer: ReturnType<typeof setTimeout> | undefined;
+let expiry: ReturnType<typeof setTimeout> | undefined;
+
+const base = (host: string) => (host.endsWith("/") ? host : `${host}/`);
+
+/** `wss://support.example/api/presence/ws?t=…` — the support host's scheme, the socket's own path. Pure, for the tests. */
+export function liveSocketUrl(host: string, ticket: string): string {
+  const url = new URL("api/presence/ws", base(host));
+  url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+  url.searchParams.set("t", ticket);
+  return url.toString();
+}
+
+/** Where the card sends them: their request, with the call — the support host rings it there. Pure, for the tests. */
+export function answerPath(call: Pick<RingingCall, "id" | "ticketId">): string {
+  return `/me/tickets/${call.ticketId}?call=${call.id}`;
+}
+
+/** Is this a call ringing for the person at this widget? */
+export function ringsHere(call: Pick<RingingCall, "status" | "side">): boolean {
+  return call.status === "ringing" && (call.side === "reporter" || call.side === undefined || call.side === null);
+}
+
+async function hostToken(): Promise<string | null> {
+  const provider = getConfig().identity;
+  if (!provider) return null;
+  try {
+    return (await provider()) ?? null;
+  } catch {
+    return null;
+  }
+}
+
+async function post(path: string, token: string): Promise<Response> {
+  const config = getConfig();
+  return fetch(new URL(path, base(config.host)).toString(), {
+    method: "POST",
+    headers: { "content-type": "application/json", "x-realm-key": config.realmKey, authorization: `Bearer ${token}` },
+    body: "{}",
+  });
+}
+
+/** Start listening for calls. Idempotent; a no-op without identity, or with `ring: false`. */
+export function startLiveRing(): void {
+  if (started || typeof window === "undefined" || typeof WebSocket === "undefined") return;
+  const config = getConfig();
+  if (!config.identity || config.ring === false) return;
+  started = true;
+  stopped = false;
+  void connect();
+}
+
+/** Let go — the socket, the card, the timers. For a host that unmounts, and for the tests. */
+export function stopLiveRing(): void {
+  stopped = true;
+  started = false;
+  clearTimeout(reconnectTimer);
+  clearInterval(pinger);
+  clearTimeout(expiry);
+  try {
+    socket?.close(1000, "bye");
+  } catch {
+    /* already */
+  }
+  socket = null;
+  hideRing();
+}
+
+function schedule(slow = false): void {
+  if (stopped) return;
+  const wait = slow ? RETRY_MS[RETRY_MS.length - 1]! : RETRY_MS[Math.min(retry++, RETRY_MS.length - 1)]!;
+  clearTimeout(reconnectTimer);
+  reconnectTimer = setTimeout(() => void connect(), wait);
+}
+
+async function connect(): Promise<void> {
+  if (stopped) return;
+  const token = await hostToken();
+  // Nobody signed in to the host yet: ask again, slowly — a few times, then stop.
+  if (!token) {
+    if (++tokenless >= TOKENLESS_MAX) {
+      stopped = true;
+      return;
+    }
+    return schedule(true);
+  }
+  tokenless = 0;
+  let res: Response;
+  try {
+    res = await post("ingest/live-ticket", token);
+  } catch {
+    return schedule();
+  }
+  // A token the desk does not accept, or a support host from before the ring: nothing to do, and nothing to say.
+  if (res.status === 401 || res.status === 404 || res.status === 403) {
+    stopped = true;
+    return;
+  }
+  if (!res.ok) return schedule(res.status === 429);
+  let out: { calls?: boolean; ticket?: string | null; call?: RingingCall | null };
+  try {
+    out = await res.json();
+  } catch {
+    return schedule();
+  }
+  // Calls off for this desk: no socket at all.
+  if (!out.calls || !out.ticket) {
+    stopped = true;
+    return;
+  }
+  if (out.call) hear(out.call);
+  const ws = new WebSocket(liveSocketUrl(getConfig().host, out.ticket));
+  socket = ws;
+  ws.onopen = () => {
+    retry = 0;
+    clearInterval(pinger);
+    pinger = setInterval(() => {
+      if (ws.readyState === WebSocket.OPEN) ws.send(JSON.stringify({ type: "ping" }));
+    }, PING_MS);
+  };
+  ws.onmessage = (e) => {
+    try {
+      const frame = JSON.parse(String(e.data)) as { type?: string; call?: RingingCall };
+      if (frame.type === "call-state" && frame.call) hear(frame.call);
+    } catch {
+      /* not ours to read */
+    }
+  };
+  ws.onclose = () => {
+    clearInterval(pinger);
+    if (socket === ws) socket = null;
+    schedule();
+  };
+}
+
+/** The support host's word on a call: ringing here shows the card; anything else takes it away. */
+function hear(call: RingingCall): void {
+  if (!ringsHere(call)) return hideRing(call.id);
+  showRing(call, { open: () => answer(call), decline: () => void decline(call) });
+  // Never longer than it rings: a socket that dropped mid-ring must not leave a card up for good.
+  clearTimeout(expiry);
+  const left = new Date(call.ringUntil).getTime() - Date.now();
+  expiry = setTimeout(() => {
+    if (ringShownFor() === call.id) hideRing(call.id);
+  }, Math.max(5000, left + 5000));
+}
+
+/**
+ * เปิดเพื่อรับสาย. The tab is opened HERE, inside the press — after an await the
+ * browser would call it an unasked-for popup — then sent to the signed-in
+ * link once the host's token arrives. The support host is told the reporter
+ * is coming, so the ring waits for the hand-off and the team sees it.
+ */
+function answer(call: RingingCall): void {
+  const tab = window.open("about:blank", "_blank");
+  void (async () => {
+    const token = await hostToken();
+    if (token) void post(`ingest/calls/${call.id}/coming`, token).catch(() => undefined);
+    let url: string;
+    try {
+      url = await preparePortalUrl(answerPath(call));
+    } catch {
+      tab?.close();
+      return;
+    }
+    if (tab && !tab.closed) {
+      tab.location.href = url;
+      try {
+        tab.opener = null;
+      } catch {
+        /* open either way */
+      }
+      ringOpened();
+    } else ringOpened(url);
+  })();
+}
+
+async function decline(call: RingingCall): Promise<void> {
+  hideRing(call.id);
+  const token = await hostToken();
+  if (token) await post(`ingest/calls/${call.id}/decline`, token).catch(() => undefined);
+}

package/src/portal.ts

@@ -79,6 +79,9 @@ async function prepareUrl(returnTo?: string): Promise<string> {
   return supportPortalUrl(config.host, config.realmKey, token, returnTo);
 }
 
+/** The signed-in link to a path on the support host — for a caller that opened its own tab first (the call ring, ui/ring). */
+export const preparePortalUrl = prepareUrl;
+
 /** False when the browser refused — a popup blocker, almost always. */
 function navigate(url: string, target: OpenPortalOptions["target"]): boolean {
   if (target === "_self") {

package/src/ui/ring.ts

@@ -0,0 +1,248 @@
+/**
+ * A call from the support team, rung in the host app (live.ts).
+ *
+ * The call itself happens on the support host — its media code, its screen
+ * sharing, its dock — so this card does one thing: say who is calling and
+ * about what, and open the reporter's request there to answer it. A soft ring
+ * and the tab's title too, because a call that rings in a background tab and
+ * says nothing is a missed call.
+ *
+ * Its own shadow root and styles, like the dialog, the toast and the hand-off:
+ * it lands on pages we do not control. Marked as ours, so a report filed while
+ * it is up does not photograph it.
+ */
+import { getConfig } from "../config";
+import { containKeys } from "./keys";
+import { strings } from "./strings";
+
+const HOST_TAG = "lw-call-ring";
+
+const CSS = `
+:host { all: initial; }
+.card {
+  position: fixed; right: 16px; bottom: 16px; z-index: 2147483002;
+  width: min(340px, calc(100vw - 32px)); box-sizing: border-box;
+  padding: 16px; border-radius: 16px; background: #fff; color: #0f172a;
+  border: 1px solid #e2e8f0; box-shadow: 0 24px 60px rgba(15, 23, 42, 0.24);
+  font-family: system-ui, -apple-system, "Segoe UI", Roboto, "Noto Sans Thai", sans-serif;
+  animation: in 200ms cubic-bezier(0.16, 1, 0.3, 1);
+}
+@media (max-width: 480px) { .card { right: 8px; left: 8px; bottom: 8px; width: auto; } }
+.head { display: flex; align-items: center; gap: 12px; }
+.icon {
+  position: relative; flex: none; width: 44px; height: 44px; border-radius: 50%;
+  display: grid; place-items: center; background: #ecfdf5; color: #059669;
+}
+.icon::after {
+  content: ""; position: absolute; inset: 0; border-radius: 50%;
+  background: rgba(16, 185, 129, 0.25); animation: ping 1.4s ease-out infinite;
+}
+.icon svg { position: relative; width: 20px; height: 20px; }
+h2 { margin: 0; font-size: 15px; font-weight: 600; line-height: 1.4; }
+.about { margin: 2px 0 0; font-size: 12px; color: #475569; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; max-width: 250px; }
+.how { margin: 10px 0 0; font-size: 12px; line-height: 1.6; color: #64748b; }
+.how a { color: #0369a1; font-weight: 600; }
+.actions { display: flex; gap: 8px; margin-top: 12px; }
+.actions button {
+  flex: 1; box-sizing: border-box; display: inline-flex; align-items: center; justify-content: center;
+  height: 40px; padding: 0 12px; border-radius: 999px; font: inherit; font-size: 14px; font-weight: 600; cursor: pointer;
+}
+.decline { border: 1px solid #fecdd3; background: #fff1f2; color: #be123c; }
+.decline:hover { background: #ffe4e6; }
+.open { border: none; background: #059669; color: #fff; }
+.open:hover { background: #047857; }
+.close { border: 1px solid #e2e8f0; background: #fff; color: #334155; }
+.actions button:focus-visible { outline: 2px solid #0ea5e9; outline-offset: 2px; }
+@keyframes in { from { opacity: 0; transform: translateY(8px); } to { opacity: 1; transform: none; } }
+@keyframes ping { from { transform: scale(1); opacity: 1; } to { transform: scale(1.6); opacity: 0; } }
+@media (prefers-reduced-motion: reduce) { .card { animation: none; } .icon::after { animation: none; opacity: 0; } }
+`;
+
+const PHONE = `<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M22 16.92v3a2 2 0 0 1-2.18 2 19.79 19.79 0 0 1-8.63-3.07 19.5 19.5 0 0 1-6-6 19.79 19.79 0 0 1-3.07-8.67A2 2 0 0 1 4.11 2h3a2 2 0 0 1 2 1.72c.13.96.36 1.9.7 2.81a2 2 0 0 1-.45 2.11L8.09 9.91a16 16 0 0 0 6 6l1.27-1.27a2 2 0 0 1 2.11-.45c.91.34 1.85.57 2.81.7A2 2 0 0 1 22 16.92z"/></svg>`;
+
+export interface RingCall {
+  id: string;
+  ticketKey: string;
+  ticketTitle: string;
+}
+
+export interface RingHandlers {
+  /** Runs INSIDE the press: a tab can be opened only there, before anything is awaited. */
+  open: () => void;
+  decline: () => void;
+}
+
+let host: HTMLElement | null = null;
+let shownId: string | null = null;
+let titleBefore: string | null = null;
+
+/** "เรื่อง CALL-12 · title" — the line under the card's title. Pure, for the tests. */
+export function ringAbout(template: string, call: RingCall): string {
+  return template.replace("{key}", call.ticketKey).replace("{title}", call.ticketTitle);
+}
+
+const t = () => strings(getConfig().locale);
+
+function mount(): ShadowRoot | null {
+  if (typeof document === "undefined") return null;
+  if (host?.isConnected) return host.shadowRoot;
+  host = document.createElement(HOST_TAG);
+  host.dataset.debugReporter = "true";
+  const root = host.attachShadow({ mode: "open" });
+  containKeys(root);
+  document.body.append(host);
+  return root;
+}
+
+/** Show the ring for this call — once; the same call again changes nothing. */
+export function showRing(call: RingCall, handlers: RingHandlers): void {
+  if (shownId === call.id && host?.isConnected) return;
+  const root = mount();
+  if (!root) return;
+  shownId = call.id;
+  const s = t();
+  root.innerHTML = "";
+  const style = document.createElement("style");
+  style.textContent = CSS;
+  const card = document.createElement("div");
+  card.className = "card";
+  card.setAttribute("role", "alertdialog");
+  card.setAttribute("aria-label", s.ringTitle);
+  card.dataset.lwCallRing = call.id;
+  const head = document.createElement("div");
+  head.className = "head";
+  const icon = document.createElement("span");
+  icon.className = "icon";
+  icon.innerHTML = PHONE;
+  const words = document.createElement("div");
+  const h = document.createElement("h2");
+  h.textContent = s.ringTitle;
+  const about = document.createElement("p");
+  about.className = "about";
+  about.textContent = ringAbout(s.ringAbout, call);
+  about.title = about.textContent;
+  words.append(h, about);
+  head.append(icon, words);
+  const how = document.createElement("p");
+  how.className = "how";
+  how.textContent = s.ringHow;
+  const actions = document.createElement("div");
+  actions.className = "actions";
+  const decline = document.createElement("button");
+  decline.type = "button";
+  decline.className = "decline";
+  decline.textContent = s.ringDecline;
+  decline.dataset.lwRing = "decline";
+  decline.onclick = () => handlers.decline();
+  const open = document.createElement("button");
+  open.type = "button";
+  open.className = "open";
+  open.textContent = s.ringOpen;
+  open.dataset.lwRing = "open";
+  open.onclick = () => handlers.open();
+  actions.append(decline, open);
+  card.append(head, how, actions);
+  root.append(style, card);
+  startTone();
+  if (titleBefore === null) {
+    titleBefore = document.title;
+    document.title = `${s.ringTab} — ${titleBefore}`;
+  }
+  open.focus({ preventScroll: true });
+}
+
+/** Opened: the card says where to answer, and stops ringing. `blockedUrl` — the browser refused the tab: a link, which is a fresh press. */
+export function ringOpened(blockedUrl?: string): void {
+  const root = host?.shadowRoot;
+  if (!root) return;
+  stopTone();
+  restoreTitle();
+  const s = t();
+  const how = root.querySelector(".how");
+  const actions = root.querySelector(".actions");
+  if (how) {
+    how.textContent = "";
+    if (blockedUrl) {
+      const a = document.createElement("a");
+      a.href = blockedUrl;
+      a.target = "_blank";
+      a.rel = "noopener";
+      a.textContent = s.ringBlocked;
+      a.dataset.lwRing = "link";
+      a.onclick = () => window.setTimeout(() => ringOpened(), 0);
+      how.append(a);
+    } else how.textContent = s.ringOpened;
+  }
+  if (actions) {
+    actions.innerHTML = "";
+    const close = document.createElement("button");
+    close.type = "button";
+    close.className = "close";
+    close.textContent = s.ringClose;
+    close.dataset.lwRing = "close";
+    close.onclick = () => hideRing();
+    actions.append(close);
+  }
+}
+
+/** The call is no longer ringing for this person — answered, declined, missed or ended. */
+export function hideRing(id?: string): void {
+  if (id && shownId && id !== shownId) return;
+  stopTone();
+  restoreTitle();
+  host?.remove();
+  host = null;
+  shownId = null;
+}
+
+export function ringShownFor(): string | null {
+  return host?.isConnected ? shownId : null;
+}
+
+function restoreTitle(): void {
+  if (titleBefore === null || typeof document === "undefined") return;
+  if (document.title.startsWith(t().ringTab)) document.title = titleBefore;
+  titleBefore = null;
+}
+
+/* ── A soft ring: two notes every two seconds, as the support host's own ── */
+
+let audio: AudioContext | null = null;
+let toneTimer: ReturnType<typeof setInterval> | undefined;
+
+function startTone(): void {
+  stopTone();
+  const w = window as unknown as { AudioContext?: typeof AudioContext; webkitAudioContext?: typeof AudioContext };
+  const Ctx = w.AudioContext ?? w.webkitAudioContext;
+  if (!Ctx) return;
+  try {
+    const ctx = audio ?? new Ctx();
+    audio = ctx;
+    // A page nobody has pressed anything on may not play sound — then the card and the title carry it.
+    void ctx.resume?.().catch(() => undefined);
+  } catch {
+    return;
+  }
+  const beep = () => {
+    if (!audio || audio.state !== "running") return;
+    const now = audio.currentTime;
+    for (const [i, f] of [660, 880].entries()) {
+      const osc = audio.createOscillator();
+      const gain = audio.createGain();
+      osc.frequency.value = f;
+      gain.gain.setValueAtTime(0.0001, now + i * 0.22);
+      gain.gain.exponentialRampToValueAtTime(0.08, now + i * 0.22 + 0.02);
+      gain.gain.exponentialRampToValueAtTime(0.0001, now + i * 0.22 + 0.2);
+      osc.connect(gain).connect(audio.destination);
+      osc.start(now + i * 0.22);
+      osc.stop(now + i * 0.22 + 0.21);
+    }
+  };
+  beep();
+  toneTimer = setInterval(beep, 2200);
+}
+
+function stopTone(): void {
+  clearInterval(toneTimer);
+  toneTimer = undefined;
+}

package/src/ui/strings.ts

@@ -108,6 +108,16 @@ export interface Strings {
   /** Carry `{n}`. */
   days: string;
   hours: string;
+  /** A call from the support team (ui/ring). `ringAbout` carries `{key}` and `{title}`. */
+  ringTitle: string;
+  ringAbout: string;
+  ringHow: string;
+  ringOpen: string;
+  ringDecline: string;
+  ringOpened: string;
+  ringBlocked: string;
+  ringClose: string;
+  ringTab: string;
 }
 
 const th: Strings = {
@@ -183,6 +193,15 @@ const th: Strings = {
   requestLeavesWhat: "บันทึกการใช้งานของหน้านี้ — ใช้กับการแจ้งปัญหาเท่านั้น",
   days: "{n} วัน",
   hours: "{n} ชั่วโมง",
+  ringTitle: "ทีมงานกำลังโทรหาคุณ",
+  ringAbout: "เรื่อง {key} · {title}",
+  ringHow: "รับสายในหน้าคำร้องของคุณ — เปิดในแท็บใหม่ ไม่ต้องเข้าสู่ระบบอีก",
+  ringOpen: "เปิดเพื่อรับสาย",
+  ringDecline: "ไม่รับ",
+  ringOpened: "เปิดหน้ารับสายแล้ว — กด รับสาย ในแท็บที่เปิดขึ้น",
+  ringBlocked: "เบราว์เซอร์บล็อกแท็บใหม่ — กดที่นี่เพื่อเปิดหน้ารับสาย",
+  ringClose: "ปิด",
+  ringTab: "📞 สายเข้า",
 };
 
 const en: Strings = {
@@ -258,6 +277,15 @@ const en: Strings = {
   requestLeavesWhat: "this page's activity log — it is for problem reports only",
   days: "{n} days",
   hours: "{n} hours",
+  ringTitle: "The support team is calling you",
+  ringAbout: "About {key} · {title}",
+  ringHow: "Answer on your request's page — it opens in a new tab, already signed in",
+  ringOpen: "Open to answer",
+  ringDecline: "Decline",
+  ringOpened: "Opened — press Answer in the new tab",
+  ringBlocked: "Your browser blocked the new tab — open the call here",
+  ringClose: "Close",
+  ringTab: "📞 Incoming call",
 };
 
 export function strings(locale: "th" | "en" | undefined): Strings {