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
usage_events.json · 3.2 KB · 35 lines
| 1 | { |
| 2 | "name": "usage_events", |
| 3 | "title": "Usage Events", |
| 4 | "version": 1, |
| 5 | "storage": "append", |
| 6 | "description": "One measured thing happened: tokens consumed, a task run, a gigabyte-hour held. Append-only, because a bill must be reconstructable from the facts that produced it -- a customer disputing an invoice is entitled to the line items behind it, and a mutable usage table cannot answer that. event_id is a CALLER-supplied idempotency key and the most important field here: retries are the number one corruption source in metering, and a client that resends after a timeout must not be charged twice for one call. cost_minor stamps what the usage cost US at the moment it happened, which is what makes margin a fold over stored facts instead of a spreadsheet somebody maintains separately -- a billing system that knows revenue but not cost cannot answer which customer loses money. Rating never reads this collection: it reads the period summaries folded from it (object_billing), which is the boundary that lets the write side change later without touching pricing.", |
| 7 | "hooks": {"before_write": "hook_usage_events"}, |
| 8 | "fields": [ |
| 9 | {"name": "id"}, |
| 10 | {"name": "event_id", "type": "text", "required": true, "label": "Event Key", |
| 11 | "help": "Caller-supplied idempotency key, unique per owner. Resending the same key records nothing -- a timeout retry must never bill twice."}, |
| 12 | {"name": "subscription_id", "label": "Subscription", |
| 13 | "relation": {"collection": "subscriptions", "display_field": "customer_name"}}, |
| 14 | {"name": "metric", "type": "text", "required": true, "label": "Metric", |
| 15 | "help": "What was measured, matching a key in the plan's prices (ai.tokens, storage.gb_hours, tasks.run)."}, |
| 16 | {"name": "quantity", "type": "number", "required": true, "label": "Quantity", |
| 17 | "help": "How much. A count or measure, not money -- may be fractional (gigabyte-hours), and read with Decimal wherever it is summed."}, |
| 18 | {"name": "unit", "type": "text", "label": "Unit", |
| 19 | "help": "What the quantity counts (tokens, gb_hours, requests). Documentation for humans; the metric name is what pricing matches on."}, |
| 20 | {"name": "cost_minor", "type": "integer", "default": "0", "label": "Our Cost", |
| 21 | "help": "What this usage cost the business, stamped at the moment it happened under the vendor price THEN -- later price changes must not restate history."}, |
| 22 | {"name": "occurred_at", "type": "datetime", "label": "Occurred"}, |
| 23 | {"name": "reference", "type": "text", "label": "Reference", |
| 24 | "help": "The task, request or object that caused it, so a line on a bill can be traced to the work."}, |
| 25 | {"name": "rated", "type": "boolean", "default": "false", "label": "Rated", |
| 26 | "help": "Set once folded into a period summary."}, |
| 27 | {"name": "owner_id", "type": "text", "label": "Owner"}, |
| 28 | {"name": "created_at", "type": "datetime", "read_only": true, "label": "Recorded"} |
| 29 | ], |
| 30 | "search": {"fields": ["metric", "reference"]}, |
| 31 | "forms": {"default": {"fields": ["subscription_id", "metric", "quantity", "unit", "reference"]}}, |
| 32 | "views": {"list_mode": "table", |
| 33 | "list_fields": ["occurred_at", "metric", "quantity", "cost_minor", "rated"], |
| 34 | "filter_fields": ["metric", "rated", "subscription_id"]} |
| 35 | } |