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.

docs/sphinx/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`.
+

docs/sphinx/modules/zappier/accounting-export.rst

@@ -0,0 +1,7 @@
+zappier.accounting-export
+=========================
+
+Generated API sheet for ``zappier/accounting-export``.
+
+.. include:: accounting-export.md
+   :parser: myst_parser.sphinx_

docs/sphinx/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.
 

docs/sphinx/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.
 

docs/sphinx/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`.
+

docs/sphinx/modules/zappier/billing-nats.rst

@@ -0,0 +1,7 @@
+zappier.billing-nats
+====================
+
+Generated API sheet for ``zappier/billing-nats``.
+
+.. include:: billing-nats.md
+   :parser: myst_parser.sphinx_

docs/sphinx/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`.
+

docs/sphinx/modules/zappier/credits.rst

@@ -0,0 +1,7 @@
+zappier.credits
+===============
+
+Generated API sheet for ``zappier/credits``.
+
+.. include:: credits.md
+   :parser: myst_parser.sphinx_

docs/sphinx/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)
 

docs/sphinx/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`.
+

docs/sphinx/modules/zappier/nats-shim.d.rst

@@ -0,0 +1,7 @@
+zappier.nats-shim.d
+===================
+
+Generated API sheet for ``zappier/nats-shim.d``.
+
+.. include:: nats-shim.d.md
+   :parser: myst_parser.sphinx_

docs/sphinx/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.
 

docs/sphinx/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`.
+

docs/sphinx/modules/zappier/statement.rst

@@ -0,0 +1,7 @@
+zappier.statement
+=================
+
+Generated API sheet for ``zappier/statement``.
+
+.. include:: statement.md
+   :parser: myst_parser.sphinx_

docs/sphinx/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`.
+

docs/sphinx/modules/zappier/upstream.rst

@@ -0,0 +1,7 @@
+zappier.upstream
+================
+
+Generated API sheet for ``zappier/upstream``.
+
+.. include:: upstream.md
+   :parser: myst_parser.sphinx_