@graph8/sdk 0.370.0 → 0.374.0

package/blocks/phone-numbers/components/a2p-registration.tsx

@@ -0,0 +1,230 @@
+"use client";
+
+/**
+ * A2pRegistration: US carriers filter text messages from numbers whose business is not registered (A2P 10DLC). This shows
+ * where the workspace's registration stands, saves the details as a draft, submits them, and re-runs numbers that got stuck.
+ *
+ * SDK operations, in order:
+ *   1. getPhoneA2pStatus              GET  /phone-numbers/a2p/status      (read; brand and campaign status, missing inputs, carrier failures)
+ *   2. saveA2pInputs                  POST /phone-numbers/a2p/inputs      (write; saves a DRAFT, sends nothing; it REPLACES what was saved,
+ *                                     so the whole object is sent, merged over what the status returned)
+ *   3. startA2pRegistration           POST /phone-numbers/a2p/register    (external: reaches the carrier registry and carries
+ *                                     carrier fees, takes days and can be rejected. Idempotent per workspace. Confirmed
+ *                                     with ConfirmSpendDialog.)
+ *   4. reconcileA2pRegistration       POST /phone-numbers/a2p/reconcile   (write; re-attaches pending or failed numbers; safe to repeat)
+ *
+ * The form is shown only once the status has loaded and is seeded from it, so a save never overwrites saved details with blanks.
+ * Brand and campaign objects are open: keys this form does not edit (an address, say) are carried through untouched.
+ */
+
+import { useEffect, useState } from "react";
+import { Button, Input, Label, Textarea } from "@graph8/sdk/ui";
+import { g8Get, g8Post } from "@/g8/lib/g8-client";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+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 { SectionCard } from "@/g8/components/screen/section-card";
+import { StatusPill } from "@/g8/components/screen/status-pill";
+import { Skeleton } from "@graph8/sdk/ui";
+import { a2pTone, asObject, dataOf } from "../lib/phone-numbers-utils";
+
+export interface A2pRegistrationProps {
+  /** Called when the status was reloaded, so a stat can follow it. */
+  onStatus?: (status: A2pStatus) => void;
+  className?: string;
+}
+
+export interface A2pStatus {
+  brandStatus: string | null;
+  campaignStatus: string | null;
+  submitted: boolean;
+  inputsComplete: boolean;
+  missing: string[];
+  failures: Array<{ scope?: string | null; code?: number | null; reason?: string | null; fields?: string[] }>;
+  brand: Record<string, unknown>;
+  campaign: Record<string, unknown>;
+}
+
+export function a2pStatusOf(envelope: unknown): A2pStatus {
+  const d = dataOf(envelope);
+  const text = (v: unknown) => (typeof v === "string" && v ? v : null);
+  return {
+    brandStatus: text(d.brand_status),
+    campaignStatus: text(d.campaign_status),
+    submitted: Boolean(d.workflow_id),
+    inputsComplete: d.inputs_complete === true,
+    missing: Array.isArray(d.missing_inputs) ? d.missing_inputs.filter((m): m is string => typeof m === "string") : [],
+    failures: (Array.isArray(d.failures) ? d.failures : []).map((f) => asObject(f)) as A2pStatus["failures"],
+    brand: asObject(d.brand_inputs),
+    campaign: asObject(d.campaign_inputs),
+  };
+}
+
+const NAMES: Record<string, string> = {
+  legal_business_name: "Legal business name",
+  use_case: "Use case",
+  message_samples: "Sample messages",
+  description: "Campaign description",
+  message_flow: "How people opt in",
+  privacy_policy_url: "Privacy policy URL",
+  terms_and_conditions_url: "Terms of service URL",
+};
+
+const BRAND_FIELDS: Array<[string, string, string]> = [
+  ["legal_business_name", "Legal business name", "Acme Inc."],
+  ["ein", "EIN (tax id)", "12-3456789"],
+  ["website", "Website", "https://acme.example"],
+  ["business_type", "Business type", "Corporation"],
+  ["vertical", "Industry", "Technology"],
+];
+const CAMPAIGN_LINES: Array<[string, string, string]> = [
+  ["use_case", "Use case", "MIXED, MARKETING or ACCOUNT_NOTIFICATION"],
+  ["privacy_policy_url", "Privacy policy URL", "https://acme.example/privacy"],
+  ["terms_and_conditions_url", "Terms of service URL", "https://acme.example/terms"],
+];
+
+const asText = (v: unknown): string => (typeof v === "string" ? v : "");
+const samplesOf = (v: unknown): string => (Array.isArray(v) ? v.filter((x) => typeof x === "string").join("\n") : asText(v));
+
+export function A2pRegistration({ onStatus, className }: A2pRegistrationProps) {
+  const q = useG8Query(async (signal) => a2pStatusOf(await g8Get("/phone-numbers/a2p/status", undefined, { signal })), []);
+  const status = q.data;
+  useEffect(() => {
+    if (status) onStatus?.(status);
+  }, [status]); // eslint-disable-line react-hooks/exhaustive-deps
+  if (q.error && !status) return <ApiError error={q.error} onRetry={() => void q.refetch()} className={className} />;
+  if (!status) return <Skeleton className={`h-40 w-full ${className ?? ""}`} />;
+  // The form is mounted only once the status has loaded, with its state seeded at the FIRST render from it. (Seeding in an effect
+  // let an edit typed right after the form appeared be overwritten by the late seed, and a save then dropped that field.)
+  // A reload after a save keeps what is typed; the save merges over the fresh server copy (`status`).
+  return <A2pForm status={status} reload={() => q.refetch()} className={className} />;
+}
+
+function A2pForm({ status, reload, className }: { status: A2pStatus; reload: () => Promise<unknown>; className?: string }) {
+  const [brand, setBrand] = useState<Record<string, string>>(() => Object.fromEntries(BRAND_FIELDS.map(([k]) => [k, asText(status.brand[k])])));
+  const [campaign, setCampaign] = useState<Record<string, string>>(() =>
+    Object.fromEntries([...CAMPAIGN_LINES.map(([k]) => k), "description", "message_flow", "opt_in_method"].map((k) => [k, asText(status.campaign[k])])),
+  );
+  const [samples, setSamples] = useState(() => samplesOf(status.campaign.message_samples));
+  const [confirming, setConfirming] = useState(false);
+  const [note, setNote] = useState<string | null>(null);
+
+  const body = () => {
+    const clean = (o: Record<string, string>) => Object.fromEntries(Object.entries(o).filter(([, v]) => v.trim() !== "").map(([k, v]) => [k, v.trim()]));
+    const lines = samples.split("\n").map((l) => l.trim()).filter(Boolean);
+    return {
+      brand_inputs: { ...status.brand, ...clean(brand) },
+      campaign_inputs: { ...status.campaign, ...clean(campaign), ...(lines.length ? { message_samples: lines } : {}) },
+    };
+  };
+
+  const save = useG8Mutation(async () => {
+    await g8Post("/phone-numbers/a2p/inputs", body());
+    setNote("Draft saved. Nothing was sent to the carriers.");
+    await reload();
+  });
+  const submit = useG8Mutation(async () => {
+    await g8Post("/phone-numbers/a2p/register", body());
+    setNote("Registration submitted. The carriers take days to decide; this page shows the result.");
+    setConfirming(false);
+    await reload();
+  });
+  const reconcile = useG8Mutation(async () => {
+    await g8Post("/phone-numbers/a2p/reconcile", {});
+    setNote("Pending and failed numbers were re-attached to the messaging service.");
+    await reload();
+  });
+
+  const failed = status.failures.filter((f) => f.reason);
+  const busy = save.loading || submit.loading || reconcile.loading;
+  const field = (id: string, label: string, value: string, set: (v: string) => void, placeholder?: string) => (
+    <div className="space-y-1" key={id}>
+      <Label htmlFor={`a2p-${id}`}>{label}</Label>
+      <Input id={`a2p-${id}`} value={value} placeholder={placeholder} onChange={(e) => set(e.target.value)} />
+    </div>
+  );
+
+  return (
+    <div className={`space-y-4 ${className ?? ""}`}>
+      <SectionCard
+        title="Text message registration (A2P 10DLC)"
+        description="US carriers filter business text messages from numbers that are not registered."
+        actions={
+          <StatusPill tone={a2pTone(status.campaignStatus ?? status.brandStatus)} dot>
+            {status.campaignStatus ?? status.brandStatus ?? "Not started"}
+          </StatusPill>
+        }
+      >
+        <KeyValueList
+          columns={2}
+          items={[
+            { label: "Brand", value: status.brandStatus ?? "-" },
+            { label: "Campaign", value: status.campaignStatus ?? "-" },
+            { label: "Submitted", value: status.submitted ? "Yes" : "No" },
+            { label: "Details complete", value: status.inputsComplete ? "Yes" : "No" },
+          ]}
+        />
+        {status.missing.length > 0 ? (
+          <p className="mt-3 text-sm text-muted-foreground">Still needed: {status.missing.map((m) => NAMES[m] ?? m).join(", ")}.</p>
+        ) : null}
+        {failed.length > 0 ? (
+          <ul aria-label="Carrier feedback" className="mt-3 space-y-1 text-sm">
+            {failed.map((f, i) => (
+              <li key={i} className="rounded-md border border-border bg-muted px-3 py-2">
+                {f.scope ? <span className="font-medium capitalize">{f.scope}: </span> : null}
+                {f.reason}
+                {f.code ? <span className="text-xs text-muted-foreground"> (code {f.code})</span> : null}
+              </li>
+            ))}
+          </ul>
+        ) : null}
+      </SectionCard>
+
+      <SectionCard title="Business and campaign details" description="Saving a draft sends nothing. Submitting registers with the carriers.">
+        <form className="space-y-4" onSubmit={(e) => { e.preventDefault(); void save.mutate(undefined); }}>
+          <div className="grid gap-3 sm:grid-cols-2">
+            {BRAND_FIELDS.map(([k, label, ph]) => field(`b-${k}`, label, brand[k] ?? "", (v) => setBrand((b) => ({ ...b, [k]: v })), ph))}
+            {CAMPAIGN_LINES.map(([k, label, ph]) => field(`c-${k}`, label, campaign[k] ?? "", (v) => setCampaign((c) => ({ ...c, [k]: v })), ph))}
+          </div>
+          <div className="space-y-1">
+            <Label htmlFor="a2p-description">What the messages are (40 characters or more)</Label>
+            <Textarea id="a2p-description" rows={2} value={campaign.description ?? ""} onChange={(e) => setCampaign((c) => ({ ...c, description: e.target.value }))} />
+          </div>
+          <div className="space-y-1">
+            <Label htmlFor="a2p-flow">How people opt in (40 characters or more)</Label>
+            <Textarea id="a2p-flow" rows={2} value={campaign.message_flow ?? ""} onChange={(e) => setCampaign((c) => ({ ...c, message_flow: e.target.value }))} />
+          </div>
+          <div className="space-y-1">
+            <Label htmlFor="a2p-samples">Sample messages (one per line)</Label>
+            <Textarea id="a2p-samples" rows={3} value={samples} onChange={(e) => setSamples(e.target.value)} />
+          </div>
+          <div className="flex flex-wrap gap-2">
+            <Button type="submit" variant="outline" loading={save.loading} disabled={busy}>Save draft</Button>
+            <Button type="button" disabled={busy || !status.inputsComplete} onClick={() => setConfirming(true)}>Submit registration</Button>
+            <Button type="button" variant="ghost" loading={reconcile.loading} disabled={busy} onClick={() => void reconcile.mutate(undefined)}>Retry stuck numbers</Button>
+          </div>
+          {!status.inputsComplete ? <p className="text-xs text-muted-foreground">Submitting unlocks once the saved details are complete. Save the draft to check.</p> : null}
+        </form>
+        {save.error ? <ApiError error={save.error} title="The draft was not saved" onRetry={save.reset} className="mt-3" /> : null}
+        {submit.error ? <ApiError error={submit.error} title="The registration was not submitted" onRetry={submit.reset} className="mt-3" /> : null}
+        {reconcile.error ? <ApiError error={reconcile.error} title="The numbers were not re-attached" onRetry={reconcile.reset} className="mt-3" /> : null}
+        {note ? <p role="status" className="mt-3 text-sm">{note}</p> : null}
+      </SectionCard>
+
+      {confirming ? (
+        <ConfirmSpendDialog
+          open
+          tier="external"
+          title="Submit the registration to the carriers"
+          description="This sends your business details to the US carrier registry and carries carrier fees. It takes days, the carriers can reject it, and a second submit while one is running does nothing."
+          confirmLabel="Submit registration"
+          confirming={submit.loading}
+          onCancel={() => setConfirming(false)}
+          onConfirm={() => void submit.mutate(undefined).then(() => setConfirming(false))}
+        />
+      ) : null}
+    </div>
+  );
+}

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

