@graph8/sdk 0.308.1 → 0.357.0

package/blocks/dialer/components/dialer-workspace.tsx

@@ -0,0 +1,47 @@
+"use client";
+
+/**
+ * DialerWorkspace: the whole rep screen. CallQueue on the left; on the right the Softphone, the outcome panel for
+ * the selected call, and the transcript of whatever was just worked. It owns the wiring between them: the
+ * conference from each confirmed batch goes to the Softphone, and a finished call opens the DispositionPanel.
+ *
+ * SDK operations: none of its own; see CallQueue, Softphone, DispositionPanel and TranscriptViewer for theirs.
+ */
+import { useMemo, useState } from "react";
+import { EmptyState } from "@/g8/components/empty-state";
+import { isLiveCall, needsDisposition, type LiveCall, type NextBatchResult } from "../lib/dialer-types";
+import type { SoftphoneTransport } from "../lib/softphone-transport";
+import { CallQueue } from "./call-queue";
+import { DispositionPanel } from "./disposition-panel";
+import { Softphone } from "./softphone";
+import { TranscriptViewer } from "./transcript-viewer";
+
+export interface DialerWorkspaceProps {
+  userId: string;
+  userEmail?: string;
+  listId?: string;
+  listTitle?: string;
+  sessionId?: string;
+  /** Your audio client, for example `createTwilioTransport()` created once. */
+  transport: SoftphoneTransport;
+  className?: string;
+}
+
+export function DialerWorkspace({ userId, userEmail, listId, listTitle, sessionId, transport, className }: DialerWorkspaceProps) {
+  const [calls, setCalls] = useState<LiveCall[]>([]);
+  const [selected, setSelected] = useState<LiveCall | null>(null);
+  const [batch, setBatch] = useState<NextBatchResult | null>(null);
+  const waiting = useMemo(() => calls.find(needsDisposition) ?? null, [calls]);
+  const focus = selected ?? waiting;
+
+  return (
+    <div className={`grid gap-4 lg:grid-cols-[minmax(0,3fr)_minmax(0,2fr)] ${className ?? ""}`}>
+      <CallQueue sessionId={sessionId} userId={userId} userEmail={userEmail} listId={listId} listTitle={listTitle} onBatch={setBatch} onCalls={setCalls} onSelectCall={setSelected} />
+      <div className="space-y-4">
+        <Softphone userId={userId} transport={transport} conferenceName={batch?.conference_name} joinMuted={(batch?.batch?.length ?? 1) > 1} />
+        <DispositionPanel key={`outcome-${focus?.call_id}`} call={focus} onSaved={() => setSelected(null)} />
+        {focus ? <TranscriptViewer key={`transcript-${focus.call_id}`} roomName={focus.room_name ?? focus.call_id} live={isLiveCall(focus)} /> : <EmptyState title="Nothing on screen" description="The transcript of the call you select shows here." />}
+      </div>
+    </div>
+  );
+}

package/blocks/dialer/components/disposition-panel.tsx

