@graph8/sdk 0.362.0 → 0.373.0

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

@@ -0,0 +1,239 @@
+"use client";
+
+/**
+ * NumberSearch: find a number a carrier has available, then buy it.
+ *
+ * SDK operations, in order:
+ *   1. searchAvailablePhoneNumbers  POST /phone-numbers/search    (read; nothing is held or charged)
+ *   2. purchasePhoneNumber          POST /phone-numbers/purchase  (billable: SPENDS CREDITS AND REAL MONEY, so it opens
+ *                                   ConfirmSpendDialog with the price first; sent with an Idempotency-Key)
+ *
+ * Ids passed between steps: the `phone_number` of a search result (E.164) is the body of step 2. The price is an
+ * ESTIMATE (250 credits held on purchase, then about 250 credits each month): the API has no price read. A 402 means
+ * not enough credits; the number was not bought and nothing was charged. A 409 means the number is already taken.
+ */
+
+import { useRef, useState } from "react";
+import { Phone, Search } from "lucide-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 { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { EmptyState } from "@/g8/components/empty-state";
+import { StatusPill } from "@/g8/components/screen/status-pill";
+import { plural } from "@/g8/lib/plural";
+import { MemberPicker } from "@/g8/pickers/components/member-picker";
+import type { MemberOption } from "@/g8/pickers/components/member-picker";
+import { MONTHLY_RENTAL_CREDITS, PROVIDERS, PURCHASE_CREDITS, asObject, formatNumber, newIdempotencyKey } from "../lib/phone-numbers-utils";
+import type { AvailableNumber, Provider } from "../lib/phone-numbers-utils";
+
+export interface NumberSearchProps {
+  /** Called after a purchase went through, so the list can refresh. */
+  onPurchased?: (phoneNumber: string) => void;
+  className?: string;
+}
+
+type Use = "dialer" | "ai" | "work";
+
+const USE_LABEL: Record<Use, string> = { dialer: "Outbound dialer", ai: "Voice AI agent", work: "Personal work phone" };
+const SELECT = "h-9 w-full rounded-md border border-border bg-background px-2 text-sm";
+
+function resultsOf(envelope: unknown): AvailableNumber[] {
+  const data = asObject(envelope).data;
+  const rows = Array.isArray(data) ? data : asObject(data).items;
+  return (Array.isArray(rows) ? rows : []).filter((r): r is AvailableNumber => typeof asObject(r).phone_number === "string");
+}
+
+function Field({ id, label, children }: { id: string; label: string; children: React.ReactNode }) {
+  return (
+    <div className="space-y-1">
+      <Label htmlFor={id}>{label}</Label>
+      {children}
+    </div>
+  );
+}
+
+export function NumberSearch({ onPurchased, className }: NumberSearchProps) {
+  const [provider, setProvider] = useState<Provider>("twilio");
+  const [country, setCountry] = useState("US");
+  const [numberType, setNumberType] = useState<"local" | "toll_free">("local");
+  const [areaCode, setAreaCode] = useState("");
+  const [by, setBy] = useState<"locality" | "pattern">("pattern");
+  const [text, setText] = useState("");
+  const [match, setMatch] = useState<"first" | "anywhere" | "last">("first");
+  // The results remember the carrier they were searched on: a number is bought from THAT carrier, even if the select moved since.
+  const [found, setFound] = useState<{ provider: Provider; rows: AvailableNumber[] } | null>(null);
+  const results = found?.rows ?? null;
+  const boughtFrom = found?.provider ?? provider;
+  const [picked, setPicked] = useState<AvailableNumber | null>(null);
+  const [use, setUse] = useState<Use>("dialer");
+  const [assignee, setAssignee] = useState<MemberOption | null>(null);
+  const [confirming, setConfirming] = useState(false);
+  const [done, setDone] = useState<string | null>(null);
+  const idem = useRef<{ sig: string; key: string } | null>(null);
+
+  const search = useG8Mutation(async () => {
+    const body = {
+      provider,
+      country: country.trim().toUpperCase() || "US",
+      number_type: numberType,
+      ...(areaCode.trim() ? { area_code: areaCode.trim() } : {}),
+      ...(text.trim() ? (by === "pattern" ? { pattern: text.trim(), match } : { locality: text.trim() }) : {}),
+    };
+    setPicked(null);
+    setDone(null);
+    setFound({ provider, rows: resultsOf(await g8Post("/phone-numbers/search", body)) });
+  });
+
+  const purchaseBody = picked
+    ? {
+        phone_number: picked.phone_number,
+        provider: boughtFrom,
+        dialer: use !== "ai",
+        work: use === "work",
+        ...(assignee?.email ? { assignee: assignee.email } : {}),
+      }
+    : null;
+
+  const buy = useG8Mutation(async () => {
+    if (!purchaseBody) return;
+    const sig = JSON.stringify(purchaseBody);
+    if (idem.current?.sig !== sig) idem.current = { sig, key: newIdempotencyKey() };
+    await g8Post("/phone-numbers/purchase", purchaseBody, { idempotencyKey: idem.current.key });
+    setDone(`${formatNumber(purchaseBody.phone_number)} is yours. It can take a minute to appear in your numbers.`);
+    setFound((f) => (f ? { ...f, rows: f.rows.filter((x) => x.phone_number !== purchaseBody.phone_number) } : f));
+    setPicked(null);
+    setConfirming(false);
+    onPurchased?.(purchaseBody.phone_number);
+  });
+
+  const status = (buy.error as { status?: number } | undefined)?.status;
+
+  return (
+    <div className={`space-y-5 ${className ?? ""}`}>
+      <form
+        className="space-y-3"
+        onSubmit={(e) => {
+          e.preventDefault();
+          void search.mutate(undefined);
+        }}
+      >
+        <div className="grid gap-3 sm:grid-cols-2">
+          <Field id="ns-provider" label="Carrier">
+            <select id="ns-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>
+          </Field>
+          <Field id="ns-type" label="Number type">
+            <select id="ns-type" className={SELECT} value={numberType} onChange={(e) => setNumberType(e.target.value as "local" | "toll_free")}>
+              <option value="local">Local</option>
+              <option value="toll_free">Toll free</option>
+            </select>
+          </Field>
+          <Field id="ns-country" label="Country (ISO code)">
+            <Input id="ns-country" value={country} maxLength={2} onChange={(e) => setCountry(e.target.value)} />
+          </Field>
+          <Field id="ns-area" label="Area code">
+            <Input id="ns-area" inputMode="numeric" placeholder="415" value={areaCode} onChange={(e) => setAreaCode(e.target.value)} />
+          </Field>
+        </div>
+        <div className="grid gap-3 sm:grid-cols-[10rem_1fr_9rem]">
+          <Field id="ns-by" label="Narrow by">
+            <select id="ns-by" className={SELECT} value={by} onChange={(e) => setBy(e.target.value as "locality" | "pattern")}>
+              <option value="pattern">Digits or phrase</option>
+              <option value="locality">City</option>
+            </select>
+          </Field>
+          <Field id="ns-text" label={by === "pattern" ? "Digits or phrase" : "City"}>
+            <Input id="ns-text" placeholder={by === "pattern" ? "555 or 0100" : "San Francisco"} value={text} onChange={(e) => setText(e.target.value)} />
+          </Field>
+          {by === "pattern" ? (
+            <Field id="ns-match" label="Where it appears">
+              <select id="ns-match" className={SELECT} value={match} onChange={(e) => setMatch(e.target.value as "first" | "anywhere" | "last")}>
+                <option value="first">At the start</option>
+                <option value="anywhere">Anywhere</option>
+                <option value="last">At the end</option>
+              </select>
+            </Field>
+          ) : null}
+        </div>
+        <Button type="submit" loading={search.loading}>
+          <Search className="mr-1 h-4 w-4" aria-hidden /> Search numbers
+        </Button>
+        <p className="text-xs text-muted-foreground">Searching is free. Nothing is held or charged until you confirm a purchase.</p>
+      </form>
+
+      {search.error ? <ApiError error={search.error} onRetry={search.reset} /> : null}
+      {done ? <p role="status" className="rounded-md border border-border bg-muted px-3 py-2 text-sm">{done}</p> : null}
+
+      {results && results.length === 0 ? (
+        <EmptyState compact title="No numbers available" description="Try another area code, a shorter pattern, or the other carrier." />
+      ) : null}
+      {results && results.length > 0 ? (
+        <section aria-label="Available numbers" className="space-y-2">
+          <h3 className="text-sm font-medium">{plural(results.length, "number")} available</h3>
+          <ul className="divide-y rounded-md border border-border">
+            {results.map((r) => (
+              <li key={r.phone_number} className={`flex flex-wrap items-center justify-between gap-2 px-3 py-2 text-sm ${picked?.phone_number === r.phone_number ? "bg-muted" : ""}`}>
+                <span className="flex flex-wrap items-center gap-2">
+                  <Phone className="h-4 w-4 text-muted-foreground" aria-hidden />
+                  <span className="font-medium tabular-nums">{formatNumber(r.phone_number)}</span>
+                  <span className="text-xs text-muted-foreground">{[r.locality, r.region].filter(Boolean).join(", ")}</span>
+                  {r.capabilities?.voice ? <StatusPill tone="neutral">Voice</StatusPill> : null}
+                  {r.capabilities?.sms ? <StatusPill tone="neutral">SMS</StatusPill> : null}
+                </span>
+                <Button size="sm" variant="outline" aria-label={`Choose ${r.phone_number}`} onClick={() => { setPicked(r); setDone(null); buy.reset(); }}>
+                  {picked?.phone_number === r.phone_number ? "Chosen" : "Choose"}
+                </Button>
+              </li>
+            ))}
+          </ul>
+        </section>
+      ) : null}
+
+      {picked ? (
+        <section aria-label="Buy this number" className="space-y-3 rounded-md border border-border p-3">
+          <h3 className="text-sm font-medium">Buy {formatNumber(picked.phone_number)}</h3>
+          <div className="grid gap-3 sm:grid-cols-2">
+            <Field id="ns-use" label="What it is for">
+              <select id="ns-use" className={SELECT} value={use} onChange={(e) => setUse(e.target.value as Use)}>
+                {(Object.keys(USE_LABEL) as Use[]).map((u) => (
+                  <option key={u} value={u}>{USE_LABEL[u]}</option>
+                ))}
+              </select>
+            </Field>
+            <Field id="ns-assignee" label="Assign to (optional)">
+              <MemberPicker id="ns-assignee" label="Assign to" value={assignee?.id ?? null} selectedName={assignee?.name} onChange={setAssignee} />
+            </Field>
+          </div>
+          {use === "work" && !assignee ? <p className="text-xs text-muted-foreground">A personal work phone rings for one person: pick who, or it is yours.</p> : null}
+          {buy.error ? (
+            <ApiError
+              error={buy.error}
+              title={status === 402 ? "Not enough credits. Nothing was bought and nothing was charged." : status === 409 ? "That number is no longer available" : "The purchase did not go through"}
+              onRetry={buy.reset}
+            />
+          ) : null}
+          <Button onClick={() => setConfirming(true)}>Buy for about {PURCHASE_CREDITS} credits</Button>
+        </section>
+      ) : null}
+
+      {picked && confirming ? (
+        <ConfirmSpendDialog
+          open
+          tier="billable"
+          title={`Buy ${formatNumber(picked.phone_number)} from ${boughtFrom === "twilio" ? "Twilio" : "Telnyx"}`}
+          description={`This spends credits now, whether or not the number is ever used. It is then rented for about ${MONTHLY_RENTAL_CREDITS} credits a month until you release it. These are estimates: the exact rate comes from your plan.`}
+          estimatedCredits={PURCHASE_CREDITS}
+          confirmLabel="Buy number"
+          confirming={buy.loading}
+          onCancel={() => setConfirming(false)}
+          onConfirm={() => void buy.mutate(undefined).then(() => setConfirming(false))}
+        />
+      ) : null}
+    </div>
+  );
+}

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

