@graph8/sdk 0.370.0 → 0.374.0

package/blocks/phone-numbers/components/register-owned-number.tsx

@@ -0,0 +1,98 @@
+"use client";
+
+/**
+ * RegisterOwnedNumber: wire a number you already own (bought outside, or whose voice half failed) into the voice platform.
+ *
+ * SDK operations:
+ *   provisionVoiceNumber  POST /voice/numbers/provision  (write; BUYS NOTHING and charges nothing: it creates SIP trunks
+ *                         and dispatch rules for a number you already hold. Idempotent: a number already registered
+ *                         comes back as a success.)
+ *
+ * The person comes from MemberPicker, not a typed email. A personal work phone needs someone assigned, or no one can
+ * reach it by name.
+ */
+
+import { useState } from "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 { MemberPicker } from "@/g8/pickers/components/member-picker";
+import type { MemberOption } from "@/g8/pickers/components/member-picker";
+import { INBOUND_LABEL, INBOUND_TYPES, PROVIDERS, formatNumber, isE164 } from "../lib/phone-numbers-utils";
+import type { InboundType, Provider } from "../lib/phone-numbers-utils";
+
+export interface RegisterOwnedNumberProps {
+  onRegistered?: (phoneNumber: string) => void;
+  className?: string;
+}
+
+const SELECT = "h-9 w-full rounded-md border border-border bg-background px-2 text-sm";
+
+export function RegisterOwnedNumber({ onRegistered, className }: RegisterOwnedNumberProps) {
+  const [number, setNumber] = useState("");
+  const [provider, setProvider] = useState<Provider>("twilio");
+  const [mode, setMode] = useState<InboundType>("ai");
+  const [assignee, setAssignee] = useState<MemberOption | null>(null);
+  const [note, setNote] = useState<string | null>(null);
+  const valid = isE164(number);
+  const needsPerson = mode === "work" && !assignee?.email;
+
+  const register = useG8Mutation(async () => {
+    const n = number.trim();
+    await g8Post("/voice/numbers/provision", {
+      number: n,
+      provider,
+      inbound_type: mode,
+      dialer: mode === "dialer",
+      work: mode === "work",
+      ...(assignee?.email ? { assigned_to: assignee.email } : {}),
+    });
+    setNote(`${formatNumber(n)} is registered with the voice platform.`);
+    setNumber("");
+    onRegistered?.(n);
+  });
+
+  return (
+    <form
+      className={`space-y-4 ${className ?? ""}`}
+      onSubmit={(e) => {
+        e.preventDefault();
+        if (valid && !needsPerson) void register.mutate(undefined);
+      }}
+    >
+      <p className="text-sm text-muted-foreground">Use this for a number you already own. Nothing is bought and no credits are spent.</p>
+      <div className="space-y-1">
+        <Label htmlFor="ro-number">Phone number (E.164)</Label>
+        <Input id="ro-number" placeholder="+14155550123" value={number} onChange={(e) => setNumber(e.target.value)} aria-invalid={number !== "" && !valid} />
+        {number !== "" && !valid ? <p className="text-xs text-error">Use the international format: a plus sign, the country code, then the number.</p> : null}
+      </div>
+      <div className="grid gap-3 sm:grid-cols-2">
+        <div className="space-y-1">
+          <Label htmlFor="ro-provider">Carrier that holds it</Label>
+          <select id="ro-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>
+        </div>
+        <div className="space-y-1">
+          <Label htmlFor="ro-mode">How it answers</Label>
+          <select id="ro-mode" className={SELECT} value={mode} onChange={(e) => setMode(e.target.value as InboundType)}>
+            {INBOUND_TYPES.map((t) => (
+              <option key={t} value={t}>{INBOUND_LABEL[t]}</option>
+            ))}
+          </select>
+        </div>
+      </div>
+      <div className="space-y-1">
+        <Label htmlFor="ro-assignee">Assign to {mode === "work" ? "" : "(optional)"}</Label>
+        <MemberPicker id="ro-assignee" label="Assign to" value={assignee?.id ?? null} selectedName={assignee?.name} onChange={setAssignee} />
+        {needsPerson ? <p className="text-xs text-muted-foreground">A personal work phone needs a person, or no one can reach it by name.</p> : null}
+      </div>
+      {register.error ? <ApiError error={register.error} title="The number was not registered" onRetry={register.reset} /> : null}
+      {note ? <p role="status" className="text-sm">{note}</p> : null}
+      <Button type="submit" loading={register.loading} disabled={!valid || needsPerson}>Register number</Button>
+    </form>
+  );
+}

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

