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

0 downloads

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
billing_runner.py · 13.3 KB · 319 lines
1"""system_billing_runner -- close periods, raise invoices, move the ladder.
2
3POST {today?, dry_run?} -- the daily pass that turns subscriptions into
4money owed. Three jobs, in this order:
5
61. **Trials that ended** become active (or move on unpaid, below).
72. **Periods that closed** raise ONE invoice for the period just ended
8 and advance the subscription's dates. Idempotent by provenance:
9 generated_from = "subscriptions/{id}:{period_start}", so a biller that
10 runs twice, or is re-run after a crash, cannot double-bill. That
11 property is not a nicety -- double-billing is the failure customers
12 never forgive, and a dedup table would be one more thing to get wrong.
133. **Unpaid invoices age the subscription**: past due beyond a grace
14 window moves active -> past_due, and further silence -> suspended.
15 Paying restores service, because the ladder must be climbable in both
16 directions or a paying customer stays cut off.
17
18What it deliberately does NOT do: cancel anything on its own beyond
19suspension, prorate arithmetic inside a line (a plan change closes the
20period early and opens a new one -- see the spec), or bill wallet-mode
21subscriptions, which have no periodic invoice by definition; their money
22moved when the usage did.
23
24Everything downstream is the machinery that already ships: the invoice
25gets its portal token, its dunning schedule, its books entry when paid.
26The biller's whole job is to decide that money is owed and say so once.
27"""
28
29import json
30import os
31from datetime import date, timedelta
32
33import object_billing
34import object_ids
35import object_records
36
37ACTOR = "system_billing_runner"
38
39DEFAULT_GRACE_DAYS = 7
40DEFAULT_SUSPEND_AFTER_DAYS = 30
41
42
43def _base_dir():
44 return os.environ.get("DBBASIC_DATA_DIR", "data")
45
46
47def _setting(base, key, default):
48 try:
49 for row in object_records.read_collection_records("app_settings", base_dir=base):
50 if row.get("key") == key and str(row.get("value") or "").strip():
51 return row["value"].strip()
52 except Exception:
53 pass
54 return default
55
56
57def _int(value, default=0):
58 try:
59 return int(str(value or "").strip() or default)
60 except (TypeError, ValueError):
61 return default
62
63
64def _truthy(value):
65 return str(value or "").strip().lower() in ("true", "1", "yes", "on")
66
67
68def _advance(day_iso, period):
69 """Same day next month/year, clamped -- the 31st of a 30-day month
70 bills on the 30th rather than skipping a cycle."""
71 try:
72 y, m, d = (int(x) for x in str(day_iso)[:10].split("-"))
73 except (ValueError, AttributeError):
74 return ""
75 if period == "year":
76 for day in (d, 28):
77 try:
78 return date(y + 1, m, day).isoformat()
79 except ValueError:
80 continue
81 return ""
82 month = m + 1
83 year = y + (1 if month > 12 else 0)
84 month = 1 if month > 12 else month
85 for day in (d, 30, 29, 28):
86 try:
87 return date(year, month, day).isoformat()
88 except ValueError:
89 continue
90 return ""
91
92
93def _existing_invoice(base, marker):
94 try:
95 for row in object_records.read_collection_records("invoices", base_dir=base):
96 if row.get("notes") and marker in str(row.get("notes")):
97 return row
98 except Exception:
99 return True # cannot tell -> do not risk a second invoice
100 return None
101
102
103def _usage_lines(base, subscription, plan, period_start, period_end):
104 """Rated overage for the period, from SUMMARIES not raw events.
105
106 Allowances and tiers are properties of a period's total, so this can
107 only happen at close -- rating each event as it landed would charge
108 the first calls at retail and never apply the included quantity.
109 """
110 prices = object_billing.parse_prices(plan.get("prices"))
111 if not prices:
112 return [], 0, [], []
113 try:
114 rows = object_records.read_collection_records("usage_summaries", base_dir=base)
115 except Exception:
116 return [], 0, [], []
117 mine = [r for r in rows
118 if r.get("subscription_id") == subscription.get("id")
119 and str(r.get("period_start") or "")[:10] == period_start
120 and not _truthy(r.get("invoiced"))]
121 rated = object_billing.rate_period(mine, prices)
122 return rated["lines"], rated["total_minor"], rated["unpriced"], [r["id"] for r in mine]
123
124
125def _raise_invoice(base, subscription, plan, period_start, period_end, today):
126 """One invoice for the period that just ended: the base fee, plus any
127 rated usage overage."""
128 marker = f"subscriptions/{subscription['id']}:{period_start}"
129 existing = _existing_invoice(base, marker)
130 if existing:
131 return {"skipped": "already invoiced", "marker": marker}
132
133 base_minor = _int(plan.get("base_minor"))
134 usage_lines, usage_minor, unpriced, summary_ids = _usage_lines(
135 base, subscription, plan, period_start, period_end)
136 if base_minor <= 0 and usage_minor <= 0:
137 return {"skipped": "nothing to bill for this period",
138 **({"unpriced_metrics": unpriced} if unpriced else {})}
139 total_minor = base_minor + usage_minor
140
141 grace = _int(_setting(base, "billing.invoice_due_days", "14"), 14)
142 invoice_id = object_ids.new_uuid4()
143 number = f"SUB-{str(subscription['id'])[:8]}-{period_start[:7]}"
144 object_records.create_collection_record(
145 "invoices",
146 {
147 "id": invoice_id,
148 "number": number,
149 "customer_id": subscription.get("customer_id", ""),
150 "customer_name": subscription.get("customer_name") or "Customer",
151 "customer_email": subscription.get("customer_email", ""),
152 "status": "sent",
153 "issue_date": today,
154 "due_date": (date.fromisoformat(today) + timedelta(days=grace)).isoformat(),
155 "subtotal_cents": str(total_minor),
156 "total_cents": str(total_minor),
157 # Provenance lives in notes because invoices carry no
158 # generated_from column; the marker is what makes a re-run a
159 # no-op, so it must be written where it can be found again.
160 "notes": f"Generated by {ACTOR} [{marker}]",
161 "owner_id": subscription.get("owner_id", ""),
162 },
163 base_dir=base, actor=ACTOR)
164 try:
165 if base_minor > 0:
166 object_records.create_collection_record(
167 "invoice_lines",
168 {
169 "id": object_ids.new_uuid4(),
170 "invoice_id": invoice_id,
171 "description": f"{plan.get('name') or 'Subscription'} "
172 f"({period_start} to {period_end})",
173 "quantity": "1",
174 "unit_price_cents": str(base_minor),
175 "line_total_cents": str(base_minor),
176 "owner_id": subscription.get("owner_id", ""),
177 },
178 base_dir=base, actor=ACTOR)
179 for line in usage_lines:
180 # The line says what was used, what the plan included, and what
181 # the overage cost -- a bill a customer can check rather than
182 # a single opaque "usage" figure they can only dispute.
183 object_records.create_collection_record(
184 "invoice_lines",
185 {
186 "id": object_ids.new_uuid4(),
187 "invoice_id": invoice_id,
188 "description": (f"{line['metric']}: {line['quantity']} used, "
189 f"{line['included']} included, "
190 f"{line['overage']} billable"),
191 "quantity": str(line["overage"]),
192 "unit_price_cents": str(line["unit_minor"] or 0),
193 "line_total_cents": str(line["amount_minor"]),
194 "owner_id": subscription.get("owner_id", ""),
195 },
196 base_dir=base, actor=ACTOR)
197 for summary_id in summary_ids:
198 object_records.update_collection_record(
199 "usage_summaries", summary_id, {"invoiced": "true"},
200 base_dir=base, actor=ACTOR)
201 except Exception as exc:
202 return {"invoice_id": invoice_id, "warning": f"line not written: {str(exc)[:100]}"}
203 return {"invoice_id": invoice_id, "number": number, "amount_minor": total_minor,
204 "base_minor": base_minor, "usage_minor": usage_minor,
205 **({"unpriced_metrics": unpriced} if unpriced else {})}
206
207
208def _unpaid_days(base, subscription, today):
209 """Days past due of the oldest unpaid invoice for this subscriber."""
210 worst = 0
211 marker = f"subscriptions/{subscription['id']}:"
212 try:
213 rows = object_records.read_collection_records("invoices", base_dir=base)
214 except Exception:
215 return 0
216 for row in rows:
217 if marker not in str(row.get("notes") or ""):
218 continue
219 if row.get("status") in ("paid", "void"):
220 continue
221 due = str(row.get("due_date") or "")[:10]
222 if not due or due >= today:
223 continue
224 try:
225 days = (date.fromisoformat(today) - date.fromisoformat(due)).days
226 except ValueError:
227 continue
228 worst = max(worst, days)
229 return worst
230
231
232def POST(request):
233 base = _base_dir()
234 today = str(request.get("today") or date.today().isoformat())
235 dry_run = _truthy(request.get("dry_run"))
236
237 try:
238 subscriptions = object_records.read_collection_records("subscriptions", base_dir=base)
239 except Exception:
240 return {"ok": True, "skipped": "billing not installed (subscriptions absent)"}
241 try:
242 plans = {p["id"]: p for p in
243 object_records.read_collection_records("billing_plans", base_dir=base)}
244 except Exception:
245 plans = {}
246
247 grace = _int(_setting(base, "billing.past_due_grace_days", DEFAULT_GRACE_DAYS),
248 DEFAULT_GRACE_DAYS)
249 suspend_after = _int(_setting(base, "billing.suspend_after_days",
250 DEFAULT_SUSPEND_AFTER_DAYS), DEFAULT_SUSPEND_AFTER_DAYS)
251
252 invoiced = advanced = laddered = 0
253 results = []
254 for sub in subscriptions:
255 sub_id = sub.get("id")
256 status = sub.get("status") or "trialing"
257 if status == "canceled":
258 continue
259 plan = plans.get(sub.get("plan_id")) or {}
260 mode = sub.get("billing_mode") or "subscription"
261
262 # 1. trial expiry
263 trial_end = str(sub.get("trial_ends_on") or "")[:10]
264 if status == "trialing" and trial_end and trial_end <= today:
265 if not dry_run:
266 object_records.update_collection_record(
267 "subscriptions", sub_id, {"status": "active"},
268 base_dir=base, actor=ACTOR)
269 status = "active"
270 laddered += 1
271 results.append({"subscription": sub_id, "trial_ended": trial_end})
272
273 # 2. close the period -- wallet mode never gets a periodic invoice,
274 # because its money already moved when the usage did.
275 period_end = str(sub.get("current_period_end") or "")[:10]
276 if (mode in ("subscription", "hybrid") and status in ("active", "past_due")
277 and period_end and period_end <= today):
278 period_start = str(sub.get("current_period_start") or "")[:10] or period_end
279 if dry_run:
280 results.append({"subscription": sub_id, "would_invoice_period": period_start})
281 else:
282 outcome = _raise_invoice(base, sub, plan, period_start, period_end, today)
283 results.append({"subscription": sub_id, **outcome})
284 if outcome.get("invoice_id"):
285 invoiced += 1
286 next_end = _advance(period_end, plan.get("period") or "month")
287 if next_end:
288 object_records.update_collection_record(
289 "subscriptions", sub_id,
290 {"current_period_start": period_end,
291 "current_period_end": next_end},
292 base_dir=base, actor=ACTOR)
293 advanced += 1
294 if _truthy(sub.get("cancel_at_period_end")):
295 object_records.update_collection_record(
296 "subscriptions", sub_id, {"status": "canceled"},
297 base_dir=base, actor=ACTOR)
298 results.append({"subscription": sub_id,
299 "canceled": "at period end, as requested"})
300 continue
301
302 # 3. the ladder: unpaid invoices age the subscription
303 overdue_days = _unpaid_days(base, sub, today)
304 if not dry_run and overdue_days:
305 if status == "active" and overdue_days > grace:
306 object_records.update_collection_record(
307 "subscriptions", sub_id, {"status": "past_due"},
308 base_dir=base, actor=ACTOR)
309 laddered += 1
310 results.append({"subscription": sub_id, "past_due_after_days": overdue_days})
311 elif status == "past_due" and overdue_days > suspend_after:
312 object_records.update_collection_record(
313 "subscriptions", sub_id, {"status": "suspended"},
314 base_dir=base, actor=ACTOR)
315 laddered += 1
316 results.append({"subscription": sub_id, "suspended_after_days": overdue_days})
317
318 return {"ok": True, "today": today, "invoiced": invoiced, "advanced": advanced,
319 "status_moves": laddered, "results": results}