@@ -0,0 +1,75 @@
+"use client";
+
+/**
+ * DispositionPanel: record how a finished call went (connected, voicemail, callback, wrong number, ...).
+ *
+ * SDK operations, in order:
+ *   1. GET   /voice/dispositions                                          (voice.listVoiceDispositions)  read - the outcomes this org accepts
+ *   2. PATCH /dialer/parallel-calls/calls/{room_name}/disposition         (dialer.setCallDisposition)    write
+ * `room_name` is the call's `call_id` (they are the same value). Setting `callback_at` schedules a follow-up; it
+ * does not place the call. The session list refreshes by polling (CallQueue), so call `onSaved` to nudge it.
+ */
+import { useEffect, useState } from "react";
+import { Button, Input, Skeleton, Textarea } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { EmptyState } from "@/g8/components/empty-state";
+import { g8Patch } from "@/g8/lib/g8-client";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useDispositions } from "../hooks/use-dispositions";
+import { contactName, type LiveCall } from "../lib/dialer-types";
+
+export interface DispositionPanelProps {
+  /** The finished call to classify (a row from CallQueue). */
+  call: Pick<LiveCall, "call_id" | "first_name" | "last_name" | "email" | "to_phone" | "disposition"> | null;
+  onSaved?: (disposition: string) => void;
+  className?: string;
+}
+
+export function DispositionPanel({ call, onSaved, className }: DispositionPanelProps) {
+  const { options, loading, error, refetch } = useDispositions();
+  const [picked, setPicked] = useState<string | null>(null);
+  const [notes, setNotes] = useState("");
+  const [callbackAt, setCallbackAt] = useState("");
+
+  // Stale context: a different call starts with a clean form, never the previous call's outcome and notes.
+  useEffect(() => { setPicked(null); setNotes(""); setCallbackAt(""); }, [call?.call_id]);
+
+  const save = useG8Mutation(
+    async (disposition: string) => {
+      await g8Patch(`/dialer/parallel-calls/calls/${encodeURIComponent(call?.call_id ?? "")}/disposition`, {
+        disposition,
+        notes: notes.trim() || undefined,
+        callback_at: callbackAt ? new Date(callbackAt).toISOString() : undefined,
+      });
+      return disposition;
+    },
+    { onSuccess: (d) => { setPicked(null); setNotes(""); setCallbackAt(""); onSaved?.(d); } },
+  );
+
+  if (!call) return <EmptyState className={className} title="No call selected" description="Pick a finished call from the queue to record its outcome." />;
+  if (error) return <ApiError error={error} title="Could not load outcomes" onRetry={() => void refetch()} />;
+  if (loading) return <Skeleton className="h-32 w-full" aria-label="Loading outcomes" />;
+  const wantsCallback = picked != null && /callback|call_back|follow/.test(picked);
+
+  return (
+    <section className={`space-y-3 rounded-lg border p-4 ${className ?? ""}`} aria-label="Call outcome">
+      <header>
+        <h3 className="text-sm font-semibold">How did the call with {contactName(call)} go?</h3>
+        {call.disposition ? <p className="text-xs text-muted-foreground">Currently: {call.disposition}</p> : null}
+      </header>
+      <div role="radiogroup" aria-label="Outcome" className="flex flex-wrap gap-2">
+        {options.map((o) => (
+          <Button key={o.key} role="radio" aria-checked={picked === o.key} size="sm" variant={picked === o.key ? "default" : "outline"} onClick={() => setPicked(o.key)}>
+            {o.label}
+          </Button>
+        ))}
+      </div>
+      {wantsCallback ? <Input aria-label="Call back at" type="datetime-local" value={callbackAt} onChange={(e) => setCallbackAt(e.target.value)} /> : null}
+      <Textarea aria-label="Notes" rows={3} placeholder="Notes (optional)" value={notes} onChange={(e) => setNotes(e.target.value)} />
+      {save.error ? <ApiError error={save.error} title="Could not save the outcome" /> : null}
+      <Button disabled={!picked || save.loading} loading={save.loading} onClick={() => picked && void save.mutate(picked)}>
+        Save outcome
+      </Button>
+    </section>
+  );
+}

package/blocks/dialer/components/live-calls-table.tsx

