@substrat-run/engine-invoicing 0.1.0 → 0.1.1

package/README.md

@@ -0,0 +1,65 @@
+# @substrat-run/engine-invoicing
+
+Invoicing engine for [Substrat](https://github.com/substrat-run/substrat) —
+accumulates **invoice bases** (Swedish: *fakturaunderlag*) from billable events and
+makes them **immutable once exported**.
+
+It produces the *basis* for an invoice: per-customer collections of billable lines
+with frozen prices and provenance, ready to hand to whatever actually issues invoices
+(typically an accounting connector). It is **not** a ledger, not accounts receivable,
+not payment tracking.
+
+**Full documentation: https://substrat.ahlstrand.es/engines/invoicing**
+
+## Snapshot, not join
+
+The engine consumes `workorder.completed` with **zero imports** from the work-order
+engine — star topology. The consumer parses its own Zod view of the event payload,
+finds or creates the open underlag for that customer, and copies the billable lines
+with provenance (`source_type`, `source_id`):
+
+```ts
+events: {
+  consumes: [{ type: 'workorder.completed', schemaVersion: 1 }],
+}
+```
+
+Prices are frozen from the payload at the moment the work order completed. If the
+vertical's price list changes tomorrow, yesterday's underlag doesn't. Consumers are
+delivered at-least-once; find-or-create plus the kernel's delivery journal keep the
+handler idempotent.
+
+## The immutability invariant
+
+An underlag is `open` or `exported`:
+
+- While **open**, consumed events append lines.
+- **`invoicing/export`** flips it to `exported` — from then on it is immutable.
+  Nothing appends, nothing edits, exporting again throws.
+- Billable work arriving *after* export opens a **new** underlag. History is never
+  rewritten; late facts become new facts.
+
+`invoicing.underlag-exported` is the natural hook for an accounting connector that
+turns the frozen basis into a real invoice.
+
+## Operations
+
+| Operation | Permission | Does |
+|---|---|---|
+| `invoicing/list` | `invoicing:read` | list underlag, each with computed total |
+| `invoicing/get` | `invoicing:read` | one underlag with all lines and total |
+| `invoicing/export` | `invoicing:export` | flip to `exported` — the point of no return |
+
+Totals use exact decimal arithmetic from
+[`@substrat-run/contracts`](https://npmjs.com/package/@substrat-run/contracts), never floats.
+
+## Related packages
+
+- [`@substrat-run/kernel`](https://npmjs.com/package/@substrat-run/kernel) — the
+  scope-host contract these operations run on
+- [`@substrat-run/engine-workorder`](https://npmjs.com/package/@substrat-run/engine-workorder) —
+  the producer of the billable events this engine consumes
+
+## Status
+
+Pre-release (0.x): surfaces change without notice until the first vertical ships.

package/dist/index.d.ts

@@ -35,6 +35,12 @@ export declare const invoicingManifest: {
         entityType: string;
         parentType: string;
     }[] | undefined;
+    guards?: {
+        before: string;
+        predicate: string;
+        config: Record<string, unknown>;
+    }[] | undefined;
+    withdraws?: string[] | undefined;
     api?: string | undefined;
     searchables?: {
         entityType: string;

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAQxB,OAAO,EAIL,KAAK,kBAAkB,EAGxB,MAAM,sBAAsB,CAAC;AAS9B,eAAO,MAAM,cAAc;;;CAG1B,CAAC;AAEF,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAyNM,CAAC;;;;;WAKT,CAAC;;;;gBAIhB,CAAC;;mBAImC,CAAC;;;;eAIjC,CAAC;;;;;sBAK4B,CAAC;;;;;;CAxN7C,CAAC;AAEH,eAAO,MAAM,mBAAmB;;;GA6B/B,CAAC;AAuBF,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,GAAG,UAAU,CAAC;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,iBAAiB,EAAE,MAAM,CAAC;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,UAAU,EAAE,MAAM,CAAC;CACpB;AAkID,eAAO,MAAM,eAAe,EAAE,kBAW7B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAQxB,OAAO,EAIL,KAAK,kBAAkB,EAGxB,MAAM,sBAAsB,CAAC;AAS9B,eAAO,MAAM,cAAc;;;CAG1B,CAAC;AAEF,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAkPyb,CAAC;;;;;WAAyJ,CAAC;;;;gBAAkI,CAAC;;mBAAkE,CAAC;;;;eAAsG,CAAC;;;;;sBAAuK,CAAC;;;;;;CA3NrkC,CAAC;AAEH,eAAO,MAAM,mBAAmB;;;GA6B/B,CAAC;AAuBF,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,GAAG,UAAU,CAAC;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,iBAAiB,EAAE,MAAM,CAAC;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,UAAU,EAAE,MAAM,CAAC;CACpB;AAkID,eAAO,MAAM,eAAe,EAAE,kBAW7B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@substrat-run/engine-invoicing",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Substrat engine: fakturaunderlag — consumes billable events, snapshots lines with provenance, immutable once exported",
   "license": "AGPL-3.0-only",
   "repository": {
@@ -26,8 +26,8 @@
   },
   "dependencies": {
     "zod": "^3.25.0",
-    "@substrat-run/kernel": "^0.1.0",
-    "@substrat-run/contracts": "^0.1.0"
+    "@substrat-run/contracts": "^0.2.0",
+    "@substrat-run/kernel": "^0.2.0"
   },
   "devDependencies": {
     "typescript": "^5.6.0"