askrobots / dbbasic-object-server
Public
Runs live, versioned Python application objects on one VM, with a suite of apps: projects, notes, tasks, files and more.
danq9
signup: the person chooses the password and name on the confirm page
83c7aa6
2 weeks, 5 days ago
History
object_billing.py · 14.8 KB · 361 lines
| 1 | """Rating: turning measured usage into money owed. |
| 2 | |
| 3 | The pure half of metered billing, kept out of the runner so it can be |
| 4 | tested exhaustively without a data directory -- same posture as |
| 5 | object_finance's folds and object_money's conversions. |
| 6 | |
| 7 | Three rules shape everything here, and each exists because of a way real |
| 8 | vendors get bills wrong: |
| 9 | |
| 10 | **Rate at period close, never per event.** Allowances and tiers are |
| 11 | properties of a PERIOD's total, not of an individual call. Rating each |
| 12 | event as it lands means the first thousand calls get charged at the |
| 13 | retail rate and the allowance never applies, which is precisely how |
| 14 | customers end up disputing invoices they cannot reconstruct. |
| 15 | |
| 16 | **Rate from summaries, never from raw events.** A summary is a period |
| 17 | bucket; a month of per-request rows is not something a bill should be |
| 18 | re-derived from every time someone opens a page. This boundary is also |
| 19 | the scale valve: the write side can change (batching, an accumulator) |
| 20 | without touching a single line of pricing logic. |
| 21 | |
| 22 | **Stamp what it cost US alongside what we charge.** usage_events carry a |
| 23 | cost, so margin is a fold over stored facts rather than a spreadsheet |
| 24 | someone maintains separately. A billing system that knows revenue but not |
| 25 | cost cannot answer "which customer loses us money", which is the first |
| 26 | question anyone asks once the AI bills arrive. |
| 27 | |
| 28 | Integer minor units throughout; Decimal only where a rate multiplication |
| 29 | needs it, and rounding is stated at the point it happens. |
| 30 | """ |
| 31 | |
| 32 | from __future__ import annotations |
| 33 | |
| 34 | import json |
| 35 | from decimal import Decimal, InvalidOperation, ROUND_HALF_UP |
| 36 | from typing import Any |
| 37 | |
| 38 | |
| 39 | def parse_prices(raw: Any) -> dict[str, dict]: |
| 40 | """A plan's price JSON -> {metric: {included, unit_minor, tiers?}}. |
| 41 | |
| 42 | Unparseable pricing yields NO prices rather than an exception: a |
| 43 | malformed plan must fail as "nothing to charge for", never as a |
| 44 | crashed billing run that leaves half a customer base uninvoiced. |
| 45 | The runner reports it; the pass keeps going. |
| 46 | """ |
| 47 | if isinstance(raw, dict): |
| 48 | candidate = raw |
| 49 | else: |
| 50 | text = str(raw or "").strip() |
| 51 | if not text: |
| 52 | return {} |
| 53 | try: |
| 54 | candidate = json.loads(text) |
| 55 | except (ValueError, TypeError): |
| 56 | return {} |
| 57 | if not isinstance(candidate, dict): |
| 58 | return {} |
| 59 | out = {} |
| 60 | for metric, spec in candidate.items(): |
| 61 | if isinstance(spec, dict): |
| 62 | out[str(metric)] = spec |
| 63 | return out |
| 64 | |
| 65 | |
| 66 | def _num(value, default=0): |
| 67 | try: |
| 68 | return Decimal(str(value if value not in (None, "") else default)) |
| 69 | except (InvalidOperation, TypeError, ValueError): |
| 70 | return Decimal(default) |
| 71 | |
| 72 | |
| 73 | def rate_metric(quantity: Any, spec: dict) -> dict: |
| 74 | """Charge for one metric's period total under one plan's terms. |
| 75 | |
| 76 | Returns {"billable", "included", "overage", "unit_minor", "amount_minor", |
| 77 | "tier_detail"}. `included` is consumed before anything is charged, and |
| 78 | tiers (when present) price successive bands of the OVERAGE, which is |
| 79 | the shape every metered vendor actually publishes: |
| 80 | |
| 81 | tiers: [{"upto": 1000, "unit_minor": 2}, {"unit_minor": 1}] |
| 82 | |
| 83 | The last tier may omit `upto`, meaning "everything above". Rounding is |
| 84 | half-up, applied ONCE to the metric's total rather than per tier: |
| 85 | rounding each band separately is how a bill stops matching the sum of |
| 86 | its own line items. |
| 87 | """ |
| 88 | total = _num(quantity) |
| 89 | included = _num(spec.get("included")) |
| 90 | overage = total - included |
| 91 | if overage <= 0: |
| 92 | return {"billable": total, "included": included, "overage": Decimal(0), |
| 93 | "unit_minor": _num(spec.get("unit_minor")), "amount_minor": 0, |
| 94 | "tier_detail": []} |
| 95 | |
| 96 | tiers = spec.get("tiers") |
| 97 | if isinstance(tiers, list) and tiers: |
| 98 | remaining = overage |
| 99 | amount = Decimal(0) |
| 100 | detail = [] |
| 101 | consumed = Decimal(0) |
| 102 | for tier in tiers: |
| 103 | if remaining <= 0: |
| 104 | break |
| 105 | if not isinstance(tier, dict): |
| 106 | continue |
| 107 | unit = _num(tier.get("unit_minor")) |
| 108 | upto = tier.get("upto") |
| 109 | if upto in (None, ""): |
| 110 | band = remaining |
| 111 | else: |
| 112 | band = min(remaining, max(_num(upto) - consumed, Decimal(0))) |
| 113 | if band <= 0: |
| 114 | continue |
| 115 | amount += band * unit |
| 116 | detail.append({"band": str(band), "unit_minor": str(unit)}) |
| 117 | consumed += band |
| 118 | remaining -= band |
| 119 | if remaining > 0 and detail: |
| 120 | # Tiers that do not cover the whole overage bill the remainder |
| 121 | # at the last stated rate rather than silently free. |
| 122 | unit = _num(tiers[-1].get("unit_minor") if isinstance(tiers[-1], dict) else 0) |
| 123 | amount += remaining * unit |
| 124 | detail.append({"band": str(remaining), "unit_minor": str(unit), |
| 125 | "note": "beyond the last tier, charged at its rate"}) |
| 126 | return {"billable": total, "included": included, "overage": overage, |
| 127 | "unit_minor": None, "tier_detail": detail, |
| 128 | "amount_minor": int(amount.to_integral_value(rounding=ROUND_HALF_UP))} |
| 129 | |
| 130 | unit = _num(spec.get("unit_minor")) |
| 131 | amount = overage * unit |
| 132 | return {"billable": total, "included": included, "overage": overage, |
| 133 | "unit_minor": unit, "tier_detail": [], |
| 134 | "amount_minor": int(amount.to_integral_value(rounding=ROUND_HALF_UP))} |
| 135 | |
| 136 | |
| 137 | def rate_period(summaries: list[dict], prices: dict[str, dict]) -> dict: |
| 138 | """Every metric's charge for one period. |
| 139 | |
| 140 | Returns {"lines": [...], "total_minor": int, "unpriced": [metrics]}. |
| 141 | A metric with usage but no price lands in `unpriced` and is charged |
| 142 | NOTHING -- and is reported, because silently billing for something a |
| 143 | plan never named is worse than the revenue is worth, while silently |
| 144 | dropping it hides a pricing gap the operator needs to close. |
| 145 | """ |
| 146 | lines = [] |
| 147 | unpriced = [] |
| 148 | total = 0 |
| 149 | for summary in sorted(summaries, key=lambda s: str(s.get("metric") or "")): |
| 150 | metric = str(summary.get("metric") or "") |
| 151 | if not metric: |
| 152 | continue |
| 153 | spec = prices.get(metric) |
| 154 | if not isinstance(spec, dict): |
| 155 | if _num(summary.get("quantity")) > 0: |
| 156 | unpriced.append(metric) |
| 157 | continue |
| 158 | rated = rate_metric(summary.get("quantity"), spec) |
| 159 | if rated["amount_minor"] <= 0: |
| 160 | continue |
| 161 | lines.append({ |
| 162 | "metric": metric, |
| 163 | "quantity": str(rated["billable"]), |
| 164 | "included": str(rated["included"]), |
| 165 | "overage": str(rated["overage"]), |
| 166 | "unit_minor": (None if rated["unit_minor"] is None |
| 167 | else str(rated["unit_minor"])), |
| 168 | "amount_minor": rated["amount_minor"], |
| 169 | "tier_detail": rated["tier_detail"], |
| 170 | }) |
| 171 | total += rated["amount_minor"] |
| 172 | return {"lines": lines, "total_minor": total, "unpriced": unpriced} |
| 173 | |
| 174 | |
| 175 | def margin(revenue_minor: int, cost_minor: int) -> dict: |
| 176 | """What was earned against what it cost -- the question a billing |
| 177 | system that only knows revenue can never answer.""" |
| 178 | revenue = int(revenue_minor or 0) |
| 179 | cost = int(cost_minor or 0) |
| 180 | gross = revenue - cost |
| 181 | pct = None |
| 182 | if revenue: |
| 183 | pct = round((gross / revenue) * 100, 2) |
| 184 | return {"revenue_minor": revenue, "cost_minor": cost, |
| 185 | "gross_minor": gross, "gross_pct": pct} |
| 186 | |
| 187 | |
| 188 | # === wallet money reaching the books ========================================== |
| 189 | # |
| 190 | # The gap this closes: wallet_entries recorded every movement of customer |
| 191 | # money and NONE of it reached fin_journals. system_books (app-payments) |
| 192 | # composes journals for payments/refunds/invoices; nothing did the same |
| 193 | # for the prepaid wallet, so a box that charged real money showed zero |
| 194 | # revenue on the P&L and neither the cash nor the customer liability on |
| 195 | # the balance sheet. |
| 196 | # |
| 197 | # THE ACCOUNTING POINT, which is easy to get flatteringly wrong: **a |
| 198 | # top-up is not revenue.** Money taken before the service is rendered is |
| 199 | # money owed back -- a LIABILITY -- and it becomes revenue only when the |
| 200 | # work is done. Booking top-ups as revenue overstates income by |
| 201 | # everything sitting unspent in customer wallets and understates what is |
| 202 | # owed by the same amount. So the pair is: |
| 203 | # |
| 204 | # top-up DR cash CR customer funds (deferred, not earned) |
| 205 | # debit DR customer funds CR revenue (earned, now) |
| 206 | # |
| 207 | # Holds compose NOTHING, and that is doctrine rather than an omission: a |
| 208 | # hold is not a debit that got undone, it is money that was never spent. |
| 209 | # No economic event occurs when funds are ring-fenced inside the same |
| 210 | # liability, so no entry should exist -- and the reconciliation below |
| 211 | # knows to add outstanding holds back, which is the difference between a |
| 212 | # report that is right and a report that cries wolf whenever a run is in |
| 213 | # flight. |
| 214 | |
| 215 | WALLET_NO_ENTRY_KINDS = ("hold", "release") |
| 216 | |
| 217 | WALLET_ACCOUNT_KEYS = ( |
| 218 | "cash", "customer_funds", "revenue", "promo_expense", "adjustment", |
| 219 | ) |
| 220 | |
| 221 | |
| 222 | def wallet_posting(kind: Any, amount_minor: Any, accounts: dict) -> dict: |
| 223 | """Map one wallet entry to a DR/CR pair, or refuse with a reason. |
| 224 | |
| 225 | Pure: no I/O, no clock, no settings lookup -- the caller resolves |
| 226 | account ids and this decides the accounting. Returns either |
| 227 | {"skip": reason} or {"debit", "credit", "amount_minor"} with a |
| 228 | POSITIVE amount (the direction is carried by which account is which, |
| 229 | never by a sign, so a negative never reaches a journal line). |
| 230 | |
| 231 | `accounts` maps the WALLET_ACCOUNT_KEYS names to fin_accounts ids; |
| 232 | an unconfigured account is a skip, never a guess, because posting |
| 233 | real money to a plausible-looking account is worse than not posting. |
| 234 | """ |
| 235 | kind_text = str(kind or "").strip() |
| 236 | try: |
| 237 | amount = int(amount_minor) |
| 238 | except (TypeError, ValueError): |
| 239 | return {"skip": f"unusable amount {amount_minor!r}"} |
| 240 | |
| 241 | if kind_text in WALLET_NO_ENTRY_KINDS: |
| 242 | return {"skip": "a hold is money that was never spent, not a debit " |
| 243 | "that got undone -- ring-fencing funds inside the " |
| 244 | "same liability is not an economic event"} |
| 245 | if amount == 0: |
| 246 | return {"skip": "zero amount"} |
| 247 | |
| 248 | def resolved(*names): |
| 249 | missing = [n for n in names if not str(accounts.get(n) or "").strip()] |
| 250 | if missing: |
| 251 | return None, ("accounts unconfigured: " |
| 252 | + ", ".join(f"billing.journal.{n}_account" for n in missing)) |
| 253 | return [str(accounts[n]).strip() for n in names], None |
| 254 | |
| 255 | if kind_text in ("topup", "auto_topup"): |
| 256 | # Cash in, service owed. Deliberately NOT revenue. |
| 257 | got, why = resolved("cash", "customer_funds") |
| 258 | if why: |
| 259 | return {"skip": why} |
| 260 | cash, funds = got |
| 261 | if amount < 0: |
| 262 | # A negative top-up is a withdrawal: cash leaves, the debt shrinks. |
| 263 | return {"debit": funds, "credit": cash, "amount_minor": -amount} |
| 264 | return {"debit": cash, "credit": funds, "amount_minor": amount} |
| 265 | |
| 266 | if kind_text == "debit": |
| 267 | # The moment the service is rendered: the liability shrinks and |
| 268 | # the revenue is finally real. |
| 269 | got, why = resolved("customer_funds", "revenue") |
| 270 | if why: |
| 271 | return {"skip": why} |
| 272 | funds, revenue = got |
| 273 | if amount > 0: |
| 274 | return {"skip": "a positive debit is not a debit"} |
| 275 | return {"debit": funds, "credit": revenue, "amount_minor": -amount} |
| 276 | |
| 277 | if kind_text == "refund": |
| 278 | # Credit returned to the wallet un-earns revenue; it does not move |
| 279 | # cash, because the money never left the wallet in the first place. |
| 280 | got, why = resolved("customer_funds", "revenue") |
| 281 | if why: |
| 282 | return {"skip": why} |
| 283 | funds, revenue = got |
| 284 | if amount < 0: |
| 285 | return {"skip": "a negative refund is not a refund"} |
| 286 | return {"debit": revenue, "credit": funds, "amount_minor": amount} |
| 287 | |
| 288 | if kind_text == "promo": |
| 289 | # Credit we granted. It costs us even though no cash moved -- |
| 290 | # which is exactly why promotional credit belongs on the P&L |
| 291 | # rather than quietly inflating the liability from nowhere. |
| 292 | got, why = resolved("promo_expense", "customer_funds") |
| 293 | if why: |
| 294 | return {"skip": why} |
| 295 | expense, funds = got |
| 296 | if amount < 0: |
| 297 | return {"debit": funds, "credit": expense, "amount_minor": -amount} |
| 298 | return {"debit": expense, "credit": funds, "amount_minor": amount} |
| 299 | |
| 300 | if kind_text == "adjustment": |
| 301 | # Deliberately its own account rather than folded into revenue: |
| 302 | # an adjustment is somebody correcting something, and burying |
| 303 | # those in revenue is how a P&L stops being auditable. |
| 304 | got, why = resolved("adjustment", "customer_funds") |
| 305 | if why: |
| 306 | return {"skip": why} |
| 307 | adjust, funds = got |
| 308 | if amount < 0: |
| 309 | return {"debit": funds, "credit": adjust, "amount_minor": -amount} |
| 310 | return {"debit": adjust, "credit": funds, "amount_minor": amount} |
| 311 | |
| 312 | return {"skip": f"no accounting policy for wallet entry kind {kind_text!r}"} |
| 313 | |
| 314 | |
| 315 | def outstanding_holds_minor(entries) -> int: |
| 316 | """How much is ring-fenced right now, as a POSITIVE number. |
| 317 | |
| 318 | Holds are negative entries and releases positive ones, so a |
| 319 | hold that has been released cancels itself and only funds still in |
| 320 | flight survive the fold. |
| 321 | """ |
| 322 | total = 0 |
| 323 | for row in entries or []: |
| 324 | if str(row.get("kind") or "") not in WALLET_NO_ENTRY_KINDS: |
| 325 | continue |
| 326 | try: |
| 327 | total += int(row.get("amount_minor") or 0) |
| 328 | except (TypeError, ValueError): |
| 329 | continue |
| 330 | return -total |
| 331 | |
| 332 | |
| 333 | def customer_funds_reconciliation( |
| 334 | wallet_balances_minor, booked_debit_minor: int, booked_credit_minor: int, |
| 335 | *, outstanding_holds: int = 0, |
| 336 | ) -> dict: |
| 337 | """Does what customers are owed match what the books say we owe? |
| 338 | |
| 339 | The invariant that makes prepaid balances honest: sum every wallet, |
| 340 | add back what is merely ring-fenced, and it must equal the credit |
| 341 | balance of the customer-funds liability account. |
| 342 | |
| 343 | The holds term is what stops this being a false alarm generator. A |
| 344 | wallet with an open hold reports a balance BELOW what the customer is |
| 345 | actually owed -- the money is theirs until the run settles -- while |
| 346 | the books, correctly, composed nothing for the hold. Without adding |
| 347 | holds back, every reconciliation run during an in-flight template run |
| 348 | reports a discrepancy that is not one. |
| 349 | """ |
| 350 | held = sum(int(b or 0) for b in wallet_balances_minor or []) |
| 351 | owed = held + int(outstanding_holds or 0) |
| 352 | booked = int(booked_credit_minor or 0) - int(booked_debit_minor or 0) |
| 353 | difference = owed - booked |
| 354 | return { |
| 355 | "wallet_balances_minor": held, |
| 356 | "outstanding_holds_minor": int(outstanding_holds or 0), |
| 357 | "owed_to_customers_minor": owed, |
| 358 | "booked_liability_minor": booked, |
| 359 | "difference_minor": difference, |
| 360 | "balanced": difference == 0, |
| 361 | } |