@@ -0,0 +1,134 @@
+"use client";
+
+/**
+ * NumberSettings: how one number behaves. Answering mode, caller-ID verification, and who picks up.
+ *
+ * SDK operations, in order:
+ *   1. getVoiceAnsweringAgent     GET   /voice/numbers/answering-agent?number=       (read; who picks up when it is called)
+ *   2. updatePhoneCapabilities    PATCH /phone-numbers/update-capabilities           (write; switches a number between the
+ *                                 dialer and a voice AI agent and re-provisions it; admin-only)
+ *   3. updateVoiceInboundType     PATCH /voice/numbers/inbound-type                  (write; retypes among ai, sdr, dialer
+ *                                 and work on the voice side)
+ *   4. verifyVoiceCallerId        POST  /voice/numbers/verify-caller-id/{number}     (write; Telnyx numbers only)
+ *
+ * Mapping: "Voice AI agent" and "Outbound dialer" go through 2 (the app's own derivation, which also updates the CRM
+ * record); "Rep answers" and "Personal work phone" go through 3. Changing the mode tears down and rebuilds the number's
+ * routing, so the number answers nothing for a moment: the change takes a second click on a button that says so.
+ * Call forwarding, voicemail greetings and ring-group routing have no API operations, so they are not offered here.
+ */
+
+import { useState } from "react";
+import { ExternalLink } from "lucide-react";
+import { Button } from "@graph8/sdk/ui";
+import { g8Get, g8Patch, g8Post } from "@/g8/lib/g8-client";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { useBrand, brandUrl } from "@/g8/hooks/use-brand";
+import { ApiError } from "@/g8/components/api-error";
+import { KeyValueList } from "@/g8/components/screen/key-value-list";
+import { StatusPill } from "@/g8/components/screen/status-pill";
+import { INBOUND_LABEL, INBOUND_TYPES, dataOf, formatNumber, scalarItems, typeLabel } from "../lib/phone-numbers-utils";
+import type { InboundType, NumberRow } from "../lib/phone-numbers-utils";
+
+export interface NumberSettingsProps {
+  row: NumberRow;
+  onChanged?: () => void;
+  className?: string;
+}
+
+const SELECT = "h-9 rounded-md border border-border bg-background px-2 text-sm";
+
+export function NumberSettings({ row, onChanged, className }: NumberSettingsProps) {
+  const brand = useBrand();
+  // An unreported mode is "" (never guessed as voice AI), so every real mode can be applied to it.
+  const current: InboundType | "" = (INBOUND_TYPES as readonly string[]).includes(row.inboundType) ? (row.inboundType as InboundType) : "";
+  const [mode, setMode] = useState<InboundType | "">(current);
+  const [armed, setArmed] = useState(false);
+  const [note, setNote] = useState<string | null>(null);
+
+  const who = useG8Query(async (signal) => dataOf(await g8Get("/voice/numbers/answering-agent", { number: row.number }, { signal })), [row.number]);
+
+  const retype = useG8Mutation(async (next: InboundType) => {
+    if (next === "ai" || next === "dialer") await g8Patch("/phone-numbers/update-capabilities", { phone_number: row.number, dialer: next === "dialer", voice: next === "ai" });
+    else await g8Patch("/voice/numbers/inbound-type", { number: row.number, inbound_type: next });
+    setNote(`${formatNumber(row.number)} is now: ${INBOUND_LABEL[next]}.`);
+    setArmed(false);
+    onChanged?.();
+    void who.refetch();
+  });
+  const verify = useG8Mutation(async () => {
+    const res = dataOf(await g8Post(`/voice/numbers/verify-caller-id/${encodeURIComponent(row.number)}`, {}));
+    const state = typeof res.status === "string" ? res.status : typeof res.result === "string" ? res.result : "verification_started";
+    setNote(state.includes("already") ? "Already verified as a caller ID." : "Verification started. It takes a few minutes; this page shows the result once it lands.");
+    onChanged?.();
+  });
+
+  const changed = mode !== "" && mode !== current;
+  const telnyx = row.provider === "telnyx";
+  const answering = scalarItems(who.data ?? {});
+
+  return (
+    <div className={`space-y-6 ${className ?? ""}`}>
+      <section className="space-y-2" aria-label="Answering mode">
+        <h3 className="text-sm font-medium">Answering mode</h3>
+        <div className="flex flex-wrap items-center gap-2">
+          <select aria-label="Answering mode" className={SELECT} value={mode} onChange={(e) => { setMode(e.target.value as InboundType | ""); setArmed(false); retype.reset(); }}>
+            {current === "" ? <option value="" disabled>Not reported</option> : null}
+            {INBOUND_TYPES.map((t) => (
+              <option key={t} value={t}>{INBOUND_LABEL[t]}</option>
+            ))}
+          </select>
+          {!armed ? (
+            <Button variant="outline" disabled={!changed} onClick={() => setArmed(true)}>Change mode</Button>
+          ) : (
+            <Button loading={retype.loading} onClick={() => mode !== "" && void retype.mutate(mode)}>Switch now: the number answers nothing for a moment</Button>
+          )}
+          {armed ? <Button variant="ghost" onClick={() => setArmed(false)}>Cancel</Button> : null}
+        </div>
+        <p className="text-xs text-muted-foreground">
+          Now: {typeLabel(row.inboundType)}. Switching rebuilds how calls reach the number, so calls in that moment are missed. Admin-only.
+        </p>
+        {retype.error ? <ApiError error={retype.error} title="The mode did not change" onRetry={retype.reset} /> : null}
+      </section>
+
+      <section className="space-y-2" aria-label="Caller ID">
+        <h3 className="text-sm font-medium">Caller ID</h3>
+        {telnyx ? (
+          <div className="flex flex-wrap items-center gap-2">
+            <StatusPill tone={row.callerIdVerified === true ? "positive" : row.callerIdVerified === false ? "warning" : "neutral"} dot>
+              {row.callerIdVerified === true ? "Verified" : row.callerIdVerified === false ? "Not verified" : "Unknown"}
+            </StatusPill>
+            <Button size="sm" variant="outline" loading={verify.loading} disabled={row.callerIdVerified === true} onClick={() => void verify.mutate(undefined)}>
+              Verify as caller ID
+            </Button>
+          </div>
+        ) : row.provider === "twilio" ? (
+          <p className="text-sm text-muted-foreground">Twilio numbers are valid caller IDs as they are. Nothing to verify.</p>
+        ) : (
+          <p className="text-sm text-muted-foreground">The carrier is not reported for this number, so caller-ID verification cannot be offered.</p>
+        )}
+        {telnyx ? <p className="text-xs text-muted-foreground">An unverified number cannot place calls, so it stays out of the dialer rotation.</p> : null}
+        {verify.error ? <ApiError error={verify.error} title="Verification did not start" onRetry={verify.reset} /> : null}
+      </section>
+
+      <section className="space-y-2" aria-label="Who answers">
+        <h3 className="text-sm font-medium">Who answers</h3>
+        {who.error ? (
+          <ApiError compact error={who.error} onRetry={() => void who.refetch()} />
+        ) : answering.length > 0 ? (
+          <KeyValueList items={answering} />
+        ) : (
+          <p className="text-sm text-muted-foreground">{who.loading ? "Looking up who answers." : "No answering agent is set for this number."}</p>
+        )}
+      </section>
+
+      {note ? <p role="status" className="text-sm">{note}</p> : null}
+      <p className="text-xs text-muted-foreground">
+        Call forwarding, voicemail greetings and ring-group routing are not available through the API yet.{" "}
+        <a className="inline-flex items-center gap-1 underline" href={brandUrl(brand)} target="_blank" rel="noreferrer">
+          Manage them in {brand.linkLabel} <ExternalLink className="h-3 w-3" aria-hidden />
+        </a>
+      </p>
+    </div>
+  );
+}

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

