Add NATS account-balance SoT and statement review for customers, CS, and sales
Some checks are pending
offline / test (push) Waiting to run

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.
This commit is contained in:
George Lambert 2026-09-11 15:35:37 -04:00
commit ac38676645
68 changed files with 3078 additions and 130 deletions

View file

@ -2,14 +2,19 @@
Master map of every service in the Zapier ↔ middleware ↔ chain ↔ WORM-archive path.
Zapier cloud **never** connects to NATS. Only middleware workers and archives do.
Zapier cloud **never** connects to NATS. Internal services do: middleware workers, archives, account-balance, zappier-edge billing, CS, sales, and accounting.
## Who talks to whom (HTTPS vs NATS)
```text
[Zapier Platform app] HTTPS [zappier-edge] HTTPS [middleware-http]
|
NATS JetStream (NS1 loopback :4222) |
| | NATS verae.billing.* |
| v |
[customer portal] [account-balance] NATS JetStream
[CS :3011] queue account-balance (NS1 loopback :4222)
[sales :3012] ^ |
[accounting :3013] | request-reply |
+-------------------------------+
+------------------+------------------+-------------+
| | |
[job-poller] [webhook-deliver] [archive-aggregator]
@ -25,7 +30,11 @@ Zapier cloud **never** connects to NATS. Only middleware workers and archives do
| Module | Repo (Forgejo) | Runtime | Listens | Sends |
|--------|----------------|---------|---------|-------|
| zapier-platform-app | `verae-zapier-app` | Zapier cloud | User Zap steps | HTTPS to zappier-edge |
| zappier-edge | `zappier-edge` | Public HTTPS :3000 | Zapier, portal, admin | HTTPS to middleware |
| zappier-edge | `zappier-edge` | Public HTTPS :3000 | Zapier, portal, admin | HTTPS to middleware; NATS billing pub |
| account-balance | `zappier-account-balance` | :3010 + NATS | `verae.billing.*` | statement/adjust replies |
| customer-service | `zappier-customer-service` | :3011 | CS staff HTTP | NATS balance.adjust / statement.get |
| sales-pricing | `zappier-sales-pricing` | :3012 | Sales HTTP | NATS statement.get; HTTPS to edge for multipliers |
| accounting-export | `zappier-accounting-export` | :3013 | Accounting HTTP | reads invoices; NATS statement |
| middleware-http | `verae-middleware` | Public HTTPS :3100 | zappier-edge | NATS jobs.watch; HTTP to chain; wait on jobs.events |
| job-poller | `verae-job-poller` | Worker | `verae.zapier.jobs.watch` | `verae.zapier.jobs.events`; HTTP GET chain status |
| webhook-deliver | `verae-webhook-deliver` | Worker | `verae.zapier.webhooks.deliver` + events | HTTPS POST Zapier REST Hook |
@ -49,6 +58,11 @@ Zapier cloud **never** connects to NATS. Only middleware workers and archives do
| `verae.zapier.jobs.events` | JetStream events | `event` (`timestamp.completed\|failed\|timeout`), `tenantId`, `jobId`, `status`, `traceId`, `emittedAt` |
| `verae.zapier.webhooks.deliver` | JetStream work queue | `hookId`, `tenantId`, `targetUrl`, `event`, `payload`, `attempt`, `traceId` |
| `verae.zapier.usage` | optional | `tenantId`, `action`, `amount`, `at` |
| `verae.billing.statement.get` | request-reply | `customerId` → prepaid, credits, usage, payments |
| `verae.billing.balance.adjust` | request-reply | `customerId`, `cents`, `reason`, `agent` |
| `verae.billing.usage.recorded` | pub | meter events from zappier-edge |
| `verae.billing.payment.recorded` | pub | portal reload / invoice paid |
| `verae.billing.credit.applied` | pub | CS goodwill |
| `verae.archive.put` | JetStream | `sha256`, `tenantId`, `kind` (`publicMeta\|privateMeta\|file\|tree`), `record`, `traceId` |
| `verae.archive.query` | pub to **all** archives | `correlationId`, `sha256`, `tenantId`, `kinds[]`, `traceId` |
| `verae.archive.reply.<correlationId>` | replies | `archiveId`, `sha256`, `records[]`, `traceId` |

View file

@ -0,0 +1,12 @@
# NATS — zappier-account-balance
Queue group `account-balance`. This process is the source of truth for prepaid cents.
| Direction | Address | Kind | Body |
|-----------|---------|------|------|
| IN | `verae.billing.statement.get` | request-reply | `{ customerId }` → statement |
| IN | `verae.billing.balance.get` | request-reply | `{ customerId }` → statement |
| IN | `verae.billing.balance.adjust` | request-reply | `{ customerId, cents, reason, agent, kind }` |
| IN | `verae.billing.usage.recorded` | pub | `{ customerId, endpointId, cents, at }` (debits prepaid) |
`payment.recorded` and `credit.applied` are fan-out events from publishers; prepaid mutations go through `balance.adjust`.

View file

@ -0,0 +1,3 @@
# zappier-account-balance
NATS source of truth for prepaid balances, credits, usage events, and payments.

View file

@ -1,3 +1,7 @@
# zappier-accounting-export NATS
# NATS — zappier-accounting-export
None.
| Direction | Address | Kind |
|-----------|---------|------|
| OUT | `verae.billing.statement.get` | request-reply (review) |
IIF/CSV export remains HTTPS to zappier-edge admin.

View file

@ -1,3 +1,5 @@
# zappier-accounting-export
Exports zappier invoices to QuickBooks IIF and accounting CSV.
Accounting export of invoices to QuickBooks IIF and CSV, plus **review** of customer credits, balances, usage, and payments over NATS.
Forgejo: https://git.georgelambert.org/marchon/zappier-accounting-export

View file

@ -1,3 +1,8 @@
# zappier-customer-service NATS
# NATS — zappier-customer-service
None. HTTPS only to zappier-edge admin.
| Direction | Address | Kind |
|-----------|---------|------|
| OUT | `verae.billing.statement.get` | request-reply (review) |
| OUT | `verae.billing.balance.adjust` | request-reply (credits) |
HTTP fallback: `ACCOUNT_BALANCE_URL` then zappier-edge admin. Zapier cloud never connects here.

View file

@ -1,3 +1,7 @@
# zappier-customer-service
CS department API for prepaid credit additions. Writes `balanceCents` on zappier-edge.
CS department API and UI for prepaid credit additions and **review** of credits, balances, usage, and payments.
Internal path: NATS `verae.billing.statement.get` / `verae.billing.balance.adjust` → account-balance. HTTP fallback to `:3010` then zappier-edge admin.
Forgejo: https://git.georgelambert.org/marchon/zappier-customer-service

View file

@ -1,3 +1,7 @@
# zappier-sales-pricing NATS
# NATS — zappier-sales-pricing
None.
| Direction | Address | Kind |
|-----------|---------|------|
| OUT | `verae.billing.statement.get` | request-reply (review) |
Pricing writes remain HTTPS to zappier-edge admin.

View file

@ -1,3 +1,5 @@
# zappier-sales-pricing
Sales department per-customer tier and multiplier. Writes through zappier-edge `/admin/api/customers`.
Sales department API and UI for per-customer tier/multiplier and **review** of the same NATS statement as CS and the customer portal.
Forgejo: https://git.georgelambert.org/marchon/zappier-sales-pricing

View file

@ -1,10 +1,15 @@
# NATS — zappier-edge
This process **does not subscribe or publish** on NATS.
Zapier cloud still never connects to NATS. The edge process **does** publish and request on the private billing bus.
| Direction | Address | Peer | Body |
|-----------|---------|------|------|
| IN HTTPS | `/v1/*` | Zapier Platform app | JSON + `x-api-key` |
| OUT HTTPS | middleware `/zapier/v1/*` | verae-middleware | same tenant request |
| OUT NATS | `verae.billing.usage.recorded` | account-balance | meter event |
| OUT NATS | `verae.billing.payment.recorded` | account-balance / others | portal reload |
| OUT NATS | `verae.billing.credit.applied` | account-balance / others | admin/CS credit |
| OUT NATS | `verae.billing.statement.get` | account-balance | portal/admin review |
| OUT NATS | `verae.billing.balance.adjust` | account-balance | prepaid mutation |
NATS is private to middleware workers and archives.
Jobs, archive, and webhooks stay on middleware workers.

View file

@ -11,8 +11,9 @@ Verae Time proves a SHA-256 existed at a given time. Zapier lets customers regis
| Plane | What | Network |
|-------|------|---------|
| Zapier cloud | `verae-zapier-app`, `verae-activate` | HTTPS to zappier-edge |
| Commercial edge | `zappier-edge` portal, admin, `x-api-key`, Stripe meter | Public HTTPS |
| CS / sales / accounting | `zappier-customer-service`, `zappier-sales-pricing`, `zappier-accounting-export` | Loopback/private HTTP into zappier-edge admin |
| Commercial edge | `zappier-edge` portal, admin, `x-api-key`, Stripe meter | Public HTTPS; NATS billing pubs/requests |
| Account balance | `zappier-account-balance` prepaid SoT | NATS `verae.billing.*` + HTTP `:3010` |
| CS / sales / accounting | `zappier-customer-service`, `zappier-sales-pricing`, `zappier-accounting-export` | Private HTTP; NATS statement/adjust |
| Middleware HTTP | `/zapier/v1/*` job id + wait | Public HTTPS from edge only |
| NATS cluster | JetStream subjects under `verae.*` | Private; loopback or SSH tunnel |
| Workers | poller, webhook-deliver, aggregator | NATS + HTTPS to chain or Zapier hooks |
@ -22,6 +23,6 @@ Verae Time proves a SHA-256 existed at a given time. Zapier lets customers regis
## Request in one sentence
A Zap step POSTs to zappier-edge (`x-api-key`); edge meters the call and, when `ZAPPIER_UPSTREAM` is set, forwards timestamp/receipt/hash to middleware `/zapier/v1`. Middleware splits hash vs files, writes the hash (or Merkle root) to the chain, publishes `verae.zapier.jobs.watch`, and either returns `jobId` or waits on `verae.zapier.jobs.events`. Customer-service credits, sales per-customer multipliers, invoices, payment history, and QuickBooks export sit on zappier-edge (department APIs on :3011–:3013). Attached metadata and bulk-summary **leaves** are found later by broadcasting `verae.archive.query` to every archive/tree node.
A Zap step POSTs to zappier-edge (`x-api-key`); edge meters the call and, when `ZAPPIER_UPSTREAM` is set, forwards timestamp/receipt/hash to middleware `/zapier/v1`. Middleware splits hash vs files, writes the hash (or Merkle root) to the chain, publishes `verae.zapier.jobs.watch`, and either returns `jobId` or waits on `verae.zapier.jobs.events`. Meter events, CS credits, and portal reloads go over NATS `verae.billing.*` to **account-balance** (source of truth). Customers review the same statement in the portal; CS (`:3011`) and sales (`:3012`) review it on their department UIs. Attached metadata and bulk-summary **leaves** are found later by broadcasting `verae.archive.query` to every archive/tree node.
See [diagrams](08-diagrams.md).

View file

@ -8,6 +8,7 @@ Each runtime piece is its **own git repo** on Forgejo (`git.georgelambert.org`,
| **verae-nats-process** | `packages/verae-nats-process` | **Template** for a new addressed NATS process |
| **master-zapier-plan-draft** | workspace root | Combined snapshot (`main` and `master`) |
| **zappier-edge** | `packages/zappier` | Metered HTTPS, portal, admin, Stripe; **proxies Verae calls to middleware** |
| **zappier-account-balance** | `packages/zappier-account-balance` | NATS source of truth for prepaid balances |
| **zappier-customer-service** | `packages/zappier-customer-service` | CS goodwill credits onto prepaid balances |
| **zappier-sales-pricing** | `packages/zappier-sales-pricing` | Sales per-customer tier / multiplier |
| **zappier-accounting-export** | `packages/zappier-accounting-export` | QuickBooks IIF + accounting CSV |

View file

@ -4,7 +4,7 @@ All durable messaging for this product is **NATS JetStream**, not Zapier queues
## Cluster
Three `nats-server -js` nodes form the Verae cluster (routes between them, JetStream replication). Clients (middleware, poller, aggregator, WORM, tree nodes, and any new process cloned from `verae-nats-process`) connect with a **cluster URL list**, for example:
Three `nats-server -js` nodes form the Verae cluster (routes between them, JetStream replication). Clients (middleware, poller, aggregator, WORM, tree nodes, account-balance, zappier-edge billing, CS/sales/accounting, and any new process cloned from `verae-nats-process`) connect with a **cluster URL list**, for example:
```text
nats://127.0.0.1:4222,nats://127.0.0.1:4223,nats://127.0.0.1:4224
@ -20,7 +20,7 @@ Today’s NS1 box (`NS1.GEORGELAMBERT.ORG`, `70.88.205.138`) already runs JetStr
| Allowed | Forbidden |
|---------|-----------|
| verae-middleware, fleet workers, WORM, tree nodes, `verae-nats-process` clones | Zapier cloud, browsers, zappier-edge |
| verae-middleware, fleet workers, WORM, tree nodes, account-balance, zappier-edge billing, CS/sales/accounting, `verae-nats-process` clones | Zapier cloud, customer browsers (they use HTTPS portal/CS/sales UIs) |
## Address families already in use
@ -30,6 +30,9 @@ Today’s NS1 box (`NS1.GEORGELAMBERT.ORG`, `70.88.205.138`) already runs JetStr
| `verae.zapier.jobs.events` | events | wait + webhooks |
| `verae.zapier.webhooks.deliver` | work queue | HTTPS to Zapier REST Hook |
| `verae.zapier.usage` | optional | metering |
| `verae.billing.statement.get` | request-reply | portal, CS, sales, admin |
| `verae.billing.balance.adjust` | request-reply | CS credits, portal reload |
| `verae.billing.usage.recorded` | pub | zappier-edge meter |
| `verae.archive.put` | JetStream | splitter / merkle builder |
| `verae.archive.query` | **broadcast** (no queue group) | every WORM and tree node |
| `verae.archive.reply.<correlationId>` | replies | **only on bloom hit** |

View file

@ -9,12 +9,15 @@ SVG files in [`diagrams/`](diagrams/). The same shapes are repeated below in mer
```mermaid
flowchart LR
Z[Zapier cloud apps] -->|HTTPS x-api-key| E[zappier-edge]
CS[customer-service] --> E
SA[sales-pricing] --> E
AC[accounting-export QuickBooks] --> E
Cust[customer portal] -->|HTTPS statement| E
CS[customer-service] -->|NATS statement/adjust| N[NATS 3-node cluster]
SA[sales-pricing] -->|NATS statement| N
AC[accounting-export] -->|NATS statement| N
E -->|NATS billing| N
BAL[account-balance] -->|reply verae.billing.*| N
E -->|HTTPS metered| M[verae-middleware]
M -->|HTTPS| C[Verae chain]
M -->|JetStream| N[NATS 3-node cluster]
M -->|JetStream| N
N --> P[job-poller]
N --> W[webhook-deliver]
N --> A[archive-aggregator]

View file

@ -15,9 +15,10 @@
"services": {
"nats": { "min": 1, "max": 1, "keepFloor": false, "enabled": true, "managed": false },
"zappier-edge": { "min": 1, "max": 1, "keepFloor": true, "enabled": true },
"customer-service": { "min": 0, "max": 1, "keepFloor": false, "enabled": true },
"sales-pricing": { "min": 0, "max": 1, "keepFloor": false, "enabled": true },
"accounting-export": { "min": 0, "max": 1, "keepFloor": false, "enabled": true },
"account-balance": { "min": 1, "max": 1, "keepFloor": true, "enabled": true },
"customer-service": { "min": 1, "max": 1, "keepFloor": true, "enabled": true },
"sales-pricing": { "min": 1, "max": 1, "keepFloor": true, "enabled": true },
"accounting-export": { "min": 1, "max": 1, "keepFloor": true, "enabled": true },
"middleware-http": { "min": 1, "max": 1, "keepFloor": true, "enabled": true },
"job-poller": { "min": 1, "max": 2, "keepFloor": true, "enabled": true },
"webhook-deliver": { "min": 1, "max": 2, "keepFloor": true, "enabled": true },

View file

@ -0,0 +1,31 @@
{
"id": "account-balance",
"title": "Account balance (NATS billing SoT)",
"kind": "http",
"package": "zappier-account-balance",
"role": "account-balance",
"managed": true,
"runtime": "HTTP :3010 + NATS verae.billing.*",
"health": { "type": "http", "path": "/health", "timeoutMs": 2000 },
"ports": { "healthBase": 3010 },
"spawn": {
"cwd": "../zappier-account-balance",
"command": "node",
"args": ["src/server.js"]
},
"env": {
"PORT": "3010",
"NATS_URL": "nats://127.0.0.1:4222"
},
"nats": {
"in": [
"verae.billing.statement.get",
"verae.billing.balance.get",
"verae.billing.balance.adjust",
"verae.billing.usage.recorded",
"verae.billing.payment.recorded",
"verae.billing.credit.applied"
],
"out": []
}
}

View file

@ -15,7 +15,9 @@
},
"env": {
"PORT": "3013",
"ZAPPIER_ADMIN_URL": "http://127.0.0.1:3000"
"ZAPPIER_ADMIN_URL": "http://127.0.0.1:3000",
"ACCOUNT_BALANCE_URL": "http://127.0.0.1:3010",
"NATS_URL": "nats://127.0.0.1:4222"
},
"nats": { "in": [], "out": [] }
"nats": { "in": [], "out": ["verae.billing.statement.get"] }
}

View file

@ -1,11 +1,11 @@
{
"id": "customer-service",
"title": "Customer-service credits",
"title": "Customer-service credits and review",
"kind": "http",
"package": "zappier-customer-service",
"role": "customer-service",
"managed": true,
"runtime": "HTTP :3011 CS credits → zappier-edge",
"runtime": "HTTP :3011 CS credits + NATS statement review",
"health": { "type": "http", "path": "/health", "timeoutMs": 2000 },
"ports": { "healthBase": 3011 },
"spawn": {
@ -15,8 +15,13 @@
},
"env": {
"PORT": "3011",
"ZAPPIER_ADMIN_URL": "http://127.0.0.1:3000"
"ZAPPIER_ADMIN_URL": "http://127.0.0.1:3000",
"ACCOUNT_BALANCE_URL": "http://127.0.0.1:3010",
"NATS_URL": "nats://127.0.0.1:4222"
},
"nats": { "in": [], "out": [] },
"notes": "Department API. Prepaid balances live on zappier-edge."
"nats": {
"in": [],
"out": ["verae.billing.statement.get", "verae.billing.balance.adjust"]
},
"notes": "CS review and credits. Balances live on account-balance over NATS."
}

View file

@ -5,7 +5,7 @@
"package": "zappier-sales-pricing",
"role": "sales-pricing",
"managed": true,
"runtime": "HTTP :3012 quotes → zappier-edge",
"runtime": "HTTP :3012 quotes + NATS statement review",
"health": { "type": "http", "path": "/health", "timeoutMs": 2000 },
"ports": { "healthBase": 3012 },
"spawn": {
@ -15,7 +15,9 @@
},
"env": {
"PORT": "3012",
"ZAPPIER_ADMIN_URL": "http://127.0.0.1:3000"
"ZAPPIER_ADMIN_URL": "http://127.0.0.1:3000",
"ACCOUNT_BALANCE_URL": "http://127.0.0.1:3010",
"NATS_URL": "nats://127.0.0.1:4222"
},
"nats": { "in": [], "out": [] }
"nats": { "in": [], "out": ["verae.billing.statement.get"] }
}

View file

@ -18,8 +18,18 @@
"ZAPPIER_UPSTREAM": "http://127.0.0.1:3100",
"CS_SERVICE_URL": "http://127.0.0.1:3011",
"SALES_PRICING_URL": "http://127.0.0.1:3012",
"ACCOUNTING_EXPORT_URL": "http://127.0.0.1:3013"
"ACCOUNTING_EXPORT_URL": "http://127.0.0.1:3013",
"NATS_URL": "nats://127.0.0.1:4222"
},
"nats": { "in": [], "out": [] },
"notes": "Zapier x-api-key lands here. HTTPS to middleware only."
"nats": {
"in": [],
"out": [
"verae.billing.usage.recorded",
"verae.billing.payment.recorded",
"verae.billing.credit.applied",
"verae.billing.statement.get",
"verae.billing.balance.adjust"
]
},
"notes": "Zapier x-api-key lands here. HTTPS to middleware. NATS billing to account-balance."
}

Some files were not shown because too many files have changed in this diff Show more