billing

Overview ¶

Package billing mounts the CUSTOMER-facing, org-scoped billing surface (/v1/billing/{usage,balance,gpu-eligibility,gpu-charge,payment-methods}) on the unified cloud binary.

WHY THIS EXISTS. On the console host (console.hanzo.ai) the ingress routes /v1/* straight to cloud-api:8000 — the console's Next BFF is reached only at "/". So the console's /v1/billing/usage + /v1/billing/balance calls land HERE, on cloud-api, NOT on the console's per-tenant commerce proxy. cloud-api previously wired commerce billing ONLY under the admin-gated aggregate (clients/admin, /v1/admin/*), so a normal org owner (e.g. davelorenzini / maxpower) hitting /v1/billing/usage had NO customer route and was denied — the "Access required" wall on every product overview + o11y usage panel. This adds exactly the customer surface those calls need.

TENANT ISOLATION (the whole point). The org is the VALIDATED IAM owner claim (principal.Tenant — the trusted X-Org-Id the identity middleware minted from the caller's verified session/bearer, HIP-0026; NEVER a client-supplied header). A customer therefore reads ONLY their OWN org's ledger. The commerce billing subject is pinned server-side to that org and NO client-supplied subject/org query param is ever forwarded, so the browser cannot widen scope. This is the per-org READ twin of the admin god-view (clients/admin) — the SAME commerce S2S machinery, but scoped to the caller instead of all-orgs (which stays admin-only).

SUBJECT. Prepaid balance is per-ORG: commerce keys the wallet under the BARE org slug as the `user` subject + the trusted `X-Org-Id` (admin.orgSubject / metering identityFromCtx — verified live: user=<org> + X-Org-Id=<org> returns the real wallet, "org/user" reads an empty one). The gateway debits this SAME key, so a read here shows exactly what the org is charged.

PASSTHROUGH. The console's normalizeUsageRecords parses commerce's RAW per-request ledger ({usage:[{transactionId,amount,metadata,createdAt}]}); balance is the raw {balance,holds,available} cents object. So this proxies commerce's body + status VERBATIM — it never reshapes or rolls up (the rollup is the admin aggregate's job).