Billing Lifecycle (TUI)

This is the map from every billing.*/subscription.* state shape the gateway serves (from NAS) to what the terminal actually renders, and from every typed refusal/error code to its exact user-facing copy and recovery action. The guarantee: no NAS billing state and no typed refusal falls through to a generic toast — every case below is an explicit branch in ui-tui/src/app/slash/commands/topup.ts, ui-tui/src/components/billingOverlay.tsx, or ui-tui/src/components/subscriptionOverlay.tsx. An unknown code still degrades gracefully: it hits the default branch (a generic-but-real message pulled from the server payload, never a blank toast) rather than crashing or silently dropping the refusal.

1. `billing.state` shapes → render

Source: ui-tui/src/components/billingOverlay.tsx (OverviewScreen, BuyScreen, AutoReloadScreen), ui-tui/src/app/slash/commands/topup.ts (/topup run).

State shape	Render
Logged out (`s.logged_in === false`)	Overlay never opens. `sys`: `💳 Not logged into Nous Portal — run /portal to log in, then /topup.`
`billing.state` RPC fetch fails (transport/timeout)	Fail-closed: `.catch(ctx.guardedErr)` — overlay never opens, no state is assumed. `sys`: `error: <message or "request failed">`. Never renders “no card” or any other guessed state; user must retry `/topup`.
`card: null` (no saved card), full menu (`is_admin && cli_billing_enabled`)	Overview shows `No saved card on file — "Add funds" walks you through adding one.` “Add funds” opens the add-card path: `Add a card on the portal` / `I've added it — check again` / `Back` (never an amount picker, which would 403 `no_payment_method`).
`card` present, `resolved_via` set	`Card: {display}` (e.g. `Visa ····4242 — the card on your subscription`) using the provenance-aware `display` field.
`card` present, `resolved_via` absent (older NAS)	Falls back to the generic `Card: {masked}`; Confirm screen adds `Your card saved on the portal will be charged.`
`auto_reload: null`	No auto-reload line at all (`autoReloadLine` returns `null`) — the feature isn’t surfaced.
`auto_reload.card.kind: 'canonical'`	No distinct-card warning; card line falls back to the card on file.
`auto_reload.card.kind: 'distinct'`	`⚠ Auto-refill is charging {brand} ••{last4} — not your card on file.` in the Auto-reload screen (the divergence notice).
`auto_reload.card.kind: 'none'`	Same as `canonical` rendering-wise — no distinct-card warning shown.
`monthly_cap` present, `limit_usd != null`	`{spent_display} of {limit_display} used this month` (+ `(default ceiling)` iff `is_default_ceiling`).
`monthly_cap` absent or `limit_usd == null`	`No monthly cap visible (managed on the portal).`
Role without billing capability (`!is_admin`, menu collapses)	Note: `Billing actions need someone with billing permissions (owner, admin, or finance admin).` Menu collapses to `Manage on portal` / `Cancel`.
Org kill-switch off (`is_admin` but `!cli_billing_enabled`)	Note: `Remote spending is off for this org — a billing admin can turn it on from the portal's Mibyan page.` Same collapsed menu.

Note: full = s.is_admin && s.cli_billing_enabled gates the org-level switch, not the per-terminal billing:manage scope — that’s discovered reactively (a charge 403s insufficient_scope) and routes to the resumable step-up screen instead of a preflight check.

2. Refusal codes (`renderBillingError`, in code order)

Source: renderBillingError in ui-tui/src/app/slash/commands/topup.ts:37-149. “Portal” row = sys('Portal: {portal_url}') is appended whenever portal_url is present, for every code (including default).

