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
billing_runner.py · 13.3 KB · 319 lines
| 1 | """system_billing_runner -- close periods, raise invoices, move the ladder. |
| 2 | |
| 3 | POST {today?, dry_run?} -- the daily pass that turns subscriptions into |
| 4 | money owed. Three jobs, in this order: |
| 5 | |
| 6 | 1. **Trials that ended** become active (or move on unpaid, below). |
| 7 | 2. **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. |
| 13 | 3. **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 | |
| 18 | What it deliberately does NOT do: cancel anything on its own beyond |
| 19 | suspension, prorate arithmetic inside a line (a plan change closes the |
| 20 | period early and opens a new one -- see the spec), or bill wallet-mode |
| 21 | subscriptions, which have no periodic invoice by definition; their money |
| 22 | moved when the usage did. |
| 23 | |
| 24 | Everything downstream is the machinery that already ships: the invoice |
| 25 | gets its portal token, its dunning schedule, its books entry when paid. |
| 26 | The biller's whole job is to decide that money is owed and say so once. |
| 27 | """ |
| 28 | |
| 29 | import json |
| 30 | import os |
| 31 | from datetime import date, timedelta |
| 32 | |
| 33 | import object_billing |
| 34 | import object_ids |
| 35 | import object_records |
| 36 | |
| 37 | ACTOR = "system_billing_runner" |
| 38 | |
| 39 | DEFAULT_GRACE_DAYS = 7 |
| 40 | DEFAULT_SUSPEND_AFTER_DAYS = 30 |
| 41 | |
| 42 | |
| 43 | def _base_dir(): |
| 44 | return os.environ.get("DBBASIC_DATA_DIR", "data") |
| 45 | |
| 46 | |
| 47 | def _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 | |
| 57 | def _int(value, default=0): |
| 58 | try: |
| 59 | return int(str(value or "").strip() or default) |
| 60 | except (TypeError, ValueError): |
| 61 | return default |
| 62 | |
| 63 | |
| 64 | def _truthy(value): |
| 65 | return str(value or "").strip().lower() in ("true", "1", "yes", "on") |
| 66 | |
| 67 | |
| 68 | def _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 | |
| 93 | def _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 | |
| 103 | def _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 | |
| 125 | def _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 | |
| 208 | def _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 | |
| 232 | def 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} |