@@ -0,0 +1,97 @@
+"use client";
+
+/**
+ * NumberUsage: how hard one number is being used today, against the daily cap that keeps carriers from flagging it.
+ *
+ * SDK operations:
+ *   resetVoiceDailyCounts  DELETE /voice/numbers/daily-counts  (destructive: clears today's outbound call counters for EVERY
+ *                          number in the workspace, which lets numbers dial past a cap that exists to protect their
+ *                          reputation. Admin-only. Confirmed with ConfirmSpendDialog.)
+ *
+ * The figures come from the number list (GET /voice/dialer/numbers), so this component reads nothing itself. Counters
+ * reset on their own at midnight US Eastern. Costs: the API has no per-number cost read; the rental is shown as an
+ * estimate on the purchase dialog only, and a number the platform provisioned for you is never rental-billed.
+ */
+
+import { useState } from "react";
+import { Button } from "@graph8/sdk/ui";
+import { g8Delete } 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 { KeyValueList } from "@/g8/components/screen/key-value-list";
+import { StatusPill } from "@/g8/components/screen/status-pill";
+import { dataOf, numberHealth, percent } from "../lib/phone-numbers-utils";
+import type { NumberRow } from "../lib/phone-numbers-utils";
+
+export interface NumberUsageProps {
+  row: NumberRow;
+  onChanged?: () => void;
+  className?: string;
+}
+
+const show = (n: number | null) => (n == null ? "-" : n.toLocaleString());
+
+export function NumberUsage({ row, onChanged, className }: NumberUsageProps) {
+  const [confirming, setConfirming] = useState(false);
+  const [note, setNote] = useState<string | null>(null);
+  const reset = useG8Mutation(async () => {
+    const out = dataOf(await g8Delete("/voice/numbers/daily-counts"));
+    const n = typeof out.deleted === "number" ? out.deleted : null;
+    setNote(n === null ? "Today's counters were cleared." : `Cleared ${n.toLocaleString()} counter${n === 1 ? "" : "s"}.`);
+    setConfirming(false);
+    onChanged?.();
+  });
+  const health = numberHealth(row);
+  const used = row.callsToday ?? 0;
+  const pct = row.dailyLimit ? Math.min(100, Math.round((used / row.dailyLimit) * 100)) : 0;
+
+  return (
+    <div className={`space-y-5 ${className ?? ""}`}>
+      <div className="flex items-center gap-2">
+        <StatusPill tone={health.tone} dot>{health.label}</StatusPill>
+        {row.isValid === false ? <span className="text-xs text-muted-foreground">The carrier would refuse calls from this number.</span> : null}
+      </div>
+      <div className="space-y-1">
+        <div className="flex items-baseline justify-between text-sm">
+          <span>Outbound calls today</span>
+          <span className="tabular-nums">{show(row.callsToday)} of {row.dailyLimit ? row.dailyLimit.toLocaleString() : "no limit set"}</span>
+        </div>
+        <div role="progressbar" aria-label="Daily limit used" aria-valuenow={pct} aria-valuemin={0} aria-valuemax={100} className="h-2 overflow-hidden rounded-full bg-muted">
+          <div className={`h-full ${pct >= 100 ? "bg-error" : pct >= 80 ? "bg-warning" : "bg-primary"}`} style={{ width: `${pct}%` }} />
+        </div>
+      </div>
+      <KeyValueList
+        columns={2}
+        items={[
+          { label: "Calls, last 7 days", value: show(row.calls7d) },
+          { label: "Connect rate, 7 days", value: percent(row.connectRate7d) },
+          { label: "Daily limit", value: row.dailyLimit ? show(row.dailyLimit) : "-" },
+          { label: "Carrier", value: row.provider ? (row.provider === "telnyx" ? "Telnyx" : "Twilio") : "-" },
+        ]}
+      />
+      <section className="space-y-2 rounded-md border border-border p-3" aria-label="Reset counters">
+        <h3 className="text-sm font-medium">Reset today&apos;s counters</h3>
+        <p className="text-sm text-muted-foreground">
+          Clears today&apos;s call counts for every number in the workspace, not only this one, so they can dial past the daily limit that protects them from being flagged
+          as spam. They reset on their own at midnight US Eastern. Admin-only.
+        </p>
+        <Button variant="outline" onClick={() => setConfirming(true)}>Reset counters</Button>
+        {reset.error ? <ApiError error={reset.error} title="The counters were not reset" onRetry={reset.reset} /> : null}
+        {note ? <p role="status" className="text-sm">{note}</p> : null}
+      </section>
+      {confirming ? (
+        <ConfirmSpendDialog
+          open
+          tier="destructive"
+          title="Reset today's call counters for every number"
+          description="Numbers that have reached their daily limit can dial again today. The limit exists to keep carriers from flagging a number as spam."
+          confirmLabel="Reset counters"
+          confirming={reset.loading}
+          onCancel={() => setConfirming(false)}
+          onConfirm={() => void reset.mutate(undefined).then(() => setConfirming(false))}
+        />
+      ) : null}
+    </div>
+  );
+}

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