`error` code	Copy	Portal URL	`retry_after`
`insufficient_scope`	`This needs Remote Spending allowed. Start a top-up to allow it, then retry.`	if present	—
`remote_spending_revoked` (CF-4)	`{An admin stopped remote spending for this terminal. \| You stopped remote spending for this terminal.}` (by `actor`) `Reconnect to restore — run /portal to re-authorize this terminal.` Also clears `billing` overlay state immediately (doesn’t wait for token refresh).	if present	—
`session_revoked`	`Your session was logged out. Run /portal to log in again.` Also clears `billing` overlay state.	if present	—
`cli_billing_disabled` / `remote_spending_disabled` (dual-emitted)	`Remote spending is off for this account — a billing admin can turn it on from the portal's Mibyan page.`	if present	—
`role_required`	`Adding funds needs someone with billing permissions (owner, admin, or finance admin), or manage this on the portal.`	if present	—
`consent_required`	`This action needs a one-time card confirmation and consent step on the portal before it can proceed.`	if present	—
`org_access_denied`	`This token isn't bound to an org you can manage. Sign in with the right org, or manage this on the portal.`	if present	—
`upgrade_cap_exceeded`	`🔴 Daily plan-change limit reached (5 per org) — try again tomorrow, or manage this on the portal.`	if present	—
`auto_top_up_disabled_failures`	`Auto-reload was turned off after repeated charge failures. Fix the card issue, then re-enable it from /topup → Auto-reload.`	if present	—
`idempotency_conflict`	`🔴 That charge key was already used for a different amount. Start a fresh top-up.`	if present	—
`no_payment_method`	`💳 No saved card for terminal charges yet. Set one up on the portal (one-time credit buys don't save a reusable card).`	if present	—
`monthly_cap_exceeded`	`🔴 Monthly spend cap reached — ${remainingUsd} headroom left.` if `payload.remainingUsd` present, else `🔴 Monthly spend cap reached.`	if present	—
`rate_limited` / `temporarily_unavailable`	`🟡 Too many charges right now{ (try again in ~N min)}. This isn't a payment failure.`	if present	yes — minutes computed as `max(1, round(retry_after/60))`
`stripe_unavailable`	`🟡 Stripe is having trouble right now — try again shortly{ (try again in ~N min)}.`	if present	yes (same formula)
default (unknown/other)	`🔴 {message \|\| error \|\| 'Billing request failed.'}` — still surfaces whatever the server said, never a blank toast.	if present	—

3. Charge settlement outcomes (`pollCharge` / `renderChargeFailed`)

Source: pollCharge (ui-tui/src/app/slash/commands/topup.ts:170-258) and renderChargeFailed (:260-290). Poll cadence: 2s interval, 5-minute cap (POLL_INTERVAL_MS=2000, POLL_CAP_MS=5*60*1000), applied on every non-terminal path (pending and throttled), so a sustained 429/503 can’t keep the poll alive forever.

Outcome	Copy	Notes
`status: 'settled'`	`✅ ${amount_usd} added.` (or `✅ Credits added.` if no amount)	Terminal success.
`status: 'failed'`, `reason: 'authentication_required'`	`🔴 Your bank requires verification (3DS). Complete it on the portal to finish this purchase.`	+ `Portal:` line if `portalUrl`.
`status: 'failed'`, `reason: 'payment_method_expired'`	`🔴 Your card has expired. Update it on the portal.`	+ `Portal:` line.
`status: 'failed'`, `reason: 'card_declined'`	`🔴 Your card was declined. Try another card on the portal.`	+ `Portal:` line.
`status: 'failed'`, `reason: 'processing_error'`	`🔴 The charge didn't go through (processing_error).`	+ `Portal:` line.
`status: 'failed'`, unrecognized/missing `reason`	`🔴 The charge didn't go through ({reason \|\| 'processing_error'}).`	Same portal funnel — parity with `cli.py`’s `_billing_portal_hint`.
Poll timeout (still `pending` past the 5-min cap)	`🟡 Still processing after 5 minutes — this is a timeout, not a failure. Check /topup or the portal shortly.`	+ `Portal:` line if `portalUrl`. Explicitly NOT called a failure.
Revocation mid-poll (`remote_spending_revoked` / `session_revoked` while polling)	Renders the matching §2 copy, then appends: `🟡 Your last charge's outcome is unconfirmed — check your balance/history before retrying.`	CF-7 rule 4: a post-revoke 403 while polling is ambiguous (the charge may have already settled) — never call it “failed”.
429/503 while polling (`rate_limited`/`temporarily_unavailable`/`stripe_unavailable`)	No error shown; backs off using `retry_after` (default 5s, capped at 30s) and keeps polling until the 5-min cap, then reads as timeout.	Not a payment failure.
Other `!ok` status-check error	`🔴 Could not check the charge: {message \|\| error \|\| 'error'}`
Transport loss (poll RPC throws/rejects)	`🟡 Your last charge's outcome is unconfirmed — check your balance/history before retrying.` (`UNCONFIRMED_CHARGE_MESSAGE`)	Same “unconfirmed, check balance” framing as revocation mid-poll — a dropped connection can never be read as “failed”.

