Number & usage hooks

The headless layer behind the provisioning and ops components: searching and buying numbers, watching ports and readiness, reading usage.

useAvailableNumbers / useBuyNumber

const { results, search, isSearching, hasSearched } = useAvailableNumbers();
await search({ areaCode: "415", limit: 6 });

const { buy, purchased, isBuying } = useBuyNumber();
await buy({ phoneNumber: results[0].phone_number, campaignId });

Search is on-demand (no polling). buy sends an Idempotency-Key per attempt, so a network retry can't double-purchase; a lost race for a number surfaces as a retryable error.

usePhoneNumber

const { number } = usePhoneNumber(numberId, { pollMs: 30000 });
number?.messaging_ready; // flips true at carrier approval

usePortIn

const { portIn } = usePortIn(portInId); // polls every 30s
portIn?.status; // draft → in_review → foc_confirmed → completed

action_needed carries the carrier's explanation in status_detail.

useUsage

const { usage } = useUsage();                       // this month
const july = useUsage({ start: "2026-07-01", end: "2026-08-01" });
usage?.data; // [{ kind: "sms_segment_outbound", quantity: 4218 }, …]