@@ -0,0 +1,107 @@
+"use client";
+
+/**
+ * LiveCallsTable: the calls in the current session with hang-up, mute and voicemail-drop controls.
+ *
+ * SDK operations:
+ *   POST /dialer/sessions/calls/hangup          (dialer.hangupSessionCall)       write     - ends a call that is up
+ *   POST /dialer/sessions/calls/mute?call_id=   (dialer.muteCall)                write     - explicit muted true/false
+ *   POST /dialer/sessions/calls/drop-voicemail  (dialer.dropSessionVoicemail)    EXTERNAL  -> ConfirmSpendDialog first
+ *        plays the rep's cloned-voice recording to a real person's voicemail; there is no undo.
+ * The rows themselves come from useDialerSession (poll), not from this component.
+ */
+import { useState } from "react";
+import { Button, Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { EmptyState } from "@/g8/components/empty-state";
+import { g8Post } from "@/g8/lib/g8-client";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { contactName, isLiveCall, normalizeStatus, type LiveCall } from "../lib/dialer-types";
+
+export interface LiveCallsTableProps {
+  sessionId: string;
+  calls: LiveCall[];
+  /** Called after a control succeeded; refresh the session here. */
+  onChanged?: () => void;
+  /** Open a finished call's disposition panel. */
+  onSelect?: (call: LiveCall) => void;
+  className?: string;
+}
+
+export function LiveCallsTable({ sessionId, calls, onChanged, onSelect, className }: LiveCallsTableProps) {
+  const [voicemailFor, setVoicemailFor] = useState<LiveCall | null>(null);
+  // Per-row busy state: only the row being acted on is disabled, not every call in the table.
+  const [busy, setBusy] = useState<ReadonlySet<string>>(new Set());
+  const track = async <T,>(id: string, run: () => Promise<T>): Promise<T> => {
+    setBusy((b) => new Set(b).add(id));
+    try { return await run(); } finally { setBusy((b) => { const n = new Set(b); n.delete(id); return n; }); }
+  };
+  const hangup = useG8Mutation((call: LiveCall) => track(call.call_id, () => g8Post("/dialer/sessions/calls/hangup", { call_id: call.call_id, session_id: sessionId })), { onSuccess: () => onChanged?.() });
+  const [muted, setMuted] = useState<ReadonlySet<string>>(new Set());
+  const mute = useG8Mutation(
+    (v: { call: LiveCall; muted: boolean }) => track(v.call.call_id, async () => {
+      await g8Post("/dialer/sessions/calls/mute", undefined, { query: { call_id: v.call.call_id, muted: v.muted } });
+      setMuted((prev) => { const next = new Set(prev); if (v.muted) next.add(v.call.call_id); else next.delete(v.call.call_id); return next; });
+    }),
+  );
+  const voicemail = useG8Mutation((call: LiveCall) => track(call.call_id, () => g8Post("/dialer/sessions/calls/drop-voicemail", { call_id: call.call_id, session_id: sessionId })), {
+    onSuccess: () => { setVoicemailFor(null); onChanged?.(); },
+    onError: () => setVoicemailFor(null),
+  });
+  const failure = hangup.error ?? mute.error ?? voicemail.error;
+
+  if (calls.length === 0) {
+    return <EmptyState title="No calls yet" description="Calls appear here as soon as you dial the next batch." className={className} />;
+  }
+  return (
+    <div className={`space-y-2 ${className ?? ""}`}>
+      {failure ? <ApiError error={failure} title="That call control failed" /> : null}
+      <Table aria-label="Calls in this session">
+        <TableHeader>
+          <TableRow>
+            <TableHead>Contact</TableHead>
+            <TableHead>Number</TableHead>
+            <TableHead>Status</TableHead>
+            <TableHead className="text-right">Controls</TableHead>
+          </TableRow>
+        </TableHeader>
+        <TableBody>
+          {calls.map((call) => {
+            const live = isLiveCall(call);
+            const rowBusy = busy.has(call.call_id);
+            return (
+              <TableRow key={call.call_id} className={onSelect ? "cursor-pointer" : undefined} onClick={() => onSelect?.(call)}>
+                <TableCell className="font-medium">{contactName(call)}</TableCell>
+                <TableCell>{call.to_phone}</TableCell>
+                <TableCell className="capitalize">{call.is_voicemail ? "voicemail" : normalizeStatus(call.status)}{call.disposition ? ` · ${call.disposition}` : ""}</TableCell>
+                <TableCell className="space-x-1 text-right" onClick={(e) => e.stopPropagation()}>
+                  {live ? (
+                    <>
+                      <Button size="sm" variant="ghost" disabled={rowBusy} aria-label={`${muted.has(call.call_id) ? "Unmute" : "Mute"} ${contactName(call)}`} onClick={() => void mute.mutate({ call, muted: !muted.has(call.call_id) })}>
+                        {muted.has(call.call_id) ? "Unmute" : "Mute"}
+                      </Button>
+                      <Button size="sm" variant="ghost" disabled={rowBusy} aria-label={`Voicemail for ${contactName(call)}`} onClick={() => setVoicemailFor(call)}>Voicemail</Button>
+                      <Button size="sm" variant="outline" disabled={rowBusy} loading={rowBusy} aria-label={`Hang up ${contactName(call)}`} onClick={() => void hangup.mutate(call)}>Hang up</Button>
+                    </>
+                  ) : null}
+                </TableCell>
+              </TableRow>
+            );
+          })}
+        </TableBody>
+      </Table>
+      <ConfirmSpendDialog
+        open={voicemailFor != null}
+        tier="external"
+        title={`Leave a voicemail for ${voicemailFor ? contactName(voicemailFor) : "this contact"}?`}
+        description="Your recorded voicemail plays to their phone and the call ends. This cannot be undone, so check it is the right person."
+        confirmLabel="Drop voicemail"
+        recipients={1}
+        confirming={voicemail.loading}
+        onConfirm={() => voicemailFor && void voicemail.mutate(voicemailFor)}
+        onCancel={() => setVoicemailFor(null)}
+      />
+    </div>
+  );
+}

package/blocks/dialer/components/session-start-form.tsx

@@ -0,0 +1,111 @@
+"use client";
+
+/**
+ * SessionStartForm: create a DRAFT dialer session for a list. A draft dials NOBODY; dialing starts only when
+ * CallQueue's "Dial next batch" is confirmed.
+ *
+ * SDK operations, in order:
+ *   1. GET  /voice/dialer/numbers      (voice.listDialerNumbers)       read  - caller IDs and today's usage
+ *   2. POST /dialer/sessions/draft     (dialer.createSessionDraft)     write - safe: resolves the list, dials no one
+ * Calling the draft twice for the same list returns the existing live session instead of making a second one.
+ */
+import { useState } from "react";
+import { Button, Input, Label } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { g8Post } from "@/g8/lib/g8-client";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useDialerNumbers } from "../hooks/use-dialer-numbers";
+import { dataOf, type DialerMode } from "../lib/dialer-types";
+
+export interface SessionStartFormProps {
+  /** The rep these calls are attributed to. An organisation API key has no user of its own, so you name one. */
+  /** The rep these calls belong to. Optional so the form works as a nav page: when omitted the rep types their graph8 user id. */
+  userId?: string;
+  userEmail?: string;
+  /** Prefill from the lists block (ListPicker). */
+  listId?: string;
+  listTitle?: string;
+  onCreated: (session: { sessionId: string; mode: DialerMode; parallelCount: number; fromPhone: string }) => void;
+  className?: string;
+}
+
+export function SessionStartForm({ userId, userEmail, listId: initialListId = "", listTitle, onCreated, className }: SessionStartFormProps) {
+  const { numbers, loading, error, refetch } = useDialerNumbers();
+  const [listId, setListId] = useState(initialListId);
+  const [typedUserId, setTypedUserId] = useState("");
+  const repId = userId || typedUserId.trim();
+  const [fromPhone, setFromPhone] = useState("");
+  const [mode, setMode] = useState<DialerMode>("power");
+  const [parallelCount, setParallelCount] = useState(3);
+  const [name, setName] = useState(listTitle ? `Dialing ${listTitle}` : "");
+
+  const chosenPhone = fromPhone || numbers[0]?.phone_number || "";
+  const create = useG8Mutation(
+    async () => {
+      const count = mode === "parallel" ? Math.min(10, Math.max(2, Math.round(parallelCount) || 2)) : 1;
+      const env = await g8Post("/dialer/sessions/draft", {
+        user_id: repId,
+        user_email: userEmail,
+        list_id: listId,
+        list_title: listTitle,
+        name: name || undefined,
+        from_phone: chosenPhone || undefined,
+        dialing_mode: mode,
+        parallel_count: count,
+        user_timezone: Intl.DateTimeFormat().resolvedOptions().timeZone,
+      });
+      const sessionId = dataOf<{ session_id?: string }>(env).session_id;
+      if (!sessionId) throw new Error("graph8 did not return a session id");
+      return { sessionId, mode, parallelCount: count, fromPhone: chosenPhone };
+    },
+    { onSuccess: onCreated },
+  );
+
+  return (
+    <form className={`space-y-3 rounded-lg border p-4 ${className ?? ""}`} onSubmit={(e) => { e.preventDefault(); if (listId && repId) void create.mutate(undefined); }}>
+      <h3 className="text-sm font-semibold">Start a dialing session</h3>
+      <div className="grid gap-3 sm:grid-cols-2">
+        <div className="space-y-1">
+          <Label htmlFor="ds-list">List id</Label>
+          <Input id="ds-list" value={listId} onChange={(e) => setListId(e.target.value)} placeholder="From your lists" />
+        </div>
+        {userId ? null : (
+          <div className="space-y-1">
+            <Label htmlFor="ds-user">Rep user id</Label>
+            <Input id="ds-user" value={typedUserId} onChange={(e) => setTypedUserId(e.target.value)} placeholder="graph8 user id" />
+          </div>
+        )}
+        <div className="space-y-1">
+          <Label htmlFor="ds-name">Session name</Label>
+          <Input id="ds-name" value={name} onChange={(e) => setName(e.target.value)} />
+        </div>
+        <div className="space-y-1">
+          <Label htmlFor="ds-from">Caller ID</Label>
+          <select id="ds-from" className="h-9 w-full rounded-md border bg-background px-2 text-sm" value={chosenPhone} disabled={loading} onChange={(e) => setFromPhone(e.target.value)}>
+            {numbers.length === 0 ? <option value="">{loading ? "Loading numbers..." : "No numbers available"}</option> : null}
+            {numbers.map((n) => (
+              <option key={n.phone_number} value={n.phone_number}>
+                {n.phone_number} ({n.calls_today ?? 0} calls today)
+              </option>
+            ))}
+          </select>
+        </div>
+        <div className="space-y-1">
+          <Label htmlFor="ds-mode">Mode</Label>
+          <div className="flex items-center gap-2">
+            <select id="ds-mode" className="h-9 rounded-md border bg-background px-2 text-sm" value={mode} onChange={(e) => setMode(e.target.value as DialerMode)}>
+              <option value="power">Power (one call at a time)</option>
+              <option value="parallel">Parallel (several at once)</option>
+            </select>
+            {mode === "parallel" ? <Input aria-label="Calls at once" type="number" min={2} max={10} className="w-20" value={parallelCount} onChange={(e) => setParallelCount(Number(e.target.value))} onBlur={() => setParallelCount((n) => Math.min(10, Math.max(2, Math.round(n) || 2)))} /> : null}
+          </div>
+        </div>
+      </div>
+      {error ? <ApiError error={error} title="Could not load caller IDs" onRetry={() => void refetch()} /> : null}
+      {create.error ? <ApiError error={create.error} title="Could not create the session" /> : null}
+      <Button type="submit" disabled={!listId || !repId || create.loading} loading={create.loading}>
+        Create session (dials no one yet)
+      </Button>
+    </form>
+  );
+}

