@tribe-nest/forge 3.65.0 → 3.67.0

package/src/ui/headless/agent/callChallenge.ts

@@ -0,0 +1,72 @@
+/**
+ * The bot check in front of "Call us".
+ *
+ * A call costs real money per minute, so before the backend starts one it asks
+ * the browser to spend a second or so of work: find a decimal `solution` such
+ * that SHA-256 of `${challenge}:${solution}` starts with `difficulty` zero
+ * bits. One visitor barely notices; a script dialling thousands of calls pays
+ * for every one. The backend checks the same thing in `callGuard.ts`.
+ */
+
+/** How many zero bits the digest starts with. */
+export function leadingZeroBits(bytes: Uint8Array): number {
+  let bits = 0;
+  for (const byte of bytes) {
+    if (byte === 0) {
+      bits += 8;
+      continue;
+    }
+    return bits + Math.clz32(byte) - 24;
+  }
+  return bits;
+}
+
+/** The backend accepts up to 12 digits. */
+const MAX_SOLUTION = 999_999_999_999;
+
+export interface SolveCallChallengeOptions {
+  /** Hashes per batch. Between batches the solver yields, so the page can paint. */
+  batchSize?: number;
+  signal?: AbortSignal;
+  /** How the solver gives the page a turn. Defaults to a zero timeout. */
+  yieldToPage?: () => Promise<void>;
+}
+
+const defaultYield = () => new Promise<void>((resolve) => setTimeout(resolve, 0));
+
+/**
+ * Finds the smallest solution. At the backend's difficulty of 16 that is about
+ * 65k hashes on average. `crypto.subtle` is async, so a batch is hashed in
+ * parallel and the solver then yields, which keeps a "Connecting" spinner
+ * turning while it works. Rejects with an `AbortError` when `signal` aborts.
+ */
+export async function solveCallChallenge(
+  challenge: string,
+  difficulty: number,
+  { batchSize = 512, signal, yieldToPage = defaultYield }: SolveCallChallengeOptions = {},
+): Promise<string> {
+  const subtle = globalThis.crypto?.subtle;
+  if (!subtle) throw new Error("This browser cannot run the call check.");
+  const encoder = new TextEncoder();
+
+  for (let start = 0; start <= MAX_SOLUTION; start += batchSize) {
+    if (signal?.aborted) throw abortError();
+    const end = Math.min(start + batchSize, MAX_SOLUTION + 1);
+    const candidates: number[] = [];
+    for (let n = start; n < end; n++) candidates.push(n);
+    const digests = await Promise.all(
+      candidates.map((n) => subtle.digest("SHA-256", encoder.encode(`${challenge}:${n}`))),
+    );
+    for (let i = 0; i < digests.length; i++) {
+      if (leadingZeroBits(new Uint8Array(digests[i])) >= difficulty) return String(candidates[i]);
+    }
+    await yieldToPage();
+  }
+  throw new Error("No solution found.");
+}
+
+function abortError(): Error {
+  const err = new Error("The call check was cancelled.");
+  err.name = "AbortError";
+  return err;
+}

package/src/ui/headless/agent/useAgentCall.ts