@@ -0,0 +1,104 @@
+"use client";
+
+/**
+ * AssignNumber: who a number belongs to. The assignee is not a label: it decides who the number rings, who is told about
+ * a missed call, and whose outbound caller-ID pool it joins.
+ *
+ * SDK operations:
+ *   updatePhoneAssignee  PATCH /phone-numbers/update-assignee  (write; moves the number to a person, in the CRM record and in voice)
+ *   updateVoiceAssignee  PATCH /voice/numbers/assignee         (write; the VOICE half alone. `assigned_to: ""` clears the
+ *                                                               assignment, and sending the current assignee again re-syncs voice)
+ *
+ * The person comes from MemberPicker (no one types an email); "Assign to me" uses the signed-in member. Reassigning is
+ * admin-only through the API: a 403 says so instead of failing silently.
+ * Unassign is VOICE-ONLY: update-assignee requires an assignee, so there is no operation that clears the CRM record's owner.
+ * The UI says so next to the button.
+ */
+
+import { useState } from "react";
+import { Button } from "@graph8/sdk/ui";
+import { g8Patch } 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 { useCurrentMember } from "@/g8/pickers/hooks/use-current-member";
+import { formatNumber } from "../lib/phone-numbers-utils";
+import type { NumberRow } from "../lib/phone-numbers-utils";
+
+export interface AssignNumberProps {
+  row: NumberRow;
+  /** Called after the assignment changed, so the list can refresh. */
+  onChanged?: () => void;
+  className?: string;
+}
+
+export function AssignNumber({ row, onChanged, className }: AssignNumberProps) {
+  const me = useCurrentMember();
+  const [picked, setPicked] = useState<MemberOption | null>(null);
+  const [note, setNote] = useState<string | null>(null);
+
+  const assign = useG8Mutation(async (member: MemberOption) => {
+    if (!member.email) throw new Error(`${member.name} has no email on file, so the number cannot be assigned to them.`);
+    await g8Patch("/phone-numbers/update-assignee", { phone_number: row.number, assignee: member.email });
+    setNote(`${formatNumber(row.number)} now rings for ${member.name}.`);
+    setPicked(null);
+    onChanged?.();
+  });
+  const voice = useG8Mutation(async (assignedTo: string) => {
+    await g8Patch("/voice/numbers/assignee", { number: row.number, assigned_to: assignedTo });
+    setNote(assignedTo ? "Voice assignment re-synced." : `${formatNumber(row.number)} is unassigned.`);
+    onChanged?.();
+  });
+
+  const error = assign.error ?? voice.error;
+  const forbidden = (error as { status?: number } | undefined)?.status === 403;
+  const busy = assign.loading || voice.loading;
+  const clearError = () => {
+    assign.reset();
+    voice.reset();
+  };
+
+  return (
+    <div className={`space-y-3 ${className ?? ""}`}>
+      <p className="text-sm">
+        {row.assignedTo ? (
+          <>Assigned to <span className="font-medium">{row.assignedTo}</span>.</>
+        ) : (
+          "Not assigned to anyone."
+        )}
+        {row.agentName ? <> Held by the voice agent <span className="font-medium">{row.agentName}</span>.</> : null}
+      </p>
+      <div className="flex flex-wrap items-end gap-2">
+        <MemberPicker label="Assign to" value={picked?.id ?? null} selectedName={picked?.name} onChange={setPicked} disabled={busy} />
+        <Button disabled={!picked || busy} loading={assign.loading} onClick={() => picked && void assign.mutate(picked)}>
+          Assign
+        </Button>
+        {me.member ? (
+          <Button variant="outline" disabled={busy} onClick={() => me.member && void assign.mutate(me.member)}>
+            Assign to me
+          </Button>
+        ) : null}
+      </div>
+      {row.assignedTo ? (
+        <div className="flex flex-wrap gap-2">
+          <Button size="sm" variant="outline" disabled={busy} onClick={() => void voice.mutate("")}>
+            Unassign (voice)
+          </Button>
+          <Button size="sm" variant="ghost" disabled={busy} onClick={() => void voice.mutate(row.assignedTo ?? "")}>
+            Re-sync voice record
+          </Button>
+        </div>
+      ) : null}
+      <p className="text-xs text-muted-foreground">
+        Unassign clears the voice assignment only; the API has no way to clear the owner on the CRM record, so assign someone else to change that.
+      </p>
+      <p className="text-xs text-muted-foreground">
+        The assignee decides who the number rings, who hears about a missed call, and whose outbound caller IDs include it.
+        Only workspace admins can reassign numbers through the API.
+      </p>
+      {note ? <p role="status" className="text-sm">{note}</p> : null}
+      {error ? <ApiError error={error} title={forbidden ? "Only workspace admins can reassign numbers" : "The assignment did not change"} onRetry={clearError} /> : null}
+    </div>
+  );
+}

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