package/blocks/dialer/components/softphone.tsx

@@ -0,0 +1,122 @@
+"use client";
+
+/**
+ * Softphone: the rep's browser audio endpoint. It registers a voice client and joins the conference each dialed
+ * batch opens, with mute and hang-up. It does NOT dial: calls are placed by the server when CallQueue's
+ * "Dial next batch" is confirmed; the Softphone only brings the rep's audio into the conference.
+ *
+ * SDK operations, in order:
+ *   1. GET /dialer/sessions/token?user_id=   (dialer.mintSoftphoneToken)   EXTERNAL -> ConfirmSpendDialog first
+ *        Returns a 1-hour bearer credential ({ token, identity }) that lets the browser place and receive calls as
+ *        the rep. It is a SECRET: it is only passed to `transport.connect`, never rendered or logged.
+ * Everything after that is the audio vendor, behind the `transport` prop (see lib/softphone-transport.ts). The API
+ * has no event stream; `transport` events are the only live signal about the audio leg.
+ *
+ * Use `createTwilioTransport()` (lib/twilio-transport.ts, needs the optional peer @twilio/voice-sdk) or write your own.
+ */
+import { useCallback, useEffect, useRef, useState } from "react";
+import { Button } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { g8Get } from "@/g8/lib/g8-client";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { dataOf } from "../lib/dialer-types";
+import type { SoftphoneTransport } from "../lib/softphone-transport";
+
+export interface SoftphoneProps {
+  /** The rep whose identity the credential is minted for. */
+  userId: string;
+  transport: SoftphoneTransport;
+  /** Join this conference when it changes (the `conference_name` from next-batch). */
+  conferenceName?: string | null;
+  /** Join muted (parallel mode: the server unmutes when a person answers). */
+  joinMuted?: boolean;
+  onStateChange?: (state: SoftphoneState) => void;
+  className?: string;
+}
+
+export type SoftphoneState = "off" | "connecting" | "ready" | "in-call" | "error";
+
+export function Softphone({ userId, transport, conferenceName, joinMuted, onStateChange, className }: SoftphoneProps) {
+  const [state, setState] = useState<SoftphoneState>("off");
+  const [muted, setMuted] = useState(false);
+  const [expiring, setExpiring] = useState(false);
+  const [asking, setAsking] = useState<"enable" | "renew" | null>(null);
+  const [joinedConference, setJoinedConference] = useState<string | null>(null);
+  const joining = useRef<string | null>(null);
+  const [transportError, setTransportError] = useState<string | null>(null);
+
+  const update = useCallback((next: SoftphoneState) => { setState(next); onStateChange?.(next); }, [onStateChange]);
+
+  useEffect(() => transport.subscribe((e) => {
+    if (e.type === "registered") update("ready");
+    else if (e.type === "connected") update("in-call");
+    else if (e.type === "disconnected") { setMuted(false); update("ready"); }
+    else if (e.type === "unregistered") update("off");
+    else if (e.type === "muted") setMuted(e.muted);
+    else if (e.type === "token-expiring") setExpiring(true);
+    else if (e.type === "error") { setTransportError(e.message); update("error"); }
+  }), [transport, update]);
+
+  const mint = useG8Mutation(async () => {
+    const env = await g8Get("/dialer/sessions/token", { user_id: userId });
+    const { token, identity } = dataOf<{ token?: string; identity?: string }>(env);
+    if (!token) throw new Error("graph8 did not return a softphone credential");
+    return { token, identity };
+  });
+
+  const confirm = async () => {
+    const intent = asking;
+    try {
+      const creds = await mint.mutateAsync(undefined);
+      if (intent === "renew") { transport.updateToken?.(creds.token); setExpiring(false); }
+      else { update("connecting"); setTransportError(null); await transport.connect(creds); }
+    } catch (err) {
+      setTransportError(err instanceof Error ? err.message : "Could not start the softphone");
+      if (intent === "enable") update("error");
+    } finally {
+      setAsking(null);
+    }
+  };
+
+  useEffect(() => {
+    if (state !== "ready" && state !== "in-call") return;
+    if (!conferenceName || conferenceName === joinedConference || conferenceName === joining.current || !transport.joinConference) return;
+    joining.current = conferenceName;
+    // Only a SUCCESSFUL join counts: a failed one leaves joinedConference unset so the next state change retries.
+    transport.joinConference(conferenceName, { muted: joinMuted }).then(() => setJoinedConference(conferenceName)).catch((e: unknown) => { joining.current = null; setTransportError(e instanceof Error ? e.message : "Could not join the call"); });
+  }, [conferenceName, joinedConference, joinMuted, state, transport]);
+
+  const label = { off: "Calling is off", connecting: "Connecting...", ready: "Ready for calls", "in-call": "On a call", error: "Softphone error" }[state];
+  return (
+    <section className={`space-y-3 rounded-lg border p-4 ${className ?? ""}`} aria-label="Softphone">
+      <div className="flex items-center justify-between">
+        <h3 className="text-sm font-semibold">Softphone</h3>
+        <span role="status" className="text-sm text-muted-foreground">{label}</span>
+      </div>
+      {transportError ? <p role="alert" className="text-sm text-destructive">{transportError}</p> : null}
+      {mint.error ? <ApiError error={mint.error} title="Could not get a softphone credential" /> : null}
+      {expiring ? <p className="text-sm">Your softphone credential expires soon. <Button size="sm" variant="link" onClick={() => setAsking("renew")}>Renew</Button></p> : null}
+      <div className="flex flex-wrap gap-2">
+        {state === "off" || state === "error" ? <Button onClick={() => setAsking("enable")}>Enable calling</Button> : null}
+        {state === "in-call" ? (
+          <>
+            <Button variant="outline" onClick={() => transport.mute(!muted)}>{muted ? "Unmute" : "Mute"}</Button>
+            <Button variant="destructive" onClick={() => transport.hangup()}>Leave call</Button>
+          </>
+        ) : null}
+        {state === "ready" || state === "in-call" ? <Button variant="ghost" onClick={() => { void transport.disconnect(); setJoinedConference(null); joining.current = null; }}>Turn off</Button> : null}
+      </div>
+      <ConfirmSpendDialog
+        open={asking != null}
+        tier="external"
+        title={asking === "renew" ? "Renew the softphone credential?" : "Let this browser place and receive calls?"}
+        description="This mints a one-hour credential that lets this browser make and take calls as you. It is kept in memory only."
+        confirmLabel={asking === "renew" ? "Renew" : "Enable calling"}
+        confirming={mint.loading}
+        onConfirm={() => void confirm()}
+        onCancel={() => setAsking(null)}
+      />
+    </section>
+  );
+}

