billing_view.py 16 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374
  1. """Surface-agnostic core for the Remote Spending screens (CLI ``_show_billing``, TUI JSON-RPC).
  2. One fetch/parse per concern; the server payload is parsed into frozen dataclasses.
  3. **Fail open**: when not logged in or the portal is unreachable, return a struct with
  4. ``logged_in=False`` and let the surface degrade gracefully (never crash).
  5. Money discipline: the server emits decimal STRINGS (``"142.5"``, not fixed 2dp).
  6. We keep them as :class:`decimal.Decimal` end-to-end and only format for display.
  7. """
  8. from __future__ import annotations
  9. import logging
  10. import os
  11. import uuid
  12. from dataclasses import dataclass
  13. from decimal import Decimal, InvalidOperation
  14. from typing import Any, Callable, Optional
  15. logger = logging.getLogger(__name__)
  16. def parse_money(value: Any) -> Optional[Decimal]:
  17. """Server money value (decimal string; defensively int/float) -> Decimal, or None. Never raises."""
  18. try:
  19. # Decimal(str(...)) avoids binary-float artifacts if a float ever sneaks in.
  20. return Decimal(str(value).strip()) if value is not None else None
  21. except (InvalidOperation, ValueError, TypeError):
  22. return None
  23. def format_money(value: Optional[Decimal], *, grouped: bool = False) -> str:
  24. """``$X`` for whole dollars, ``$X.YY`` (exactly 2dp) otherwise; ``None`` -> ``—``.
  25. ``grouped=True`` adds thousands separators (mirrors the TUI's ``toLocaleString('en-US')``
  26. on plan-catalog rows); the default is intentionally ungrouped across the other surfaces.
  27. """
  28. if value is None:
  29. return "—"
  30. spec = ",f" if grouped else "f"
  31. if value == value.to_integral_value():
  32. # format(..., "f") avoids 1E+3 for 1000.
  33. return f"${format(value.to_integral_value(), spec)}"
  34. return f"${format(value.quantize(Decimal('0.01')), spec)}"
  35. def _optional_str(raw: dict, key: str) -> Optional[str]:
  36. value = raw.get(key)
  37. return value if isinstance(value, str) else None
  38. def _dict_parser(fn: Callable[[dict], Any]) -> Callable[[Any], Any]:
  39. """Sub-structure parsers accept anything and return None unless the payload is a dict."""
  40. return lambda raw: fn(raw) if isinstance(raw, dict) else None
  41. # resolvedVia (server card-on-file ladder rung) → "why THIS card?". Unknown/absent
  42. # rungs render no label so older servers degrade cleanly.
  43. _CARD_PROVENANCE_LABELS = {
  44. "subPin": "the card on your subscription",
  45. "customerDefault": "your default card saved on the portal",
  46. "autoRefill": "your auto-reload card",
  47. }
  48. @dataclass(frozen=True)
  49. class CardInfo:
  50. brand: str
  51. last4: str
  52. resolved_via: Optional[str] = None # ladder rung; None on pre-resolver payloads
  53. @property
  54. def masked(self) -> str:
  55. # A Link payment method has no card number (last4 = "") — brand alone, not "Link ····".
  56. return f"{self.brand} ····{self.last4}" if self.last4 else self.brand
  57. @property
  58. def provenance(self) -> Optional[str]:
  59. """Human label for why this card was picked, or None (unknown rung / old server)."""
  60. return _CARD_PROVENANCE_LABELS.get(self.resolved_via) if self.resolved_via is not None else None
  61. @property
  62. def display(self) -> str:
  63. """``Visa ····4242 — the card on your subscription`` (masked only when provenance unknown)."""
  64. label = self.provenance
  65. return f"{self.masked} — {label}" if label else self.masked
  66. @dataclass(frozen=True)
  67. class PaymentMethodInfo:
  68. """Payment method on file. ``kind`` is "card" | "link" | "unknown" (settled at parse time
  69. so consumers only see fields that belong to the kind they are looking at)."""
  70. kind: str
  71. brand: Optional[str] = None
  72. last4: Optional[str] = None
  73. wallet: Optional[str] = None
  74. email: Optional[str] = None
  75. resolved_via: Optional[str] = None
  76. raw_kind: Optional[str] = None # what the server called an unrecognised kind
  77. @dataclass(frozen=True)
  78. class MonthlyCap:
  79. limit_usd: Optional[Decimal] = None
  80. spent_this_month_usd: Optional[Decimal] = None
  81. is_default_ceiling: bool = False
  82. @dataclass(frozen=True)
  83. class AutoReloadCard:
  84. kind: str # "canonical" | "distinct" | "none"
  85. payment_method_id: Optional[str] = None
  86. brand: Optional[str] = None
  87. last4: Optional[str] = None
  88. @dataclass(frozen=True)
  89. class AutoReload:
  90. enabled: bool = False
  91. threshold_usd: Optional[Decimal] = None
  92. reload_to_usd: Optional[Decimal] = None
  93. card: Optional[AutoReloadCard] = None
  94. class OrgRoleCapability:
  95. """``is_admin`` / ``can_change_plan`` shared by the billing and subscription states."""
  96. role: Optional[str]
  97. can_change_plan_raw: Optional[bool]
  98. @property
  99. def is_admin(self) -> bool:
  100. """Display only — legacy OWNER/ADMIN check; gate plan-change actions on :attr:`can_change_plan`."""
  101. return (self.role or "").upper() in ("OWNER", "ADMIN")
  102. @property
  103. def can_change_plan(self) -> bool:
  104. """Server capability when supplied; otherwise the legacy role fallback."""
  105. return self.can_change_plan_raw if self.can_change_plan_raw is not None else self.is_admin
  106. @dataclass(frozen=True)
  107. class BillingState(OrgRoleCapability):
  108. """Parsed ``GET /api/billing/state``; fail-open ``logged_in=False`` (empty fields) when unavailable."""
  109. logged_in: bool
  110. org_id: Optional[str] = None
  111. org_slug: Optional[str] = None
  112. org_name: Optional[str] = None
  113. role: Optional[str] = None # "OWNER" | "ADMIN" | "FINANCE_ADMIN" | "SECURITY_ADMIN" | "MEMBER"
  114. can_change_plan_raw: Optional[bool] = None
  115. balance_usd: Optional[Decimal] = None
  116. cli_billing_enabled: bool = False
  117. charge_presets: tuple[Decimal, ...] = ()
  118. min_usd: Optional[Decimal] = None
  119. max_usd: Optional[Decimal] = None
  120. card: Optional[CardInfo] = None
  121. payment_method: Optional[PaymentMethodInfo] = None
  122. monthly_cap: Optional[MonthlyCap] = None
  123. auto_reload: Optional[AutoReload] = None
  124. # Window plans only: "Keep going on credits". None below ADMIN, on any
  125. # other plan, and from a portal that predates the setting (no control offered).
  126. keep_going_on_credits: Optional[bool] = None
  127. portal_url: Optional[str] = None
  128. error: Optional[str] = None # set when the fetch failed (vs cleanly not-logged-in)
  129. @property
  130. def can_charge(self) -> bool:
  131. """Offer charge/auto-reload actions: ``can_change_plan`` (server-grantable, e.g. FINANCE_ADMIN)
  132. AND the per-org kill-switch. Display gating only — the server still enforces."""
  133. return self.can_change_plan and self.cli_billing_enabled
  134. @_dict_parser
  135. def _parse_card(raw: dict) -> Optional[CardInfo]:
  136. brand, last4 = raw.get("brand"), raw.get("last4")
  137. if not (isinstance(brand, str) and isinstance(last4, str)):
  138. return None
  139. return CardInfo(brand=brand, last4=last4, resolved_via=_optional_str(raw, "resolvedVia"))
  140. @_dict_parser
  141. def _parse_payment_method(raw: dict) -> Optional[PaymentMethodInfo]:
  142. if not isinstance(kind := raw.get("kind"), str):
  143. return None
  144. resolved_via = _optional_str(raw, "resolvedVia")
  145. brand = _optional_str(raw, "brand")
  146. last4 = _optional_str(raw, "last4")
  147. # Settle the kind here (like _parse_card) so nothing downstream re-checks fields.
  148. if kind == "card" and brand and last4:
  149. return PaymentMethodInfo(kind="card", brand=brand, last4=last4, wallet=_optional_str(raw, "wallet"), resolved_via=resolved_via)
  150. if kind == "link":
  151. return PaymentMethodInfo(kind="link", email=_optional_str(raw, "email"), resolved_via=resolved_via)
  152. return PaymentMethodInfo(kind="unknown", raw_kind=kind, resolved_via=resolved_via)
  153. @_dict_parser
  154. def _parse_monthly_cap(raw: dict) -> MonthlyCap:
  155. return MonthlyCap(limit_usd=parse_money(raw.get("limitUsd")), spent_this_month_usd=parse_money(raw.get("spentThisMonthUsd")),
  156. is_default_ceiling=bool(raw.get("isDefaultCeiling")))
  157. @_dict_parser
  158. def _parse_auto_reload(raw: dict) -> AutoReload:
  159. return AutoReload(enabled=bool(raw.get("enabled")), threshold_usd=parse_money(raw.get("thresholdUsd")),
  160. reload_to_usd=parse_money(raw.get("reloadToUsd")), card=_parse_auto_reload_card(raw.get("card")))
  161. @_dict_parser
  162. def _parse_auto_reload_card(raw: dict) -> Optional[AutoReloadCard]:
  163. if (kind := raw.get("kind")) not in ("canonical", "distinct", "none"):
  164. return None
  165. if kind != "distinct":
  166. return AutoReloadCard(kind=kind)
  167. return AutoReloadCard(kind=kind, payment_method_id=_optional_str(raw, "paymentMethodId"),
  168. brand=_optional_str(raw, "brand"), last4=_optional_str(raw, "last4"))
  169. def parse_org_fields(payload: dict[str, Any]) -> tuple[dict[str, Any], Optional[bool]]:
  170. """``(org dict or {}, canChangePlan if bool else None)`` — shared by both state parsers."""
  171. raw_org, ccp = payload.get("org"), payload.get("canChangePlan")
  172. return (raw_org if isinstance(raw_org, dict) else {}), (ccp if isinstance(ccp, bool) else None)
  173. def billing_state_from_payload(payload: dict[str, Any], *, portal_url: Optional[str] = None) -> BillingState:
  174. """Map a raw ``/api/billing/state`` JSON dict into :class:`BillingState`."""
  175. org, can_change_plan_raw = parse_org_fields(payload)
  176. bounds: dict[str, Any] = payload.get("bounds") if isinstance(payload.get("bounds"), dict) else {}
  177. presets = [p for p in map(parse_money, payload.get("chargePresets") or ()) if p is not None]
  178. return BillingState(
  179. logged_in=True,
  180. org_id=org.get("id"),
  181. org_slug=org.get("slug"),
  182. org_name=org.get("name"),
  183. role=org.get("role"),
  184. can_change_plan_raw=can_change_plan_raw,
  185. balance_usd=parse_money(payload.get("balanceUsd")),
  186. cli_billing_enabled=bool(payload.get("cliBillingEnabled")),
  187. charge_presets=tuple(presets),
  188. min_usd=parse_money(bounds.get("minUsd")),
  189. max_usd=parse_money(bounds.get("maxUsd")),
  190. card=_parse_card(payload.get("card")),
  191. payment_method=_parse_payment_method(payload.get("paymentMethod")),
  192. monthly_cap=_parse_monthly_cap(payload.get("monthlyCap")),
  193. auto_reload=_parse_auto_reload(payload.get("autoReload")),
  194. keep_going_on_credits=_parse_keep_going_on_credits(payload.get("keepGoingOnCredits")),
  195. portal_url=portal_url,
  196. )
  197. def _parse_keep_going_on_credits(raw: Any) -> Optional[bool]:
  198. """``{enabled: bool}`` → the bool; anything else (null, absent, malformed) → None."""
  199. enabled = raw.get("enabled") if isinstance(raw, dict) else None
  200. return enabled if isinstance(enabled, bool) else None
  201. def fetch_portal_state(
  202. endpoint: str, label: str, *, failed: Callable[..., Any], parse: Callable[[dict, Optional[str]], Any],
  203. portal_fallback: Callable[[str], str], timeout: float, log: logging.Logger,
  204. ):
  205. """Shared fail-open fetch+parse for the billing/subscription overview builders.
  206. ``failed(**kw)`` builds the ``logged_in=False`` struct: bare on auth failure, with ``error``
  207. set on a portal/HTTP failure. Portal URL: server ``portalUrl`` (absolutized), else
  208. ``portal_fallback(portal_base_url)``.
  209. """
  210. try:
  211. import hermes_cli.nous_billing as nb
  212. except Exception:
  213. return failed(error="billing client unavailable")
  214. try:
  215. payload = getattr(nb, endpoint)(timeout=timeout)
  216. except nb.BillingAuthError:
  217. return failed()
  218. except nb.BillingError as exc:
  219. log.debug("%s ▸ /state fetch failed (fail-open)", label, exc_info=True)
  220. return failed(error=str(exc))
  221. except Exception:
  222. log.debug("%s ▸ /state unexpected error (fail-open)", label, exc_info=True)
  223. return failed(error=f"could not load {label} state")
  224. raw_portal = payload.get("portalUrl") if isinstance(payload, dict) else None
  225. portal_url = nb._absolutize_portal_url(raw_portal) if raw_portal else None
  226. if not portal_url:
  227. try:
  228. portal_url = portal_fallback(nb.resolve_portal_base_url())
  229. except Exception:
  230. portal_url = None
  231. return parse(payload, portal_url)
  232. def build_billing_state(*, timeout: float = 15.0) -> BillingState:
  233. """Fetch + parse ``/api/billing/state``; fail-open. ``HERMES_DEV_BILLING_FIXTURE`` short-circuits to a fixture."""
  234. fixture = _dev_fixture_billing_state()
  235. if fixture is not None:
  236. return fixture
  237. return fetch_portal_state(
  238. "get_billing_state", "billing", timeout=timeout, log=logger,
  239. failed=lambda **kw: BillingState(logged_in=False, **kw),
  240. parse=lambda payload, portal_url: billing_state_from_payload(payload, portal_url=portal_url),
  241. portal_fallback=lambda base: f"{base.rstrip('/')}/billing?topup=open",
  242. )
  243. # ── Dev fixtures (env-var driven, no live portal) ────────────────────────────
  244. _FIXTURE_ALIASES = {
  245. "logged_out": "logged-out", "loggedout": "logged-out", "card_sub": "card-sub", "card_autoreload": "card-autoreload",
  246. "autoreload": "card-autoreload", "not-admin": "notadmin", "member": "notadmin", "billing_off": "billing-off", "off": "billing-off",
  247. }
  248. def _dev_fixture_billing_state() -> Optional[BillingState]:
  249. """``HERMES_DEV_BILLING_FIXTURE`` -> :class:`BillingState` for offline UX; None when unset.
  250. Names: nocard · card · card-sub · card-autoreload · notadmin · billing-off · logged-out; an
  251. unknown name yields logged-out with ``error`` so the misconfiguration is visible.
  252. """
  253. name = (os.getenv("HERMES_DEV_BILLING_FIXTURE") or "").strip().lower()
  254. if not name:
  255. return None
  256. name = _FIXTURE_ALIASES.get(name, name)
  257. if name == "logged-out":
  258. return BillingState(logged_in=False)
  259. # Prod portal host (matches subscription_view._DEV_FIXTURE_PORTAL) + the /topup deep-link suffix.
  260. common: dict[str, Any] = dict(
  261. logged_in=True, org_id="org_acme", org_slug="acme", org_name="Acme Inc", role="OWNER",
  262. balance_usd=Decimal("3.40"), cli_billing_enabled=True, min_usd=Decimal(5), max_usd=Decimal(500),
  263. charge_presets=(Decimal(10), Decimal(25), Decimal(50)), portal_url="https://portal.nousresearch.com/billing?topup=open",
  264. )
  265. card = CardInfo(brand="Visa", last4="4242")
  266. overrides: dict[str, dict[str, Any]] = {
  267. "nocard": dict(card=None),
  268. "card": dict(card=card),
  269. "card-sub": dict(card=CardInfo(brand="Visa", last4="4242", resolved_via="subPin")),
  270. "card-autoreload": dict(card=card, auto_reload=AutoReload(enabled=True, threshold_usd=Decimal(5), reload_to_usd=Decimal(25))),
  271. "notadmin": dict(card=card, role="MEMBER"),
  272. "billing-off": dict(card=None, cli_billing_enabled=False),
  273. }
  274. if name not in overrides:
  275. return BillingState(logged_in=False, error=f"unknown HERMES_DEV_BILLING_FIXTURE: {name}")
  276. return BillingState(**{**common, **overrides[name]})
  277. def new_idempotency_key() -> str:
  278. """Fresh ``Idempotency-Key`` for ``POST /charge``: reuse across retries of the SAME buy so a
  279. double-submit collapses to one charge; never across amounts (server 409 idempotency_conflict)."""
  280. return str(uuid.uuid4())
  281. @dataclass(frozen=True)
  282. class AmountValidation:
  283. ok: bool
  284. amount: Optional[Decimal] = None
  285. error: Optional[str] = None
  286. def validate_charge_amount(raw: str, *, min_usd: Optional[Decimal], max_usd: Optional[Decimal]) -> AmountValidation:
  287. """Mirror the server's accept/reject (bounds + multipleOf 0.01) for instant UI feedback; server is authoritative."""
  288. amount = parse_money((raw or "").strip().lstrip("$").strip())
  289. if amount is None:
  290. error = "Enter a dollar amount, e.g. 100"
  291. elif amount <= 0:
  292. error = "Amount must be greater than $0"
  293. elif amount != amount.quantize(Decimal("0.01")):
  294. error = "Amount can't be smaller than a cent"
  295. elif min_usd is not None and amount < min_usd:
  296. error = f"Minimum is {format_money(min_usd)}"
  297. elif max_usd is not None and amount > max_usd:
  298. error = f"Maximum is {format_money(max_usd)}"
  299. else:
  300. return AmountValidation(ok=True, amount=amount)
  301. return AmountValidation(ok=False, error=error)