@graph8/sdk 0.362.0 → 0.373.0

package/blocks/phone-numbers/block.json

@@ -0,0 +1,262 @@
+{
+  "$schema": "../block.schema.json",
+  "id": "phone-numbers",
+  "title": "Phone numbers",
+  "summary": "Phone numbers: list, search and buy numbers, assign them to reps or agents, configure how they answer, check usage and text registration, and release them.",
+  "features": [
+    "every number in one list (dialer and voice agent numbers), searchable and filterable, paged on the client with Load more",
+    "search a carrier for available numbers by area code, digits or city, then buy one behind a confirm dialog that shows the price",
+    "assign a number to a teammate with a picker (or Assign to me), unassign it, re-sync its voice record",
+    "answering mode (voice AI agent, rep, dialer, personal work phone), Telnyx caller-ID verification, who answers",
+    "today's usage against the daily limit, 7-day calls and connect rate, confirmed counter reset",
+    "A2P 10DLC text registration: status, draft details, confirmed submit, retry stuck numbers",
+    "release a number (type it, then confirm) or remove its voice routing only, both confirmed"
+  ],
+  "dependsOn": [
+    "foundation",
+    "pickers"
+  ],
+  "operations": [
+    "delete_voice_number_voice_numbers_delete",
+    "get_my_team_member_team_members_me_get",
+    "get_phone_a2p_status_phone_numbers_a2p_status_get",
+    "get_voice_answering_agent_voice_numbers_answering_agent_get",
+    "list_agent_phone_numbers_voice_agent_phone_numbers_get",
+    "list_dialer_numbers_voice_dialer_numbers_get",
+    "list_team_members_team_members_get",
+    "provision_voice_number_voice_numbers_provision_post",
+    "purchase_phone_number_phone_numbers_purchase_post",
+    "reconcile_a2p_registration_phone_numbers_a2p_reconcile_post",
+    "release_phone_number_phone_numbers_release_post",
+    "reset_voice_daily_counts_voice_numbers_daily_counts_delete",
+    "save_a2p_inputs_phone_numbers_a2p_inputs_post",
+    "search_available_phone_numbers_phone_numbers_search_post",
+    "start_a2p_registration_phone_numbers_a2p_register_post",
+    "update_phone_assignee_phone_numbers_update_assignee_patch",
+    "update_phone_capabilities_phone_numbers_update_capabilities_patch",
+    "update_voice_assignee_voice_numbers_assignee_patch",
+    "update_voice_inbound_type_voice_numbers_inbound_type_patch",
+    "verify_voice_caller_id_voice_numbers_verify_caller_id__phone_number__post"
+  ],
+  "components": [
+    {
+      "name": "PhoneNumbersScreen",
+      "file": "components/phone-numbers-screen.tsx",
+      "purpose": "The finished Phone numbers page: inventory with stats, search and filters, a detail for each number, buy, add an owned number, and text registration. Composes the parts below.",
+      "operations": [],
+      "tiers": []
+    },
+    {
+      "name": "PhoneNumberList",
+      "file": "components/phone-number-list.tsx",
+      "purpose": "The numbers as a table, paged on the client with Load more so nothing is cut off silently. Reads nothing itself.",
+      "operations": [],
+      "tiers": []
+    },
+    {
+      "name": "PhoneNumberDetail",
+      "file": "components/phone-number-detail.tsx",
+      "purpose": "One number in full: Overview, Assign, Usage, Settings and Release tabs, with slots for extra actions and tabs.",
+      "operations": [],
+      "tiers": []
+    },
+    {
+      "name": "NumberSearch",
+      "file": "components/number-search.tsx",
+      "purpose": "Search a carrier for available numbers, choose one and buy it. The purchase is billable and opens a confirm dialog with the price estimate first.",
+      "operations": [
+        "list_team_members_team_members_get",
+        "purchase_phone_number_phone_numbers_purchase_post",
+        "search_available_phone_numbers_phone_numbers_search_post"
+      ],
+      "tiers": [
+        "read",
+        "billable"
+      ]
+    },
+    {
+      "name": "AssignNumber",
+      "file": "components/assign-number.tsx",
+      "purpose": "Assign a number to a teammate with a picker or Assign to me, unassign it, or re-sync its voice record.",
+      "operations": [
+        "get_my_team_member_team_members_me_get",
+        "list_team_members_team_members_get",
+        "update_phone_assignee_phone_numbers_update_assignee_patch",
+        "update_voice_assignee_voice_numbers_assignee_patch"
+      ],
+      "tiers": [
+        "read",
+        "write"
+      ]
+    },
+    {
+      "name": "NumberSettings",
+      "file": "components/number-settings.tsx",
+      "purpose": "Answering mode (voice AI, rep, dialer, work phone), Telnyx caller-ID verification and who answers the number.",
+      "operations": [
+        "get_voice_answering_agent_voice_numbers_answering_agent_get",
+        "update_phone_capabilities_phone_numbers_update_capabilities_patch",
+        "update_voice_inbound_type_voice_numbers_inbound_type_patch",
+        "verify_voice_caller_id_voice_numbers_verify_caller_id__phone_number__post"
+      ],
+      "tiers": [
+        "read",
+        "write"
+      ]
+    },
+    {
+      "name": "NumberUsage",
+      "file": "components/number-usage.tsx",
+      "purpose": "Today's calls against the daily limit, 7-day usage and connect rate, and a confirmed reset of today's counters.",
+      "operations": [
+        "reset_voice_daily_counts_voice_numbers_daily_counts_delete"
+      ],
+      "tiers": [
+        "destructive"
+      ]
+    },
+    {
+      "name": "ReleaseNumber",
+      "file": "components/release-number.tsx",
+      "purpose": "Release a number back to the carrier (type the number, then confirm) or remove its voice routing without releasing it. Both are confirmed.",
+      "operations": [
+        "delete_voice_number_voice_numbers_delete",
+        "release_phone_number_phone_numbers_release_post"
+      ],
+      "tiers": [
+        "destructive"
+      ]
+    },
+    {
+      "name": "RegisterOwnedNumber",
+      "file": "components/register-owned-number.tsx",
+      "purpose": "Register a number you already own with the voice platform. Buys nothing.",
+      "operations": [
+        "list_team_members_team_members_get",
+        "provision_voice_number_voice_numbers_provision_post"
+      ],
+      "tiers": [
+        "read",
+        "write"
+      ]
+    },
+    {
+      "name": "A2pRegistration",
+      "file": "components/a2p-registration.tsx",
+      "purpose": "A2P 10DLC text-message registration: status, a saved draft of the business details, a confirmed submit and a retry for stuck numbers.",
+      "operations": [
+        "get_phone_a2p_status_phone_numbers_a2p_status_get",
+        "reconcile_a2p_registration_phone_numbers_a2p_reconcile_post",
+        "save_a2p_inputs_phone_numbers_a2p_inputs_post",
+        "start_a2p_registration_phone_numbers_a2p_register_post"
+      ],
+      "tiers": [
+        "read",
+        "write",
+        "external"
+      ]
+    }
+  ],
+  "hooks": [
+    {
+      "name": "usePhoneNumbers",
+      "file": "hooks/use-phone-numbers.ts",
+      "purpose": "Every number of the workspace: the dialer list and the voice agents' numbers read together and merged. Neither endpoint caps or pages, so the whole inventory arrives; a key that cannot read agents still gets the dialer list and the hook says so.",
+      "operations": [
+        "list_agent_phone_numbers_voice_agent_phone_numbers_get",
+        "list_dialer_numbers_voice_dialer_numbers_get"
+      ]
+    }
+  ],
+  "lib": [
+    {
+      "file": "lib/phone-numbers-utils.ts",
+      "purpose": "Row types, the carrier and answering-mode enums, E.164 checks and formatting, the inventory merge, health and A2P tones, price estimates."
+    }
+  ],
+  "recipes": [
+    {
+      "file": "recipes/01-search-and-buy-number.ts",
+      "title": "Search for a number and buy it",
+      "when": "An agent setting up calling for a workspace. The search is free; the purchase spends credits and needs a human to approve it."
+    },
+    {
+      "file": "recipes/02-assign-number-to-rep.ts",
+      "title": "Assign a number to a rep, or clear it",
+      "when": "Onboarding a rep: give them a caller ID, or take a number back from someone who left."
+    },
+    {
+      "file": "recipes/03-audit-numbers.ts",
+      "title": "Audit the inventory: usage, unassigned numbers and text registration",
+      "when": "A health check before a calling campaign; read-only."
+    },
+    {
+      "file": "recipes/04-register-text-messaging.ts",
+      "title": "Save A2P details and check registration",
+      "when": "Before sending texts to US numbers; saving is safe, submitting reaches the carriers and needs approval."
+    }
+  ],
+  "prerequisites": [
+    {
+      "id": "credits",
+      "description": "Credits for buying a number: 250 are held on purchase, then about 250 a month in rental (estimates; the API has no price read). A 402 means not enough credits and nothing was charged.",
+      "where": "api",
+      "verify": "A test purchase of one number returns 200, or 402 with no charge."
+    },
+    {
+      "id": "admin-key",
+      "description": "Reassigning a number, switching its answering mode and resetting counters are admin-only through the API. A key without that role gets a 403, which the screens explain.",
+      "where": "api",
+      "verify": "PATCH /phone-numbers/update-assignee on a test number returns 200, not 403."
+    },
+    {
+      "id": "voice-scopes",
+      "description": "Key scopes voice:read, voice:write and voice:run (buy, A2P submit), voice:delete (release, remove routing, reset counters) and team:read for the assignee picker.",
+      "where": "api",
+      "verify": "`g8.api.me.describeCurrentKey()` lists voice:read, voice:write, voice:run, voice:delete and team:read."
+    }
+  ],
+  "scopes": [
+    "team:read",
+    "voice:delete",
+    "voice:read",
+    "voice:run",
+    "voice:write"
+  ],
+  "defaults": [
+    {
+      "decision": "Which carrier to buy from",
+      "default": "Twilio. Telnyx is one select away; a Telnyx number must then be verified as a caller ID before it can dial",
+      "askHuman": false
+    },
+    {
+      "decision": "What a newly bought number is for",
+      "default": "The outbound dialer, unassigned (it is the signed-in key's person unless an assignee is chosen)",
+      "askHuman": false
+    },
+    {
+      "decision": "Buying numbers",
+      "default": "Always behind a confirm dialog with the price estimate and an Idempotency-Key; never automatic",
+      "askHuman": true
+    },
+    {
+      "decision": "Releasing a number",
+      "default": "Needs the number typed and a second confirm; it cannot be undone and the number can be bought by anyone",
+      "askHuman": true
+    },
+    {
+      "decision": "Is a number billable",
+      "default": "The block never labels a number billable: the API reports no rental per number, and numbers the platform provisioned itself (the onboarding receptionist) are never rental-billed. Only the purchase dialog shows a price",
+      "askHuman": false
+    },
+    {
+      "decision": "Call forwarding, voicemail greetings and routing rules",
+      "default": "Not offered: the API has no operations for them. The screen points to the platform app",
+      "askHuman": false
+    }
+  ],
+  "peerDependencies": {
+    "react": ">=18",
+    "lucide-react": ">=0.400.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>
+  );
+}