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
dbbasic-package.json · 8.6 KB · 141 lines
1{
2 "id": "app-billing",
3 "name": "Billing",
4 "version": "0.7.0",
5 "description": "Prepaid wallets and the ledger that IS their balance. The predecessor kept a mutable Wallet.balance column beside a Transaction table -- two truths that drift, and when they drift the customer is right and you cannot prove otherwise; here wallets.balance_minor is a ROLLUP over append-only wallet_entries, so the entries are the balance and nothing may write the number (docs/logic-decisions.md #3). Amounts are integer minor units (object_money.py), so a wallet holds dollars or satoshis or a gift-card unit without special cases. hook_wallet_entries gates debits by summing the ENTRIES rather than trusting the rollup -- a gate must be authoritative, and it documents the known check-then-append race honestly rather than pretending a reserve/capture system exists. system_wallet_replenish tops up from a saved card off-session, with the safeguard the predecessor also carried and most systems skip: a MONTHLY CAP, because autopay plus one runaway metering bug is a four-figure surprise, and a cap of zero (the default) means auto top-up is simply off. Declines -- especially the authentication-required kind an off-session charge cannot satisfy -- are reported for a human to act on, never retried in a loop that gets a processor account flagged. Plans, subscriptions and the period biller are the next slice; this one is the money container they will draw on. 0.2.0 adds the recurring half: billing_plans is a price book that VERSIONS FORWARD (an invoice must forever show the price it was billed under, so a change is a new row, never a rewrite of history customers already paid against), subscriptions carry billing_mode explicitly (wallet | subscription | hybrid -- guessing the mode from whether a plan has a base price breaks the moment someone sells a zero-base plan with a real contract), and system_billing_runner closes periods into invoices. Double-billing is the failure customers never forgive, so the runner is idempotent by provenance rather than by a dedup table: a marker on the invoice means a re-run after a crash raises nothing. The status ladder climbs BOTH ways -- paying restores service, because a ladder that only descends leaves a paying customer cut off -- and cancel-at-period-end runs service to the end of the paid period rather than billing someone for time they cannot use. 0.3.0 completes the metering half: usage_events (append, caller-supplied event_id deduped by hook -- retries are metering's number one corruption source and a timed-out client must not be billed twice), system_usage_rollup folding them into usage_summaries, and rating at period close via object_billing. Rating reads SUMMARIES, never raw events: allowances and tiers are properties of a period's total, so per-event rating charges the first calls at retail and never applies the included quantity -- and the bucket boundary means metering can start batching later without touching one line of pricing. Usage lines say what was used, what the plan included and what the overage cost, so a customer can CHECK a bill rather than only dispute it. A metric with usage but no price is charged nothing and REPORTED, because silently billing for something the plan never named is worse than the revenue, while silently dropping it hides a pricing gap. Events stamp our own cost, so margin per customer per metric is a fold rather than a spreadsheet. 0.5.0 says out loud what this container already was: A GIFT CARD IS A WALLET, and store credit is the same thing issued by a refund or a dispute rather than bought. Both are prepaid money somebody can spend here, both need a movement log rather than a mutable number, and both need a gate that refuses to let anybody spend what is not there -- which is exactly this collection and hook_wallet_entries. Building a gift_cards table with its own balance column beside them would be reconstructing the predecessor's drift bug in a corner nobody watches, for money that arrives as a bearer instrument and is therefore the least forgiving place to be wrong. So the slice is two fields and no new machinery: wallets.kind (balance | gift_card | store_credit) and wallets.code, the bearer token a card is redeemed by, unique when present and compared upper-cased. Uniqueness lives in hook_wallets because schemas here carry no uniqueness constraint, and it fails CLOSED on an unreadable list: a refused card is reissued in ten seconds, a duplicated one is discovered when somebody's balance is gone. system_gift_card_issue is the fulfilment half -- buying a card is an ORDINARY PRODUCT SALE (products.is_gift_card marks the catalogue row) whose fulfilment credits a wallet instead of putting something in a box, one wallet per LINE because three cards on one order are three presents for three people, waiting for the invoice to be SETTLED because a card is money, and idempotent by a generated_from marker per order line because a replayed payment that issued a second card is the shop giving away money. Redemption is nobody's new code: action_checkout debits the wallet through the EXISTING hook_wallet_entries gate, asked in process because trusted server-side writes bypass hooks by design, so a card cannot overdraw and a preview writes nothing. action_resolve_dispute already wrote store credit into this same ledger; the only thing v2 adds to that path is a name for what it was doing.",
6 "compatibility": {
7 "dbbasic_object_server": ">=0.1.0"
8 },
9 "dependencies": [
10 "app-finance",
11 "app-payments",
12 "app-invoices"
13 ],
14 "objects": [
15 {
16 "id": "hook_wallet_entries",
17 "path": "objects/hook/wallet_entries.py"
18 },
19 {
20 "id": "hook_wallets",
21 "path": "objects/hook/wallets.py"
22 },
23 {
24 "id": "system_wallet_replenish",
25 "path": "objects/system/wallet_replenish.py"
26 },
27 {
28 "id": "system_billing_runner",
29 "path": "objects/system/billing_runner.py"
30 },
31 {
32 "id": "hook_usage_events",
33 "path": "objects/hook/usage_events.py"
34 },
35 {
36 "id": "system_usage_rollup",
37 "path": "objects/system/usage_rollup.py"
38 },
39 {
40 "id": "system_gift_card_issue",
41 "path": "objects/system/gift_card_issue.py"
42 },
43 {
44 "id": "system_wallet_books",
45 "path": "objects/system/wallet_books.py"
46 },
47 {
48 "id": "site_customer_funds",
49 "path": "objects/site/customer_funds.py"
50 }
51 ],
52 "schemas": [
53 {
54 "collection": "wallets",
55 "path": "schemas/wallets.json"
56 },
57 {
58 "collection": "wallet_entries",
59 "path": "schemas/wallet_entries.json"
60 },
61 {
62 "collection": "billing_plans",
63 "path": "schemas/billing_plans.json"
64 },
65 {
66 "collection": "subscriptions",
67 "path": "schemas/subscriptions.json"
68 },
69 {
70 "collection": "usage_events",
71 "path": "schemas/usage_events.json"
72 },
73 {
74 "collection": "usage_summaries",
75 "path": "schemas/usage_summaries.json"
76 }
77 ],
78 "permissions": [
79 {
80 "path": "permissions/rules.json"
81 }
82 ],
83 "seed": [
84 {
85 "collection": "wallets",
86 "path": "seed/wallets.tsv"
87 },
88 {
89 "collection": "wallet_entries",
90 "path": "seed/wallet_entries.tsv"
91 },
92 {
93 "collection": "billing_plans",
94 "path": "seed/billing_plans.tsv"
95 },
96 {
97 "collection": "subscriptions",
98 "path": "seed/subscriptions.tsv"
99 },
100 {
101 "collection": "usage_events",
102 "path": "seed/usage_events.tsv"
103 },
104 {
105 "collection": "usage_summaries",
106 "path": "seed/usage_summaries.tsv"
107 }
108 ],
109 "migrations": [],
110 "schedules": [
111 {
112 "id": "billing_usage_rollup_daily",
113 "object_id": "system_usage_rollup",
114 "schedule": "10 7 * * *",
115 "description": "Fold usage events into period summaries. Runs BEFORE the biller so a period that closes today is rated against usage that has already been folded."
116 },
117 {
118 "id": "billing_runner_daily",
119 "object_id": "system_billing_runner",
120 "schedule": "25 7 * * *",
121 "description": "Close periods that ended, raise one invoice each, and walk the unpaid ladder. Idempotent by provenance, so a missed day is caught up rather than double-billed."
122 },
123 {
124 "id": "wallet_replenish_daily",
125 "object_id": "system_wallet_replenish",
126 "schedule": "40 7 * * *",
127 "description": "Top up wallets that fell below their threshold, within the monthly cap."
128 }
129 ],
130 "nav": [
131 {
132 "id": "customer_funds",
133 "label": "Customer Funds",
134 "path": "/customer-funds",
135 "blurb": "What customers are owed, checked against what the books say we owe",
136 "surface": "member",
137 "group": "Money",
138 "order": 345
139 }
140 ]
141}