Add NATS account-balance SoT and statement review for customers, CS, and sales

Internal billing now uses verae.billing.* request-reply and pubs. zappier-account-balance tracks prepaid, credits, usage, and payments. Portal, admin, CS, and sales all review the same statement. Independent Forgejo repos stay split via push-module-repos.
2026-09-11 15:35:37 -04:00 · 2026-09-11 15:35:37 -04:00 · ac38676645
commit ac38676645
parent a1a5b957fd
135 changed files with 3078 additions and 130 deletions
--- a/docs/modules/README.md
+++ b/docs/modules/README.md
@ -2,6 +2,7 @@

 One MD file per source module.

+- [zappier/accounting-export](zappier/accounting-export.md)
 - [zappier/accounts](zappier/accounts.md)
 - [zappier/admin-users](zappier/admin-users.md)
 - [zappier/admin](zappier/admin.md)
@ -10,6 +11,8 @@ One MD file per source module.
 - [zappier/billing/credit](zappier/billing/credit.md)
 - [zappier/billing/reload](zappier/billing/reload.md)
 - [zappier/billing/stripe](zappier/billing/stripe.md)
+- [zappier/billing-nats](zappier/billing-nats.md)
+- [zappier/credits](zappier/credits.md)
 - [zappier/db/admin-user-repo](zappier/db/admin-user-repo.md)
 - [zappier/db/billing-repo](zappier/db/billing-repo.md)
 - [zappier/db/customer-repo](zappier/db/customer-repo.md)
@ -21,10 +24,13 @@ One MD file per source module.
 - [zappier/invoicing](zappier/invoicing.md)
 - [zappier/jobs/report-usage](zappier/jobs/report-usage.md)
 - [zappier/meter](zappier/meter.md)
+- [zappier/nats-shim.d](zappier/nats-shim.d.md)
 - [zappier/paths](zappier/paths.md)
 - [zappier/portal](zappier/portal.md)
 - [zappier/pricing](zappier/pricing.md)
 - [zappier/reports](zappier/reports.md)
+- [zappier/statement](zappier/statement.md)
+- [zappier/upstream](zappier/upstream.md)
 - [zappier/usage](zappier/usage.md)
 - [verae-zapier-middleware/app](verae-zapier-middleware/app.md)
 - [verae-zapier-middleware/clients/veraeClient](verae-zapier-middleware/clients/veraeClient.md)
@ -111,3 +117,12 @@ One MD file per source module.
 - [verae-zapier-simulator/pipeline](verae-zapier-simulator/pipeline.md)
 - [verae-zapier-simulator/server](verae-zapier-simulator/server.md)
 - [verae-zapier-simulator/trace](verae-zapier-simulator/trace.md)
+- [zappier-account-balance/books](zappier-account-balance/books.md)
+- [zappier-account-balance/server](zappier-account-balance/server.md)
+- [zappier-account-balance/subjects](zappier-account-balance/subjects.md)
+- [zappier-customer-service/nats-billing](zappier-customer-service/nats-billing.md)
+- [zappier-customer-service/server](zappier-customer-service/server.md)
+- [zappier-sales-pricing/nats-billing](zappier-sales-pricing/nats-billing.md)
+- [zappier-sales-pricing/server](zappier-sales-pricing/server.md)
+- [zappier-accounting-export/nats-billing](zappier-accounting-export/nats-billing.md)
+- [zappier-accounting-export/server](zappier-accounting-export/server.md)
--- a/docs/modules/verae-fleet/supervisor.md
+++ b/docs/modules/verae-fleet/supervisor.md
@ -2,7 +2,7 @@

 **Package:** `verae-fleet`  
 **Source:** `packages/verae-fleet/src/supervisor.js`  
-**Lines:** 511
+**Lines:** 528

 ## What this module is

@ -10,7 +10,7 @@ Implementation module in `verae-fleet`. The tables below are extracted from the

 ## Exports

-`Supervisor`
+`spawnLocal`, `Supervisor`

 ## Types / interfaces / classes

@ -22,6 +22,7 @@ Implementation module in `verae-fleet`. The tables below are extracted from the

 | Name | Parameters | Param types (JSDoc) | Returns | Calls (same file / helpers) |
 |------|------------|---------------------|---------|-----------------------------|
+| `spawnLocal` | `root, spec, env, healthPort` | — | `unknown` | see Call graph |
 | `waitExit` | `child, ms` | — | `unknown` | see Call graph |
 | `waitForHealth` | `rec, ms` | — | `unknown` | see Call graph |

@ -70,7 +71,7 @@ Implementation module in `verae-fleet`. The tables below are extracted from the

 ## Call graph (identifiers invoked)

