@graph8/sdk 0.370.0 → 0.374.0

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) })),
+      ]}
+    />
+  );
+}

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>
+  );
+}