# Workspace readiness contract

> The exact preview, payment, number request, assignment, and sending states used across Beam.

## State contract

GET /api/me returns a readiness object. Product surfaces, communications workflows, and integrations must consume these server-derived fields instead of guessing from UI state.

| State | Meaning | Can send? | 
  
| preview | Unpaid, isolated workspace. The deterministic demo has no contacts or external actions. | No | 
  
| paid_number_requested | Payment is confirmed and one idempotent number request exists. | No | 
  
| number_assigned | A line record exists but is inactive. | No | 
  
| active | Payment is confirmed and at least one dedicated line is actively assigned. | Yes | 

The companion booleans are paid, number_requested, number_assigned, and sending_enabled. Removing the last active assignment immediately makes sending_enabled false.

## Billing integration contract

The engine accepts the payment platform's signed raw event at POST /webhooks/billing. A hosted-checkout browser return never proves payment. Only a verified paid-invoice event moves a preview to paid/requested and creates the single tracked allocation request.
Events are durably deduplicated. Replaying the same event or receiving another paid invoice for the same allocation still produces one request. A new paid allocation after a portal plan change produces one new adjustment request. The webhook never leases or assigns a line.

## Area-code preferences

POST /api/onboarding/preferences accepts { "area_codes": ["713", "469"] }. Send zero to three unique, three-digit codes. They guide sourcing only and are never guaranteed.

## Release verification

  - Create a preview through the public signup and confirm it has zero contacts, messages, and numbers.
  - Run every demo branch and confirm no message, contact, number, or capacity row changes.
  - Replay one signed paid-invoice fixture and confirm exactly one request exists while sending stays locked.
  - Assign one available platform line as super-admin and confirm sending_enabled: true.
  - Remove the assignment and confirm all send entry points return 423 sending_locked.