-`floor`, `join`, `dirname`, `fileURLToPath`, `constructor`, `loadFleet`, `mkdirSync`, `isArray`, `machines`, `addMachine`, `upsertMachine`, `saveOverlay`, `log`, `setMachineEnabled`, `find`, `checkMachine`, `sshCheck`, `httpProbe`, `machineOf`, `controlInstance`, `sshHttp`, `postControl`, `toISOString`, `push`, `splice`, `spec`, `nextIndex`, `values`, `filter`, `map`, `has`, `startOne`, `get`, `pickMachine`, `sshSpawnWorker`, `spawn`, `now`, `on`, `set`, `waitForHealth`, `stopInstance`, `sshKillWorker`, `kill`, `waitExit`, `delete`, `reconcile`, `pauseInstance`, `resumeInstance`, `restartInstance`, `markUnhealthy`, `probe`, `isFinite`, `summarizeRtt`, `available`, `keys`, `min`, `startService`, `stopService`, `pauseService`, `resumeService`
+`floor`, `join`, `dirname`, `fileURLToPath`, `apps`, `spawnLocal`, `resolve`, `spawn`, `constructor`, `loadFleet`, `mkdirSync`, `isArray`, `machines`, `addMachine`, `upsertMachine`, `saveOverlay`, `log`, `setMachineEnabled`, `find`, `checkMachine`, `sshCheck`, `httpProbe`, `machineOf`, `controlInstance`, `sshHttp`, `postControl`, `toISOString`, `push`, `splice`, `spec`, `nextIndex`, `values`, `filter`, `map`, `has`, `startOne`, `get`, `pickMachine`, `sshSpawnWorker`, `now`, `on`, `set`, `waitForHealth`, `stopInstance`, `sshKillWorker`, `kill`, `waitExit`, `delete`, `reconcile`, `pauseInstance`, `resumeInstance`, `restartInstance`, `markUnhealthy`, `probe`, `isFinite`, `summarizeRtt`, `available`, `keys`, `min`, `startService`

 Each identifier is a call site in this file. Follow the import list to see the defining module; open that module’s MD for parameter and return types.

