TypeScript & HTTP API Conventions

Type Safety

• No implicit any: Prefer unknown at untrusted I/O boundaries (HTTP request bodies, queue messages, external webhooks) and narrow with explicit schema validation.
• Shared contracts: Keep request/response types and entitlement constants in shared/ so worker routes and frontend hooks cannot drift.
• Exhaustive switches: Use discriminated unions for status and state machines (status: "pending" | "completed" | "failed").

HTTP Error Envelopes

All API error responses must return a consistent JSON structure with an appropriate HTTP status code and Cache-Control: no-store on authenticated routes:

{
  "error": {
    "code": "QUOTA_EXCEEDED",
    "message": "Workspace share limit reached. Upgrade to Pro for up to 500 active shares."
  }
}

Idempotency & Concurrency

• Mutating publish and revision endpoints accept an explicit Idempotency-Key or --expected-revision guard so retried CI jobs never create duplicate shares or overwrite concurrent edits silently.