@graph8/sdk 0.362.0 → 0.373.0

package/blocks/phone-numbers/components/phone-number-list.tsx

@@ -0,0 +1,110 @@
+"use client";
+
+/**
+ * PhoneNumberList: the workspace's numbers as a table, paged on the client with a "Load more" so a long inventory is never
+ * cut off silently. It reads nothing itself: the screen passes the filtered rows from usePhoneNumbers.
+ *
+ * SDK operations: none (rows come from usePhoneNumbers: listDialerNumbers + listAgentPhoneNumbers).
+ */
+
+import { useEffect, useState } from "react";
+import type { ReactNode } from "react";
+import { Skeleton, Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { EmptyState } from "@/g8/components/empty-state";
+import { LoadMore } from "@/g8/components/paging-notices";
+import { RecordLink } from "@/g8/components/screen/record-link";
+import { StatusPill } from "@/g8/components/screen/status-pill";
+import { rowActivationProps } from "@/g8/hooks/use-row-activation";
+import { formatNumber, numberHealth, typeLabel } from "../lib/phone-numbers-utils";
+import type { NumberRow } from "../lib/phone-numbers-utils";
+
+export const PAGE_SIZE = 25;
+const COLUMNS = 6;
+
+export interface PhoneNumberListProps {
+  rows: NumberRow[];
+  loading?: boolean;
+  error?: unknown;
+  onRetry?: () => void;
+  /** The open number (E.164). */
+  selected?: string;
+  onSelect: (row: NumberRow) => void;
+  /** Extra buttons in each row's last cell. */
+  renderRowActions?: (row: NumberRow) => ReactNode;
+  /** Shown when there are no rows at all. */
+  emptyAction?: ReactNode;
+  /** Shown instead of the empty state when filters hid every row. */
+  filtered?: boolean;
+  /** Bump to go back to the first page (filters changed). */
+  resetKey?: string;
+  className?: string;
+}
+
+export function PhoneNumberList({ rows, loading, error, onRetry, selected, onSelect, renderRowActions, emptyAction, filtered, resetKey, className }: PhoneNumberListProps) {
+  const [shown, setShown] = useState(PAGE_SIZE);
+  useEffect(() => setShown(PAGE_SIZE), [resetKey]);
+
+  if (error) return <ApiError error={error} onRetry={onRetry} className={className} />;
+  if (loading && rows.length === 0) {
+    return (
+      <Table className={className}>
+        <TableBody>
+          {Array.from({ length: 5 }, (_, i) => (
+            <TableRow key={i}>
+              <TableCell colSpan={COLUMNS}><Skeleton className="h-5 w-full" /></TableCell>
+            </TableRow>
+          ))}
+        </TableBody>
+      </Table>
+    );
+  }
+  if (rows.length === 0) {
+    return filtered ? (
+      <EmptyState className={className} title="No numbers match" description="Clear a filter or change the search to see more." />
+    ) : (
+      <EmptyState className={className} title="No phone numbers yet" description="Buy a number to call from, to give a voice agent, or as a rep's work phone." action={emptyAction} />
+    );
+  }
+  const visible = rows.slice(0, shown);
+
+  return (
+    <div className={`space-y-2 ${className ?? ""}`}>
+      <Table>
+        <TableHeader>
+          <TableRow>
+            <TableHead>Number</TableHead>
+            <TableHead>Use</TableHead>
+            <TableHead>Assigned to</TableHead>
+            <TableHead>Carrier</TableHead>
+            <TableHead className="text-right">Calls today</TableHead>
+            <TableHead>Status</TableHead>
+          </TableRow>
+        </TableHeader>
+        <TableBody>
+          {visible.map((r) => {
+            const health = numberHealth(r);
+            return (
+              <TableRow key={r.number} data-state={selected === r.number ? "selected" : undefined} className="cursor-pointer" {...rowActivationProps(() => onSelect(r))}>
+                <TableCell className="font-medium tabular-nums">
+                  <RecordLink param="id" id={r.number} onOpen={() => onSelect(r)}>{formatNumber(r.number)}</RecordLink>
+                </TableCell>
+                <TableCell>{typeLabel(r.inboundType)}{r.agentName ? <span className="block text-xs text-muted-foreground">{r.agentName}</span> : null}</TableCell>
+                <TableCell>{r.assignedTo ?? <span className="text-muted-foreground">-</span>}</TableCell>
+                <TableCell>{r.provider === "telnyx" ? "Telnyx" : r.provider === "twilio" ? "Twilio" : <span className="text-muted-foreground">-</span>}</TableCell>
+                <TableCell className="text-right tabular-nums">{r.callsToday ?? "-"}{r.dailyLimit ? <span className="text-xs text-muted-foreground"> / {r.dailyLimit}</span> : null}</TableCell>
+                <TableCell>
+                  <span className="flex items-center justify-between gap-2">
+                    <StatusPill tone={health.tone} dot>{health.label}</StatusPill>
+                    {renderRowActions ? <span data-row-ignore>{renderRowActions(r)}</span> : null}
+                  </span>
+                </TableCell>
+              </TableRow>
+            );
+          })}
+        </TableBody>
+      </Table>
+      <LoadMore shown={visible.length} noun={`of ${rows.length.toLocaleString()} numbers`} hasMore={visible.length < rows.length} onLoadMore={() => setShown((n) => n + PAGE_SIZE)} />
+    </div>
+  );
+}

package/blocks/phone-numbers/components/phone-numbers-screen.tsx

@@ -0,0 +1,201 @@
+"use client";
+
+/**
+ * PhoneNumbersScreen: the finished "Phone numbers" page. Every number the workspace owns, who has it, what it is for, and
+ * how to get, assign, configure and give back numbers.
+ *
+ * Composes: PhoneNumberList, PhoneNumberDetail (Overview, Assign, Usage, Settings, Release), NumberSearch (search and
+ * buy), RegisterOwnedNumber, A2pRegistration.
+ *
+ * User flows:
+ *   - See the inventory at a glance (stat strip), search it and filter by use, carrier, assignment and status. The list is
+ *     paged on the client ("Load more"); the API returns the whole inventory, so nothing is cut off.
+ *   - Open a number (deep link `?id=<number>`, `?tab=`, full page with `?view=full`): assign it to a teammate (MemberPicker,
+ *     "Assign to me", unassign), see today's usage against the daily limit, change what answers it, verify a Telnyx caller
+ *     ID, see who answers, remove its voice routing (confirmed) or release it (type the number, then confirm).
+ *   - "Buy a number" opens a sheet: search a carrier by area code, digits or city, choose one, and buy it. The purchase is
+ *     billable, so it opens ConfirmSpendDialog with the price first (an estimate: the API has no price read).
+ *   - "Add a number you own" registers an owned number with the voice platform (spends nothing).
+ *   - Text registration tab: A2P 10DLC status, a draft of the business details, a confirmed submit, and a retry for stuck numbers.
+ *
+ * SDK operations: none of its own. The list is read by usePhoneNumbers; billable, external and destructive calls live in the
+ * composed parts, each of which opens ConfirmSpendDialog itself.
+ *
+ * Billing: numbers the platform provisioned for you (the onboarding receptionist line) are never rental-billed, and nothing
+ * here labels any number as billable. The purchase dialog is the only place a price appears.
+ */
+
+import { useState } from "react";
+import type { ReactNode } from "react";
+import { Phone, Plus } from "lucide-react";
+import { Button } from "@graph8/sdk/ui";
+import { FormSheet } from "@/g8/components/screen/form-sheet";
+import { SelectFilter } from "@/g8/components/screen/filter-controls";
+import { ScreenLayout } from "@/g8/components/screen/screen-layout";
+import { SplitView } from "@/g8/components/screen/split-view";
+import type { StatItem } from "@/g8/components/screen/stat-strip";
+import { Toolbar } from "@/g8/components/screen/toolbar";
+import { useUrlFilters } from "@/g8/hooks/use-url-filters";
+import { useUrlState } from "@/g8/hooks/use-url-state";
+import { usePhoneNumbers } from "../hooks/use-phone-numbers";
+import { digits, numberHealth, typeLabel, INBOUND_TYPES } from "../lib/phone-numbers-utils";
+import type { NumberRow } from "../lib/phone-numbers-utils";
+import { A2pRegistration } from "./a2p-registration";
+import { NumberSearch } from "./number-search";
+import { PhoneNumberDetail } from "./phone-number-detail";
+import { PhoneNumberList } from "./phone-number-list";
+import { RegisterOwnedNumber } from "./register-owned-number";
+
+export interface PhoneNumbersScreenProps {
+  /** Extra buttons in the toolbar. */
+  toolbarActions?: ReactNode;
+  /** Extra buttons in each row. */
+  renderRowActions?: (row: NumberRow) => ReactNode;
+  /** Extra buttons in the open number's header. */
+  renderDetailActions?: (row: NumberRow) => ReactNode;
+  /** Extra tabs in the open number's panel. */
+  extraDetailTabs?: Array<{ id: string; label: string; render: (row: NumberRow) => ReactNode }>;
+  className?: string;
+}
+
+const TABS = [
+  { id: "numbers", label: "Numbers" },
+  { id: "texting", label: "Text registration" },
+];
+const FILTERS = ["q", "use", "carrier", "assigned", "status"] as const;
+
+/** Rows that match the filters (all client-side: the API returns the whole inventory). */
+export function filterNumbers(rows: NumberRow[], f: Record<(typeof FILTERS)[number], string>): NumberRow[] {
+  const q = f.q.trim().toLowerCase();
+  const qDigits = digits(f.q);
+  return rows.filter((r) => {
+    if (q) {
+      const hay = [r.assignedTo, r.agentName, typeLabel(r.inboundType)].join(" ").toLowerCase();
+      if (!(hay.includes(q) || (qDigits && digits(r.number).includes(qDigits)))) return false;
+    }
+    if (f.use && r.inboundType !== f.use) return false;
+    if (f.carrier && r.provider !== f.carrier) return false;
+    if (f.assigned === "assigned" && !r.assignedTo) return false;
+    if (f.assigned === "unassigned" && r.assignedTo) return false;
+    if (f.status && numberHealth(r).label !== f.status) return false;
+    return true;
+  });
+}
+
+export function PhoneNumbersScreen({ toolbarActions, renderRowActions, renderDetailActions, extraDetailTabs, className }: PhoneNumbersScreenProps) {
+  const [tab, setTab] = useUrlState("tab", "numbers");
+  const [selected, setSelected] = useUrlState("id", "");
+  const [detailTab, setDetailTab] = useUrlState("dtab", "");
+  const [view, setView] = useUrlState("view", "");
+  const [sheet, setSheet] = useState<"buy" | "own" | null>(null);
+  const numbers = usePhoneNumbers();
+  const uf = useUrlFilters(FILTERS, { prefix: "n_" });
+  const rows = filterNumbers(numbers.rows, uf.filters);
+  const open = numbers.rows.find((r) => digits(r.number) === digits(selected));
+
+  const close = () => { setSelected(null); setDetailTab(null); setView(null); };
+  const openRow = (r: NumberRow) => { setSelected(r.number); setDetailTab(null); setView(null); };
+  const assigned = numbers.rows.filter((r) => r.assignedTo).length;
+  const stats: StatItem[] = numbers.loaded
+    ? [
+        { label: "Numbers", value: numbers.rows.length.toLocaleString() },
+        { label: "Assigned", value: assigned.toLocaleString() },
+        { label: "Unassigned", value: (numbers.rows.length - assigned).toLocaleString(), tone: numbers.rows.length - assigned > 0 ? "warning" : undefined },
+        { label: "Calls today", value: numbers.rows.reduce((n, r) => n + (r.callsToday ?? 0), 0).toLocaleString() },
+      ]
+    : [];
+
+  const actions = (
+    <>
+      <Button variant="outline" onClick={() => setSheet("own")}>Add a number you own</Button>
+      <Button onClick={() => setSheet("buy")}>
+        <Plus className="mr-1 h-4 w-4" aria-hidden /> Buy a number
+      </Button>
+    </>
+  );
+  const resetKey = JSON.stringify(uf.filters);
+
+  return (
+    <ScreenLayout
+      className={className}
+      title="Phone numbers"
+      description="The numbers you call from, answer on and text from: buy, assign, configure and release."
+      icon={<Phone className="h-5 w-5" aria-hidden />}
+      actions={actions}
+      tabs={TABS}
+      activeTab={TABS.some((t) => t.id === tab) ? tab : "numbers"}
+      onTabChange={(id) => { setTab(id === "numbers" ? null : id); close(); }}
+      stats={stats.length > 0 ? stats : undefined}
+      statsLoading={numbers.loading && !numbers.loaded}
+    >
+      {tab === "texting" ? (
+        <A2pRegistration />
+      ) : (
+        <div className="space-y-3">
+          <Toolbar
+            search={{ value: uf.draft.q, onChange: (v) => uf.set("q", v), debounceMs: 0, placeholder: "Search by number, person or agent" }}
+            actions={toolbarActions}
+            filters={
+              <>
+                <SelectFilter label="use" value={uf.draft.use} onChange={(v) => uf.set("use", v)} any="Any use" options={INBOUND_TYPES.map((t) => ({ value: t, label: typeLabel(t) }))} />
+                <SelectFilter label="carrier" value={uf.draft.carrier} onChange={(v) => uf.set("carrier", v)} any="Any carrier" options={[{ value: "twilio", label: "Twilio" }, { value: "telnyx", label: "Telnyx" }]} />
+                <SelectFilter label="assignment" value={uf.draft.assigned} onChange={(v) => uf.set("assigned", v)} any="Assigned or not" options={[{ value: "assigned", label: "Assigned" }, { value: "unassigned", label: "Unassigned" }]} />
+                <SelectFilter label="status" value={uf.draft.status} onChange={(v) => uf.set("status", v)} any="Any status" options={["Ready", "Near limit", "At daily limit", "Cannot dial"]} />
+              </>
+            }
+          />
+          {numbers.agentsUnavailable ? (
+            <p role="note" className="text-xs text-muted-foreground">
+              Numbers held by voice agents could not be read with this key, so they may be missing from the list.
+            </p>
+          ) : null}
+          <SplitView
+            expanded={view === "full"}
+            onExpandedChange={(e) => setView(e ? "full" : null)}
+            detailOpen={Boolean(selected)}
+            onCloseDetail={close}
+            list={
+              <PhoneNumberList
+                rows={rows}
+                loading={numbers.loading && !numbers.loaded}
+                error={numbers.error}
+                onRetry={numbers.refetch}
+                selected={open?.number}
+                onSelect={openRow}
+                renderRowActions={renderRowActions}
+                filtered={uf.active}
+                resetKey={resetKey}
+                emptyAction={<Button onClick={() => setSheet("buy")}>Buy a number</Button>}
+              />
+            }
+            detail={
+              selected && open ? (
+                <PhoneNumberDetail
+                  key={open.number}
+                  row={open}
+                  tab={detailTab || undefined}
+                  onTabChange={(t) => setDetailTab(t === "overview" ? null : t)}
+                  onClose={close}
+                  onExpand={view === "full" ? undefined : () => setView("full")}
+                  onCollapse={view === "full" ? () => setView(null) : undefined}
+                  onChanged={numbers.refetch}
+                  onReleased={() => { close(); numbers.refetch(); }}
+                  renderActions={renderDetailActions}
+                  extraTabs={extraDetailTabs}
+                />
+              ) : selected && numbers.loaded ? (
+                <p className="p-4 text-sm text-muted-foreground">No number matches this link. It may have been released.</p>
+              ) : null
+            }
+          />
+        </div>
+      )}
+      <FormSheet width="xl" open={sheet === "buy"} onOpenChange={(o) => !o && setSheet(null)} title="Buy a number" description="Search for a number, choose one, and confirm the purchase.">
+        {sheet === "buy" ? <NumberSearch onPurchased={() => numbers.refetch()} /> : null}
+      </FormSheet>
+      <FormSheet width="md" open={sheet === "own"} onOpenChange={(o) => !o && setSheet(null)} title="Add a number you own" description="Register a number you already hold with the voice platform.">
+        {sheet === "own" ? <RegisterOwnedNumber onRegistered={() => { setSheet(null); numbers.refetch(); }} /> : null}
+      </FormSheet>
+    </ScreenLayout>
+  );
+}

package/blocks/phone-numbers/components/register-owned-number.tsx

@@ -0,0 +1,98 @@
+"use client";
+
+/**
+ * RegisterOwnedNumber: wire a number you already own (bought outside, or whose voice half failed) into the voice platform.
+ *
+ * SDK operations:
+ *   provisionVoiceNumber  POST /voice/numbers/provision  (write; BUYS NOTHING and charges nothing: it creates SIP trunks
+ *                         and dispatch rules for a number you already hold. Idempotent: a number already registered
+ *                         comes back as a success.)
+ *
+ * The person comes from MemberPicker, not a typed email. A personal work phone needs someone assigned, or no one can
+ * reach it by name.
+ */
+
+import { useState } from "react";
+import { Button, Input, Label } from "@graph8/sdk/ui";
+import { g8Post } from "@/g8/lib/g8-client";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { ApiError } from "@/g8/components/api-error";
+import { MemberPicker } from "@/g8/pickers/components/member-picker";
+import type { MemberOption } from "@/g8/pickers/components/member-picker";
+import { INBOUND_LABEL, INBOUND_TYPES, PROVIDERS, formatNumber, isE164 } from "../lib/phone-numbers-utils";
+import type { InboundType, Provider } from "../lib/phone-numbers-utils";
+
+export interface RegisterOwnedNumberProps {
+  onRegistered?: (phoneNumber: string) => void;
+  className?: string;
+}
+
+const SELECT = "h-9 w-full rounded-md border border-border bg-background px-2 text-sm";
+
+export function RegisterOwnedNumber({ onRegistered, className }: RegisterOwnedNumberProps) {
+  const [number, setNumber] = useState("");
+  const [provider, setProvider] = useState<Provider>("twilio");
+  const [mode, setMode] = useState<InboundType>("ai");
+  const [assignee, setAssignee] = useState<MemberOption | null>(null);
+  const [note, setNote] = useState<string | null>(null);
+  const valid = isE164(number);
+  const needsPerson = mode === "work" && !assignee?.email;
+
+  const register = useG8Mutation(async () => {
+    const n = number.trim();
+    await g8Post("/voice/numbers/provision", {
+      number: n,
+      provider,
+      inbound_type: mode,
+      dialer: mode === "dialer",
+      work: mode === "work",
+      ...(assignee?.email ? { assigned_to: assignee.email } : {}),
+    });
+    setNote(`${formatNumber(n)} is registered with the voice platform.`);
+    setNumber("");
+    onRegistered?.(n);
+  });
+
+  return (
+    <form
+      className={`space-y-4 ${className ?? ""}`}
+      onSubmit={(e) => {
+        e.preventDefault();
+        if (valid && !needsPerson) void register.mutate(undefined);
+      }}
+    >
+      <p className="text-sm text-muted-foreground">Use this for a number you already own. Nothing is bought and no credits are spent.</p>
+      <div className="space-y-1">
+        <Label htmlFor="ro-number">Phone number (E.164)</Label>
+        <Input id="ro-number" placeholder="+14155550123" value={number} onChange={(e) => setNumber(e.target.value)} aria-invalid={number !== "" && !valid} />
+        {number !== "" && !valid ? <p className="text-xs text-error">Use the international format: a plus sign, the country code, then the number.</p> : null}
+      </div>
+      <div className="grid gap-3 sm:grid-cols-2">
+        <div className="space-y-1">
+          <Label htmlFor="ro-provider">Carrier that holds it</Label>
+          <select id="ro-provider" className={SELECT} value={provider} onChange={(e) => setProvider(e.target.value as Provider)}>
+            {PROVIDERS.map((p) => (
+              <option key={p} value={p}>{p === "twilio" ? "Twilio" : "Telnyx"}</option>
+            ))}
+          </select>
+        </div>
+        <div className="space-y-1">
+          <Label htmlFor="ro-mode">How it answers</Label>
+          <select id="ro-mode" className={SELECT} value={mode} onChange={(e) => setMode(e.target.value as InboundType)}>
+            {INBOUND_TYPES.map((t) => (
+              <option key={t} value={t}>{INBOUND_LABEL[t]}</option>
+            ))}
+          </select>
+        </div>
+      </div>
+      <div className="space-y-1">
+        <Label htmlFor="ro-assignee">Assign to {mode === "work" ? "" : "(optional)"}</Label>
+        <MemberPicker id="ro-assignee" label="Assign to" value={assignee?.id ?? null} selectedName={assignee?.name} onChange={setAssignee} />
+        {needsPerson ? <p className="text-xs text-muted-foreground">A personal work phone needs a person, or no one can reach it by name.</p> : null}
+      </div>
+      {register.error ? <ApiError error={register.error} title="The number was not registered" onRetry={register.reset} /> : null}
+      {note ? <p role="status" className="text-sm">{note}</p> : null}
+      <Button type="submit" loading={register.loading} disabled={!valid || needsPerson}>Register number</Button>
+    </form>
+  );
+}

package/blocks/phone-numbers/components/release-number.tsx

@@ -0,0 +1,126 @@
+"use client";
+
+/**
+ * ReleaseNumber: give a number back, or take it off the voice platform without giving it back.
+ *
+ * SDK operations:
+ *   releasePhoneNumber  POST   /phone-numbers/release  (destructive: IRREVERSIBLE. The number returns to the carrier's pool
+ *                       and anyone can buy it, including a competitor; calls and messages stop at once. Confirmed with
+ *                       ConfirmSpendDialog after the person types the number.)
+ *   deleteVoiceNumber   DELETE /voice/numbers          (destructive: tears down the number's SIP trunks, dispatch rules and
+ *                       carrier routing. It does NOT release the number: you keep owning it and the carrier keeps billing
+ *                       it. Confirmed with ConfirmSpendDialog.)
+ *
+ * The carrier must match where the number was bought: releasing a Telnyx number as Twilio reaches the wrong provider. The
+ * list knows it for every dialer number; when it does not, the person chooses and the form says why.
+ */
+
+import { useState } from "react";
+import { Button, Input, Label } from "@graph8/sdk/ui";
+import { g8Delete, g8Post } from "@/g8/lib/g8-client";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { ApiError } from "@/g8/components/api-error";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { PROVIDERS, dataOf, digits, formatNumber } from "../lib/phone-numbers-utils";
+import type { NumberRow, Provider } from "../lib/phone-numbers-utils";
+
+export interface ReleaseNumberProps {
+  row: NumberRow;
+  /** Called after the number was released (the record is gone: close its detail). */
+  onReleased?: () => void;
+  /** Called after the voice registration was removed (the number is still owned). */
+  onChanged?: () => void;
+  className?: string;
+}
+
+type Pending = "release" | "deregister";
+
+export function ReleaseNumber({ row, onReleased, onChanged, className }: ReleaseNumberProps) {
+  const known = (PROVIDERS as readonly string[]).includes(row.provider);
+  const [provider, setProvider] = useState<Provider | "">(known ? (row.provider as Provider) : "");
+  const [typed, setTyped] = useState("");
+  const [pending, setPending] = useState<Pending | null>(null);
+  const [note, setNote] = useState<string | null>(null);
+
+  const release = useG8Mutation(async () => {
+    if (!provider) return;
+    const out = dataOf(await g8Post("/phone-numbers/release", { phone_number: row.number, provider }));
+    const detail = typeof out.message === "string" ? ` ${out.message}` : "";
+    setNote(`${formatNumber(row.number)} was released.${detail}`);
+    setPending(null);
+    onReleased?.();
+  });
+  const deregister = useG8Mutation(async () => {
+    await g8Delete("/voice/numbers", { body: { number: row.number, ...(provider ? { provider } : {}) } });
+    setNote(`${formatNumber(row.number)} was removed from the voice platform. You still own it.`);
+    setPending(null);
+    onChanged?.();
+  });
+
+  const matches = digits(typed) === digits(row.number);
+  const assignedNote = row.agentName ? ` The voice agent ${row.agentName} stops answering on it.` : "";
+
+  return (
+    <div className={`space-y-6 ${className ?? ""}`}>
+      {!known ? (
+        <div className="space-y-1">
+          <Label htmlFor="rn-provider">Carrier it was bought from</Label>
+          <select id="rn-provider" className="h-9 rounded-md border border-border bg-background px-2 text-sm" value={provider} onChange={(e) => setProvider(e.target.value as Provider | "")}>
+            <option value="">Choose the carrier</option>
+            {PROVIDERS.map((p) => (
+              <option key={p} value={p}>{p === "twilio" ? "Twilio" : "Telnyx"}</option>
+            ))}
+          </select>
+          <p className="text-xs text-muted-foreground">The carrier is not known for this number. It must match, or the wrong provider is asked to release it.</p>
+        </div>
+      ) : null}
+
+      <section className="space-y-2" aria-label="Release this number">
+        <h3 className="text-sm font-medium">Release this number</h3>
+        <p className="text-sm text-muted-foreground">
+          Gives the number back to the carrier. It returns to the public pool and anyone can buy it, including a competitor. Calls and messages to it stop
+          at once, and monthly rental billing for it ends. There is no undo.
+        </p>
+        <div className="flex flex-wrap items-end gap-2">
+          <div className="space-y-1">
+            <Label htmlFor="rn-confirm">Type {row.number} to enable release</Label>
+            <Input id="rn-confirm" value={typed} placeholder={row.number} onChange={(e) => setTyped(e.target.value)} />
+          </div>
+          <Button variant="destructive" disabled={!matches || !provider} onClick={() => setPending("release")}>
+            Release number
+          </Button>
+        </div>
+        {release.error ? <ApiError error={release.error} title="The number was not released" onRetry={release.reset} /> : null}
+      </section>
+
+      <section className="space-y-2" aria-label="Remove from voice">
+        <h3 className="text-sm font-medium">Remove from the voice platform</h3>
+        <p className="text-sm text-muted-foreground">
+          Tears down the number&apos;s call routing so nothing answers it. You still own the number and the carrier still bills for it. Use Release to give it up.
+        </p>
+        <Button variant="outline" onClick={() => setPending("deregister")}>Remove voice routing</Button>
+        {deregister.error ? <ApiError error={deregister.error} title="The voice routing was not removed" onRetry={deregister.reset} /> : null}
+      </section>
+
+      {note ? <p role="status" className="text-sm">{note}</p> : null}
+
+      {pending ? (
+        <ConfirmSpendDialog
+          open
+          tier="destructive"
+          title={pending === "release" ? `Release ${formatNumber(row.number)}` : `Remove voice routing for ${formatNumber(row.number)}`}
+          description={
+            pending === "release"
+              ? `The number goes back to the carrier and can be bought by anyone, including a competitor. Inbound calls and messages stop at once.${assignedNote}`
+              : `Nothing will answer this number until it is set up again. You keep owning it and the carrier keeps billing it.${assignedNote}`
+          }
+          confirmLabel={pending === "release" ? "Release number" : "Remove routing"}
+          affected={1}
+          confirming={release.loading || deregister.loading}
+          onCancel={() => setPending(null)}
+          onConfirm={() => void (pending === "release" ? release.mutate(undefined) : deregister.mutate(undefined)).then(() => setPending(null))}
+        />
+      ) : null}
+    </div>
+  );
+}

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

@@ -0,0 +1,58 @@
+"use client";
+
+/**
+ * usePhoneNumbers: every phone number of the workspace, in full.
+ *
+ * SDK operations, in order (both read, in parallel):
+ *   1. listDialerNumbers      GET /voice/dialer/numbers        every number except the ones a voice AI agent holds, with
+ *                             usage (calls today / 7 days, connect rate) and the daily limit
+ *   2. listAgentPhoneNumbers  GET /voice/agent-phone-numbers   the AI-capable numbers and which agent holds each
+ *
+ * Neither endpoint pages or caps: each answers the whole inventory, so nothing is cut off and the screen pages the list
+ * on the client ("Load more"). A key that cannot read agents (403) still gets the dialer list; `agentsUnavailable` says
+ * so, and the AI-held numbers are then missing and the screen says that rather than hiding it.
+ */
+import { g8Get } from "@/g8/lib/g8-client";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { agentNumbers, dialerRows, mergeInventory } from "../lib/phone-numbers-utils";
+import type { NumberRow } from "../lib/phone-numbers-utils";
+
+export interface UsePhoneNumbers {
+  rows: NumberRow[];
+  loading: boolean;
+  /** The first read has finished. */
+  loaded: boolean;
+  /** The dialer list failed (the agents list failing alone is not an error, see `agentsUnavailable`). */
+  error: unknown;
+  /** Numbers held by voice AI agents could not be read, so they may be missing from `rows`. */
+  agentsUnavailable: boolean;
+  refetch: () => void;
+}
+
+export function usePhoneNumbers(deps: readonly unknown[] = []): UsePhoneNumbers {
+  const q = useG8Query(
+    async (signal) => {
+      const [dialer, agents] = await Promise.allSettled([
+        g8Get("/voice/dialer/numbers", undefined, { signal }),
+        g8Get("/voice/agent-phone-numbers", undefined, { signal }),
+      ]);
+      if (dialer.status === "rejected") throw dialer.reason;
+      const agentsOk = agents.status === "fulfilled";
+      return {
+        rows: mergeInventory(dialerRows(dialer.value), agentsOk ? agentNumbers(agents.value) : { available: [], booked: [] }),
+        agentsUnavailable: !agentsOk,
+      };
+    },
+    [...deps],
+  );
+  return {
+    rows: q.data?.rows ?? EMPTY,
+    loading: q.loading,
+    loaded: q.data !== undefined,
+    error: q.error,
+    agentsUnavailable: q.data?.agentsUnavailable ?? false,
+    refetch: () => void q.refetch(),
+  };
+}
+
+const EMPTY: NumberRow[] = [];