--- a/docs/modules/zappier-account-balance/books.md
+++ b/docs/modules/zappier-account-balance/books.md
@ -0,0 +1,54 @@
+# `zappier-account-balance/books`
+
+**Package:** `zappier-account-balance`  
+**Source:** `packages/zappier-account-balance/src/books.js`  
+**Lines:** 90
+
+## What this module is
+
+Implementation module in `zappier-account-balance`. The tables below are extracted from the source (signatures + JSDoc).
+
+## Exports
+
+`AccountBooks`, `handle`
+
+## Types / interfaces / classes
+
+| Kind | Name |
+|------|------|
+| class | `AccountBooks` |
+
+## Functions
+
+| Name | Parameters | Param types (JSDoc) | Returns | Calls (same file / helpers) |
+|------|------------|---------------------|---------|-----------------------------|
+| `handle` | `subject, payload, books` | — | `unknown` | see Call graph |
+| `match` | `rows` | — | `unknown` | see Call graph |
+
+## Methods (class / object)
+
+| Name | Parameters |
+|------|------------|
+| `constructor` | `(none)` |
+| `prepaidCents` | `customerId` |
+| `adjust` | `{ customerId, cents, reason, agent, kind = 'credit' }` |
+| `recordUsage` | `entry` |
+| `recordPayment` | `entry` |
+| `statement` | `customerId` |
+
+## What it imports / requires
+
+_No imports detected._
+
+## Call graph (identifiers invoked)
+
+`constructor`, `prepaidCents`, `adjust`, `trunc`, `now`, `toString`, `random`, `slice`, `toISOString`, `unshift`, `recordUsage`, `recordPayment`, `statement`, `filter`, `match`, `handle`, `endsWith`
+
+Each identifier is a call site in this file. Follow the import list to see the defining module; open that module’s MD for parameter and return types.
+
+## Return values (how to read this)
+
+- HTTP route handlers return Express `res.json(...)` bodies (see route docs).
+- Zapier `perform` functions return a **single object** (creates) or an **array** (triggers/searches).
+- Pricing functions return integer **cents** on `Quote.totalCents`.
+
--- a/docs/modules/zappier-account-balance/server.md
+++ b/docs/modules/zappier-account-balance/server.md
@ -0,0 +1,53 @@
+# `zappier-account-balance/server`
+
+**Package:** `zappier-account-balance`  
+**Source:** `packages/zappier-account-balance/src/server.js`  
+**Lines:** 93
+
+## What this module is
+
+Implementation module in `zappier-account-balance`. The tables below are extracted from the source (signatures + JSDoc).
+
+## Exports
+
+_No named `export` / `module.exports` keys detected._
+
+## Types / interfaces / classes
+
+_None extracted._
+
+## Functions
+
+| Name | Parameters | Param types (JSDoc) | Returns | Calls (same file / helpers) |
+|------|------------|---------------------|---------|-----------------------------|
+| `startNats` | `(none)` | — | `unknown` | see Call graph |
+| `readBody` | `req` | — | `unknown` | see Call graph |
+| `reply` | `sub, fn` | — | `unknown` | see Call graph |
+| `json` | `code, obj` | — | `unknown` | see Call graph |
+
+## Methods (class / object)
+
+| Name | Parameters |
+|------|------------|
+| `reply` | `nc.subscribe(SUBJECTS.STATEMENT_GET, { queue: SUBJECTS.QUEUE }` |
+| `reply` | `nc.subscribe(SUBJECTS.BALANCE_GET, { queue: SUBJECTS.QUEUE }` |
+| `reply` | `nc.subscribe(SUBJECTS.BALANCE_ADJUST, { queue: SUBJECTS.QUEUE }` |
+
+## What it imports / requires
+
+- `node:http`
+- `./books.js`
+- `./subjects.js`
+
+## Call graph (identifiers invoked)
+
+`startNats`, `import`, `connect`, `split`, `async`, `parse`, `decode`, `fn`, `respond`, `encode`, `stringify`, `reply`, `subscribe`, `handle`, `write`, `readBody`, `on`, `push`, `resolve`, `concat`, `toString`, `createServer`, `writeHead`, `end`, `json`, `match`, `statement`, `adjust`, `listen`
+
+Each identifier is a call site in this file. Follow the import list to see the defining module; open that module’s MD for parameter and return types.
+
+## Return values (how to read this)
+
+- HTTP route handlers return Express `res.json(...)` bodies (see route docs).
+- Zapier `perform` functions return a **single object** (creates) or an **array** (triggers/searches).
+- Pricing functions return integer **cents** on `Quote.totalCents`.
+
--- a/docs/modules/zappier-account-balance/subjects.md
+++ b/docs/modules/zappier-account-balance/subjects.md
@ -0,0 +1,36 @@
+# `zappier-account-balance/subjects`
+
+**Package:** `zappier-account-balance`  
+**Source:** `packages/zappier-account-balance/src/subjects.js`  
+**Lines:** 11
+
+## What this module is
+
+Implementation module in `zappier-account-balance`. The tables below are extracted from the source (signatures + JSDoc).
+
+## Exports
+
+`SUBJECTS`
+
+## Types / interfaces / classes
+
+_None extracted._
+
+## Functions
+
+_No top-level functions extracted._
+
+## What it imports / requires
+
+_No imports detected._
+
+## Call graph (identifiers invoked)
+
+_No local call identifiers extracted._
+
+## Return values (how to read this)
+
+- HTTP route handlers return Express `res.json(...)` bodies (see route docs).
+- Zapier `perform` functions return a **single object** (creates) or an **array** (triggers/searches).
+- Pricing functions return integer **cents** on `Quote.totalCents`.
+
--- a/docs/modules/zappier-accounting-export/nats-billing.md
+++ b/docs/modules/zappier-accounting-export/nats-billing.md
@ -0,0 +1,40 @@
+# `zappier-accounting-export/nats-billing`
+
+**Package:** `zappier-accounting-export`  
+**Source:** `packages/zappier-accounting-export/src/nats-billing.js`  
+**Lines:** 18
+
+## What this module is
+
+Implementation module in `zappier-accounting-export`. The tables below are extracted from the source (signatures + JSDoc).
+
+## Exports
+
+`SUBJECTS`, `billingRequest`
+
+## Types / interfaces / classes
+
+_None extracted._
+
+## Functions
+
+| Name | Parameters | Param types (JSDoc) | Returns | Calls (same file / helpers) |
+|------|------------|---------------------|---------|-----------------------------|
+| `billingRequest` | `subject, payload` | — | `unknown` | see Call graph |
+
+## What it imports / requires
+
+_No imports detected._
+
+## Call graph (identifiers invoked)
+
+`billingRequest`, `import`, `connect`, `split`, `request`, `encode`, `stringify`, `parse`, `decode`, `close`
+
+Each identifier is a call site in this file. Follow the import list to see the defining module; open that module’s MD for parameter and return types.
+
+## Return values (how to read this)
+
+- HTTP route handlers return Express `res.json(...)` bodies (see route docs).
+- Zapier `perform` functions return a **single object** (creates) or an **array** (triggers/searches).
+- Pricing functions return integer **cents** on `Quote.totalCents`.
+
--- a/docs/modules/zappier-accounting-export/server.md
+++ b/docs/modules/zappier-accounting-export/server.md
@ -0,0 +1,46 @@
+# `zappier-accounting-export/server`
+
+**Package:** `zappier-accounting-export`  
+**Source:** `packages/zappier-accounting-export/src/server.js`  
+**Lines:** 62
+
+## What this module is
+
+Implementation module in `zappier-accounting-export`. The tables below are extracted from the source (signatures + JSDoc).
+
+## Exports
+
+_No named `export` / `module.exports` keys detected._
+
+## Types / interfaces / classes
+
+_None extracted._
+
+## Functions
+
+| Name | Parameters | Param types (JSDoc) | Returns | Calls (same file / helpers) |
+|------|------------|---------------------|---------|-----------------------------|
+| `edge` | `pathname` | — | `unknown` | see Call graph |
+| `send` | `code, type, body` | — | `unknown` | see Call graph |
+| `json` | `code, obj` | — | `unknown` | see Call graph |
+
+## What it imports / requires
+
+- `node:fs`
+- `node:http`
+- `node:path`
+- `node:url`
+- `./nats-billing.js`
+
+## Call graph (identifiers invoked)
+
+`replace`, `join`, `dirname`, `fileURLToPath`, `edge`, `fetch`, `createServer`, `async`, `writeHead`, `end`, `send`, `stringify`, `readFileSync`, `json`, `match`, `billingRequest`, `text`, `get`, `encodeURIComponent`, `listen`, `write`
+
+Each identifier is a call site in this file. Follow the import list to see the defining module; open that module’s MD for parameter and return types.
+
+## Return values (how to read this)
+
+- HTTP route handlers return Express `res.json(...)` bodies (see route docs).
+- Zapier `perform` functions return a **single object** (creates) or an **array** (triggers/searches).
+- Pricing functions return integer **cents** on `Quote.totalCents`.
+
--- a/docs/modules/zappier-customer-service/nats-billing.md
+++ b/docs/modules/zappier-customer-service/nats-billing.md
@ -0,0 +1,40 @@
+# `zappier-customer-service/nats-billing`
+
+**Package:** `zappier-customer-service`  
+**Source:** `packages/zappier-customer-service/src/nats-billing.js`  
+**Lines:** 21
+
+## What this module is
+
+Implementation module in `zappier-customer-service`. The tables below are extracted from the source (signatures + JSDoc).
+
+## Exports
+
+`SUBJECTS`, `billingRequest`
+
+## Types / interfaces / classes
+
+_None extracted._
+
+## Functions
+
+| Name | Parameters | Param types (JSDoc) | Returns | Calls (same file / helpers) |
+|------|------------|---------------------|---------|-----------------------------|
+| `billingRequest` | `subject, payload` | — | `unknown` | see Call graph |
+
+## What it imports / requires
+
+_No imports detected._
+
+## Call graph (identifiers invoked)
+
+`billingRequest`, `import`, `connect`, `split`, `request`, `encode`, `stringify`, `parse`, `decode`, `close`
+
+Each identifier is a call site in this file. Follow the import list to see the defining module; open that module’s MD for parameter and return types.
+
+## Return values (how to read this)
+
+- HTTP route handlers return Express `res.json(...)` bodies (see route docs).
+- Zapier `perform` functions return a **single object** (creates) or an **array** (triggers/searches).
+- Pricing functions return integer **cents** on `Quote.totalCents`.
+
--- a/docs/modules/zappier-customer-service/server.md
+++ b/docs/modules/zappier-customer-service/server.md
@ -0,0 +1,45 @@
+# `zappier-customer-service/server`
+
+**Package:** `zappier-customer-service`  
+**Source:** `packages/zappier-customer-service/src/server.js`  
+**Lines:** 81
+
+## What this module is
+
+Implementation module in `zappier-customer-service`. The tables below are extracted from the source (signatures + JSDoc).
+
+## Exports
+
+_No named `export` / `module.exports` keys detected._
+
+## Types / interfaces / classes
+
+_None extracted._
+
+## Functions
+
+| Name | Parameters | Param types (JSDoc) | Returns | Calls (same file / helpers) |
+|------|------------|---------------------|---------|-----------------------------|
+| `statement` | `customerId` | — | `unknown` | see Call graph |
+| `json` | `code, obj` | — | `unknown` | see Call graph |
+
+## What it imports / requires
+
+- `node:fs`
+- `node:http`
+- `node:path`
+- `node:url`
+- `./nats-billing.js`
+
+## Call graph (identifiers invoked)
+
+`join`, `dirname`, `fileURLToPath`, `replace`, `statement`, `billingRequest`, `fetch`, `json`, `createServer`, `async`, `writeHead`, `end`, `stringify`, `readFileSync`, `match`, `push`, `parse`, `concat`, `toString`, `get`, `listen`, `write`
+
+Each identifier is a call site in this file. Follow the import list to see the defining module; open that module’s MD for parameter and return types.
+
+## Return values (how to read this)
+
+- HTTP route handlers return Express `res.json(...)` bodies (see route docs).
+- Zapier `perform` functions return a **single object** (creates) or an **array** (triggers/searches).
+- Pricing functions return integer **cents** on `Quote.totalCents`.
+
--- a/docs/modules/zappier-sales-pricing/nats-billing.md
+++ b/docs/modules/zappier-sales-pricing/nats-billing.md
@ -0,0 +1,40 @@
+# `zappier-sales-pricing/nats-billing`
+
+**Package:** `zappier-sales-pricing`  
+**Source:** `packages/zappier-sales-pricing/src/nats-billing.js`  
+**Lines:** 18
+
+## What this module is
+
+Implementation module in `zappier-sales-pricing`. The tables below are extracted from the source (signatures + JSDoc).
+
+## Exports
+
+`SUBJECTS`, `billingRequest`
+
+## Types / interfaces / classes
+
+_None extracted._
+
+## Functions
+
+| Name | Parameters | Param types (JSDoc) | Returns | Calls (same file / helpers) |
+|------|------------|---------------------|---------|-----------------------------|
+| `billingRequest` | `subject, payload` | — | `unknown` | see Call graph |
+
+## What it imports / requires
+
+_No imports detected._
+
+## Call graph (identifiers invoked)
+
+`billingRequest`, `import`, `connect`, `split`, `request`, `encode`, `stringify`, `parse`, `decode`, `close`
+
+Each identifier is a call site in this file. Follow the import list to see the defining module; open that module’s MD for parameter and return types.
+
+## Return values (how to read this)
+
+- HTTP route handlers return Express `res.json(...)` bodies (see route docs).
+- Zapier `perform` functions return a **single object** (creates) or an **array** (triggers/searches).
+- Pricing functions return integer **cents** on `Quote.totalCents`.
+
--- a/docs/modules/zappier-sales-pricing/server.md
+++ b/docs/modules/zappier-sales-pricing/server.md
@ -0,0 +1,45 @@
+# `zappier-sales-pricing/server`
+
+**Package:** `zappier-sales-pricing`  
+**Source:** `packages/zappier-sales-pricing/src/server.js`  
+**Lines:** 77
+
+## What this module is
+
+Implementation module in `zappier-sales-pricing`. The tables below are extracted from the source (signatures + JSDoc).
+
+## Exports
+
+_No named `export` / `module.exports` keys detected._
+
+## Types / interfaces / classes
+
+_None extracted._
+
+## Functions
+
+| Name | Parameters | Param types (JSDoc) | Returns | Calls (same file / helpers) |
+|------|------------|---------------------|---------|-----------------------------|
+| `edge` | `pathname, { method = 'GET', body } = {}` | — | `unknown` | see Call graph |
+| `json` | `code, obj` | — | `unknown` | see Call graph |
+
+## What it imports / requires
+
+- `node:fs`
+- `node:http`
+- `node:path`
+- `node:url`
+- `./nats-billing.js`
+
+## Call graph (identifiers invoked)
+
+`join`, `dirname`, `fileURLToPath`, `replace`, `edge`, `fetch`, `stringify`, `text`, `parse`, `createServer`, `async`, `writeHead`, `end`, `readFileSync`, `json`, `match`, `billingRequest`, `push`, `concat`, `toString`, `listen`, `write`
+
+Each identifier is a call site in this file. Follow the import list to see the defining module; open that module’s MD for parameter and return types.
+
+## Return values (how to read this)
+
+- HTTP route handlers return Express `res.json(...)` bodies (see route docs).
+- Zapier `perform` functions return a **single object** (creates) or an **array** (triggers/searches).
+- Pricing functions return integer **cents** on `Quote.totalCents`.
+
--- a/docs/modules/zappier/accounting-export.md
+++ b/docs/modules/zappier/accounting-export.md
@ -0,0 +1,43 @@
+# `zappier/accounting-export`
+
+**Package:** `zappier`  
+**Source:** `packages/zappier/src/accounting-export.ts`  
+**Lines:** 37
+
+## What this module is
+
+Implementation module in `zappier`. The tables below are extracted from the source (signatures + JSDoc).
+
+## Exports
+
+`invoicesToQuickBooksIif`, `invoicesToAccountingCsv`
+
+## Types / interfaces / classes
+
+_None extracted._
+
+## Functions
+
+| Name | Parameters | Param types (JSDoc) | Returns | Calls (same file / helpers) |
+|------|------------|---------------------|---------|-----------------------------|
+| `iifDate` | `ms: number` | — | `unknown` | see Call graph |
+| `invoicesToQuickBooksIif` | `invoices: Invoice[]` | — | `unknown` | see Call graph |
+|  | _QuickBooks IIF journal for issued/paid invoices (Accounts Receivable + Sales)._ | | | |
+| `invoicesToAccountingCsv` | `invoices: Invoice[]` | — | `unknown` | see Call graph |
+
+## What it imports / requires
+
+- `./invoicing`
+
+## Call graph (identifiers invoked)
+
+`iifDate`, `getUTCMonth`, `padStart`, `getUTCDate`, `getUTCFullYear`, `invoices`, `invoicesToQuickBooksIif`, `now`, `toFixed`, `push`, `join`, `invoicesToAccountingCsv`, `map`
+
+Each identifier is a call site in this file. Follow the import list to see the defining module; open that module’s MD for parameter and return types.
+
+## Return values (how to read this)
+
+- HTTP route handlers return Express `res.json(...)` bodies (see route docs).
+- Zapier `perform` functions return a **single object** (creates) or an **array** (triggers/searches).
+- Pricing functions return integer **cents** on `Quote.totalCents`.
+
--- a/docs/modules/zappier/admin.md
+++ b/docs/modules/zappier/admin.md
@ -2,7 +2,7 @@

 **Package:** `zappier`  
 **Source:** `packages/zappier/src/admin.ts`  