@@ -0,0 +1,126 @@
+"use client";
+
+/**
+ * ReleaseNumber: give a number back, or take it off the voice platform without giving it back.
+ *
+ * SDK operations:
+ *   releasePhoneNumber  POST   /phone-numbers/release  (destructive: IRREVERSIBLE. The number returns to the carrier's pool
+ *                       and anyone can buy it, including a competitor; calls and messages stop at once. Confirmed with
+ *                       ConfirmSpendDialog after the person types the number.)
+ *   deleteVoiceNumber   DELETE /voice/numbers          (destructive: tears down the number's SIP trunks, dispatch rules and
+ *                       carrier routing. It does NOT release the number: you keep owning it and the carrier keeps billing
+ *                       it. Confirmed with ConfirmSpendDialog.)
+ *
+ * The carrier must match where the number was bought: releasing a Telnyx number as Twilio reaches the wrong provider. The
+ * list knows it for every dialer number; when it does not, the person chooses and the form says why.
+ */
+
+import { useState } from "react";
+import { Button, Input, Label } from "@graph8/sdk/ui";
+import { g8Delete, 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 { PROVIDERS, dataOf, digits, formatNumber } from "../lib/phone-numbers-utils";
+import type { NumberRow, Provider } from "../lib/phone-numbers-utils";
+
+export interface ReleaseNumberProps {
+  row: NumberRow;
+  /** Called after the number was released (the record is gone: close its detail). */
+  onReleased?: () => void;
+  /** Called after the voice registration was removed (the number is still owned). */
+  onChanged?: () => void;
+  className?: string;
+}
+
+type Pending = "release" | "deregister";
+
+export function ReleaseNumber({ row, onReleased, onChanged, className }: ReleaseNumberProps) {
+  const known = (PROVIDERS as readonly string[]).includes(row.provider);
+  const [provider, setProvider] = useState<Provider | "">(known ? (row.provider as Provider) : "");
+  const [typed, setTyped] = useState("");
+  const [pending, setPending] = useState<Pending | null>(null);
+  const [note, setNote] = useState<string | null>(null);
+
+  const release = useG8Mutation(async () => {
+    if (!provider) return;
+    const out = dataOf(await g8Post("/phone-numbers/release", { phone_number: row.number, provider }));
+    const detail = typeof out.message === "string" ? ` ${out.message}` : "";
+    setNote(`${formatNumber(row.number)} was released.${detail}`);
+    setPending(null);
+    onReleased?.();
+  });
+  const deregister = useG8Mutation(async () => {
+    await g8Delete("/voice/numbers", { body: { number: row.number, ...(provider ? { provider } : {}) } });
+    setNote(`${formatNumber(row.number)} was removed from the voice platform. You still own it.`);
+    setPending(null);
+    onChanged?.();
+  });
+
+  const matches = digits(typed) === digits(row.number);
+  const assignedNote = row.agentName ? ` The voice agent ${row.agentName} stops answering on it.` : "";
+
+  return (
+    <div className={`space-y-6 ${className ?? ""}`}>
+      {!known ? (
+        <div className="space-y-1">
+          <Label htmlFor="rn-provider">Carrier it was bought from</Label>
+          <select id="rn-provider" className="h-9 rounded-md border border-border bg-background px-2 text-sm" value={provider} onChange={(e) => setProvider(e.target.value as Provider | "")}>
+            <option value="">Choose the carrier</option>
+            {PROVIDERS.map((p) => (
+              <option key={p} value={p}>{p === "twilio" ? "Twilio" : "Telnyx"}</option>
+            ))}
+          </select>
+          <p className="text-xs text-muted-foreground">The carrier is not known for this number. It must match, or the wrong provider is asked to release it.</p>
+        </div>
+      ) : null}
+
+      <section className="space-y-2" aria-label="Release this number">
+        <h3 className="text-sm font-medium">Release this number</h3>
+        <p className="text-sm text-muted-foreground">
+          Gives the number back to the carrier. It returns to the public pool and anyone can buy it, including a competitor. Calls and messages to it stop
+          at once, and monthly rental billing for it ends. There is no undo.
+        </p>
+        <div className="flex flex-wrap items-end gap-2">
+          <div className="space-y-1">
+            <Label htmlFor="rn-confirm">Type {row.number} to enable release</Label>
+            <Input id="rn-confirm" value={typed} placeholder={row.number} onChange={(e) => setTyped(e.target.value)} />
+          </div>
+          <Button variant="destructive" disabled={!matches || !provider} onClick={() => setPending("release")}>
+            Release number
+          </Button>
+        </div>
+        {release.error ? <ApiError error={release.error} title="The number was not released" onRetry={release.reset} /> : null}
+      </section>
+
+      <section className="space-y-2" aria-label="Remove from voice">
+        <h3 className="text-sm font-medium">Remove from the voice platform</h3>
+        <p className="text-sm text-muted-foreground">
+          Tears down the number&apos;s call routing so nothing answers it. You still own the number and the carrier still bills for it. Use Release to give it up.
+        </p>
+        <Button variant="outline" onClick={() => setPending("deregister")}>Remove voice routing</Button>
+        {deregister.error ? <ApiError error={deregister.error} title="The voice routing was not removed" onRetry={deregister.reset} /> : null}
+      </section>
+
+      {note ? <p role="status" className="text-sm">{note}</p> : null}
+
+      {pending ? (
+        <ConfirmSpendDialog
+          open
+          tier="destructive"
+          title={pending === "release" ? `Release ${formatNumber(row.number)}` : `Remove voice routing for ${formatNumber(row.number)}`}
+          description={
+            pending === "release"
+              ? `The number goes back to the carrier and can be bought by anyone, including a competitor. Inbound calls and messages stop at once.${assignedNote}`
+              : `Nothing will answer this number until it is set up again. You keep owning it and the carrier keeps billing it.${assignedNote}`
+          }
+          confirmLabel={pending === "release" ? "Release number" : "Remove routing"}
+          affected={1}
+          confirming={release.loading || deregister.loading}
+          onCancel={() => setPending(null)}
+          onConfirm={() => void (pending === "release" ? release.mutate(undefined) : deregister.mutate(undefined)).then(() => setPending(null))}
+        />
+      ) : null}
+    </div>
+  );
+}

package/blocks/phone-numbers/hooks/use-phone-numbers.ts

@@ -0,0 +1,58 @@
+"use client";
+
+/**
+ * usePhoneNumbers: every phone number of the workspace, in full.
+ *
+ * SDK operations, in order (both read, in parallel):
+ *   1. listDialerNumbers      GET /voice/dialer/numbers        every number except the ones a voice AI agent holds, with
+ *                             usage (calls today / 7 days, connect rate) and the daily limit
+ *   2. listAgentPhoneNumbers  GET /voice/agent-phone-numbers   the AI-capable numbers and which agent holds each
+ *
+ * Neither endpoint pages or caps: each answers the whole inventory, so nothing is cut off and the screen pages the list
+ * on the client ("Load more"). A key that cannot read agents (403) still gets the dialer list; `agentsUnavailable` says
+ * so, and the AI-held numbers are then missing and the screen says that rather than hiding it.
+ */
+import { g8Get } from "@/g8/lib/g8-client";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { agentNumbers, dialerRows, mergeInventory } from "../lib/phone-numbers-utils";
+import type { NumberRow } from "../lib/phone-numbers-utils";
+
+export interface UsePhoneNumbers {
+  rows: NumberRow[];
+  loading: boolean;
+  /** The first read has finished. */
+  loaded: boolean;
+  /** The dialer list failed (the agents list failing alone is not an error, see `agentsUnavailable`). */
+  error: unknown;
+  /** Numbers held by voice AI agents could not be read, so they may be missing from `rows`. */
+  agentsUnavailable: boolean;
+  refetch: () => void;
+}
+
+export function usePhoneNumbers(deps: readonly unknown[] = []): UsePhoneNumbers {
+  const q = useG8Query(
+    async (signal) => {
+      const [dialer, agents] = await Promise.allSettled([
+        g8Get("/voice/dialer/numbers", undefined, { signal }),
+        g8Get("/voice/agent-phone-numbers", undefined, { signal }),
+      ]);
+      if (dialer.status === "rejected") throw dialer.reason;
+      const agentsOk = agents.status === "fulfilled";
+      return {
+        rows: mergeInventory(dialerRows(dialer.value), agentsOk ? agentNumbers(agents.value) : { available: [], booked: [] }),
+        agentsUnavailable: !agentsOk,
+      };
+    },
+    [...deps],
+  );
+  return {
+    rows: q.data?.rows ?? EMPTY,
+    loading: q.loading,
+    loaded: q.data !== undefined,
+    error: q.error,
+    agentsUnavailable: q.data?.agentsUnavailable ?? false,
+    refetch: () => void q.refetch(),
+  };
+}
+
+const EMPTY: NumberRow[] = [];

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 |