4. Subscription preview / pending-change / upgrade outcomes

Source: previewAndRoute, applyPendingAndRoute, upgradeResult, stepUpDenialResult in ui-tui/src/components/subscriptionOverlay.tsx. Preview effect values (drive the Confirm screen):

`effect`	Confirm screen copy	Primary action
`charge_now`	`Upgrade to {target}. You will be charged {amount} now (prorated).` (+ monthly-credits delta, + which card if resolver confidently knows)	`Pay {amount} & upgrade now`
`scheduled`	`Change to {target} — takes effect {date}. No charge now; you keep your current plan until then.`	`Schedule change to {target}`
`no_op`	`You are already on {target} — nothing to change.`	none (Back only)
`blocked`	`{preview.reason}` or fallback `That change cannot be made here — manage it on the portal.`	`Manage on portal`
Preview RPC returns `null`/transport failure	routes straight to Result: `Could not preview that change.`	—
Preview `!ok`, `insufficient_scope`	routes to `stepup` screen (`{kind:'preview', tierId}`)	—
Preview `!ok`, other error	routes to Result with `errorResult(p)` (`message \|\| error \|\| 'Something went wrong. Try again, or manage on the portal.'`)	—

Pending-change apply outcomes (applyPendingAndRoute):

`pending.kind`	Success copy
`cancellation`	`Scheduled — your plan stays active until the end of the billing period, then it cancels. Nothing changes today.`
`tier_change` (downgrade/schedule)	`Scheduled — your plan doesn't change today. You keep your current plan until the end of the billing period, then it switches.`
`upgrade`	routed through `upgradeResult` (below)
any kind, mutation `insufficient_scope`	routes to stepup (`{kind:'apply'}`)

Upgrade status × reason matrix (upgradeResult, checked in this order — reason is checked before status):

Condition	Result
`r === null` (transport failure on the charging route)	`Couldn't confirm the upgrade — your card may or may not have been charged. Re-run /subscription to check your plan before trying again.` — ambiguous, never a blind retry.
`reason: 'authentication_required'` or `reason: 'subscription_payment_intent_requires_action'`	`Please verify your card in the portal to finish this upgrade.` → `recovery_url`. Both reasons map to the same SCA copy — the client branches on `reason`, not `status`, specifically so an SCA case that pre-#711 NAS mislabels with `status: 'payment_failed'` (no distinguishing reason yet) still routes to the correct “verify your card” copy instead of reading as a hard decline.
`reason: 'card_declined'`	`Your card was declined — try a different card on the portal.` → `recovery_url`.
`ok && status: 'already_on_tier'`	`You are already on {target_tier_name}.` (success)
`ok && status: 'upgraded'`	`Upgraded to {target_tier_name}. Your new monthly credits land in a moment.` — starts the eventual-consistency apply-poll (below).
`status: 'requires_action'` (no distinguishing reason)	`This upgrade needs extra verification (3DS). Finish it on the portal.` → `recovery_url`.
`status: 'payment_failed'` (no distinguishing reason)	`Your card was declined. Update your payment method on the portal and try again.` → `recovery_url`.
anything else	`errorResult(r)`: `message \|\| error \|\| 'Something went wrong. Try again, or manage on the portal.'`

Eventual-consistency apply-poll (ResultScreen, only after status: 'upgraded'): polls billing/subscription state every 2s (UPGRADE_CONFIRM_INTERVAL_MS) up to 15 attempts (UPGRADE_CONFIRM_ATTEMPTS, i.e. ~30s) until current.tier_id flips to the target. While waiting the screen reads Applying…; if it never flips inside the budget it reads Still applying / Your upgrade succeeded and is still applying — refresh in a moment. — the upgrade is never re-reported as failed just because NAS hasn’t caught up yet. Step-up denial copy (stepUpDenialResult, subscription flow):

`error`	Copy
`session_revoked`	`Your session expired — run /portal to log in again, then retry the change.`
`remote_spending_revoked`	`{message}` or `Remote spending was stopped for this terminal — reconnect from the portal, then retry.`
`rate_limited`	`Too many attempts — wait a moment, then try again.`
other/unknown	`{message}` or `Remote Spending was not allowed — someone with billing permissions (owner, admin, or finance admin) must approve it. You can also make this change on the portal.`