@@ -0,0 +1,189 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useForge } from "../../../provider/ForgeProvider";
+import {
+  AgentCallRequestError,
+  endAgentCall,
+  joinAgentCall,
+  requestAgentCallChallenge,
+  startAgentCall,
+  type AgentCallCredentials,
+} from "../../../data/queries/useWebsiteAgent";
+import { solveCallChallenge, type SolveCallChallengeOptions } from "./callChallenge";
+import { getAgentVisitorId } from "./visitorId";
+
+/**
+ * Why a call could not start, by what the backend said.
+ *
+ * - `too_many`: the visitor or their network called too often (429).
+ * - `unavailable`: this website's agent takes no calls (404).
+ * - `busy`: every line is taken, or the business's minutes are used up (409).
+ * - `check_failed`: the bot check was refused, usually an expired challenge (400).
+ * - `failed`: anything else, including the call network being down (503).
+ */
+export type AgentCallErrorKind = "too_many" | "unavailable" | "busy" | "check_failed" | "failed";
+
+export type AgentCallState =
+  | { phase: "idle" }
+  /** Asking for the bot check, solving it and starting the call. */
+  | { phase: "connecting" }
+  /** The call exists: join its media room with `getCredentials`. */
+  | { phase: "live"; call: AgentCallCredentials }
+  | { phase: "ended"; callId: string }
+  | { phase: "error"; error: AgentCallErrorKind; message: string };
+
+export function classifyAgentCallError(err: unknown): AgentCallErrorKind {
+  if (!(err instanceof AgentCallRequestError)) return "failed";
+  switch (err.status) {
+    case 429:
+      return "too_many";
+    case 404:
+      return "unavailable";
+    case 409:
+      return "busy";
+    case 400:
+      return "check_failed";
+    default:
+      return "failed";
+  }
+}
+
+export interface UseAgentCallOptions {
+  /** Defaults to the widget's own visitor id, which the chat uses too. */
+  visitorId?: string;
+  /** Passed to the bot-check solver; tests use it to keep the work small. */
+  solver?: SolveCallChallengeOptions;
+}
+
+/**
+ * Headless "Call us": a voice call with the website's agent, in the browser.
+ *
+ * `start()` asks for the bot check, solves it, and starts the call; the state
+ * then turns `live` and the UI mounts a `MediaRoomProvider` with
+ * `getCredentials`. The first connect uses the start response, and every
+ * reconnect after it fetches a fresh ticket, because a ticket expires in
+ * minutes. `end()` hangs up. Leaving the page, or unmounting the hook, hangs
+ * up too, so a forgotten tab does not hold a line that costs the business by
+ * the minute.
+ *
+ * This hook has no media code in it on purpose: the room lives in the UI that
+ * mounts on `live`, which a site can load lazily.
+ */
+export function useAgentCall(options: UseAgentCallOptions = {}) {
+  const { apiUrl, profileId, websiteId } = useForge();
+  const visitorId = useMemo(() => options.visitorId ?? getAgentVisitorId(), [options.visitorId]);
+  const [state, setState] = useState<AgentCallState>({ phase: "idle" });
+
+  // Refs, so hanging up from `pagehide` or an unmount reads the call as it is
+  // NOW rather than as it was when the listener was attached.
+  const apiUrlRef = useRef(apiUrl);
+  apiUrlRef.current = apiUrl;
+  const solverRef = useRef(options.solver);
+  solverRef.current = options.solver;
+  const callRef = useRef<AgentCallCredentials | null>(null);
+  const firstCredentials = useRef<AgentCallCredentials | null>(null);
+  const runRef = useRef<AbortController | null>(null);
+
+  const start = useCallback(async () => {
+    if (!apiUrl || !profileId || runRef.current) return;
+    const run = new AbortController();
+    runRef.current = run;
+    setState({ phase: "connecting" });
+    try {
+      const check = await requestAgentCallChallenge({ apiUrl, profileId, websiteId, visitorId });
+      const solution = await solveCallChallenge(check.challenge, check.difficulty, {
+        ...solverRef.current,
+        signal: run.signal,
+      });
+      if (run.signal.aborted) return;
+      const call = await startAgentCall({
+        apiUrl,
+        profileId,
+        websiteId,
+        visitorId,
+        challenge: check.challenge,
+        solution,
+      });
+      if (run.signal.aborted) {
+        // Hung up while the call was being set up: it exists now, so end it.
+        void endAgentCall({ apiUrl, callId: call.callId, callKey: call.callKey }).catch(() => undefined);
+        return;
+      }
+      callRef.current = call;
+      firstCredentials.current = call;
+      setState({ phase: "live", call });
+    } catch (err) {
+      if (run.signal.aborted) return;
+      runRef.current = null;
+      setState({
+        phase: "error",
+        error: classifyAgentCallError(err),
+        message: err instanceof Error ? err.message : String(err),
+      });
+    }
+  }, [apiUrl, profileId, websiteId, visitorId]);
+
+  /** Hangs up, or stops a call that is still connecting. */
+  const end = useCallback(() => {
+    const run = runRef.current;
+    runRef.current = null;
+    run?.abort();
+    const call = callRef.current;
+    callRef.current = null;
+    firstCredentials.current = null;
+    if (call) {
+      void endAgentCall({ apiUrl: apiUrlRef.current, callId: call.callId, callKey: call.callKey }).catch(
+        () => undefined,
+      );
+      setState({ phase: "ended", callId: call.callId });
+    } else {
+      setState({ phase: "idle" });
+    }
+  }, []);
+
+  /** Back to idle from `ended` or `error`, ready for another call. */
+  const reset = useCallback(() => {
+    if (runRef.current) return;
+    setState({ phase: "idle" });
+  }, []);
+
+  const getCredentials = useCallback(async () => {
+    const first = firstCredentials.current;
+    if (first) {
+      firstCredentials.current = null;
+      return { mediaUrl: first.mediaUrl, token: first.token };
+    }
+    const call = callRef.current;
+    if (!call) throw new Error("The call has ended.");
+    const fresh = await joinAgentCall({
+      apiUrl: apiUrlRef.current,
+      callId: call.callId,
+      callKey: call.callKey,
+      identity: call.identity,
+    });
+    return { mediaUrl: fresh.mediaUrl, token: fresh.token };
+  }, []);
+
+  useEffect(() => {
+    if (typeof window === "undefined") return;
+    const hangUpOnLeave = () => {
+      runRef.current?.abort();
+      runRef.current = null;
+      const call = callRef.current;
+      if (!call) return;
+      callRef.current = null;
+      void endAgentCall({
+        apiUrl: apiUrlRef.current,
+        callId: call.callId,
+        callKey: call.callKey,
+        keepalive: true,
+      }).catch(() => undefined);
+    };
+    window.addEventListener("pagehide", hangUpOnLeave);
+    return () => {
+      window.removeEventListener("pagehide", hangUpOnLeave);
+      hangUpOnLeave();
+    };
+  }, []);
+
+  return { state, start, end, reset, getCredentials, visitorId };
+}