package/blocks/dialer/components/transcript-viewer.tsx

@@ -0,0 +1,82 @@
+"use client";
+
+/**
+ * TranscriptViewer: the speaker-by-speaker transcript, AI summary, AI grading and the recording for one call.
+ *
+ * SDK operations, in order:
+ *   1. GET /voice/dialer/calls/{room_name}/transcript   (voice.getCallTranscript)   read - status "empty" until flushed
+ *   2. GET /voice/dialer/calls/{room_name}/grading      (voice.getCallGrading)      read - "pending" while being computed
+ *   3. GET /voice/calls/{call_id}/recording             (voice.downloadCallRecording) read - audio bytes through your /api/g8 proxy
+ *      (425 while the recording is still being finalised; the audio element simply fails until then)
+ * There is no live transcript stream: with `live` set the component re-reads every 4 seconds until the call ends.
+ */
+import { Skeleton } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { EmptyState } from "@/g8/components/empty-state";
+import { buildG8Url, g8Get } from "@/g8/lib/g8-client";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { useJobPoll } from "@/g8/hooks/use-job-poll";
+import { dataOf, formatDuration, type TranscriptSegment } from "../lib/dialer-types";
+
+export interface TranscriptViewerProps {
+  /** The call's room_name (equals its call_id). */
+  roomName: string;
+  /** Keep re-reading while the call is in progress. */
+  live?: boolean;
+  className?: string;
+}
+
+interface TranscriptData {
+  status?: string;
+  summary?: string | null;
+  disposition?: string | null;
+  call_duration?: number | null;
+  transcript?: TranscriptSegment[];
+}
+
+/** Grading is a free-form payload; show its flat fields rather than guess a schema. */
+function GradingSummary({ grading }: { grading: Record<string, unknown> }) {
+  const rows = Object.entries(grading).filter(([, v]) => ["string", "number", "boolean"].includes(typeof v) && String(v).length < 400);
+  if (rows.length === 0) return null;
+  return (
+    <dl className="grid gap-2 text-sm sm:grid-cols-2" aria-label="AI grading">
+      {rows.map(([k, v]) => (
+        <div key={k}><dt className="text-xs uppercase text-muted-foreground">{k.replace(/_/g, " ")}</dt><dd>{String(v)}</dd></div>
+      ))}
+    </dl>
+  );
+}
+
+export function TranscriptViewer({ roomName, live = false, className }: TranscriptViewerProps) {
+  const path = `/voice/dialer/calls/${encodeURIComponent(roomName)}`;
+  const transcript = useG8Query(async (signal) => dataOf<TranscriptData>(await g8Get(`${path}/transcript`, undefined, { signal })), [roomName]);
+  const grading = useG8Query(async (signal) => dataOf<Record<string, unknown> | null>(await g8Get(`${path}/grading`, undefined, { signal })), [roomName]);
+  useJobPoll(async () => (await transcript.refetch()) ?? null, { enabled: live, isTerminal: () => !live, intervalMs: 4000, backoff: 1, maxIntervalMs: 4000 });
+
+  if (transcript.error) return <ApiError error={transcript.error} title="Could not load the transcript" onRetry={() => void transcript.refetch()} />;
+  if (transcript.loading && !transcript.data) return <Skeleton className="h-40 w-full" aria-label="Loading transcript" />;
+  const t = transcript.data;
+  const segments = t?.transcript ?? [];
+  const pendingGrade = !grading.data || (grading.data as { status?: string }).status === "pending";
+
+  return (
+    <section className={`space-y-3 ${className ?? ""}`}>
+      <header className="flex flex-wrap items-center gap-3 text-sm text-muted-foreground">
+        <span>Length {formatDuration(t?.call_duration)}</span>
+        {t?.disposition ? <span className="capitalize">Outcome: {t.disposition.replace(/_/g, " ")}</span> : null}
+      </header>
+      <audio controls preload="none" src={buildG8Url(`/voice/calls/${encodeURIComponent(roomName)}/recording`)} aria-label="Call recording" className="w-full" />
+      {t?.summary ? <p className="rounded-lg bg-muted p-3 text-sm">{t.summary}</p> : null}
+      {!pendingGrade && grading.data ? <GradingSummary grading={grading.data} /> : <p className="text-xs text-muted-foreground">AI grading is not ready yet.</p>}
+      {segments.length === 0 ? (
+        <EmptyState title={t?.status === "empty" ? "Transcript not ready" : "No transcript"} description="Transcripts are saved a moment after a call ends." />
+      ) : (
+        <ol className="space-y-2" aria-label="Transcript">
+          {segments.map((s, i) => (
+            <li key={i} className="text-sm"><span className="mr-2 font-medium capitalize">{s.speaker ?? "speaker"}</span>{s.content}</li>
+          ))}
+        </ol>
+      )}
+    </section>
+  );
+}

