@tribe-nest/forge 3.65.0 → 3.67.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tribe-nest/forge",
-  "version": "3.65.0",
+  "version": "3.67.0",
   "publishConfig": {
     "access": "public"
   },

package/src/data/queries/useWebsite.ts

@@ -1,10 +1,11 @@
 import type { WebPage } from "../../types";
-import { useForge } from "../../provider/ForgeProvider";
+import { useContext } from "react";
+import { useForge, useOptionalForge } from "../../provider/ForgeProvider";
 import { useInitialSiteConfig } from "../../provider/SiteConfigProvider";
-import { keepPreviousData, useMutation, useQuery } from "@tanstack/react-query";
+import { keepPreviousData, QueryClientContext, useMutation, useQuery } from "@tanstack/react-query";
 
 export interface SiteConfig {
-  /** The tenant's settlement currency (e.g. "USD") — the currency API amounts
+  /** The tenant's settlement currency (e.g. "USD"): the currency API amounts
    * are in and payments are charged in. */
   currency: string;
   /** The language the tenant speaks ("en" | "de" today), from
@@ -16,7 +17,7 @@ export interface SiteConfig {
   locale?: string;
   /** Sales-tax display mode: true = listing prices already contain tax
    * ("incl. VAT" style, EU/UK), false/absent = tax added at checkout (US).
-   * Display-only — checkout totals come from the authoritative taxQuote. */
+   * Display-only: checkout totals come from the authoritative taxQuote. */
   pricesIncludeTax?: boolean;
   metaPixelId: string | null;
   stripeAccountId: string | null;
@@ -29,7 +30,7 @@ export interface SiteConfig {
   /** Whether Altcha proof-of-work bot protection is active. Self-hosted, so it
    * works on every tenant subdomain + custom domain with no per-domain config. */
   altchaEnabled?: boolean;
-  /** The creator's site display name — the manifest `name` fallback when the
+  /** The creator's site display name: the manifest `name` fallback when the
    * PWA identity has no explicit name. */
   siteName?: string | null;
   /** The profile-level PWA identity (icons/name/screenshots) used to build the
@@ -38,10 +39,21 @@ export interface SiteConfig {
   pwa?: PwaConfig | null;
   /** Suppresses the "Powered by TribeNest" badge on released builds. Server-side
    * on purpose: the tenant owns `__root.tsx`, so anything expressed as a prop is
-   * an opt-out. Absent/false today — this is the lever a white-label plan
+   * an opt-out. Absent/false today. This is the lever a white-label plan
    * entitlement flips, and it works without waiting for a Forge bump to reach
    * every site. */
   hideTribeNestBadge?: boolean;
+  /** The privacy policy and terms of the brand the site is sold under
+   * (TribeNest's, or Mandatera's for a law firm). What a site with no policy of
+   * its own links to. Optional because an older backend sends no such field,
+   * and every reader then falls back to TribeNest's. */
+  legalUrls?: BrandLegalUrls | null;
+}
+
+/** The brand's hosted legal pages, from `site-config`. */
+export interface BrandLegalUrls {
+  privacy: string;
+  terms: string;
 }
 
 /** The PWA identity block on `site-config` (mirrors `pwaConfig` on the profile). */
@@ -58,13 +70,13 @@ export interface PwaConfig {
 
 /**
  * The tenant's mutable runtime config (settlement currency, Meta Pixel id,
- * payment provider). Fetched at runtime — NOT baked into the build — so a
+ * payment provider). Fetched at runtime (NOT baked into the build) so a
  * creator can change these in settings and the live site reflects them without
  * a rebuild/redeploy.
  *
  * If a `<SiteConfigProvider>` seeded an SSR-fetched value (see `fetchSiteConfig`
  * in `@tribe-nest/forge/server`), it's used as `initialData` so the config is
- * present on the first render — no client-fetch flash, no hydration mismatch.
+ * present on the first render: no client-fetch flash, no hydration mismatch.
  * An explicit `initialData` override still wins.
  */
 export function useSiteConfig(opts?: { initialData?: SiteConfig }) {
@@ -79,10 +91,29 @@ export function useSiteConfig(opts?: { initialData?: SiteConfig }) {
     },
     enabled: !!client && !!profileId,
     initialData: opts?.initialData ?? ssrInitial,
-    staleTime: 1000 * 60 * 5, // 5 min — settings change rarely; refetch keeps it fresh
+    staleTime: 1000 * 60 * 5, // 5 min: settings change rarely; refetch keeps it fresh
   });
 }
 