package/src/ui/headless/agent/useAgentCallRoom.ts

@@ -0,0 +1,113 @@
+import { useEffect, useRef, useState } from "react";
+import { useLocalMedia, useMediaRoom, useRemoteTrack, useRoomState, useVisibleProducers } from "../../media";
+
+/**
+ * What a call with the agent looks like from inside its media room.
+ *
+ * - `connecting`: joining the room, or waiting for the agent to arrive.
+ * - `listening`: the agent is there and quiet, so it is the caller's turn.
+ * - `speaking`: the agent's audio is audible right now.
+ * - `no_mic`: the browser refused the microphone.
+ */
+export type AgentCallRoomStatus = "connecting" | "listening" | "speaking" | "no_mic";
+
+/**
+ * Inside a `MediaRoomProvider`: publishes the microphone once joined, finds
+ * the agent's audio, and says when the call is over from the room's side (the
+ * agent left, or the room closed), so the caller does not sit on a dead line.
+ *
+ * Imports the media module, so only load it with the call UI.
+ */
+export function useAgentCallRoom({ selfIdentity, onEnded }: { selfIdentity: string; onEnded: () => void }) {
+  const room = useRoomState();
+  const { connectionState } = useMediaRoom();
+  const local = useLocalMedia();
+  const producers = useVisibleProducers();
+  const [micError, setMicError] = useState<string | null>(null);
+  const [agentSpeaking, setAgentSpeaking] = useState(false);
+  const published = useRef(false);
+  const agentWasHere = useRef(false);
+  const onEndedRef = useRef(onEnded);
+  onEndedRef.current = onEnded;
+
+  // The browser asks for the microphone here, once in the room. Its own echo
+  // cancellation keeps the agent from hearing itself through the speakers.
+  useEffect(() => {
+    if (room.phase !== "joined" || published.current) return;
+    published.current = true;
+    local.publishMicrophone().catch((err: unknown) => {
+      published.current = false;
+      setMicError(err instanceof Error ? err.message : String(err));
+    });
+  }, [room.phase, local]);
+
+  const agentHere = room.peers.some((p) => p.identity !== selfIdentity);
+  const agentAudioProducerIds = producers
+    .filter((p) => p.kind === "audio" && p.identity !== selfIdentity)
+    .map((p) => p.producerId);
+
+  useEffect(() => {
+    if (agentHere) agentWasHere.current = true;
+    else if (agentWasHere.current) onEndedRef.current();
+  }, [agentHere]);
+
+  useEffect(() => {
+    if (connectionState === "closed") onEndedRef.current();
+  }, [connectionState]);
+
+  const status: AgentCallRoomStatus = micError
+    ? "no_mic"
+    : room.phase !== "joined" || !agentHere
+      ? "connecting"
+      : agentSpeaking
+        ? "speaking"
+        : "listening";
+
+  return { status, micError, agentAudioProducerIds, setAgentSpeaking };
+}
+
+/** How loud (RMS, 0 to 1) the agent's audio must be to count as speaking. */
+const SPEAKING_LEVEL = 0.01;
+/** How long below that before it counts as silent again, so a pause between
+ * words does not flicker the status. */
+const SPEAKING_HOLD_MS = 400;
+
+/**
+ * Plays one of the agent's audio producers and reports whether it is audible.
+ * Returns the ref for an `<audio autoPlay>` element. Measured in the browser
+ * because the node's speaker ranking is for people, and an agent is not in it.
+ */
+export function useAgentAudio(producerId: string, onSpeaking: (speaking: boolean) => void) {
+  const { track, attach } = useRemoteTrack(producerId);
+  const mediaTrack = track?.track ?? null;
+
+  useEffect(() => {
+    if (!mediaTrack || typeof AudioContext === "undefined") return;
+    const context = new AudioContext();
+    const analyser = context.createAnalyser();
+    analyser.fftSize = 512;
+    context.createMediaStreamSource(new MediaStream([mediaTrack])).connect(analyser);
+    const samples = new Float32Array(analyser.fftSize);
+    let lastLoudAt = 0;
+    let speaking = false;
+    const timer = window.setInterval(() => {
+      analyser.getFloatTimeDomainData(samples);
+      let sum = 0;
+      for (const sample of samples) sum += sample * sample;
+      const now = performance.now();
+      if (Math.sqrt(sum / samples.length) > SPEAKING_LEVEL) lastLoudAt = now;
+      const next = now - lastLoudAt < SPEAKING_HOLD_MS;
+      if (next !== speaking) {
+        speaking = next;
+        onSpeaking(next);
+      }
+    }, 100);
+    return () => {
+      window.clearInterval(timer);
+      onSpeaking(false);
+      void context.close();
+    };
+  }, [mediaTrack, onSpeaking]);
+
+  return attach;
+}