A repeat scope denial during a post-grant replay never re-enters the step-up screen (it’s already mounted there — re-patching would freeze it); allowStepUp=false instead surfaces a terminal result:

Remote Spending still isn’t active for this terminal — the authorization didn’t take. Retry, or make this change on the portal.

Text-mode (CLI) parity

cli.py’s _show_billing / _billing_overview and _show_subscription / _subscription_overview render the same state shapes (balance title, two-bar dollar usage, auto-reload line, card line, monthly cap) and share the “fail-open on logged-out/portal-hiccup, never crash” discipline. The CLI’s /subscription gives a paid admin/owner in an interactive context the full in-terminal change flow (tier picker → preview → confirm → apply, parity with the TUI overlay); members and non-interactive contexts fall back to _billing_portal_hint’s deep-link to subscription_manage_url. /topup’s interactive modal (prompt_toolkit) mirrors the TUI overlay the same way, and non-interactive contexts fall back to the same text + portal-link rendering, never prompting.

CLI surface / state	Behavior (parity with TUI / desktop)
`/subscription` on Free + admin/owner + interactive	`_subscription_free_catalog` prints the plan catalog from the same `tiers[]` data the TUI uses — one row per enabled paid tier, cheapest first, `name · $/mo · $credits/mo` (monthly credits are DOLLARS → `$22 credits/mo`, never a bare number). A numbered pick opens the `/manage-subscription` deep-link with `plan=<tier_id>` appended so the portal preselects the chosen plan. Starting a new subscription needs a fresh card, so the only action is the portal hand-off (the terminal never charges here).
Any CLI-built manage/subscribe URL	`subscription_manage_url(state, tier_id=…)` appends `plan=<tier_id>` (the stable `tiers[]` id, never a name/slug) only when a tier was picked (the Free catalog). The portal validates it server-side and ignores an unknown tier, so the CLI appends unconditionally on a pick, mirroring the TUI’s `?plan=`. `org_id` is emitted first, `plan` second.
Downgrades in the CLI	Stay native / in-app for normal changes (chargeless scheduling via `put_subscription_pending_change`). A blocked downgrade may still print the generic manage URL, but it never carries `plan=<tier_id>` — selected-tier deep-links are reserved for new subscriptions and upgrades.
`/topup` overview action copy	Splits one-time top-up from automatic refill, the distinction stated up front in each first sentence: `Add funds now — a single charge, added to your balance today.` vs `Refill when low — charges $X automatically when your balance falls below $Y.` (“credits” stays out of the dollars-only `/topup` surface — “Add funds now” carries the one-time meaning without it). When auto-reload is off, the automatic line omits concrete amounts.

Forward compatibility

Any error/status/reason code not in the tables above lands on the default branch in renderBillingError (§2) or errorResult/upgradeResult’s fallthrough (§4): it still renders the server’s own message (never blank, never a crash), just without bespoke copy or a typed recovery affordance. NAS W3 introduces card-health codes (card_paused, card_expired, card_mismatch) that are not yet typed here — until a client update adds explicit branches, they will arrive as unknown codes and degrade to this default path.

تطبيق ديسكتوب

البداية

استخدام مبيان

الميزات

منصات المراسلة

التكاملات

الأدلة والدروس

دليل المطوّر

المرجع

Billing Lifecycle (TUI)

1. `billing.state` shapes → render

2. Refusal codes (`renderBillingError`, in code order)

3. Charge settlement outcomes (`pollCharge` / `renderChargeFailed`)

4. Subscription preview / pending-change / upgrade outcomes

Text-mode (CLI) parity

Forward compatibility

​1. billing.state shapes → render

​2. Refusal codes (renderBillingError, in code order)

​3. Charge settlement outcomes (pollCharge / renderChargeFailed)

​4. Subscription preview / pending-change / upgrade outcomes

​Text-mode (CLI) parity

​Forward compatibility

1. `billing.state` shapes → render

2. Refusal codes (`renderBillingError`, in code order)

3. Charge settlement outcomes (`pollCharge` / `renderChargeFailed`)

4. Subscription preview / pending-change / upgrade outcomes

Text-mode (CLI) parity

Forward compatibility