Runs live, versioned Python application objects on one VM, with a suite of apps: projects, notes, tasks, files and more.

0 downloads

dbbasic-object-server/object_billing.py
Download zip
Clone
Clone with git
git clone https://gitstable.com/git/askrobots/dbbasic-object-server.git
HTTPS
https://gitstable.com/git/askrobots/dbbasic-object-server.git
SSH
ssh://git@gitstable.com:2222/askrobots/dbbasic-object-server.git

Cloning needs no sign-in. Pushing over HTTPS asks for your username and an access token. SSH needs your key under SSH keys.

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
3The pure half of metered billing, kept out of the runner so it can be
4tested exhaustively without a data directory -- same posture as
5object_finance's folds and object_money's conversions.
6
7Three rules shape everything here, and each exists because of a way real
8vendors get bills wrong:
9
10**Rate at period close, never per event.** Allowances and tiers are
11properties of a PERIOD's total, not of an individual call. Rating each
12event as it lands means the first thousand calls get charged at the
13retail rate and the allowance never applies, which is precisely how
14customers end up disputing invoices they cannot reconstruct.
15
16**Rate from summaries, never from raw events.** A summary is a period
17bucket; a month of per-request rows is not something a bill should be
18re-derived from every time someone opens a page. This boundary is also
19the scale valve: the write side can change (batching, an accumulator)
20without touching a single line of pricing logic.
21
22**Stamp what it cost US alongside what we charge.** usage_events carry a
23cost, so margin is a fold over stored facts rather than a spreadsheet
24someone maintains separately. A billing system that knows revenue but not
25cost cannot answer "which customer loses us money", which is the first
26question anyone asks once the AI bills arrive.
27
28Integer minor units throughout; Decimal only where a rate multiplication
29needs it, and rounding is stated at the point it happens.
30"""
31
32from __future__ import annotations
33
34import json
35from decimal import Decimal, InvalidOperation, ROUND_HALF_UP
36from typing import Any
37
38
39def 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
66def _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
73def 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
137def 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
175def 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
215WALLET_NO_ENTRY_KINDS = ("hold", "release")
216
217WALLET_ACCOUNT_KEYS = (
218 "cash", "customer_funds", "revenue", "promo_expense", "adjustment",
219)
220
221
222def 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
315def 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
333def 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 }