package/src/ui/headless/agent/useAiAgent.ts

@@ -7,35 +7,20 @@ import {
 } from "../../../data/queries/useWebsiteAgent";
 import { isPathExcluded } from "./pathExclusion";
 import { useCurrentPath } from "./useCurrentPath";
+import { getAgentVisitorId } from "./visitorId";
 
 export interface AiAgentMessage {
   role: "user" | "assistant";
   text: string;
 }
 
-const VISITOR_KEY = "forge_agent_visitor_id";
-
-function getVisitorId(): string {
-  if (typeof window === "undefined") return "ssr";
-  try {
-    let id = window.localStorage.getItem(VISITOR_KEY);
-    if (!id) {
-      id = (window.crypto?.randomUUID?.() ?? `v_${Date.now()}_${Math.random().toString(36).slice(2)}`);
-      window.localStorage.setItem(VISITOR_KEY, id);
-    }
-    return id;
-  } catch {
-    return `v_${Date.now()}`;
-  }
-}
-
 /**
  * Headless controller for the website AI agent widget. Owns visitor identity,
  * the conversation (created lazily on first send), the message list, and the
  * streaming turn. A site can build any UI on top of this.
  */
 export function useAiAgent() {
-  const { apiUrl, profileId, token } = useForge();
+  const { apiUrl, profileId, websiteId, token } = useForge();
   const config = useWebsiteAgentConfig();
   const path = useCurrentPath();
 
@@ -43,15 +28,15 @@ export function useAiAgent() {
   const [sending, setSending] = useState(false);
   const [error, setError] = useState<string | null>(null);
   const conversationIdRef = useRef<string | null>(null);
-  const visitorId = useMemo(getVisitorId, []);
+  const visitorId = useMemo(getAgentVisitorId, []);
 
   const ensureConversation = useCallback(async (): Promise<string | null> => {
     if (conversationIdRef.current) return conversationIdRef.current;
     if (!apiUrl || !profileId) return null;
-    const res = await createAgentConversation({ apiUrl, token, profileId, visitorId });
+    const res = await createAgentConversation({ apiUrl, token, profileId, websiteId, visitorId });
     conversationIdRef.current = res.id;
     return res.id;
-  }, [apiUrl, profileId, token, visitorId]);
+  }, [apiUrl, profileId, websiteId, token, visitorId]);
 
   const send = useCallback(
     async (text: string) => {
@@ -107,6 +92,9 @@ export function useAiAgent() {
     config: config.data,
     isEnabled: !!config.data?.enabled && !excluded,
     loading: config.isLoading,
+    /** "Call us": the agent takes calls from the browser. See `useAgentCall`. */
+    canCall: !!config.data?.enabled && !!config.data?.voiceEnabled && !excluded,
+    visitorId,
     messages,
     sending,
     error,

package/src/ui/headless/agent/visitorId.ts

@@ -0,0 +1,20 @@
+const VISITOR_KEY = "forge_agent_visitor_id";
+
+/**
+ * The widget's anonymous visitor id, kept in localStorage so a returning
+ * visitor keeps their conversations. Chat and calls share it, which is also
+ * what the per-visitor call limit counts.
+ */
+export function getAgentVisitorId(): string {
+  if (typeof window === "undefined") return "ssr";
+  try {
+    let id = window.localStorage.getItem(VISITOR_KEY);
+    if (!id) {
+      id = window.crypto?.randomUUID?.() ?? `v_${Date.now()}_${Math.random().toString(36).slice(2)}`;
+      window.localStorage.setItem(VISITOR_KEY, id);
+    }
+    return id;
+  } catch {
+    return `v_${Date.now()}`;
+  }
+}

package/src/ui/index.ts

@@ -206,6 +206,17 @@ export { NewDmDialog, type NewDmDialogProps } from "./styled/chat/NewDmDialog";
 export { AiAgentWidget, type AiAgentWidgetProps } from "./styled/AiAgentWidget";
 export { Markdown } from "./styled/Markdown";
 export { useAiAgent, type AiAgentMessage } from "./headless/agent/useAiAgent";
+// "Call us". The room hook (`useAgentCallRoom`) is deliberately not exported
+// here: it imports the media SDK, and this entry is on every page. A custom
+// call UI imports the media hooks from `@tribe-nest/forge/media` itself.
+export {
+  useAgentCall,
+  classifyAgentCallError,
+  type AgentCallState,
+  type AgentCallErrorKind,
+  type UseAgentCallOptions,
+} from "./headless/agent/useAgentCall";
+export { solveCallChallenge, leadingZeroBits, type SolveCallChallengeOptions } from "./headless/agent/callChallenge";
 export { InvoicePayment, type InvoicePaymentProps } from "./styled/InvoicePayment";
 export { PaymentLinkPayment, type PaymentLinkPaymentProps } from "./styled/PaymentLinkPayment";
 export { BlogList, type BlogListProps } from "./styled/BlogList";

package/src/ui/styled/AiAgentCallRoom.tsx

@@ -0,0 +1,76 @@
+import { useEffect, type ReactNode } from "react";
+import { useForgeT } from "../../i18n";
+import { MediaRoomProvider } from "../media";
+import { useAgentAudio, useAgentCallRoom, type AgentCallRoomStatus } from "../headless/agent/useAgentCallRoom";
+
+export interface AiAgentCallRoomProps {
+  getCredentials: () => Promise<{ mediaUrl: string; token: string }>;
+  /** This browser's identity in the room, from the start response. */
+  selfIdentity: string;
+  /** The agent's name, for the status line. */
+  agentName: string;
+  /** The room says the call is over: the agent left, or the room closed. */
+  onEnded: () => void;
+  /** Told every status change, so the widget can style around it. */
+  onStatus?: (status: AgentCallRoomStatus) => void;
+}
+
+/**
+ * The live half of "Call us": the media room, the microphone out and the
+ * agent's voice in.
+ *
+ * A DEFAULT export on purpose. `AiAgentWidget` is on every page of every site
+ * and reaches this through `React.lazy(() => import(...))`, so the media SDK
+ * and mediasoup are fetched only by a visitor who actually presses Call.
+ */
+export default function AiAgentCallRoom({ getCredentials, ...rest }: AiAgentCallRoomProps): ReactNode {
+  const t = useForgeT();
+  return (
+    <MediaRoomProvider
+      getCredentials={getCredentials}
+      fallback={<StatusLine text={t("forge.ai_agent_call_room.connecting")} />}
+    >
+      <LiveCall {...rest} />
+    </MediaRoomProvider>
+  );
+}
+
+function LiveCall({ selfIdentity, agentName, onEnded, onStatus }: Omit<AiAgentCallRoomProps, "getCredentials">) {
+  const t = useForgeT();
+  const { status, agentAudioProducerIds, setAgentSpeaking } = useAgentCallRoom({ selfIdentity, onEnded });
+
+  useEffect(() => {
+    onStatus?.(status);
+  }, [status, onStatus]);
+
+  const text =
+    status === "no_mic"
+      ? t("forge.ai_agent_call_room.no_mic")
+      : status === "speaking"
+        ? t("forge.ai_agent_call_room.speaking", { name: agentName })
+        : status === "listening"
+          ? t("forge.ai_agent_call_room.listening", { name: agentName })
+          : t("forge.ai_agent_call_room.connecting");
+
+  return (
+    <>
+      {agentAudioProducerIds.map((id) => (
+        <AgentAudio key={id} producerId={id} onSpeaking={setAgentSpeaking} />
+      ))}
+      <StatusLine text={text} alert={status === "no_mic"} />
+    </>
+  );
+}
+
+function AgentAudio({ producerId, onSpeaking }: { producerId: string; onSpeaking: (speaking: boolean) => void }) {
+  const attach = useAgentAudio(producerId, onSpeaking);
+  return <audio ref={attach} autoPlay data-testid="forge-agent-call-audio" />;
+}
+
+function StatusLine({ text, alert }: { text: string; alert?: boolean }) {
+  return (
+    <div role={alert ? "alert" : "status"} aria-live="polite" style={{ fontSize: 14, textAlign: "center" }} data-testid="forge-agent-call-status">
+      {text}
+    </div>
+  );
+}