`gjnUdZddlmZddlZddlZddlZddlZddlZddl m Z m Z dZ dZ dZGdd eZGd d eZGd d eZGddeZGddeZGddeZGddeZGddeZGddeZd4d5dZd6dZdZdaded<d7dZd4d8d Zd!d"d9d#Z d:d$Z! d4 d;d%Z"dde d&d' dd+Z%e d) d?d,Z&e d) d@d-Z'e d)d=d.Z(e d) dAd/Z)dd&e d0 dBd1Z*e d) d=d2Z+e d) dCd3Z,y)Du]Nous Portal terminal-billing HTTP client (Phase 2b). Thin, fail-loud client for the four ``/api/billing/*`` endpoints the terminal billing screens drive. Companion to ``hermes_cli/nous_account.py`` (which owns read-only entitlement/balance) — this module owns the *write* side: buy credits, poll a charge, configure auto-reload. Design rules: - **Money is decimal, never float.** The server emits decimal STRINGS (``"142.5"`` — not fixed 2dp). We parse with :class:`decimal.Decimal` and never round-trip through float. - **This client raises typed exceptions; it does NOT fail open.** Fail-open is the *caller's* job (the ``agent/billing_view.py`` builders) so each surface can decide how to degrade. A raw network/HTTP error here surfaces as :class:`BillingError` (or a subclass) carrying the parsed server ``error`` code, HTTP status, ``portalUrl`` deep-link, and ``retry_after``. - **Auth** = the OAuth bearer JWT Hermes already holds for inference (``get_provider_auth_state("nous")["access_token"]``). No API-key auth on these. - **Portal base URL** resolves with the same precedence as the device-flow login (``auth.py``): ``HERMES_PORTAL_BASE_URL`` → ``NOUS_PORTAL_BASE_URL`` → the stored auth-state ``portal_base_url`` → the registry default. This is how the E2E run points the client at a preview deployment with zero code change. ) annotationsN)AnyOptionalzhttps://portal.nousresearch.comg.@zbilling:managec ^eZdZdZddddddddd dfdZxZS) BillingErroraeA billing HTTP call failed. Carries everything a surface needs to render the right message + affordance: the server ``error`` code, HTTP ``status``, an optional human ``message``, the ``portalUrl`` deep-link (present on every gate denial), and ``retry_after`` seconds (429/503). ``payload`` is the full parsed JSON body when available. Nstatuserror portal_url retry_afterpayloadactorcoderecoveryct ||||_||_||_||_|xsi|_||_||_| |_ yN) super__init__r r r r r rrr) selfmessager r r r r rrr __class__s J/root/.hermes/venv/lib/python3.12/site-packages/hermes_cli/nous_billing.pyrzBillingError.__init__=sQ !  $&}"     )rstrr Optional[int]r Optional[str]r rr rr Optional[dict[str, Any]]rrrrrrreturnNone)__name__ __module__ __qualname____doc__r __classcell__)rs@rrr4s!%#$(%),0#""&!! !  ! " !#!*!!! ! !!rrceZdZdZy)BillingScopeRequiredu```403 insufficient_scope`` — the held token lacks ``billing:manage``. The lazy step-up trigger: catching this kicks off a fresh device-connect that requests ``billing:manage`` (and tells the user an ADMIN must tick "Allow terminal billing"). Also fires mid-session if the scope is stripped on refresh after the user loses ADMIN. Nr r!r"r#rrr&r&Yrr&ceZdZdZy)BillingAuthErroruC``401`` — missing/invalid bearer token (not logged in / expired).Nr'r(rrr+r+csMrr+ceZdZdZy)BillingRemoteSpendingRevokedu"``403 remote_spending_revoked`` — THIS terminal's spending was revoked. Distinct from ``insufficient_scope`` (never had the grant) and from ``session_revoked`` (full logout). The terminal stays logged in; only the money path is cut. ``actor`` is ``"admin"`` or ``"self"`` (absent → treat as ``"self"``); recovery is **reconnect** (re-consent device-auth). The terminal MUST disable charge/auto-reload immediately, without waiting for the next token refresh (the current token still claims the scope for ~15 min). Nr'r(rrr-r-grr-ceZdZdZy)BillingSessionRevokedu^``401 session_revoked`` — the whole session was logged out. Stronger than a spend-revoke: recovery is **re-login** (full device-auth), not just reconnect. Subclass of :class:`BillingAuthError` so existing 401 handling still treats it as not-logged-in, but the typed code lets the surface route to re-login with the right copy. Nr'r(rrr0r0sr)rr0ceZdZdZy)BillingTransientu"A deterministic non-charge outcome: the request definitely did NOT reach/complete at Stripe, so it's always safe to retry after backoff — never the "maybe charged" ambiguity of a real 5xx/timeout. Covers 429 rate limiting, 503 gate-unavailable, Stripe being down, and the daily upgrade cap — distinct failure modes that share this one contract property. Catch this (not the old ad-hoc subclass hierarchy) wherever the intent is "any transient, definitely-not-charged billing failure, back off and retry/poll". Nr'r(rrr2r2}r.rr2ceZdZdZy)BillingRateLimiteduf``429 rate_limited`` or ``503 temporarily_unavailable``. NOT a payment failure. Carries ``retry_after`` (seconds) — back off and tell the user "try again in N min"; never auto-retry-spam (the limiter is 5/org/hr + 5/token/hr and easy to dig deeper into). A 503 is the gate backend failing closed — back off, do NOT treat as revoked. Nr'r(rrr4r4r)rr4ceZdZdZy)BillingStripeUnavailableu``503 stripe_unavailable`` — Stripe itself is down. TRANSIENT: back off and retry using Retry-After; this is NOT the same as being throttled by our own rate limiter, so surfaces must not render "rate limited" copy for it — they should read ``.error`` to tell the two apart. A BillingTransient sibling of BillingRateLimited (not a subclass) — surfaces must not render "rate limited" copy for it; read ``.error`` to distinguish it. Nr'r(rrr6r6srr6ceZdZdZy)BillingUpgradeCapExceededua``429 upgrade_cap_exceeded`` — the org hit its 5-upgrades/day cap. Distinct from the hourly ``rate_limited`` charge cap (same HTTP status, different meaning + no useful short-Retry-After backoff). A BillingTransient sibling of BillingRateLimited (not a subclass) — surfaces must read ``.error`` to distinguish the failure mode. Nr'r(rrr8r8r)rr8cltjdxstjd}|r/|jr|jjdS|rP|j d}t |t r/|jr|jjdStS)uResolve the portal base URL with login-time precedence. ``HERMES_PORTAL_BASE_URL`` → ``NOUS_PORTAL_BASE_URL`` → stored auth-state ``portal_base_url`` → registry default. Trailing slash stripped. HERMES_PORTAL_BASE_URLNOUS_PORTAL_BASE_URL/portal_base_url)osgetenvstriprstripget isinstancerDEFAULT_PORTAL_BASE_URL)stateenvstoreds rresolve_portal_base_urlrHs )), - R;Q1RC syy{yy{!!#&& ,- fc "v||~<<>((- - ""rct|tr|js|St}tj j |jddz|S)uResolve a (possibly relative) server portalUrl to an absolute URL. The server emits ``portalUrl`` relative by design (e.g. ``/billing?topup=open``) — it doesn't know which deployment the client points at. Resolve it against the client's portal base (preview / staging / prod) so deep-links are clickable. Idempotent: an already-absolute URL is returned unchanged (urljoin keeps it). r<)rCrr@rHurllibparseurljoinrA)r bases r_absolutize_portal_urlrNsN z3 'J,<,<,> " $D <<   C 03 6 CCrg>@ztuple[float, str, str] | None _token_cachecday)uBust the 30s token cache so post-step-up replays use the freshly-scoped token. ``_request`` only self-busts the cache on a 401 (an expired/invalid token), not on a 403 scope denial — so after a step-up grant, the cache would otherwise still hold the pre-grant unscoped token and the immediate replay would 403 again. Callers outside this module (e.g. the CLI's scope step-up flow) call this instead of poking the private ``_token_cache`` global directly. N)rOr(rrinvalidate_cached_tokenrQs Lrc4tddd}|||_|S)zEBuild the canonical 'not logged in' BillingAuthError (single source).u>Not logged into Nous Portal — run `hermes portal` to log in. invalid_token)r r )r+ __cause__)excerrs r_billing_not_logged_inrXs( H C   JrT use_cachecPddl}|r.t(t\}}}|j|z tkr||fS ddlm}|dxsi}t |} ddlm}m} |}|j|f} |jg| a| S#t $ri}YQwxYw#t$rf|jd}t|tr:|jr*|j|f} |jg| a| cYStwxYw#|$r} t| | d} ~ wwxYw)aReturn ``(access_token, portal_base_url)`` for billing calls. Uses the same refresh-aware resolver the inference path uses (``resolve_nous_access_token``), so a short-lived (~15 min) access token that has expired is transparently refreshed via the stored ``refresh_token`` instead of failing as "not logged in". Raises :class:`BillingAuthError` only when there is no usable Nous session at all. The result is cached for ``_TOKEN_CACHE_TTL_SECONDS`` to keep the charge poll loop from re-locking + re-reading the auth store on every 2s tick. Pass ``use_cache=False`` to force a fresh resolution (e.g. after a 401). rN)get_provider_auth_statenous) AuthErrorresolve_nous_access_token access_token)timerO_TOKEN_CACHE_TTL_SECONDShermes_cli.authr\ ExceptionrHr^r_ ImportErrorrBrCrr@rX) rZ_time cached_attokenrMr\rEr^r_resolvedrVs r_resolve_token_and_baserjs0\-!- 5$ JJL9 $(@ @$; ;'/52 #5 )D 'H3)+ t$HJJL,8,L O-  ' .) eS !ekkm t,H!JJL484LO$&&' 3$S)s23s<B BD BBA"D  D D% D  D%c|y |jd}|y tt|j S#t$rd}Y3wxYw#t t f$rYywxYw)uHParse a ``Retry-After`` header (integer seconds) — None if absent/bad.Nz Retry-After)rBrdintrr@ TypeError ValueError)headersraws r_retry_after_secondsrq*spkk-( {3s8>>#$$  z "s <!A A  A  AAc t|tr|jdnd}t|tr|jdnd}t|tr|jdnd}t|tr|jdnd}t|tr|jdnd}tt|tr|jdnd}t |} |||| t|tr|nd|||d} |d k(rt |xsd fi| |d k(rt |xsd fi| |d k(r%|dk(rt|xsdfi| t|xsdfi| |dk(r>|dk(rt|xsdfi| |dk(rt|xsdfi| t|xs|xsdfi| |dvrt|xsdfi| t|xs |xsd|dfi| )ukMap an HTTP error response to the right typed :class:`BillingError`. Recognizes the Remote-Spending gate contract (NAS PR #481): 403 ``remote_spending_revoked`` (this terminal's spend revoked → reconnect), 401 ``session_revoked`` (full logout → re-login), 503 ``temporarily_unavailable`` (gate fail-closed → back off, NOT revoked). The business-denial codes (``cli_billing_disabled`` + dual ``code:remote_spending_disabled``, ``role_required``, ``idempotency_conflict``, …) flow through as a generic BillingError carrying ``error``/``code``/``recovery`` for the surface to map. r Nrrrr portalUrlrstripe_unavailableu8Stripe is temporarily unavailable — try again shortly.upgrade_cap_exceededu7Daily plan-change limit reached — try again tomorrow.rSsession_revokedu-Your session was logged out — log in again.zAuthentication required.iremote_spending_revokedz.Remote Spending was revoked for this terminal.insufficient_scopez+This action needs the billing:manage scope.zBilling request denied.)iiu#Rate limited — try again shortly.zBilling request failed (z).) rCdictrBrNrqr6r8r0r+r-r&rr4) r r ror rrrrr r commons r_raise_for_errorr{:s9%/w$=GKK 4E(27D(Agkk)$tG",Wd";7;;v D$.w$=GKK 4E*4Wd*Cw{{:&H'$.w$= K 4J'w/K "($77T F $$&  QQ U[   &&'  PP TZ  } % %'JJNT wD*DOOO } - -.KKOU  ( (&HHLR  7HeH/HSFSS   << @F   wP%P-EfXR+P [TZ [[rFbody extra_headerstimeout _retried_authc t| \}}||}d|dd} |d| d<|r| j||$tj|j dnd} t j j|| | |} t j j| | 5} | jjd} | js icdddS tj| cdddS#tj$r}td d t| d d |d}~wwxYw#1swYyxYw#t j j"$r}|j$dk(r|sdat)|||||dcYd}~Sd} |jjd} n#t*$rd} YnwxYw | jrtj| ni}n#tj$ri}YnwxYwt-|j$|t|ddd}~wt j j.$r }td|j0d|d}~wt2$r}tdd|d}~wwxYw)aMake an authenticated billing request; return the parsed JSON dict. Raises a typed :class:`BillingError` on any non-2xx response (or transport failure). 2xx with an empty body returns ``{}``. A 401 triggers exactly one retry with a freshly-resolved token (bypassing the short token cache) so a cached-but-just-expired token self-heals instead of failing the call. rYzBearer zapplication/json) AuthorizationAcceptNz Content-Typezutf-8)dataromethodrz[Billing endpoint returned a non-JSON response (it may not be available on this deployment).endpoint_unavailabler )r r rSTr|rozCould not reach Nous Portal: network_errorr z&Could not reach Nous Portal: timed out)rjupdatejsondumpsencoderJrequestRequesturlopenreaddecoder@loadsJSONDecodeErrorrgetattrr HTTPErrorrrO_requestrdr{URLErrorreason TimeoutError)rpathr}r~rrrhrMurlrorreqresprprVr s rrrst * 4EFKE4 F4&/C"5'*$G "4}%/3/?4::d  " "7 +TD .. 4 PC7 ^^ # #C # 9 T))+$$W-C99;   zz#    '' #D0"448       & << ! ! 88s?=L+"   ((*##G,C C  ),djjo"G## G 7GCD,IJ << +CJJ< 8    4O   s!E&1D5 E"D6 ED2D--D22D55D>:E>EI<#H"I<H" F*)H"* F85H"7F88H"<'G$#H"$G<9H";G<<&H"" I<I I<)I77I<rctdd|S)uH``GET /api/billing/state`` — role-tiered overview (no scope required).GETz/api/billing/staterrrs rget_billing_staters E/ AArc ^tddt|t|t|d|S)u``PATCH /api/billing/auto-top-up`` — configure auto-reload (scope required). Body is strict server-side: extra keys (``maxMonthlySpend``, a payment method) are rejected with 400. Numbers are sent as JSON numbers per the contract. PATCHz/api/billing/auto-top-up)enabled threshold topUpAmountr}r)rboolfloat)rr top_up_amountrs rpatch_auto_top_uprs8 "G}y) /   rct|tr|js tddt dddt |id|ji|S) uR``POST /api/billing/charge`` — buy credits (scope required). ``Idempotency-Key`` header is MANDATORY (a missing header is a server 400, not a default): generate a UUID per user-confirmed purchase and reuse it on retry. Returns ``202 {chargeId}`` — money is NOT confirmed yet; poll with :func:`get_charge_status`. z)Idempotency-Key is required for a charge.idempotency_key_requiredrPOSTz/api/billing/charge amountUsdIdempotency-Keyr}r~r)rCrr@rrr) amount_usdidempotency_keyrs r post_chargersb  ,1F1F1H 7,   5, -(/*?*?*AB  rct|tr|js tddtj j |jd}tdd||S) uG``GET /api/billing/charge/{id}`` — poll a charge (scope required). Returns ``{status: "pending"|"settled"|"failed", ...}``. An unknown or foreign id returns ``{status:"pending"}`` (never 404, never another org's data) — so a ``pending`` that never resolves past the 5-min cap is a *timeout*, not an error. zA charge id is required.invalid_charge_idrr)saferz/api/billing/charge/r)rCrr@rrJrKquoter) charge_idrsafe_ids rget_charge_statusrs_ y# &9??+<5=PQQll  !2    2   rctdd|S)u``DELETE /api/billing/subscription/pending-change`` — clear it (resume / undo). Removes a scheduled downgrade OR cancellation in one call, restoring the live active tier and recurring renewal. Chargeless, but it re-enables recurring spend, so it requires ``billing:manage`` and is honored by the org kill-switch. Returns ``{rail, cancelAtPeriodEnd: false, message}``. DELETErrrrs r"delete_subscription_pending_changer{s 2 rct|tr|js tddt ddd|id|ji|S) uw``POST /api/billing/subscription/upgrade`` — immediate paid upgrade. The SINGLE money route: one Stripe op prorates, charges the card already on the subscription, and flips the plan. ``Idempotency-Key`` is MANDATORY (a missing header is a server 400, not a default) — reuse the same key on retry so a replay cannot double-charge. Returns ``{status:"upgraded"|"already_on_tier", ...}`` on success, or ``{status:"requires_action"|"payment_failed", reason, recoveryUrl}`` when the charge needs 3DS / was declined and must be finished in the portal at ``recoveryUrl``. Requires ``billing:manage``. z+Idempotency-Key is required for an upgrade.rrrz!/api/billing/subscription/upgraderrrr)rrrs rpost_subscription_upgraders^  ,1F1F1H 9,   +"$8 9(/*?*?*AB  rr)rErrr)r rrr)rr)rVzOptional[BaseException]rz'BillingAuthError')rZrrztuple[str, str])rorrr)r rlr dict[str, Any]rorrr)rrrrr}rr~zOptional[dict[str, str]]rrrrrr)rrrr) rrr float | strrrrrrr)rrrrrrrr)rrrrrr)rrrrrr)rz str | Nonerrrrrr)rrrrrrrr)-r# __future__rrr> urllib.errorrJ urllib.parseurllib.requesttypingrrrDDEFAULT_TIMEOUTBILLING_MANAGE_SCOPErdrr&r+r-r0r2r4r6r8rHrNrbrO__annotations__rQrXrjrqr{rrrrrrrrrrr(rrrs2#  ; ("!9"!J<N|N < , | )/ 0 # D0 .2 +2  26/n ":>E\ E\(E\36E\ E\X&*.2$U U U # U , U  UUUz+:B%       8%    8)8NN %NN"0?I44C +0.(,$ "$" " "  "L(*%    r