@@ -0,0 +1,84 @@
+"use client";
+
+/**
+ * PhoneNumberDetail: one number in full, as tabs: Overview, Assign, Usage, Settings and Release. Each tab is its own
+ * component (AssignNumber, NumberUsage, NumberSettings, ReleaseNumber) that owns its operations and confirm dialogs.
+ *
+ * SDK operations: none of its own (the composed parts call them).
+ *
+ * Billing, stated honestly: the API reports no rental per number, so Overview does not guess one. A number bought here is
+ * rented monthly after purchase (see the purchase dialog for the estimate); a number the platform set up for you, such as
+ * the onboarding receptionist line, is never rental-billed.
+ */
+
+import type { ReactNode } from "react";
+import { Phone } from "lucide-react";
+import { DetailPanel } from "@/g8/components/screen/detail-panel";
+import { KeyValueList } from "@/g8/components/screen/key-value-list";
+import { StatusPill } from "@/g8/components/screen/status-pill";
+import { AssignNumber } from "./assign-number";
+import { NumberSettings } from "./number-settings";
+import { NumberUsage } from "./number-usage";
+import { ReleaseNumber } from "./release-number";
+import { formatNumber, numberHealth, shortDate, typeLabel } from "../lib/phone-numbers-utils";
+import type { NumberRow } from "../lib/phone-numbers-utils";
+
+export interface PhoneNumberDetailProps {
+  row: NumberRow;
+  tab?: string;
+  onTabChange?: (tab: string) => void;
+  onClose?: () => void;
+  onExpand?: () => void;
+  onCollapse?: () => void;
+  /** The list should reload (something about the number changed). */
+  onChanged?: () => void;
+  /** The number was released: the record is gone. */
+  onReleased?: () => void;
+  renderActions?: (row: NumberRow) => ReactNode;
+  extraTabs?: Array<{ id: string; label: string; render: (row: NumberRow) => ReactNode }>;
+}
+
+export function PhoneNumberDetail({ row, tab, onTabChange, onClose, onExpand, onCollapse, onChanged, onReleased, renderActions, extraTabs }: PhoneNumberDetailProps) {
+  const health = numberHealth(row);
+  const overview = (
+    <div className="space-y-4">
+      <KeyValueList
+        columns={2}
+        items={[
+          { label: "Number", value: row.number, mono: true },
+          { label: "Use", value: typeLabel(row.inboundType) },
+          { label: "Carrier", value: row.provider === "telnyx" ? "Telnyx" : row.provider === "twilio" ? "Twilio" : "-" },
+          { label: "Assigned to", value: row.assignedTo ?? "-" },
+          { label: "Voice agent", value: row.agentName ?? "-" },
+          { label: "Added", value: shortDate(row.createdAt) },
+        ]}
+      />
+      <p className="text-sm text-muted-foreground">
+        The API does not report a rental price per number. A number bought here is rented monthly after purchase; a number the platform set up for you is never
+        rental-billed.
+      </p>
+    </div>
+  );
+  return (
+    <DetailPanel
+      title={formatNumber(row.number)}
+      subtitle={typeLabel(row.inboundType)}
+      avatar={<Phone className="h-5 w-5" aria-hidden />}
+      badges={<StatusPill tone={health.tone} dot>{health.label}</StatusPill>}
+      actions={renderActions?.(row)}
+      activeTab={tab || "overview"}
+      onTabChange={onTabChange}
+      onClose={onClose}
+      onExpand={onExpand}
+      onCollapse={onCollapse}
+      tabs={[
+        { id: "overview", label: "Overview", content: overview },
+        { id: "assign", label: "Assign", content: <AssignNumber row={row} onChanged={onChanged} /> },
+        { id: "usage", label: "Usage", content: <NumberUsage row={row} onChanged={onChanged} /> },
+        { id: "settings", label: "Settings", content: <NumberSettings row={row} onChanged={onChanged} /> },
+        { id: "release", label: "Release", content: <ReleaseNumber row={row} onChanged={onChanged} onReleased={onReleased} /> },
+        ...(extraTabs ?? []).map((t) => ({ id: t.id, label: t.label, content: t.render(row) })),
+      ]}
+    />
+  );
+}