package/blocks/dialer/hooks/use-dialer-numbers.ts

@@ -0,0 +1,19 @@
+"use client";
+
+/**
+ * useDialerNumbers: caller IDs the dialer may use, with today's usage.
+ *
+ * SDK operations: GET /voice/dialer/numbers (voice.listDialerNumbers), read tier.
+ */
+import { g8Get } from "@/g8/lib/g8-client";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { dataOf, type DialerNumber } from "../lib/dialer-types";
+
+export function useDialerNumbers() {
+  const q = useG8Query(async (signal) => {
+    const data = dataOf<{ numbers?: DialerNumber[]; items?: DialerNumber[] } | DialerNumber[]>(await g8Get("/voice/dialer/numbers", undefined, { signal }));
+    const list = Array.isArray(data) ? data : (data.numbers ?? data.items ?? []);
+    return list.map((n) => ({ ...n, phone_number: n.phone_number ?? n.number ?? "" })).filter((n) => n.phone_number);
+  }, []);
+  return { ...q, numbers: q.data ?? [] };
+}

package/blocks/dialer/hooks/use-dialer-session.ts

@@ -0,0 +1,68 @@
+"use client";
+
+/**
+ * useDialerSession: poll one dialer session until it is over.
+ *
+ * SDK operations, each poll (in parallel):
+ *   GET /dialer/sessions/{id}/queue-stats   (dialer.readQueueStats)    read - status, batch_status, queue_remaining
+ *   GET /dialer/sessions/{id}               (voice.getDialerSession)   read - name, list, live call list (live_state.calls)
+ *
+ * The API has NO event stream (no WebSocket/SSE for sessions), so this polls with useJobPoll, every 5 seconds by
+ * default (the same cadence the graph8 app uses as its fallback). It stops by itself when the session is
+ * COMPLETED, after repeated errors, or on a 4xx (a missing or foreign session). Call `refresh()` right after
+ * you change something (dial, hang up, disposition) for an immediate read instead of waiting for the next tick.
+ */
+import { useCallback, useEffect } from "react";
+import { g8Get } from "@/g8/lib/g8-client";
+import { useJobPoll } from "@/g8/hooks/use-job-poll";
+import { dataOf, isSessionOver, type LiveCall, type QueueStats, type SessionDetail } from "../lib/dialer-types";
+
+const NO_CALLS: LiveCall[] = [];
+
+export interface DialerSessionSnapshot {
+  stats: QueueStats;
+  detail: SessionDetail;
+  calls: LiveCall[];
+}
+
+export interface UseDialerSessionOptions {
+  intervalMs?: number;
+  enabled?: boolean;
+}
+
+export function useDialerSession(sessionId: string | null | undefined, options: UseDialerSessionOptions = {}) {
+  const id = encodeURIComponent(sessionId ?? "");
+  const poll = useJobPoll<DialerSessionSnapshot>(
+    async (signal) => {
+      const [stats, detail] = await Promise.all([
+        g8Get(`/dialer/sessions/${id}/queue-stats`, undefined, { signal }),
+        g8Get(`/dialer/sessions/${id}`, undefined, { signal }),
+      ]);
+      const d = dataOf<SessionDetail>(detail);
+      return { stats: dataOf<QueueStats>(stats), detail: d, calls: d.live_state?.calls ?? [] };
+    },
+    {
+      isTerminal: (s) => isSessionOver(s.stats.status),
+      enabled: Boolean(sessionId) && (options.enabled ?? true),
+      intervalMs: options.intervalMs ?? 5000,
+      backoff: 1,
+      maxIntervalMs: options.intervalMs ?? 5000,
+      maxAttempts: 100_000,
+      maxConsecutiveErrors: 5,
+    },
+  );
+  const { start } = poll;
+  const refresh = useCallback(() => start(), [start]);
+  // A different session starts a fresh poll immediately and never shows the previous session's numbers.
+  useEffect(() => { if (sessionId) start(); }, [sessionId, start]);
+  const snapshot = poll.status && poll.status.stats.session_id === sessionId ? poll.status : undefined;
+  return {
+    stats: snapshot?.stats,
+    detail: snapshot?.detail,
+    calls: snapshot?.calls ?? NO_CALLS,
+    error: poll.error,
+    polling: poll.polling,
+    over: poll.done,
+    refresh,
+  };
+}