+/**
+ * The brand's hosted legal pages (`site-config.legalUrls`), or `undefined` when
+ * they are not known yet.
+ *
+ * Safe outside a `<ForgeProvider>` (returns `undefined`), because the components
+ * that read it (`CookieConsent`, `MusicLinkPage`) are also rendered standalone.
+ * Reads the SSR-seeded config first, then whatever `useSiteConfig` has cached;
+ * it never starts a fetch of its own.
+ */
+export function useBrandLegalUrls(): BrandLegalUrls | undefined {
+  const ssrInitial = useInitialSiteConfig();
+  const forge = useOptionalForge();
+  const queryClient = useContext(QueryClientContext);
+  const cached = forge?.profileId
+    ? queryClient?.getQueryData<SiteConfig>(["site-config", forge.profileId])
+    : undefined;
+  return cached?.legalUrls ?? ssrInitial?.legalUrls ?? undefined;
+}
+
 /**
  * The store's tax display mode from site config: true = prices shown to the
  * buyer already include tax (inclusive/EU display), false = tax is added at
@@ -96,7 +127,7 @@ export function usePricesIncludeTax(): boolean {
 
 // Tax-aware price rendering primitive, re-exported here (a file the root barrel
 // already star-exports) so `@tribe-nest/frontend-shared` and app code can import
-// it from "@tribe-nest/forge". Its home is `ui/format/PriceDisplay` — the
+// it from "@tribe-nest/forge". Its home is `ui/format/PriceDisplay`, and the
 // `forge/ui` barrel should export it from there as well.
 export {
   PriceDisplay,
@@ -118,7 +149,7 @@ export function useSubmitContactForm() {
 }
 
 /**
- * The rendered web page for a pathname — either the published site (by
+ * The rendered web page for a pathname: either the published site (by
  * subdomain) or a preview (by token). Keeps the previous page during navigation
  * to avoid a white flash.
  */

package/src/data/queries/useWebsiteAgent.ts

@@ -3,23 +3,33 @@ import { useQuery } from "@tanstack/react-query";
 
 export interface WebsiteAgentConfig {
   enabled: boolean;
+  /** The agent that answers on this website. */
+  agentId?: string;
   displayName?: string;
+  /** The agent's language, for example "en" or "de". */
+  language?: string;
   greeting?: string | null;
   allowAnonymous?: boolean;
   allowOrderLookup?: boolean;
   allowLeadCapture?: boolean;
   /** Paths the widget must not appear on. "/blog/*" covers every child. */
   excludedPaths?: string[];
+  /** The agent also takes calls from the browser: show "Call us". */
+  voiceEnabled?: boolean;
 }
 
