@lightworkai.official/debug-capture 0.14.3 → 0.16.0

package/dist/ui/callFrame.d.ts

@@ -0,0 +1,63 @@
+/**
+ * The call, in this app — the support host's own call UI in a frame (0.16; the support host's docs/CALLS-PLAN.md §15).
+ *
+ * A reporter used to answer in a new tab on the support host: a hand-off, a popup a browser might block, and the app
+ * with the problem left behind just when the team asks to see it. Now the support host's `/embed/call` opens here, in a
+ * frame of our own — the same ring card, call corner, screen-sharing question and voice settings as its portal, so
+ * they never drift apart — signed in by the token the portal button uses, given the microphone, camera and screen.
+ *
+ * The frame says how to hold it (its messages, below): ready, its size and whether a moment covers the page, a drag
+ * of its top line, done, failed. We listen only to that frame's own window, from the support host's origin.
+ *
+ * Its own shadow root, like the ring card: it lands on pages we do not control. Marked as ours, so a report filed
+ * during a call does not photograph it.
+ */
+export type FrameLayout = "card" | "full";
+export interface FrameMessage {
+    source?: string;
+    type?: string;
+    width?: number;
+    height?: number;
+    layout?: FrameLayout;
+    phase?: "start" | "move" | "end";
+    x?: number;
+    y?: number;
+    reason?: string;
+}
+export interface FrameHandlers {
+    /** The call is on screen in the frame. */
+    ready(): void;
+    /** Nothing left to show — the frame is gone already. */
+    done(): void;
+    /** It could not sign in or never came up — the frame is gone; the caller's own card carries the call. */
+    failed(reason: string): void;
+}
+/** The support host's page for this call. Pure, for the tests. */
+export declare function frameUrl(supportHost: string, realmKey: string, token: string, id: string): string;
+/** Within the window, by at least the margin — a corner dragged off screen comes back. Pure, for the tests. */
+export declare function clampTo(p: {
+    x: number;
+    y: number;
+}, box: {
+    w: number;
+    h: number;
+}, view: {
+    w: number;
+    h: number;
+}): {
+    x: number;
+    y: number;
+};
+/** Is this message from our frame, about the call? */
+export declare function fromFrame(e: {
+    origin: string;
+    source: unknown;
+    data: unknown;
+}, expected: {
+    origin: string;
+    window: unknown;
+}): FrameMessage | null;
+export declare function callFrameFor(): string | null;
+/** Open the call's frame — once per call; the same call again changes nothing. Shown when it says it is ready. */
+export declare function openCallFrame(src: string, id: string, h: FrameHandlers, readyWithinMs?: number): void;
+export declare function closeCallFrame(): void;

package/dist/ui/ring.d.ts

@@ -0,0 +1,25 @@
+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;
+}
+/** "เรื่อง CALL-12 · title" — the line under the card's title. Pure, for the tests. */
+export declare function ringAbout(template: string, call: RingCall): string;
+/** Show the ring for this call — once; the same call again changes nothing. */
+export declare function showRing(call: RingCall, handlers: RingHandlers): void;
+/** Opened: the card says where to answer, and stops ringing. `blockedUrl` — the browser refused the tab: a link, which is a fresh press. */
+export declare function ringOpened(blockedUrl?: string): void;
+/**
+ * The call's own frame is up (ui/callFrame, 0.16): its ring card is the one to press, so ours steps out of sight —
+ * the ring and the title stay, rung from this page, until the call stops ringing. `false` brings ours back (the frame
+ * failed: our card carries the call again).
+ */
+export declare function quietRing(id: string, quiet?: boolean): void;
+/** The call is no longer ringing for this person — answered, declined, missed or ended. */
+export declare function hideRing(id?: string): void;
+export declare function ringShownFor(): string | null;

package/dist/ui/strings.d.ts

@@ -103,5 +103,15 @@ 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;
 }
 export declare function strings(locale: "th" | "en" | undefined): Strings;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lightworkai.official/debug-capture",