-**Lines:** 486
+**Lines:** 588

 ## What this module is

@ -32,7 +32,8 @@ Implementation module in `zappier`. The tables below are extracted from the sour
 | `renderInvoiceHtml` | `invoice: Invoice, customerName: string` | — | `unknown` | see Call graph |
 | `adminRouter` | `store: PricingStore,
  customers: CustomerRepo,
-  accounting: AccountingDeps,` | — | `unknown` | see Call graph |
+  accounting: AccountingDeps,
+  credits: CreditLedger = new CreditLedger(` | — | `unknown` | see Call graph |

 ## Methods (class / object)

@ -58,10 +59,14 @@ Implementation module in `zappier`. The tables below are extracted from the sour
 - `./paths`
 - `./reports`
 - `./usage`
+- `./credits`
+- `./accounting-export`
+- `./statement`
+- `./billing-nats`

 ## Call graph (identifiers invoked)

-`tokens`, `adminLoginRouter`, `post`, `status`, `json`, `findByUsername`, `verifyPassword`, `randomBytes`, `toString`, `set`, `now`, `adminAuth`, `header`, `next`, `startsWith`, `slice`, `has`, `isValidRule`, `every`, `isValidTier`, `periodWindow`, `split`, `map`, `parseDate`, `trim`, `isNaN`, `getTime`, `escapeHtml`, `replace`, `toFixed`, `renderInvoiceHtml`, `dollars`, `join`, `toISOString`, `toUpperCase`, `adminRouter`, `get`, `getRateCard`, `getTiers`, `put`, `upsertEndpoint`, `delete`, `deleteEndpoint`, `upsertTier`, `deleteTier`, `list`, `randomUUID`, `save`, `find`, `test`, `push`, `listFor`, `filter`, `buildInvoice`, `nextSequence`, `type`, `send`, `untouched`, `flatMap`, `billingRows`
+`tokens`, `adminLoginRouter`, `post`, `status`, `json`, `findByUsername`, `verifyPassword`, `randomBytes`, `toString`, `set`, `now`, `adminAuth`, `header`, `next`, `startsWith`, `slice`, `has`, `isValidRule`, `every`, `isValidTier`, `periodWindow`, `split`, `map`, `parseDate`, `trim`, `isNaN`, `getTime`, `escapeHtml`, `replace`, `toFixed`, `renderInvoiceHtml`, `dollars`, `join`, `toISOString`, `toUpperCase`, `adminRouter`, `get`, `getRateCard`, `getTiers`, `put`, `upsertEndpoint`, `delete`, `deleteEndpoint`, `upsertTier`, `deleteTier`, `list`, `randomUUID`, `save`, `find`, `isFinite`, `trunc`, `add`, `natsPublish`, `natsAdjust`, `async`, `natsStatement`, `composeStatement`, `listFor`, `type`, `send`

 Each identifier is a call site in this file. Follow the import list to see the defining module; open that module’s MD for parameter and return types.

--- a/docs/modules/zappier/app.md
+++ b/docs/modules/zappier/app.md
@ -2,7 +2,7 @@

 **Package:** `zappier`  
 **Source:** `packages/zappier/src/app.ts`  
-**Lines:** 257
+**Lines:** 272

 ## What this module is

@ -24,6 +24,7 @@ Implementation module in `zappier`. The tables below are extracted from the sour
 | Name | Parameters | Param types (JSDoc) | Returns | Calls (same file / helpers) |
 |------|------------|---------------------|---------|-----------------------------|
 | `buildApp` | `deps: AppDeps = {}` | — | `unknown` | see Call graph |
+| `onUsage` | `e: { customerId: string; endpointId: string; cents: number }` | — | `unknown` | see Call graph |

 ## What it imports / requires

@ -44,10 +45,14 @@ Implementation module in `zappier`. The tables below are extracted from the sour
 - `./invoicing`
 - `./paths`
 - `./portal`
+- `./upstream`
+- `./credits`
+- `./statement`
+- `./billing-nats`

 ## Call graph (identifiers invoked)

-`join`, `next`, `parse`, `status`, `json`, `buildApp`, `seeded`, `seedAdminUsersFromEnv`, `rateCard`, `getRateCard`, `tiers`, `getTiers`, `express`, `use`, `load`, `setup`, `adminLoginRouter`, `adminAuth`, `adminRouter`, `static`, `async`, `import`, `toDataURL`, `portalRouter`, `apiKeyAuth`, `middleware`, `get`, `meter`, `post`, `toUpperCase`, `toLowerCase`, `createHash`, `update`, `digest`, `randomUUID`, `toISOString`, `set`, `isFinite`, `map`, `unshift`, `filter`, `setUTCDate`, `setUTCHours`, `summaryFor`, `find`, `applyMonthlyCredit`
+`join`, `next`, `parse`, `status`, `json`, `buildApp`, `seeded`, `seedAdminUsersFromEnv`, `rateCard`, `getRateCard`, `tiers`, `getTiers`, `natsPublish`, `toISOString`, `express`, `use`, `load`, `setup`, `adminLoginRouter`, `adminAuth`, `adminRouter`, `static`, `async`, `import`, `toDataURL`, `portalRouter`, `get`, `apiKeyAuth`, `middleware`, `meter`, `post`, `toUpperCase`, `proxyVerae`, `toLowerCase`, `createHash`, `update`, `digest`, `randomUUID`, `set`, `isFinite`, `map`, `unshift`, `filter`, `setUTCDate`, `setUTCHours`, `summaryFor`, `find`, `applyMonthlyCredit`

 Each identifier is a call site in this file. Follow the import list to see the defining module; open that module’s MD for parameter and return types.

--- a/docs/modules/zappier/billing-nats.md
+++ b/docs/modules/zappier/billing-nats.md
@ -0,0 +1,54 @@
+# `zappier/billing-nats`
+
+**Package:** `zappier`  
+**Source:** `packages/zappier/src/billing-nats.ts`  
+**Lines:** 74
+
+## What this module is
+
+Implementation module in `zappier`. The tables below are extracted from the source (signatures + JSDoc).
+
+## Exports
+
+`BILLING_SUBJECTS`, `BillingStatement`, `natsStatement`, `natsAdjust`, `natsPublish`
+
+## Types / interfaces / classes
+
+| Kind | Name |
+|------|------|
+| type | `BillingStatement` |
+| type | `Nc` |
+
+## Functions
+
+| Name | Parameters | Param types (JSDoc) | Returns | Calls (same file / helpers) |
+|------|------------|---------------------|---------|-----------------------------|
+| `nc` | `(none)` | — | `unknown` | see Call graph |
+| `encode` | `obj: unknown` | — | `unknown` | see Call graph |
+| `decode` | `buf: Uint8Array` | — | `unknown` | see Call graph |
+| `natsStatement` | `customerId: string` | — | `unknown` | see Call graph |
+| `natsAdjust` | `payload: {
+  customerId: string;
+  cents: number;
+  reason: string;
+  agent: string;
+  kind?: string;
+}` | — | `unknown` | see Call graph |
+| `natsPublish` | `subject: string, payload: unknown` | — | `unknown` | see Call graph |
+
+## What it imports / requires
+
+_No imports detected._
+
+## Call graph (identifiers invoked)
+
+`unset`, `nc`, `async`, `import`, `connect`, `split`, `encode`, `stringify`, `decode`, `parse`, `natsStatement`, `request`, `natsAdjust`, `natsPublish`, `then`, `publish`
+
+Each identifier is a call site in this file. Follow the import list to see the defining module; open that module’s MD for parameter and return types.
+
+## Return values (how to read this)
+
+- HTTP route handlers return Express `res.json(...)` bodies (see route docs).
+- Zapier `perform` functions return a **single object** (creates) or an **array** (triggers/searches).
+- Pricing functions return integer **cents** on `Quote.totalCents`.
+
--- a/docs/modules/zappier/credits.md
+++ b/docs/modules/zappier/credits.md
@ -0,0 +1,48 @@
+# `zappier/credits`
+
+**Package:** `zappier`  
+**Source:** `packages/zappier/src/credits.ts`  
+**Lines:** 30
+
+## What this module is
+
+Implementation module in `zappier`. The tables below are extracted from the source (signatures + JSDoc).
+
+## Exports
+
+`CreditAdjustment`, `CreditLedger`
+
+## Types / interfaces / classes
+
+| Kind | Name |
+|------|------|
+| interface | `CreditAdjustment` |
+| class | `CreditLedger` |
+
+## Functions
+
+_No top-level functions extracted._
+
+## Methods (class / object)
+
+| Name | Parameters |
+|------|------------|
+| `add` | `row: Omit<CreditAdjustment, 'id' | 'at'> & { id?: string; at?: string }` |
+| `list` | `customerId?: string` |
+
+## What it imports / requires
+
+_No imports detected._
+
+## Call graph (identifiers invoked)
+
+`add`, `now`, `toString`, `toISOString`, `unshift`, `list`, `filter`
+
+Each identifier is a call site in this file. Follow the import list to see the defining module; open that module’s MD for parameter and return types.
+
+## Return values (how to read this)
+
+- HTTP route handlers return Express `res.json(...)` bodies (see route docs).
+- Zapier `perform` functions return a **single object** (creates) or an **array** (triggers/searches).
+- Pricing functions return integer **cents** on `Quote.totalCents`.
+
--- a/docs/modules/zappier/meter.md
+++ b/docs/modules/zappier/meter.md
@ -2,7 +2,7 @@

 **Package:** `zappier`  
 **Source:** `packages/zappier/src/meter.ts`  
-**Lines:** 49
+**Lines:** 52

 ## What this module is

@ -22,7 +22,8 @@ _None extracted._
 |------|------------|---------------------|---------|-----------------------------|
 | `meter` | `endpointId: string,
  repo: UsageRepo,
-  pricing: PricingContext,` | — | `unknown` | see Call graph |
+  pricing: PricingContext,
+  onRecord?: (entry: { customerId: string; endpointId: string; cents: number }` | — | `unknown` | see Call graph |

 ## Methods (class / object)

--- a/docs/modules/zappier/nats-shim.d.md
+++ b/docs/modules/zappier/nats-shim.d.md
@ -0,0 +1,41 @@
+# `zappier/nats-shim.d`
+
+**Package:** `zappier`  
+**Source:** `packages/zappier/src/nats-shim.d.ts`  
+**Lines:** 12
+
+## What this module is
+
+Implementation module in `zappier`. The tables below are extracted from the source (signatures + JSDoc).
+
+## Exports
+
+_No named `export` / `module.exports` keys detected._
+
+## Types / interfaces / classes
+
+_None extracted._
+
+## Functions
+
+| Name | Parameters | Param types (JSDoc) | Returns | Calls (same file / helpers) |
+|------|------------|---------------------|---------|-----------------------------|
+| `connect` | `opts: unknown` | — | `unknown` | see Call graph |
+| `StringCodec` | `(none)` | — | `unknown` | see Call graph |
+
+## What it imports / requires
+
+_No imports detected._
+
+## Call graph (identifiers invoked)
+
+`connect`, `request`, `publish`, `close`, `encode`, `decode`
+
+Each identifier is a call site in this file. Follow the import list to see the defining module; open that module’s MD for parameter and return types.
+
+## Return values (how to read this)
+
+- HTTP route handlers return Express `res.json(...)` bodies (see route docs).
+- Zapier `perform` functions return a **single object** (creates) or an **array** (triggers/searches).
+- Pricing functions return integer **cents** on `Quote.totalCents`.
+
--- a/docs/modules/zappier/portal.md
+++ b/docs/modules/zappier/portal.md
@ -2,7 +2,7 @@

 **Package:** `zappier`  
 **Source:** `packages/zappier/src/portal.ts`  
-**Lines:** 285
+**Lines:** 321

 ## What this module is

@ -48,10 +48,13 @@ Implementation module in `zappier`. The tables below are extracted from the sour
 - `./invoicing`
 - `./pricing`
 - `./usage`
+- `./credits`
+- `./statement`
+- `./billing-nats`

 ## Call graph (identifiers invoked)

-`now`, `reload`, `customer`, `publicProfile`, `sessionAuth`, `header`, `startsWith`, `slice`, `get`, `list`, `find`, `status`, `json`, `next`, `save`, `portalRouter`, `post`, `trim`, `test`, `hashPassword`, `findByEmail`, `randomBytes`, `toString`, `create`, `verifyPassword`, `verifyTotp`, `use`, `delete`, `setUTCDate`, `setUTCHours`, `summaryFor`, `tiers`, `applyMonthlyCredit`, `rateCard`, `type`, `send`, `renderInvoiceHtml`, `async`, `generateTotpSecret`, `totpUri`, `qr`, `isInteger`, `put`
+`now`, `reload`, `customer`, `publicProfile`, `sessionAuth`, `header`, `startsWith`, `slice`, `get`, `list`, `find`, `status`, `json`, `next`, `save`, `portalRouter`, `post`, `trim`, `test`, `hashPassword`, `findByEmail`, `randomBytes`, `toString`, `create`, `verifyPassword`, `verifyTotp`, `use`, `delete`, `setUTCDate`, `setUTCHours`, `summaryFor`, `tiers`, `applyMonthlyCredit`, `rateCard`, `async`, `natsStatement`, `composeStatement`, `listFor`, `type`, `send`, `renderInvoiceHtml`, `generateTotpSecret`, `totpUri`, `qr`, `isInteger`, `natsPublish`, `natsAdjust`, `put`

 Each identifier is a call site in this file. Follow the import list to see the defining module; open that module’s MD for parameter and return types.

--- a/docs/modules/zappier/statement.md
+++ b/docs/modules/zappier/statement.md
@ -0,0 +1,48 @@
+# `zappier/statement`
+
+**Package:** `zappier`  
+**Source:** `packages/zappier/src/statement.ts`  
+**Lines:** 39
+
+## What this module is
+
+Implementation module in `zappier`. The tables below are extracted from the source (signatures + JSDoc).
+
+## Exports
+
+`composeStatement`
+
+## Types / interfaces / classes
+
+_None extracted._
+
+## Functions
+
+| Name | Parameters | Param types (JSDoc) | Returns | Calls (same file / helpers) |
+|------|------------|---------------------|---------|-----------------------------|
+| `composeStatement` | `args: {
+  customerId: string;
+  prepaidCents: number;
+  credits: CreditAdjustment[];
+  usage: UsageEntry[];
+  invoices: Invoice[];
+}` | — | `unknown` | see Call graph |
+
+## What it imports / requires
+
+- `./credits`
+- `./invoicing`
+- `./usage`
+
+## Call graph (identifiers invoked)
+
+`composeStatement`, `filter`, `map`, `now`, `toISOString`, `slice`, `reverse`
+
+Each identifier is a call site in this file. Follow the import list to see the defining module; open that module’s MD for parameter and return types.
+
+## Return values (how to read this)
+
+- HTTP route handlers return Express `res.json(...)` bodies (see route docs).
+- Zapier `perform` functions return a **single object** (creates) or an **array** (triggers/searches).
+- Pricing functions return integer **cents** on `Quote.totalCents`.
+
--- a/docs/modules/zappier/upstream.md
+++ b/docs/modules/zappier/upstream.md
@ -0,0 +1,45 @@
+# `zappier/upstream`
+
+**Package:** `zappier`  
+**Source:** `packages/zappier/src/upstream.ts`  
+**Lines:** 46
+
+## What this module is
+
+Implementation module in `zappier`. The tables below are extracted from the source (signatures + JSDoc).
+
+## Exports
+
+`UpstreamFetch`, `proxyVerae`
+
+## Types / interfaces / classes
+
+| Kind | Name |
+|------|------|
+| type | `UpstreamFetch` |
+
+## Functions
+
+| Name | Parameters | Param types (JSDoc) | Returns | Calls (same file / helpers) |
+|------|------------|---------------------|---------|-----------------------------|
+| `proxyVerae` | `req: Request,
+  res: Response,
+  pathname: string,
+  fetchImpl: UpstreamFetch = fetch,` | — | `unknown` | see Call graph |
+
+## What it imports / requires
+
+- `express`
+
+## Call graph (identifiers invoked)
+
+`proxyVerae`, `replace`, `entries`, `set`, `header`, `toUpperCase`, `stringify`, `fetchImpl`, `toString`, `text`, `parse`, `isArray`, `status`, `json`
+
+Each identifier is a call site in this file. Follow the import list to see the defining module; open that module’s MD for parameter and return types.
+
+## Return values (how to read this)
+
+- HTTP route handlers return Express `res.json(...)` bodies (see route docs).
+- Zapier `perform` functions return a **single object** (creates) or an **array** (triggers/searches).
+- Pricing functions return integer **cents** on `Quote.totalCents`.
+