-/** Widget bootstrap config for the profile. When `enabled` is false the widget
- * should render nothing. */
+/** Widget bootstrap config for the website. When `enabled` is false the widget
+ * should render nothing. `websiteId` picks the agent of THIS website, since a
+ * profile with several sites can give each its own; without it the backend
+ * answers with the profile's default agent. */
 export function useWebsiteAgentConfig() {
-  const { client, profileId } = useForge();
+  const { client, profileId, websiteId } = useForge();
   return useQuery<WebsiteAgentConfig>({
-    queryKey: ["website-agent-config", profileId],
+    queryKey: ["website-agent-config", profileId, websiteId ?? null],
     queryFn: async () => {
-      const res = await client.get(`/public/agent/config`, { params: { profileId } });
+      const res = await client.get(`/public/agent/config`, {
+        params: { profileId, ...(websiteId ? { websiteId } : {}) },
+      });
       return res.data;
     },
     enabled: !!profileId && !!client,
@@ -88,6 +98,7 @@ export async function createAgentConversation(params: {
   apiUrl: string;
   token?: string | null;
   profileId: string;
+  websiteId?: string;
   visitorId: string;
 }): Promise<{ id: string | null; requiresLogin?: boolean }> {
   const res = await fetch(`${params.apiUrl}/public/agent/conversations`, {
@@ -96,7 +107,126 @@ export async function createAgentConversation(params: {
       "Content-Type": "application/json",
       ...(params.token ? { authorization: `Bearer ${params.token}` } : {}),
     },
-    body: JSON.stringify({ profileId: params.profileId, visitorId: params.visitorId }),
+    body: JSON.stringify({
+      profileId: params.profileId,
+      ...(params.websiteId ? { websiteId: params.websiteId } : {}),
+      visitorId: params.visitorId,
+    }),
   });
   return res.json();
 }
+
+// "Call us": a call with the website's agent, from the browser.
+
+/** Where the call's media room is, and how to come back to it. */
+export interface AgentCallCredentials {
+  callId: string;
+  roomId: string;
+  mediaUrl: string;
+  token: string;
+  expiresAt: string;
+  /** This browser's seat in the room, reused on every reconnect. */
+  identity: string;
+  /** Proves this browser started the call: needed to rejoin or end it. */
+  callKey: string;
+}
+
+/** The bot check a call starts with. See `solveCallChallenge`. */
+export interface AgentCallChallenge {
+  challenge: string;
+  difficulty: number;
+  expiresAt: string;
+}
+
+/** A refused call request, with the HTTP status that says why. */
+export class AgentCallRequestError extends Error {
+  readonly status: number;
+  constructor(status: number, message: string) {
+    super(message);
+    this.name = "AgentCallRequestError";
+    this.status = status;
+  }
+}
+
+async function postAgentCall<T>(url: string, body: Record<string, unknown>, keepalive = false): Promise<T> {
+  let res: Response;
+  try {
+    res = await fetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body),
+      // Lets the request outlive the page, so leaving it still hangs up.
+      keepalive,
+    });
+  } catch (err) {
+    throw new AgentCallRequestError(0, err instanceof Error ? err.message : String(err));
+  }
+  const data = (await res.json().catch(() => null)) as (T & { message?: string }) | null;
+  if (!res.ok) throw new AgentCallRequestError(res.status, data?.message || res.statusText || "Request failed");
+  return data as T;
+}
+
+const withWebsite = (websiteId?: string) => (websiteId ? { websiteId } : {});
+
+/** Step 1: ask for a bot check. 404 when the website's agent takes no calls. */
+export function requestAgentCallChallenge(params: {
+  apiUrl: string;
+  profileId: string;
+  websiteId?: string;
+  visitorId: string;
+}): Promise<AgentCallChallenge> {
+  return postAgentCall(`${params.apiUrl}/public/agent/calls/challenge`, {
+    profileId: params.profileId,
+    ...withWebsite(params.websiteId),
+    visitorId: params.visitorId,
+  });
+}
+
+/**
+ * Step 2: start the call with the solved check. Refusals carry the status:
+ * 400 failed check, 429 over the limit, 404 not available, 409 the minutes or
+ * the lines are used up, 503 the call network is down.
+ */
+export function startAgentCall(params: {
+  apiUrl: string;
+  profileId: string;
+  websiteId?: string;
+  visitorId: string;
+  challenge: string;
+  solution: string;
+}): Promise<AgentCallCredentials> {
+  return postAgentCall(`${params.apiUrl}/public/agent/calls`, {
+    profileId: params.profileId,
+    ...withWebsite(params.websiteId),
+    visitorId: params.visitorId,
+    challenge: params.challenge,
+    solution: params.solution,
+  });
+}
+
+/** A fresh join ticket for a reconnect: a ticket expires in minutes. */
+export function joinAgentCall(params: {
+  apiUrl: string;
+  callId: string;
+  callKey: string;
+  identity: string;
+}): Promise<AgentCallCredentials> {
+  return postAgentCall(`${params.apiUrl}/public/agent/calls/${params.callId}/join`, {
+    callKey: params.callKey,
+    identity: params.identity,
+  });
+}
+
+/** Hangs up. `keepalive` for a page that is going away. */
+export function endAgentCall(params: {
+  apiUrl: string;
+  callId: string;
+  callKey: string;
+  keepalive?: boolean;
+}): Promise<{ ended: boolean }> {
+  return postAgentCall(
+    `${params.apiUrl}/public/agent/calls/${params.callId}/end`,
+    { callKey: params.callKey },
+    params.keepalive,
+  );
+}

package/src/i18n/de.json

@@ -185,8 +185,25 @@
   "forge.account_dashboard.waitlist_ticket_line_other": "{title} · {quantity} Tickets",
   "forge.account_dashboard.waitlists_empty": "Du stehst auf keiner Warteliste.",
   "forge.account_dashboard.waitlists_title": "Meine Wartelisten",
+  "forge.ai_agent_call_room.connecting": "Verbindung wird hergestellt…",
+  "forge.ai_agent_call_room.listening": "{name} hört zu",
+  "forge.ai_agent_call_room.no_mic": "Wir konnten dein Mikrofon nicht verwenden. Erlaube es in deinem Browser und ruf dann erneut an.",
+  "forge.ai_agent_call_room.speaking": "{name} spricht",
+  "forge.ai_agent_widget.aria_call": "Ruf uns an",
   "forge.ai_agent_widget.aria_close": "Schließen",
   "forge.ai_agent_widget.aria_open": "Chat-Assistent öffnen",
+  "forge.ai_agent_widget.aria_show_call": "Anruf anzeigen",
+  "forge.ai_agent_widget.call_again": "Erneut anrufen",
+  "forge.ai_agent_widget.call_back_to_chat": "Zurück zum Chat",
+  "forge.ai_agent_widget.call_connecting": "Verbindung wird hergestellt…",
+  "forge.ai_agent_widget.call_ended": "Anruf beendet.",
+  "forge.ai_agent_widget.call_error_busy": "Alle unsere Leitungen sind belegt. Bitte versuch es in ein paar Minuten noch einmal.",
+  "forge.ai_agent_widget.call_error_check_failed": "Wir konnten den Anruf nicht starten. Bitte versuch es noch einmal.",
+  "forge.ai_agent_widget.call_error_failed": "Wir konnten deinen Anruf nicht verbinden. Bitte versuch es noch einmal.",
+  "forge.ai_agent_widget.call_error_too_many": "Du hast in letzter Zeit mehrmals angerufen. Bitte versuch es später noch einmal.",
+  "forge.ai_agent_widget.call_error_unavailable": "Anrufe sind gerade nicht möglich.",
+  "forge.ai_agent_widget.call_hang_up": "Auflegen",
+  "forge.ai_agent_widget.call_try_again": "Erneut versuchen",
   "forge.ai_agent_widget.default_greeting": "Hi! Frag mich, was du willst.",
   "forge.ai_agent_widget.default_title": "Assistent",
   "forge.ai_agent_widget.input_placeholder": "Nachricht schreiben…",

package/src/i18n/en.json

@@ -185,8 +185,25 @@
   "forge.account_dashboard.waitlist_ticket_line_other": "{title} · {quantity} tickets",
   "forge.account_dashboard.waitlists_empty": "You're not on any waitlists.",
   "forge.account_dashboard.waitlists_title": "My Waitlists",
+  "forge.ai_agent_call_room.connecting": "Connecting…",
+  "forge.ai_agent_call_room.listening": "{name} is listening",
+  "forge.ai_agent_call_room.no_mic": "We could not use your microphone. Allow it in your browser, then call again.",
+  "forge.ai_agent_call_room.speaking": "{name} is speaking",
+  "forge.ai_agent_widget.aria_call": "Call us",
   "forge.ai_agent_widget.aria_close": "Close",
   "forge.ai_agent_widget.aria_open": "Open chat assistant",
+  "forge.ai_agent_widget.aria_show_call": "Show the call",
+  "forge.ai_agent_widget.call_again": "Call again",
+  "forge.ai_agent_widget.call_back_to_chat": "Back to chat",
+  "forge.ai_agent_widget.call_connecting": "Connecting…",
+  "forge.ai_agent_widget.call_ended": "Call ended.",
+  "forge.ai_agent_widget.call_error_busy": "All our lines are busy. Please try again in a few minutes.",
+  "forge.ai_agent_widget.call_error_check_failed": "We could not start the call. Please try again.",
+  "forge.ai_agent_widget.call_error_failed": "We could not connect your call. Please try again.",
+  "forge.ai_agent_widget.call_error_too_many": "You have called several times recently. Please try again later.",
+  "forge.ai_agent_widget.call_error_unavailable": "Calls are not available right now.",
+  "forge.ai_agent_widget.call_hang_up": "Hang up",
+  "forge.ai_agent_widget.call_try_again": "Try again",
   "forge.ai_agent_widget.default_greeting": "Hi! Ask me anything.",
   "forge.ai_agent_widget.default_title": "Assistant",
   "forge.ai_agent_widget.input_placeholder": "Type a message…",

package/src/provider/ForgeProvider.tsx

@@ -55,7 +55,7 @@ export interface ForgeClientProviderProps {
 }
 
 /**
- * Low-level tenant/client provider — supplies the `useForge()` context (Axios
+ * Low-level tenant/client provider: supplies the `useForge()` context (Axios
  * client, tenant ids, token). Most sites use the all-in-one `<ForgeProvider>`
  * (which wraps this plus query/content/auth/cart/audio/site-config/theme); reach
  * for `ForgeClientProvider` only when composing the tree yourself.
@@ -126,6 +126,12 @@ export const ForgeClientProvider = ({
   return <ForgeContext.Provider value={value}>{children}</ForgeContext.Provider>;
 };
 
+/**
+ * The Forge context, or `null` outside a `<ForgeProvider>`. For components that
+ * also render standalone and only enrich themselves when a provider is present.
+ */
+export const useOptionalForge = (): ForgeContextValue | null => useContext(ForgeContext);
+
 /** Access the Forge context. Throws if used outside a `<ForgeProvider>`. */
 export const useForge = (): ForgeContextValue => {
   const ctx = useContext(ForgeContext);

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

@@ -0,0 +1,85 @@
+import { createHash } from "node:crypto";
+import { describe, expect, it } from "vitest";
+import { leadingZeroBits, solveCallChallenge } from "../callChallenge";
+
+/**
+ * The bot check in front of "Call us". The backend (`callGuard.ts`) accepts a
+ * solution when SHA-256 of `${challenge}:${solution}` starts with `difficulty`
+ * zero bits, so the thing worth pinning is that what the browser finds is what
+ * the server would accept, checked here with Node's own hash rather than the
+ * Web Crypto the solver uses.
+ */
+
+function serverLeadingZeroBits(digest: Buffer): number {
+  let bits = 0;
+  for (const byte of digest) {
+    if (byte === 0) {
+      bits += 8;
+      continue;
+    }
+    let b = byte;
+    while ((b & 0x80) === 0) {
+      bits++;
+      b <<= 1;
+    }
+    break;
+  }
+  return bits;
+}
+
+describe("leadingZeroBits", () => {
+  it("counts whole zero bytes and the zero bits of the first non-zero byte", () => {
+    expect(leadingZeroBits(new Uint8Array([0xff]))).toBe(0);
+    expect(leadingZeroBits(new Uint8Array([0x01]))).toBe(7);
+    expect(leadingZeroBits(new Uint8Array([0x00, 0x80]))).toBe(8);
+    expect(leadingZeroBits(new Uint8Array([0x00, 0x00, 0x0f]))).toBe(20);
+  });
+
+  it("counts every bit of an all-zero digest", () => {
+    expect(leadingZeroBits(new Uint8Array(4))).toBe(32);
+  });
+});
+
+describe("solveCallChallenge", () => {
+  it("finds a solution the server's check accepts, at the production difficulty", async () => {
+    const challenge = "v1.eyJhIjoxfQ.c2ln";
+    const solution = await solveCallChallenge(challenge, 16);
+    expect(solution).toMatch(/^\d{1,12}$/);
+    const digest = createHash("sha256").update(`${challenge}:${solution}`).digest();
+    expect(serverLeadingZeroBits(digest)).toBeGreaterThanOrEqual(16);
+  });
+
+  it("returns the SMALLEST solution, so a batch boundary changes nothing", async () => {
+    const challenge = "small-batches";
+    const a = await solveCallChallenge(challenge, 10, { batchSize: 7, yieldToPage: async () => undefined });
+    const b = await solveCallChallenge(challenge, 10, { batchSize: 1000 });
+    expect(a).toBe(b);
+    for (let n = 0; n < Number(a); n++) {
+      const digest = createHash("sha256").update(`${challenge}:${n}`).digest();
+      expect(serverLeadingZeroBits(digest)).toBeLessThan(10);
+    }
+  });
+
+  it("gives the page a turn after every batch it did not solve in", async () => {
+    const solution = Number(await solveCallChallenge("yield-check", 12, { batchSize: 64 }));
+    let yields = 0;
+    await solveCallChallenge("yield-check", 12, {
+      batchSize: 64,
+      yieldToPage: async () => {
+        yields++;
+      },
+    });
+    expect(yields).toBe(Math.floor(solution / 64));
+  });
+
+  it("stops when the call is hung up while it works", async () => {
+    const controller = new AbortController();
+    const solving = solveCallChallenge("abort-me", 40, {
+      signal: controller.signal,
+      yieldToPage: async () => {
+        controller.abort();
+      },
+    });
+    await expect(solving).rejects.toMatchObject({ name: "AbortError" });
+  });
+});

package/src/ui/headless/agent/_tests/useAgentCall.spec.tsx

@@ -0,0 +1,213 @@
+// @vitest-environment jsdom
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { act, renderHook, waitFor } from "@testing-library/react";
+import type { ReactNode } from "react";
+import { ForgeClientProvider } from "../../../../provider/ForgeProvider";
+import { useAgentCall } from "../useAgentCall";
+
+/**
+ * "Call us", headless. Every call costs the business by the minute, so what
+ * is pinned here is the money-shaped part: the request sequence that starts a
+ * call, that a reconnect asks for a FRESH ticket with the identity the start
+ * gave, and that every way out (hang up, hang up mid-setup, leaving the page,
+ * unmounting) ends the call on the server.
+ */
+
+const API = "https://api.test";
+const PROFILE = "11111111-1111-4111-8111-111111111111";
+const WEBSITE = "22222222-2222-4222-8222-222222222222";
+
+const CALL = {
+  callId: "call-1",
+  roomId: "room-1",
+  mediaUrl: "wss://media.test",
+  token: "ticket-1",
+  expiresAt: "2026-10-05T12:00:00Z",
+  identity: "visitor-33333333-3333-4333-8333-333333333333",
+  callKey: "key-1",
+};
+
+type Route = (body: Record<string, unknown>) => { status: number; body: unknown };
+
+let routes: Record<string, Route>;
+let calls: { url: string; body: Record<string, unknown>; keepalive?: boolean }[];
+
+beforeEach(() => {
+  calls = [];
+  routes = {
+    "/public/agent/calls/challenge": () => ({ status: 201, body: { challenge: "c1", difficulty: 4, expiresAt: "x" } }),
+    "/public/agent/calls": () => ({ status: 201, body: CALL }),
+    "/public/agent/calls/call-1/join": () => ({ status: 201, body: { ...CALL, token: "ticket-2" } }),
+    "/public/agent/calls/call-1/end": () => ({ status: 201, body: { ended: true } }),
+  };
+  vi.stubGlobal(
+    "fetch",
+    vi.fn(async (url: string, init: RequestInit) => {
+      const path = url.replace(API, "");
+      const body = JSON.parse(String(init.body ?? "{}"));
+      calls.push({ url: path, body, keepalive: init.keepalive });
+      const route = routes[path];
+      const res = route ? route(body) : { status: 404, body: { message: "no route" } };
+      return new Response(JSON.stringify(res.body), { status: res.status, headers: { "Content-Type": "application/json" } });
+    }),
+  );
+});
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+const wrapper =
+  (websiteId?: string) =>
+  ({ children }: { children: ReactNode }) => (
+    <ForgeClientProvider apiUrl={API} profileId={PROFILE} websiteId={websiteId}>
+      {children}
+    </ForgeClientProvider>
+  );
+
+const mount = ({ websiteId }: { websiteId?: string } = { websiteId: WEBSITE }) =>
+  renderHook(() => useAgentCall({ visitorId: "visitor-a", solver: { yieldToPage: async () => undefined } }), {
+    wrapper: wrapper(websiteId),
+  });
+
+describe("useAgentCall: starting a call", () => {
+  it("asks for the check, solves it, and starts the call for THIS website", async () => {
+    const { result } = mount();
+    await act(() => result.current.start());
+
+    expect(result.current.state).toEqual({ phase: "live", call: CALL });
+    expect(calls.map((c) => c.url)).toEqual(["/public/agent/calls/challenge", "/public/agent/calls"]);
+    expect(calls[0].body).toEqual({ profileId: PROFILE, websiteId: WEBSITE, visitorId: "visitor-a" });
+    const start = calls[1].body;
+    expect(start).toMatchObject({ profileId: PROFILE, websiteId: WEBSITE, visitorId: "visitor-a", challenge: "c1" });
+    expect(String(start.solution)).toMatch(/^\d{1,12}$/);
+  });
+
+  it("leaves websiteId out when the site does not know it, so the profile's agent answers", async () => {
+    const { result } = mount({});
+    await act(() => result.current.start());
+    expect(calls[0].body).toEqual({ profileId: PROFILE, visitorId: "visitor-a" });
+    expect(calls[1].body).not.toHaveProperty("websiteId");
+  });
+
+  it.each([
+    [429, "too_many"],
+    [404, "unavailable"],
+    [409, "busy"],
+    [400, "check_failed"],
+    [503, "failed"],
+  ])("reports a %i refusal as %s, with the API's message", async (status, kind) => {
+    routes["/public/agent/calls"] = () => ({ status, body: { status, message: `refused ${status}` } });
+    const { result } = mount();
+    await act(() => result.current.start());
+    expect(result.current.state).toEqual({ phase: "error", error: kind, message: `refused ${status}` });
+  });
+
+  it("reports a refused CHALLENGE too (404: this site's agent takes no calls) without starting anything", async () => {
+    routes["/public/agent/calls/challenge"] = () => ({ status: 404, body: { message: "no calls" } });
+    const { result } = mount();
+    await act(() => result.current.start());
+    expect(result.current.state).toMatchObject({ phase: "error", error: "unavailable" });
+    expect(calls.map((c) => c.url)).toEqual(["/public/agent/calls/challenge"]);
+  });
+
+  it("can try again after an error", async () => {
+    routes["/public/agent/calls"] = () => ({ status: 409, body: { message: "busy" } });
+    const { result } = mount();
+    await act(() => result.current.start());
+    routes["/public/agent/calls"] = () => ({ status: 201, body: CALL });
+    await act(() => result.current.start());
+    expect(result.current.state.phase).toBe("live");
+  });
+
+  it("does not start a second call while one is connecting", async () => {
+    const { result } = mount();
+    await act(async () => {
+      void result.current.start();
+      void result.current.start();
+    });
+    await waitFor(() => expect(result.current.state.phase).toBe("live"));
+    expect(calls.filter((c) => c.url === "/public/agent/calls/challenge")).toHaveLength(1);
+  });
+});
+
+describe("useAgentCall: the media room's credentials", () => {
+  it("uses the start response first, then a fresh ticket per reconnect with the start's identity", async () => {
+    const { result } = mount();
+    await act(() => result.current.start());
+
+    await expect(result.current.getCredentials()).resolves.toEqual({ mediaUrl: CALL.mediaUrl, token: "ticket-1" });
+    expect(calls.some((c) => c.url.endsWith("/join"))).toBe(false);
+
+    await expect(result.current.getCredentials()).resolves.toEqual({ mediaUrl: CALL.mediaUrl, token: "ticket-2" });
+    const join = calls.find((c) => c.url === "/public/agent/calls/call-1/join");
+    expect(join?.body).toEqual({ callKey: CALL.callKey, identity: CALL.identity });
+  });
+});
+
+describe("useAgentCall: every way out ends the call on the server", () => {
+  it("hang up posts the end with the call key and shows the call ended", async () => {
+    const { result } = mount();
+    await act(() => result.current.start());
+    act(() => result.current.end());
+
+    expect(result.current.state).toEqual({ phase: "ended", callId: "call-1" });
+    await waitFor(() =>
+      expect(calls.find((c) => c.url === "/public/agent/calls/call-1/end")?.body).toEqual({ callKey: CALL.callKey }),
+    );
+  });
+
+  it("hanging up while the call is being set up ends the call the server then creates", async () => {
+    let releaseStart!: () => void;
+    const gate = new Promise<void>((resolve) => (releaseStart = resolve));
+    const fetchMock = globalThis.fetch as ReturnType<typeof vi.fn>;
+    const original = fetchMock.getMockImplementation()!;
+    fetchMock.mockImplementation(async (url: string, init: RequestInit) => {
+      if (url === `${API}/public/agent/calls`) await gate;
+      return original(url, init);
+    });
+
+    const { result } = mount();
+    let starting!: Promise<void>;
+    act(() => {
+      starting = result.current.start();
+    });
+    await waitFor(() => expect(calls.some((c) => c.url === "/public/agent/calls")).toBe(false));
+    act(() => result.current.end());
+    expect(result.current.state).toEqual({ phase: "idle" });
+
+    releaseStart();
+    await act(() => starting);
+    // Either the solver saw the abort before starting (nothing to end), or the
+    // start went out and the call it created is ended straight away. Never a
+    // live call nobody can hang up.
+    expect(result.current.state).toEqual({ phase: "idle" });
+    const started = calls.some((c) => c.url === "/public/agent/calls");
+    const ended = calls.some((c) => c.url === "/public/agent/calls/call-1/end");
+    expect(ended).toBe(started);
+  });
+
+  it("leaving the page ends the call with a request that outlives the page", async () => {
+    const { result } = mount();
+    await act(() => result.current.start());
+    act(() => {
+      window.dispatchEvent(new Event("pagehide"));
+    });
+    const end = calls.find((c) => c.url === "/public/agent/calls/call-1/end");
+    expect(end).toMatchObject({ body: { callKey: CALL.callKey }, keepalive: true });
+  });
+
+  it("unmounting ends the call", async () => {
+    const { result, unmount } = mount();
+    await act(() => result.current.start());
+    unmount();
+    expect(calls.filter((c) => c.url === "/public/agent/calls/call-1/end")).toHaveLength(1);
+  });
+
+  it("does not end anything when there is no call", () => {
+    const { unmount } = mount();
+    window.dispatchEvent(new Event("pagehide"));
+    unmount();
+    expect(calls).toEqual([]);
+  });
+});