-  "version": "0.14.3",
+  "version": "0.16.0",
   "description": "Report-a-problem widget: rolling network/console/action capture, optional rrweb session replay, annotated screenshot, and submission to a Lightwork Support host",
   "type": "module",
   "module": "./dist/index.mjs",

package/src/config.ts

@@ -149,6 +149,32 @@ 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;
+
+  /**
+   * The call itself, in this app. Default true (0.16).
+   *
+   * When a call rings, the support host's own call — its ring card, its call
+   * corner, its screen-sharing question, its voice settings — opens in a frame
+   * in this page, signed in with the same token the portal button uses: the
+   * reporter answers, talks and shows their screen without leaving the app.
+   * The frame needs nothing of the host but leave to frame the support host and
+   * to give it the microphone, camera and screen (no `frame-src` or
+   * `Permissions-Policy` that forbids them). Should the frame not come up, the
+   * card of 0.15 carries the call: open the portal to answer. `false`: always that.
+   */
+  callFrame?: 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,291 @@
+/**
+ * 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 in THIS app since 0.16 (`callFrame`, default on): the
+ * support host's own call — ring card, call corner, screen sharing, voice
+ * settings — opens in a frame here (ui/callFrame), signed in by the same
+ * token the portal button uses; our card steps aside once the frame is up,
+ * and comes back if it never does. Before 0.16, and with `callFrame: false`,
+ * the card's button opens the reporter's request on the support host — 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, quietRing, ringOpened, ringShownFor, showRing } from "./ui/ring";
+import { callFrameFor, closeCallFrame, frameUrl, openCallFrame } from "./ui/callFrame";
+
+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 LIVE_STATES = new Set(["ringing", "active"]);
+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();
+  closeCallFrame();
+}
+
+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 call this tab holds in its frame — taken back after a reload, so the call goes on. */
+const FRAMED_KEY = "lw-call-framed";
+function framedHere(): string | null {
+  try {
+    return sessionStorage.getItem(FRAMED_KEY);
+  } catch {
+    return null;
+  }
+}
+function markFramed(id: string | null): void {
+  try {
+    if (id) sessionStorage.setItem(FRAMED_KEY, id);
+    else sessionStorage.removeItem(FRAMED_KEY);
+  } catch {
+    /* this tab only, when it can */
+  }
+}
+
+let framing: string | null = null;
+/** The call in a frame here (0.16): the support host's own call UI, signed in with the host's token. */
+async function frameFor(call: RingingCall): Promise<void> {
+  const config = getConfig();
+  if (config.callFrame === false || callFrameFor() === call.id || framing === call.id) return;
+  framing = call.id;
+  const token = await hostToken();
+  framing = null;
+  if (!token) return;
+  markFramed(call.id);
+  openCallFrame(frameUrl(config.host, config.realmKey, token, call.id), call.id, {
+    ready: () => quietRing(call.id),
+    done: () => {
+      markFramed(null);
+      hideRing(call.id);
+    },
+    // Our card carries the call again — still ringing, its button opens the portal to answer.
+    failed: () => {
+      markFramed(null);
+      quietRing(call.id, false);
+    },
+  });
+}
+
+/** The support host's word on a call: ringing here shows the card (and its frame); anything else takes the card away — the frame stays, it IS the call. */
+function hear(call: RingingCall): void {
+  if (!ringsHere(call)) {
+    hideRing(call.id);
+    // Answered in this tab's frame, then the page reloaded: the frame comes back and takes the call back.
+    if (call.status === "active" && framedHere() === call.id && !callFrameFor()) void frameFor(call);
+    // Over: the frame says its last word and goes — and goes anyway if it cannot.
+    if (!LIVE_STATES.has(call.status) && callFrameFor() === call.id) {
+      setTimeout(() => {
+        if (callFrameFor() === call.id) {
+          closeCallFrame();
+          markFramed(null);
+        }
+      }, 12_000);
+    }
+    return;
+  }
+  showRing(call, { open: () => answer(call), decline: () => void decline(call) });
+  void frameFor(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") {