@graph8/sdk 0.362.0 → 0.373.0

package/blocks/phone-numbers/lib/phone-numbers-utils.ts

@@ -0,0 +1,202 @@
+"use client";
+
+/**
+ * Types and helpers shared by the phone-numbers components. The voice endpoints answer open-shaped payloads, so every
+ * field is read defensively (a missing field is "unknown", never a crash and never a made-up default).
+ */
+
+/** The carriers a number can be bought from (the contract's enum on purchase and release). */
+export const PROVIDERS = ["twilio", "telnyx"] as const;
+export type Provider = (typeof PROVIDERS)[number];
+
+/** How a number answers inbound calls (the contract's enum on `inbound-type`). */
+export const INBOUND_TYPES = ["ai", "sdr", "dialer", "work"] as const;
+export type InboundType = (typeof INBOUND_TYPES)[number];
+
+export const INBOUND_LABEL: Record<InboundType, string> = {
+  ai: "Voice AI agent",
+  sdr: "Rep answers",
+  dialer: "Outbound dialer",
+  work: "Personal work phone",
+};
+
+/**
+ * What the platform holds when you buy, and charges each month after (credits). These are the platform's current
+ * rates (250 credits held on purchase, 250 per monthly rental); the API has no price read, so they are ESTIMATES the
+ * dialogs say so. Numbers the platform provisioned itself (the onboarding receptionist line) are never rental-billed.
+ */
+export const PURCHASE_CREDITS = 250;
+export const MONTHLY_RENTAL_CREDITS = 250;
+
+export interface NumberRow {
+  /** E.164, the number's id everywhere in the API. */
+  number: string;
+  /** Empty when the list does not say (never guessed). */
+  inboundType: string;
+  /** `twilio` or `telnyx`; empty when no list says (a number only the agents list knows). */
+  provider: string;
+  assignedTo: string | null;
+  callsToday: number | null;
+  calls7d: number | null;
+  connectRate7d: number | null;
+  dailyLimit: number | null;
+  createdAt: string | null;
+  /** False when the carrier would refuse to dial from it (for example an unverified Telnyx caller ID). */
+  isValid: boolean | null;
+  callerIdVerified: boolean | null;
+  /** Set when a voice AI agent has this number booked. */
+  agentName: string | null;
+  agentId: string | null;
+}
+
+export interface AvailableNumber {
+  phone_number: string;
+  capabilities?: { voice?: boolean; sms?: boolean; mms?: boolean; fax?: boolean };
+  region?: string | null;
+  locality?: string | null;
+}
+
+export const asObject = (v: unknown): Record<string, unknown> => (v && typeof v === "object" && !Array.isArray(v) ? (v as Record<string, unknown>) : {});
+const str = (v: unknown): string | null => (typeof v === "string" && v.trim() ? v : null);
+const num = (v: unknown): number | null => (typeof v === "number" && Number.isFinite(v) ? v : null);
+const bool = (v: unknown): boolean | null => (typeof v === "boolean" ? v : null);
+
+/** The envelope's `data`, or the value itself. */
+export function dataOf(envelope: unknown): Record<string, unknown> {
+  const o = asObject(envelope);
+  return "data" in o ? asObject(o.data) : o;
+}
+
+/** Rows of `data.<key>`, `data.items` or a bare `data` array. */
+function listAt(envelope: unknown, key: string): unknown[] {
+  const o = asObject(envelope);
+  const data = "data" in o ? o.data : envelope;
+  if (Array.isArray(data)) return data;
+  const inner = asObject(data);
+  const rows = inner[key] ?? inner.items;
+  return Array.isArray(rows) ? rows : [];
+}
+
+/** GET /voice/dialer/numbers rows (`data.numbers`). */
+export function dialerRows(envelope: unknown): NumberRow[] {
+  return listAt(envelope, "numbers")
+    .map((raw) => asObject(raw))
+    .filter((r) => str(r.number))
+    .map((r) => ({
+      number: String(r.number),
+      inboundType: str(r.inbound_type) ?? "",
+      provider: str(r.telephony_provider) ?? "",
+      assignedTo: str(r.assigned_to),
+      callsToday: num(r.calls_today),
+      calls7d: num(r.calls_7d),
+      connectRate7d: num(r.connect_rate_7d),
+      dailyLimit: num(r.daily_limit),
+      createdAt: str(r.created_at),
+      isValid: bool(r.is_valid),
+      callerIdVerified: bool(r.caller_id_verified),
+      agentName: null,
+      agentId: null,
+    }));
+}
+
+export interface AgentNumbers {
+  /** AI-capable numbers no agent holds. They also appear in the dialer list, so they only mark "free for an agent". */
+  available: string[];
+  booked: Array<{ number: string; agentName: string | null; agentId: string | null }>;
+}
+
+/** GET /voice/agent-phone-numbers (`available_numbers` strings, `booked_numbers` objects). */
+export function agentNumbers(envelope: unknown): AgentNumbers {
+  const d = dataOf(envelope);
+  const available = Array.isArray(d.available_numbers) ? d.available_numbers.filter((n): n is string => typeof n === "string") : [];
+  const booked = (Array.isArray(d.booked_numbers) ? d.booked_numbers : [])
+    .map((b) => asObject(b))
+    .filter((b) => str(b.number))
+    .map((b) => ({ number: String(b.number), agentName: str(b.agent_name), agentId: str(b.agent_id) }));
+  return { available, booked };
+}
+
+/**
+ * The whole inventory. The dialer list leaves out the numbers a voice AI agent holds, and the agent list leaves out
+ * dialer-only numbers, so the union is every number. A number in both keeps the dialer row (it has the usage stats) and
+ * gains the agent's name.
+ */
+export function mergeInventory(dialer: NumberRow[], agents: AgentNumbers): NumberRow[] {
+  const byKey = new Map<string, NumberRow>();
+  for (const r of dialer) byKey.set(digits(r.number), r);
+  for (const b of agents.booked) {
+    const hit = byKey.get(digits(b.number));
+    if (hit) byKey.set(digits(b.number), { ...hit, agentName: b.agentName, agentId: b.agentId });
+    else {
+      byKey.set(digits(b.number), {
+        number: b.number, inboundType: "ai", provider: "", assignedTo: null, callsToday: null, calls7d: null,
+        connectRate7d: null, dailyLimit: null, createdAt: null, isValid: null, callerIdVerified: null, agentName: b.agentName, agentId: b.agentId,
+      });
+    }
+  }
+  return [...byKey.values()].sort((a, b) => (b.createdAt ?? "").localeCompare(a.createdAt ?? "") || a.number.localeCompare(b.number));
+}
+
+/** Digits only, so `+1 (415) 555-0123` and `+14155550123` compare equal (stored formats drift). */
+export function digits(value: string): string {
+  return value.replace(/\D/g, "");
+}
+
+/** True for a valid E.164 number: `+`, then 8 to 15 digits, no leading zero. */
+export function isE164(value: string): boolean {
+  return /^\+[1-9]\d{7,14}$/.test(value.trim());
+}
+
+/** `+14155550123` -> `+1 (415) 555-0123`; any other shape is shown as it is. */
+export function formatNumber(value: string): string {
+  const m = /^\+1(\d{3})(\d{3})(\d{4})$/.exec(value);
+  return m ? `+1 (${m[1]}) ${m[2]}-${m[3]}` : value;
+}
+
+export function typeLabel(inboundType: string): string {
+  return INBOUND_LABEL[inboundType as InboundType] ?? (inboundType || "-");
+}
+
+export type Tone = "neutral" | "info" | "positive" | "warning" | "negative";
+
+/** Health of a number for the pill: unusable, near its daily cap, or fine. */
+export function numberHealth(row: NumberRow): { tone: Tone; label: string } {
+  if (row.isValid === false) return { tone: "negative", label: "Cannot dial" };
+  if (row.dailyLimit && row.callsToday != null && row.callsToday >= row.dailyLimit) return { tone: "warning", label: "At daily limit" };
+  if (row.dailyLimit && row.callsToday != null && row.callsToday >= row.dailyLimit * 0.8) return { tone: "warning", label: "Near limit" };
+  return { tone: "positive", label: "Ready" };
+}
+
+/** A fresh idempotency key for one confirmed purchase (reuse it when the same click is retried). */
+export function newIdempotencyKey(): string {
+  return typeof crypto !== "undefined" && "randomUUID" in crypto ? crypto.randomUUID() : `g8-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+}
+
+export function percent(rate: number | null): string {
+  if (rate == null) return "-";
+  return `${Math.round((rate <= 1 ? rate * 100 : rate) * 10) / 10}%`;
+}
+
+export function shortDate(value: string | null): string {
+  if (!value) return "-";
+  const d = new Date(value);
+  return Number.isNaN(d.getTime()) ? "-" : d.toLocaleDateString("en-US", { dateStyle: "medium", timeZone: "UTC" });
+}
+
+/** A2P registration states the status payload can carry (carrier vocabulary): the pill tone for a status string. */
+export function a2pTone(status: string | null | undefined): Tone {
+  const s = (status ?? "").toUpperCase();
+  if (["VERIFIED", "APPROVED", "REGISTERED"].includes(s)) return "positive";
+  if (["FAILED", "TIMEOUT", "REJECTED"].includes(s)) return "negative";
+  if (s) return "warning";
+  return "neutral";
+}
+
+const HIDDEN_FIELDS = /password|secret|token|credential/i;
+
+/** Scalar fields of an open-shaped payload as label/value pairs (secrets are never shown). */
+export function scalarItems(obj: Record<string, unknown>): Array<{ label: string; value: string }> {
+  return Object.entries(obj)
+    .filter(([k, v]) => !HIDDEN_FIELDS.test(k) && ["string", "number", "boolean"].includes(typeof v) && v !== "")
+    .map(([k, v]) => ({ label: k.replace(/_/g, " ").replace(/^./, (c) => c.toUpperCase()), value: typeof v === "boolean" ? (v ? "Yes" : "No") : String(v) }));
+}

package/blocks/phone-numbers/recipes/01-search-and-buy-number.ts

@@ -0,0 +1,49 @@
+/**
+ * @title Search for a number and buy it
+ * @when An agent setting up calling for a workspace. The search is free. THE PURCHASE SPENDS REAL CREDITS (about 250
+ * held on purchase, then about 250 a month in rental; estimates, the API has no price read), so a human must approve the
+ * exact number first. The purchase uses an Idempotency-Key DERIVED from the number, so re-running after a timeout cannot
+ * buy it twice. 402 = not enough credits (nothing bought, nothing charged); 409 = the number is already taken.
+ */
+import { createHash } from "node:crypto";
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+interface Available {
+  phone_number: string;
+  locality?: string | null;
+  region?: string | null;
+  capabilities?: { voice?: boolean; sms?: boolean };
+}
+
+export async function findNumbers(areaCode: string, provider: "twilio" | "telnyx" = "twilio"): Promise<Available[]> {
+  // READ, free: nothing is held or charged by searching.
+  const res = await g8.api.phoneNumbers.searchAvailablePhoneNumbers({
+    body: { provider, country: "US", number_type: "local", area_code: areaCode },
+  });
+  return (res.data?.items ?? []) as Available[];
+}
+
+export async function buyNumber(
+  phoneNumber: string,
+  humanApproved: boolean,
+  options: { provider?: "twilio" | "telnyx"; use?: "dialer" | "voice-ai"; assigneeEmail?: string } = {},
+) {
+  if (!humanApproved) throw new Error("Refusing to spend credits without approval");
+  const provider = options.provider ?? "twilio";
+  const key = createHash("sha256").update(["number", phoneNumber, provider].join("|")).digest("hex").slice(0, 40);
+  // BILLABLE. `dialer: true` makes an outbound dialer number; `dialer: false` a voice-AI number. Leave `assignee` out to
+  // own it as the identity behind the key.
+  return g8.api.phoneNumbers.purchasePhoneNumber(
+    {
+      body: {
+        phone_number: phoneNumber,
+        provider,
+        dialer: (options.use ?? "dialer") === "dialer",
+        ...(options.assigneeEmail ? { assignee: options.assigneeEmail } : {}),
+      },
+    },
+    { idempotencyKey: key },
+  );
+}

package/blocks/phone-numbers/recipes/02-assign-number-to-rep.ts

@@ -0,0 +1,25 @@
+/**
+ * @title Assign a number to a rep, or clear it
+ * @when Onboarding a rep (give them a caller ID) or offboarding one (take their number back). Reassigning is ADMIN-ONLY
+ * through the API: an organisation key can never be the current assignee or the creator, so a non-admin key gets a 403.
+ * The assignee is not a label: it drives who the number rings, who hears about a missed call and whose outbound caller-ID
+ * rotation pool includes it.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+/** Move a number to a person (their email): updates the CRM record and tells voice. */
+export async function assignNumber(phoneNumber: string, repEmail: string) {
+  return g8.api.phoneNumbers.updatePhoneAssignee({ body: { phone_number: phoneNumber, assignee: repEmail } });
+}
+
+/** Clear the assignment on the voice side (`assigned_to: ""` is how voice spells "nobody"). */
+export async function unassignNumber(phoneNumber: string) {
+  return g8.api.phoneNumbers.updateVoiceAssignee({ body: { number: phoneNumber, assigned_to: "" } });
+}
+
+/** The CRM and voice records can disagree (voice is told best-effort): send the same assignee again to reconcile voice. */
+export async function resyncVoice(phoneNumber: string, repEmail: string) {
+  return g8.api.phoneNumbers.updateVoiceAssignee({ body: { number: phoneNumber, assigned_to: repEmail } });
+}

package/blocks/phone-numbers/recipes/03-audit-numbers.ts

@@ -0,0 +1,36 @@
+/**
+ * @title Audit the inventory: usage, unassigned numbers and text registration
+ * @when A health check before a calling or texting campaign. READ-ONLY: it changes nothing. The dialer list leaves out the
+ * numbers a voice AI agent holds and the agent list leaves out dialer-only numbers, so both are read and merged.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+interface DialerNumber {
+  number: string;
+  assigned_to?: string | null;
+  calls_today?: number;
+  daily_limit?: number;
+  is_valid?: boolean;
+  inbound_type?: string;
+  telephony_provider?: string;
+}
+
+export async function auditNumbers() {
+  const [dialer, agents, a2p] = await Promise.all([
+    g8.api.voice.listDialerNumbers({}),
+    g8.api.voice.listAgentPhoneNumbers({}),
+    g8.api.phoneNumbers.getPhoneA2pStatus({}),
+  ]);
+  const numbers = (dialer.data?.numbers ?? []) as DialerNumber[];
+  const booked = ((agents.data as { booked_numbers?: unknown[] } | undefined)?.booked_numbers ?? []).length;
+  return {
+    total: numbers.length + booked,
+    heldByAgents: booked,
+    unassigned: numbers.filter((n) => !n.assigned_to).map((n) => n.number),
+    cannotDial: numbers.filter((n) => n.is_valid === false).map((n) => n.number),
+    atDailyLimit: numbers.filter((n) => n.daily_limit && (n.calls_today ?? 0) >= n.daily_limit).map((n) => n.number),
+    textRegistration: a2p.data,
+  };
+}

package/blocks/phone-numbers/recipes/04-register-text-messaging.ts

@@ -0,0 +1,39 @@
+/**
+ * @title Save A2P details and check registration
+ * @when Before sending texts to US numbers: carriers filter business texts from numbers whose business is not registered
+ * (A2P 10DLC). SAVING a draft is safe (nothing reaches a carrier, nothing is charged) and REPLACES what was saved, so send
+ * the whole object. SUBMITTING reaches the carrier registry, carries carrier fees, takes days and can be rejected: a human
+ * must approve it. Submitting is idempotent per workspace.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+export interface A2pDetails {
+  brand_inputs: Record<string, unknown>;
+  campaign_inputs: Record<string, unknown>;
+}
+
+export async function saveDraft(details: A2pDetails) {
+  // Merge over what is saved so a field this call does not know about (an address, say) is not wiped.
+  const saved = (await g8.api.phoneNumbers.getPhoneA2pStatus({})).data as { brand_inputs?: object; campaign_inputs?: object } | undefined;
+  await g8.api.phoneNumbers.saveA2pInputs({
+    body: {
+      brand_inputs: { ...saved?.brand_inputs, ...details.brand_inputs },
+      campaign_inputs: { ...saved?.campaign_inputs, ...details.campaign_inputs },
+    },
+  });
+  return (await g8.api.phoneNumbers.getPhoneA2pStatus({})).data as { inputs_complete?: boolean; missing_inputs?: string[] } | undefined;
+}
+
+export async function submit(details: A2pDetails, humanApproved: boolean) {
+  if (!humanApproved) throw new Error("Refusing to submit a carrier registration without approval");
+  const status = await saveDraft(details);
+  if (!status?.inputs_complete) throw new Error(`Still missing: ${(status?.missing_inputs ?? []).join(", ")}`);
+  return g8.api.phoneNumbers.startA2pRegistration({ body: details });
+}
+
+/** Re-attach pending or failed numbers (a write, safe to repeat). A worker also does this every six hours. */
+export async function retryStuckNumbers() {
+  return g8.api.phoneNumbers.reconcileA2pRegistration({});
+}

package/blocks/pickers/README.md

@@ -0,0 +1,23 @@
+# pickers
+
+No raw ids: nobody should type an internal id they cannot discover. This opt-in block holds the signed-in-member hook and the searchable pickers. It depends on the foundation only; the blocks that use it (dialer, lists, enrichment, objects) depend on it, so an app with none of those gets no extra proxy prefixes or scopes.
+
+## What you get
+
+| File | What it is |
+|---|---|
+| `hooks/use-current-member.ts` | `useCurrentMember({ enabled? })` -> `{ member, userId, email, name, loading, forbidden }`. The signed-in team member (`GET /team-members/me`, a personal key). An organisation key has no person: `forbidden` is true, so ask with a `MemberPicker`. |
+| `components/member-picker.tsx` | `MemberPicker`: searchable team-member select (`GET /team-members`, fetched on open, "Show more"). Reports the user id operations take; people without a user id are left out. A 403 shows a plain note. |
+| `components/contact-picker.tsx` | `ContactPicker`: single, or `multiple` with chips. Search by name, or by work email for text with `@`. Paged; locked `***` values are never shown. |
+| `components/company-picker.tsx` | `CompanyPicker`: search by name or domain, paged. |
+| `components/search-picker.tsx`, `hooks/use-picker-pages.ts` | The dropdown shell and the paging/search engine the pickers share, to build another picker. Import them as `@/g8/pickers/components/search-picker` and `@/g8/pickers/hooks/use-picker-pages` from a block that `dependsOn` pickers. |
+| `lib/use-debounced.ts` | `useDebounced(value, ms)`. |
+
+## Operations
+
+| Operation | Endpoint | Tier | Scope | Used by |
+|---|---|---|---|---|
+| `teamMembers.getMyTeamMember` | GET /team-members/me | read | `team:read` | useCurrentMember |
+| `teamMembers.listTeamMembers` | GET /team-members | read | `team:read` | MemberPicker |
+| `contacts.listContacts` | GET /contacts | read | `contacts:read` | ContactPicker |
+| `companies.listCompanies` | GET /companies | read | `companies:read` | CompanyPicker |

package/blocks/pickers/block.json

@@ -0,0 +1,103 @@
+{
+  "$schema": "../block.schema.json",
+  "id": "pickers",
+  "title": "Pickers",
+  "summary": "No raw ids: signed-in member hook plus searchable team-member, contact and company pickers that report the id operations take.",
+  "features": [
+    "useCurrentMember: the signed-in teammate (user id, email, name) from GET /team-members/me",
+    "MemberPicker: searchable team-member select, paged",
+    "ContactPicker: searchable contact select (single or multiple), by name or work email, paged",
+    "CompanyPicker: searchable company select by name or domain, paged",
+    "SearchPicker + usePickerPages: the shell and paging engine to build another picker"
+  ],
+  "dependsOn": [
+    "foundation"
+  ],
+  "operations": [
+    "get_my_team_member_team_members_me_get",
+    "list_companies_companies_get",
+    "list_contacts_contacts_get",
+    "list_team_members_team_members_get"
+  ],
+  "components": [
+    {
+      "name": "SearchPicker",
+      "file": "components/search-picker.tsx",
+      "purpose": "The dropdown shell behind the pickers: trigger, search box, listbox, Show more, loading/empty/error states. Calls no API.",
+      "operations": [],
+      "tiers": []
+    },
+    {
+      "name": "MemberPicker",
+      "file": "components/member-picker.tsx",
+      "purpose": "Searchable team-member select (paged, fetched on open). Reports the user id operations take, so no screen asks a person to type one.",
+      "operations": [
+        "list_team_members_team_members_get"
+      ],
+      "tiers": [
+        "read"
+      ]
+    },
+    {
+      "name": "ContactPicker",
+      "file": "components/contact-picker.tsx",
+      "purpose": "Searchable contact select by name or work email (paged), single or multiple with chips. Reports the contact id, so no screen asks a person to type one.",
+      "operations": [
+        "list_contacts_contacts_get"
+      ],
+      "tiers": [
+        "read"
+      ]
+    },
+    {
+      "name": "CompanyPicker",
+      "file": "components/company-picker.tsx",
+      "purpose": "Searchable company select by name or domain (paged). Reports the company id, so no screen asks a person to type one.",
+      "operations": [
+        "list_companies_companies_get"
+      ],
+      "tiers": [
+        "read"
+      ]
+    }
+  ],
+  "hooks": [
+    {
+      "name": "useCurrentMember",
+      "file": "hooks/use-current-member.ts",
+      "purpose": "The signed-in team member (user id, email, name) from GET /team-members/me, shared by the dialer, CallContactButton and role/owner defaults. An organisation key has no person: `forbidden` is true and callers offer a MemberPicker.",
+      "operations": [
+        "get_my_team_member_team_members_me_get"
+      ]
+    },
+    {
+      "name": "usePickerPages",
+      "file": "hooks/use-picker-pages.ts",
+      "purpose": "Paging + debounced search engine behind ContactPicker and CompanyPicker: load more appends, a new search starts over, a stale response is dropped."
+    }
+  ],
+  "lib": [
+    {
+      "file": "lib/use-debounced.ts",
+      "purpose": "useDebounced: a value after it stops changing; the search box of every picker reads through it."
+    }
+  ],
+  "recipes": [],
+  "prerequisites": [],
+  "scopes": [
+    "companies:read",
+    "contacts:read",
+    "team:read"
+  ],
+  "defaults": [
+    {
+      "decision": "Which person a screen acts as when nobody passed a user id",
+      "default": "The signed-in team member (a personal API key). An organisation key has no person: ask with MemberPicker",
+      "askHuman": false
+    }
+  ],
+  "peerDependencies": {
+    "react": ">=18",
+    "lucide-react": ">=0.400.0"
+  }
+}

package/blocks/pickers/components/company-picker.tsx

@@ -0,0 +1,90 @@
+"use client";
+
+/**
+ * CompanyPicker: choose a company by name instead of typing a company id. A searchable select over the organisation's
+ * companies; it reports the company (id, name, hint) so a screen can show who was chosen and send the id.
+ *
+ * SDK operations, in order:
+ *   1. GET /companies?name|domain&page&limit   (companies.listCompanies)   read - fetched only once the picker is opened
+ *
+ * Search: a company name (partial match); text that looks like a domain ("acme.com") is looked up as the domain.
+ * Paged with usePickerPages: 25 per page, "Show more" keeps the earlier pages, a new search starts over.
+ */
+import { useState } from "react";
+import { g8Get } from "@/g8/lib/g8-client";
+import { usePickerPages } from "../hooks/use-picker-pages";
+import { SearchPicker } from "./search-picker";
+
+export interface CompanyOption {
+  id: number;
+  name: string;
+  /** Domain and industry: what tells two companies with a similar name apart. */
+  hint?: string;
+}
+
+export interface CompanyPickerProps {
+  value?: CompanyOption | null;
+  onChange: (company: CompanyOption) => void;
+  /** Accessible name and trigger prefix. Default "Company". */
+  label?: string;
+  placeholder?: string;
+  disabled?: boolean;
+  /** Id of the trigger button, so a <label htmlFor> can name it. */
+  id?: string;
+  className?: string;
+}
+
+interface Row { id?: number | null; name?: string | null; domain?: string | null; industry?: string | null }
+
+const PAGE = 25;
+const DOMAIN = /^[^\s@/]+\.[a-z]{2,}$/i;
+
+/** A companies-list row as a selectable option; null without an id. */
+export function toCompanyOption(r: Row): CompanyOption | null {
+  if (r.id == null) return null;
+  const hint = [r.domain, r.industry].filter(Boolean).join(" · ");
+  return { id: r.id, name: r.name || r.domain || `Company ${r.id}`, hint: hint || undefined };
+}
+
+export function CompanyPicker({ value, onChange, label = "Company", placeholder, disabled, id, className }: CompanyPickerProps) {
+  const [open, setOpen] = useState(false);
+  const pages = usePickerPages<CompanyOption>(open, async (q, page, signal) => {
+    const filter = DOMAIN.test(q) ? { domain: q.toLowerCase() } : { name: q || undefined };
+    const env = await g8Get("/companies", { ...filter, page, limit: PAGE }, { signal });
+    const rows = ((env.data ?? []) as Row[]).map(toCompanyOption).filter((o): o is CompanyOption => o !== null);
+    const has = (env.pagination as { has_next?: boolean } | undefined)?.has_next;
+    return { rows, hasNext: has ?? rows.length >= PAGE };
+  });
+  const pick = (key: string) => {
+    const c = pages.rows.find((r) => String(r.id) === key);
+    if (!c) return;
+    setOpen(false);
+    pages.setSearch("");
+    onChange(c);
+  };
+  return (
+    <SearchPicker
+      label={label}
+      id={id}
+      className={className}
+      disabled={disabled}
+      placeholder={placeholder}
+      searchPlaceholder="Search by name or domain"
+      triggerContent={value ? <span>{value.name}</span> : undefined}
+      options={pages.rows.map((r) => ({ key: String(r.id), label: r.name, hint: r.hint }))}
+      selectedKeys={new Set(value ? [String(value.id)] : [])}
+      onSelect={pick}
+      search={pages.search}
+      onSearchChange={pages.setSearch}
+      open={open}
+      onOpenChange={setOpen}
+      loading={pages.loading}
+      error={pages.error}
+      onRetry={pages.refetch}
+      hasMore={pages.hasMore}
+      loadingMore={pages.loadingMore}
+      onLoadMore={pages.loadMore}
+      emptyText={pages.q ? "No company matches that search." : "No companies yet."}
+    />
+  );
+}