diff --git a/docs/modules/README.md b/docs/modules/README.md index f0b689e..37c22cc 100644 --- a/docs/modules/README.md +++ b/docs/modules/README.md @@ -23,6 +23,7 @@ One MD file per source module. - [zappier/index](zappier/index.md) - [zappier/invoicing](zappier/invoicing.md) - [zappier/jobs/report-usage](zappier/jobs/report-usage.md) +- [zappier/ledger](zappier/ledger.md) - [zappier/meter](zappier/meter.md) - [zappier/nats-shim.d](zappier/nats-shim.d.md) - [zappier/paths](zappier/paths.md) @@ -121,6 +122,7 @@ One MD file per source module. - [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/persist](zappier-account-balance/persist.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) @@ -136,5 +138,14 @@ One MD file per source module. - [verae-access-web/gate](verae-access-web/gate.md) - [verae-access-web/server](verae-access-web/server.md) - [verae-access-api/server](verae-access-api/server.md) +- [verae-access-leaf/allow](verae-access-leaf/allow.md) - [verae-access-leaf/server](verae-access-leaf/server.md) - [verae-access-zapier/server](verae-access-zapier/server.md) +- [verae-access-staff/server](verae-access-staff/server.md) +- [zappier-identity/ids](zappier-identity/ids.md) +- [zappier-identity/server](zappier-identity/server.md) +- [zappier-identity/store](zappier-identity/store.md) +- [zappier-identity/subjects](zappier-identity/subjects.md) +- [verae-jobs-events/server](verae-jobs-events/server.md) +- [verae-jobs-events/subjects](verae-jobs-events/subjects.md) +- [verae-nats-accounts/policy](verae-nats-accounts/policy.md) diff --git a/docs/modules/verae-access-leaf/allow.md b/docs/modules/verae-access-leaf/allow.md new file mode 100644 index 0000000..1e1b106 --- /dev/null +++ b/docs/modules/verae-access-leaf/allow.md @@ -0,0 +1,41 @@ +# `verae-access-leaf/allow` + +**Package:** `verae-access-leaf` +**Source:** `packages/verae-access-leaf/src/allow.js` +**Lines:** 29 + +## What this module is + +Implementation module in `verae-access-leaf`. The tables below are extracted from the source (signatures + JSDoc). + +## Exports + +`leafAllowList`, `leafAllowed` + +## Types / interfaces / classes + +_None extracted._ + +## Functions + +| Name | Parameters | Param types (JSDoc) | Returns | Calls (same file / helpers) | +|------|------------|---------------------|---------|-----------------------------| +| `leafAllowList` | `(none)` | — | `unknown` | see Call graph | +| `leafAllowed` | `subject` | — | `unknown` | see Call graph | + +## What it imports / requires + +- `node:fs` + +## Call graph (identifiers invoked) + +`leafAllowList`, `existsSync`, `parse`, `readFileSync`, `leafAllowed`, `some`, `endsWith`, `startsWith` + +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`. + diff --git a/docs/modules/verae-access-leaf/server.md b/docs/modules/verae-access-leaf/server.md index d7b1fba..ad42867 100644 --- a/docs/modules/verae-access-leaf/server.md +++ b/docs/modules/verae-access-leaf/server.md @@ -2,7 +2,7 @@ **Package:** `verae-access-leaf` **Source:** `packages/verae-access-leaf/src/server.js` -**Lines:** 95 +**Lines:** 99 ## What this module is @@ -29,10 +29,11 @@ _None extracted._ ## What it imports / requires - `node:http` +- `./allow.js` ## Call graph (identifiers invoked) -`subjects`, `replace`, `check`, `fetch`, `stringify`, `json`, `authorizedToken`, `forward`, `import`, `connect`, `split`, `publish`, `encode`, `flush`, `close`, `startNats`, `async`, `subscribe`, `parse`, `decode`, `respond`, `write`, `createServer`, `writeHead`, `end`, `push`, `concat`, `toString`, `listen` +`subjects`, `replace`, `check`, `fetch`, `stringify`, `json`, `authorizedToken`, `forward`, `leafAllowed`, `import`, `connect`, `split`, `publish`, `encode`, `flush`, `close`, `startNats`, `async`, `subscribe`, `parse`, `decode`, `respond`, `write`, `createServer`, `writeHead`, `end`, `push`, `concat`, `toString`, `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. diff --git a/docs/modules/verae-access-staff/server.md b/docs/modules/verae-access-staff/server.md new file mode 100644 index 0000000..2f2291d --- /dev/null +++ b/docs/modules/verae-access-staff/server.md @@ -0,0 +1,41 @@ +# `verae-access-staff/server` + +**Package:** `verae-access-staff` +**Source:** `packages/verae-access-staff/src/server.js` +**Lines:** 58 + +## What this module is + +Implementation module in `verae-access-staff`. 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) | +|------|------------|---------------------|---------|-----------------------------| +| `check` | `subject, extra = {}` | — | `unknown` | see Call graph | +| `json` | `code, obj` | — | `unknown` | see Call graph | + +## What it imports / requires + +- `node:http` + +## Call graph (identifiers invoked) + +`plane`, `replace`, `check`, `fetch`, `stringify`, `json`, `createServer`, `async`, `writeHead`, `end`, `match`, `push`, `parse`, `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`. + diff --git a/docs/modules/verae-fleet/cli.md b/docs/modules/verae-fleet/cli.md index 3fb56ae..a72ea69 100644 --- a/docs/modules/verae-fleet/cli.md +++ b/docs/modules/verae-fleet/cli.md @@ -50,7 +50,7 @@ _None extracted._ ## Call graph (identifiers invoked) -`loadFleet`, `slice`, `print`, `write`, `stringify`, `help`, `off`, `pause`, `json`, `identityFile`, `login`, `api`, `request`, `on`, `push`, `concat`, `toString`, `resolve`, `parse`, `end`, `main`, `listServices`, `padEnd`, `padStart`, `import`, `find`, `sshCheck`, `keys`, `startService`, `tick`, `start`, `startControlServer`, `async`, `stop`, `stopAll`, `exit`, `test` +`loadFleet`, `slice`, `print`, `write`, `stringify`, `help`, `off`, `pause`, `json`, `identityFile`, `login`, `api`, `request`, `on`, `push`, `concat`, `toString`, `resolve`, `parse`, `end`, `main`, `listServices`, `padEnd`, `padStart`, `import`, `find`, `sshCheck`, `startControlServer`, `keys`, `startService`, `tick`, `start`, `async`, `stop`, `stopAll`, `exit`, `test` 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. diff --git a/docs/modules/verae-fleet/machines.md b/docs/modules/verae-fleet/machines.md index 628911d..54ad618 100644 --- a/docs/modules/verae-fleet/machines.md +++ b/docs/modules/verae-fleet/machines.md @@ -2,7 +2,7 @@ **Package:** `verae-fleet` **Source:** `packages/verae-fleet/src/machines.js` -**Lines:** 108 +**Lines:** 116 ## What this module is @@ -25,7 +25,7 @@ _None extracted._ | `normalizeMachine` | `m` | — | `unknown` | see Call graph | | `upsertMachine` | `list, spec` | — | `unknown` | see Call graph | | `canHost` | `machine, serviceId, role` | — | `unknown` | see Call graph | -| `pickMachine` | `machines, instances, serviceId, role, exclude = []` | machines: `object[]`, serviceId: `string`, role: `string` | `unknown` | see Call graph | +| `pickMachine` | `machines, instances, serviceId, role, exclude = [], opts = {}` | machines: `object[]`, serviceId: `string`, role: `string` | `unknown` | see Call graph | | `saveOverlay` | `overlayPath, machines` | — | `unknown` | see Call graph | ## What it imports / requires diff --git a/docs/modules/verae-fleet/server.md b/docs/modules/verae-fleet/server.md index 35986c3..ca86400 100644 --- a/docs/modules/verae-fleet/server.md +++ b/docs/modules/verae-fleet/server.md @@ -34,7 +34,7 @@ _None extracted._ ## Call graph (identifiers invoked) -`join`, `dirname`, `fileURLToPath`, `json`, `writeHead`, `end`, `stringify`, `import`, `startControlServer`, `createServer`, `async`, `snapshot`, `reset`, `push`, `parse`, `concat`, `toString`, `run`, `listServices`, `status`, `addMachine`, `match`, `checkMachine`, `setMachineEnabled`, `reconcile`, `startService`, `stopService`, `pauseService`, `resumeService`, `fn`, `pauseInstance`, `resumeInstance`, `restartInstance`, `stopInstance`, `markUnhealthy`, `createReadStream`, `pipe`, `startsWith`, `normalize`, `existsSync`, `statSync`, `isFile`, `extname`, `toLowerCase`, `listen`, `write` +`bind`, `join`, `dirname`, `fileURLToPath`, `json`, `writeHead`, `end`, `stringify`, `import`, `startControlServer`, `createServer`, `async`, `snapshot`, `reset`, `push`, `parse`, `concat`, `toString`, `run`, `listServices`, `status`, `addMachine`, `match`, `checkMachine`, `setMachineEnabled`, `reconcile`, `startService`, `stopService`, `pauseService`, `resumeService`, `fn`, `pauseInstance`, `resumeInstance`, `restartInstance`, `stopInstance`, `markUnhealthy`, `createReadStream`, `pipe`, `startsWith`, `normalize`, `existsSync`, `statSync`, `isFile`, `extname`, `toLowerCase`, `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. diff --git a/docs/modules/verae-fleet/ssh.md b/docs/modules/verae-fleet/ssh.md index d6bff8d..3e138cb 100644 --- a/docs/modules/verae-fleet/ssh.md +++ b/docs/modules/verae-fleet/ssh.md @@ -25,7 +25,7 @@ _None extracted._ | `sshTarget` | `machine` | — | `unknown` | see Call graph | | `sshBaseArgs` | `machine` | — | `unknown` | see Call graph | | `scpBaseArgs` | `machine` | — | `unknown` | see Call graph | -| `sshExec` | `machine, remoteCommand, { timeoutMs = 20000 } = {}` | — | `unknown` | see Call graph | +| `sshExec` | `machine, remoteCommand, { timeoutMs = 8000 } = {}` | — | `unknown` | see Call graph | | `scpTo` | `machine, localFiles, remoteDir` | — | `unknown` | see Call graph | | `ensureRemoteRuntime` | `machine` | — | `unknown` | see Call graph | | `sshSpawnWorker` | `machine, { instance, env }` | — | `unknown` | see Call graph | diff --git a/docs/modules/verae-fleet/supervisor.md b/docs/modules/verae-fleet/supervisor.md index e778499..6f86342 100644 --- 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:** 528 +**Lines:** 529 ## What this module is diff --git a/docs/modules/verae-jobs-events/server.md b/docs/modules/verae-jobs-events/server.md new file mode 100644 index 0000000..deab523 --- /dev/null +++ b/docs/modules/verae-jobs-events/server.md @@ -0,0 +1,41 @@ +# `verae-jobs-events/server` + +**Package:** `verae-jobs-events` +**Source:** `packages/verae-jobs-events/src/server.js` +**Lines:** 43 + +## What this module is + +Implementation module in `verae-jobs-events`. 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 | + +## What it imports / requires + +- `node:http` +- `./subjects.js` + +## Call graph (identifiers invoked) + +`startNats`, `import`, `connect`, `split`, `subscribe`, `parse`, `decode`, `respond`, `encode`, `stringify`, `createServer`, `writeHead`, `end`, `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`. + diff --git a/docs/modules/verae-jobs-events/subjects.md b/docs/modules/verae-jobs-events/subjects.md new file mode 100644 index 0000000..1083d72 --- /dev/null +++ b/docs/modules/verae-jobs-events/subjects.md @@ -0,0 +1,36 @@ +# `verae-jobs-events/subjects` + +**Package:** `verae-jobs-events` +**Source:** `packages/verae-jobs-events/src/subjects.js` +**Lines:** 5 + +## What this module is + +Implementation module in `verae-jobs-events`. 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`. + diff --git a/docs/modules/verae-nats-accounts/policy.md b/docs/modules/verae-nats-accounts/policy.md new file mode 100644 index 0000000..7248be3 --- /dev/null +++ b/docs/modules/verae-nats-accounts/policy.md @@ -0,0 +1,43 @@ +# `verae-nats-accounts/policy` + +**Package:** `verae-nats-accounts` +**Source:** `packages/verae-nats-accounts/src/policy.js` +**Lines:** 15 + +## What this module is + +Implementation module in `verae-nats-accounts`. The tables below are extracted from the source (signatures + JSDoc). + +## Exports + +`loadPolicy`, `leafAllowed` + +## Types / interfaces / classes + +_None extracted._ + +## Functions + +| Name | Parameters | Param types (JSDoc) | Returns | Calls (same file / helpers) | +|------|------------|---------------------|---------|-----------------------------| +| `loadPolicy` | `(none)` | — | `unknown` | see Call graph | +| `leafAllowed` | `subject` | — | `unknown` | see Call graph | + +## What it imports / requires + +- `node:fs` +- `node:path` +- `node:url` + +## Call graph (identifiers invoked) + +`join`, `dirname`, `fileURLToPath`, `loadPolicy`, `parse`, `readFileSync`, `leafAllowed`, `some`, `endsWith`, `startsWith` + +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`. + diff --git a/docs/modules/verae-zapier-simulator/server.md b/docs/modules/verae-zapier-simulator/server.md index ab03284..4644bf8 100644 --- a/docs/modules/verae-zapier-simulator/server.md +++ b/docs/modules/verae-zapier-simulator/server.md @@ -2,7 +2,7 @@ **Package:** `verae-zapier-simulator` **Source:** `packages/verae-zapier-simulator/src/server.js` -**Lines:** 87 +**Lines:** 88 ## What this module is diff --git a/docs/modules/zappier-account-balance/books.md b/docs/modules/zappier-account-balance/books.md index 49dc16d..5f5e467 100644 --- a/docs/modules/zappier-account-balance/books.md +++ b/docs/modules/zappier-account-balance/books.md @@ -2,7 +2,7 @@ **Package:** `zappier-account-balance` **Source:** `packages/zappier-account-balance/src/books.js` -**Lines:** 100 +**Lines:** 120 ## What this module is @@ -36,6 +36,8 @@ Implementation module in `zappier-account-balance`. The tables below are extract | `recordUsage` | `entry` | | `recordPayment` | `entry` | | `statement` | `customerId` | +| `dump` | `(none)` | +| `load` | `raw` | ## What it imports / requires @@ -43,7 +45,7 @@ _No imports detected._ ## Call graph (identifiers invoked) -`constructor`, `remember`, `prepaidCents`, `adjust`, `trunc`, `now`, `toString`, `random`, `slice`, `toISOString`, `unshift`, `recordUsage`, `recordPayment`, `statement`, `filter`, `match`, `handle`, `endsWith` +`constructor`, `remember`, `prepaidCents`, `adjust`, `trunc`, `now`, `toString`, `random`, `slice`, `toISOString`, `unshift`, `recordUsage`, `recordPayment`, `statement`, `filter`, `match`, `dump`, `load`, `isArray`, `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. diff --git a/docs/modules/zappier-account-balance/persist.md b/docs/modules/zappier-account-balance/persist.md new file mode 100644 index 0000000..0be5a03 --- /dev/null +++ b/docs/modules/zappier-account-balance/persist.md @@ -0,0 +1,50 @@ +# `zappier-account-balance/persist` + +**Package:** `zappier-account-balance` +**Source:** `packages/zappier-account-balance/src/persist.js` +**Lines:** 29 + +## What this module is + +Implementation module in `zappier-account-balance`. The tables below are extracted from the source (signatures + JSDoc). + +## Exports + +`booksPath`, `loadInto`, `saveFrom` + +## Types / interfaces / classes + +_None extracted._ + +## Functions + +| Name | Parameters | Param types (JSDoc) | Returns | Calls (same file / helpers) | +|------|------------|---------------------|---------|-----------------------------| +| `booksPath` | `(none)` | — | `unknown` | see Call graph | +| `loadInto` | `books` | — | `unknown` | see Call graph | +| `saveFrom` | `books` | — | `unknown` | see Call graph | + +## Methods (class / object) + +| Name | Parameters | +|------|------------| +| `return` | `process.env.BOOKS_PATH || + path.join(process.env.FLEET_STATE_DIR || process.cwd(` | + +## What it imports / requires + +- `node:fs` +- `node:path` + +## Call graph (identifiers invoked) + +`booksPath`, `join`, `cwd`, `loadInto`, `existsSync`, `load`, `parse`, `readFileSync`, `saveFrom`, `mkdirSync`, `dirname`, `writeFileSync`, `stringify`, `dump`, `renameSync` + +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`. + diff --git a/docs/modules/zappier-account-balance/server.md b/docs/modules/zappier-account-balance/server.md index 6b1858a..00d8a73 100644 --- a/docs/modules/zappier-account-balance/server.md +++ b/docs/modules/zappier-account-balance/server.md @@ -2,7 +2,7 @@ **Package:** `zappier-account-balance` **Source:** `packages/zappier-account-balance/src/server.js` -**Lines:** 93 +**Lines:** 101 ## What this module is @@ -20,6 +20,7 @@ _None extracted._ | Name | Parameters | Param types (JSDoc) | Returns | Calls (same file / helpers) | |------|------------|---------------------|---------|-----------------------------| +| `apply` | `subject, payload` | — | `unknown` | see Call graph | | `startNats` | `(none)` | — | `unknown` | see Call graph | | `readBody` | `req` | — | `unknown` | see Call graph | | `reply` | `sub, fn` | — | `unknown` | see Call graph | @@ -29,6 +30,7 @@ _None extracted._ | Name | Parameters | |------|------------| +| `saveFrom` | `books` | | `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 }` | @@ -38,10 +40,11 @@ _None extracted._ - `node:http` - `./books.js` - `./subjects.js` +- `./persist.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` +`loadInto`, `apply`, `handle`, `saveFrom`, `startNats`, `import`, `connect`, `split`, `async`, `parse`, `decode`, `fn`, `respond`, `encode`, `stringify`, `reply`, `subscribe`, `write`, `readBody`, `on`, `push`, `resolve`, `concat`, `toString`, `createServer`, `writeHead`, `end`, `json`, `match`, `statement`, `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. diff --git a/docs/modules/zappier-identity/ids.md b/docs/modules/zappier-identity/ids.md new file mode 100644 index 0000000..2628937 --- /dev/null +++ b/docs/modules/zappier-identity/ids.md @@ -0,0 +1,41 @@ +# `zappier-identity/ids` + +**Package:** `zappier-identity` +**Source:** `packages/zappier-identity/src/ids.js` +**Lines:** 16 + +## What this module is + +Implementation module in `zappier-identity`. The tables below are extracted from the source (signatures + JSDoc). + +## Exports + +`stableVeraeUserId`, `bindEmail` + +## Types / interfaces / classes + +_None extracted._ + +## Functions + +| Name | Parameters | Param types (JSDoc) | Returns | Calls (same file / helpers) | +|------|------------|---------------------|---------|-----------------------------| +| `stableVeraeUserId` | `username` | — | `unknown` | see Call graph | +| `bindEmail` | `email` | — | `unknown` | see Call graph | + +## What it imports / requires + +- `node:crypto` + +## Call graph (identifiers invoked) + +`stableVeraeUserId`, `trim`, `toLowerCase`, `createHash`, `update`, `digest`, `slice`, `bindEmail` + +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`. + diff --git a/docs/modules/zappier-identity/server.md b/docs/modules/zappier-identity/server.md new file mode 100644 index 0000000..aec4169 --- /dev/null +++ b/docs/modules/zappier-identity/server.md @@ -0,0 +1,53 @@ +# `zappier-identity/server` + +**Package:** `zappier-identity` +**Source:** `packages/zappier-identity/src/server.js` +**Lines:** 90 + +## What this module is + +Implementation module in `zappier-identity`. 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) | +|------|------------|---------------------|---------|-----------------------------| +| `handleBind` | `p` | — | `unknown` | see Call graph | +| `handleLookup` | `p` | — | `unknown` | see Call graph | +| `startNats` | `(none)` | — | `unknown` | see Call graph | +| `readBody` | `req` | — | `unknown` | see Call graph | +| `json` | `code, obj` | — | `unknown` | see Call graph | + +## Methods (class / object) + +| Name | Parameters | +|------|------------| +| `put` | `db, { customerId, ...bound }` | + +## What it imports / requires + +- `node:http` +- `./ids.js` +- `./store.js` +- `./subjects.js` + +## Call graph (identifiers invoked) + +`load`, `handleBind`, `bindEmail`, `put`, `handleLookup`, `startNats`, `import`, `connect`, `split`, `async`, `subscribe`, `parse`, `decode`, `respond`, `encode`, `stringify`, `readBody`, `on`, `push`, `resolve`, `concat`, `toString`, `createServer`, `writeHead`, `end`, `json`, `match`, `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`. + diff --git a/docs/modules/zappier-identity/store.md b/docs/modules/zappier-identity/store.md new file mode 100644 index 0000000..fcdd798 --- /dev/null +++ b/docs/modules/zappier-identity/store.md @@ -0,0 +1,50 @@ +# `zappier-identity/store` + +**Package:** `zappier-identity` +**Source:** `packages/zappier-identity/src/store.js` +**Lines:** 31 + +## What this module is + +Implementation module in `zappier-identity`. The tables below are extracted from the source (signatures + JSDoc). + +## Exports + +`load`, `save`, `put` + +## Types / interfaces / classes + +_None extracted._ + +## Functions + +| Name | Parameters | Param types (JSDoc) | Returns | Calls (same file / helpers) | +|------|------------|---------------------|---------|-----------------------------| +| `load` | `(none)` | — | `unknown` | see Call graph | +| `save` | `db` | — | `unknown` | see Call graph | +| `put` | `db, { customerId, veraeUserId, veraeUsername }` | — | `unknown` | see Call graph | +| `file` | `(none)` | — | `unknown` | see Call graph | + +## Methods (class / object) + +| Name | Parameters | +|------|------------| +| `save` | `db` | + +## What it imports / requires + +- `node:fs` +- `node:path` + +## Call graph (identifiers invoked) + +`join`, `cwd`, `load`, `file`, `existsSync`, `parse`, `readFileSync`, `save`, `mkdirSync`, `dirname`, `writeFileSync`, `stringify`, `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. + +## 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`. + diff --git a/docs/modules/zappier-identity/subjects.md b/docs/modules/zappier-identity/subjects.md new file mode 100644 index 0000000..063e79c --- /dev/null +++ b/docs/modules/zappier-identity/subjects.md @@ -0,0 +1,36 @@ +# `zappier-identity/subjects` + +**Package:** `zappier-identity` +**Source:** `packages/zappier-identity/src/subjects.js` +**Lines:** 6 + +## What this module is + +Implementation module in `zappier-identity`. 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`. + diff --git a/docs/modules/zappier/admin.md b/docs/modules/zappier/admin.md index 96e67cd..6180d66 100644 --- 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:** 593 +**Lines:** 597 ## What this module is @@ -63,10 +63,11 @@ Implementation module in `zappier`. The tables below are extracted from the sour - `./accounting-export` - `./statement` - `./billing-nats` +- `./ledger` ## 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`, `isFinite`, `trunc`, `add`, `natsPublish`, `natsAdjust`, `async`, `natsStatement`, `composeStatement`, `listFor`, `type`, `send` +`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`, `async`, `isFinite`, `trunc`, `add`, `ledgerAdjust`, `booksConfigured`, `natsPublish`, `ledgerStatement`, `composeStatement`, `listFor`, `type` 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. diff --git a/docs/modules/zappier/index.md b/docs/modules/zappier/index.md index 7214325..dab278a 100644 --- a/docs/modules/zappier/index.md +++ b/docs/modules/zappier/index.md @@ -2,7 +2,7 @@ **Package:** `zappier` **Source:** `packages/zappier/src/index.ts` -**Lines:** 42 +**Lines:** 43 ## What this module is diff --git a/docs/modules/zappier/ledger.md b/docs/modules/zappier/ledger.md new file mode 100644 index 0000000..4f7e82a --- /dev/null +++ b/docs/modules/zappier/ledger.md @@ -0,0 +1,52 @@ +# `zappier/ledger` + +**Package:** `zappier` +**Source:** `packages/zappier/src/ledger.ts` +**Lines:** 51 + +## What this module is + +Implementation module in `zappier`. The tables below are extracted from the source (signatures + JSDoc). + +## Exports + +`PrepaidRow`, `booksConfigured`, `ledgerAdjust`, `ledgerStatement` + +## Types / interfaces / classes + +| Kind | Name | +|------|------| +| type | `PrepaidRow` | + +## Functions + +| Name | Parameters | Param types (JSDoc) | Returns | Calls (same file / helpers) | +|------|------------|---------------------|---------|-----------------------------| +| `booksUrl` | `(none)` | — | `unknown` | see Call graph | +| `booksConfigured` | `(none)` | — | `unknown` | see Call graph | +| `ledgerAdjust` | `row: PrepaidRow, plane: AccessPlane` | — | `unknown` | see Call graph | +| `ledgerStatement` | `customerId: string, plane: AccessPlane, veraeUserId?: string` | — | `unknown` | see Call graph | + +## Methods (class / object) + +| Name | Parameters | +|------|------------| +| `return` | `process.env.ACCOUNT_BALANCE_URL || ''` | +| `return` | `await r.json(` | + +## What it imports / requires + +- `./billing-nats` + +## Call graph (identifiers invoked) + +`booksUrl`, `replace`, `booksConfigured`, `ledgerAdjust`, `natsAdjust`, `fetch`, `stringify`, `json`, `ledgerStatement`, `natsStatement`, `encodeURIComponent` + +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`. + diff --git a/docs/modules/zappier/portal.md b/docs/modules/zappier/portal.md index 4c31a9c..25d9df7 100644 --- a/docs/modules/zappier/portal.md +++ b/docs/modules/zappier/portal.md @@ -52,10 +52,11 @@ Implementation module in `zappier`. The tables below are extracted from the sour - `./statement` - `./billing-nats` - `./verae-bind` +- `./ledger` ## Call graph (identifiers invoked) -`now`, `reload`, `customer`, `publicProfile`, `sessionAuth`, `header`, `startsWith`, `slice`, `get`, `list`, `find`, `status`, `json`, `next`, `save`, `portalRouter`, `post`, `async`, `trim`, `test`, `hashPassword`, `findByEmail`, `randomBytes`, `toString`, `bindVeraeUser`, `create`, `verifyPassword`, `verifyTotp`, `use`, `delete`, `setUTCDate`, `setUTCHours`, `summaryFor`, `tiers`, `applyMonthlyCredit`, `rateCard`, `natsStatement`, `composeStatement`, `listFor`, `type`, `send`, `renderInvoiceHtml`, `generateTotpSecret`, `totpUri`, `qr`, `isInteger`, `natsPublish`, `natsAdjust`, `put` +`now`, `reload`, `customer`, `publicProfile`, `sessionAuth`, `header`, `startsWith`, `slice`, `get`, `list`, `find`, `status`, `json`, `next`, `save`, `portalRouter`, `post`, `async`, `trim`, `test`, `hashPassword`, `findByEmail`, `randomBytes`, `toString`, `bindVeraeUser`, `create`, `verifyPassword`, `verifyTotp`, `use`, `delete`, `setUTCDate`, `setUTCHours`, `summaryFor`, `tiers`, `applyMonthlyCredit`, `rateCard`, `ledgerStatement`, `composeStatement`, `listFor`, `type`, `send`, `renderInvoiceHtml`, `generateTotpSecret`, `totpUri`, `qr`, `isInteger`, `ledgerAdjust`, `booksConfigured`, `natsPublish`, `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. diff --git a/docs/modules/zappier/verae-bind.md b/docs/modules/zappier/verae-bind.md index 30f3320..547bb4c 100644 --- a/docs/modules/zappier/verae-bind.md +++ b/docs/modules/zappier/verae-bind.md @@ -2,7 +2,7 @@ **Package:** `zappier` **Source:** `packages/zappier/src/verae-bind.ts` -**Lines:** 77 +**Lines:** 90 ## What this module is @@ -25,7 +25,7 @@ Implementation module in `zappier`. The tables below are extracted from the sour | `normalizeVeraeUsername` | `username: string` | — | `unknown` | see Call graph | | `stableVeraeUserId` | `username: string` | — | `unknown` | see Call graph | | `mockBind` | `email: string` | — | `unknown` | see Call graph | -| `bindVeraeUser` | `email: string` | — | `unknown` | see Call graph | +| `bindVeraeUser` | `email: string, customerId?: string` | — | `unknown` | see Call graph | | `login` | `username: string, pass: string` | — | `unknown` | see Call graph | ## What it imports / requires @@ -34,7 +34,7 @@ Implementation module in `zappier`. The tables below are extracted from the sour ## Call graph (identifiers invoked) -`normalizeVeraeUsername`, `trim`, `toLowerCase`, `stableVeraeUserId`, `createHash`, `update`, `digest`, `slice`, `mockBind`, `bindVeraeUser`, `replace`, `randomBytes`, `toString`, `async`, `fetch`, `stringify`, `json`, `login` +`normalizeVeraeUsername`, `trim`, `toLowerCase`, `stableVeraeUserId`, `createHash`, `update`, `digest`, `slice`, `mockBind`, `bindVeraeUser`, `replace`, `fetch`, `stringify`, `json`, `randomBytes`, `toString`, `async`, `login` 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. diff --git a/docs/sphinx/index.rst b/docs/sphinx/index.rst index 47e4264..d9ebf5e 100644 --- a/docs/sphinx/index.rst +++ b/docs/sphinx/index.rst @@ -33,6 +33,11 @@ Markdown indexes: https://zapier.georgelambert.org/index-md.html repos/verae-access-api repos/verae-access-leaf repos/verae-access-zapier + repos/verae-access-staff + repos/zappier-identity + repos/verae-jobs-events + repos/verae-nats-accounts + repos/zapier-decisions .. toctree:: :maxdepth: 2 @@ -59,6 +64,7 @@ Markdown indexes: https://zapier.georgelambert.org/index-md.html modules/zappier/index modules/zappier/invoicing modules/zappier/jobs/report-usage + modules/zappier/ledger modules/zappier/meter modules/zappier/nats-shim.d modules/zappier/paths @@ -157,6 +163,7 @@ Markdown indexes: https://zapier.georgelambert.org/index-md.html modules/verae-zapier-simulator/server modules/verae-zapier-simulator/trace modules/zappier-account-balance/books + modules/zappier-account-balance/persist modules/zappier-account-balance/server modules/zappier-account-balance/subjects modules/zappier-customer-service/nats-billing @@ -172,5 +179,14 @@ Markdown indexes: https://zapier.georgelambert.org/index-md.html modules/verae-access-web/gate modules/verae-access-web/server modules/verae-access-api/server + modules/verae-access-leaf/allow modules/verae-access-leaf/server modules/verae-access-zapier/server + modules/verae-access-staff/server + modules/zappier-identity/ids + modules/zappier-identity/server + modules/zappier-identity/store + modules/zappier-identity/subjects + modules/verae-jobs-events/server + modules/verae-jobs-events/subjects + modules/verae-nats-accounts/policy diff --git a/docs/sphinx/modules/verae-access-leaf/allow.md b/docs/sphinx/modules/verae-access-leaf/allow.md new file mode 100644 index 0000000..1e1b106 --- /dev/null +++ b/docs/sphinx/modules/verae-access-leaf/allow.md @@ -0,0 +1,41 @@ +# `verae-access-leaf/allow` + +**Package:** `verae-access-leaf` +**Source:** `packages/verae-access-leaf/src/allow.js` +**Lines:** 29 + +## What this module is + +Implementation module in `verae-access-leaf`. The tables below are extracted from the source (signatures + JSDoc). + +## Exports + +`leafAllowList`, `leafAllowed` + +## Types / interfaces / classes + +_None extracted._ + +## Functions + +| Name | Parameters | Param types (JSDoc) | Returns | Calls (same file / helpers) | +|------|------------|---------------------|---------|-----------------------------| +| `leafAllowList` | `(none)` | — | `unknown` | see Call graph | +| `leafAllowed` | `subject` | — | `unknown` | see Call graph | + +## What it imports / requires + +- `node:fs` + +## Call graph (identifiers invoked) + +`leafAllowList`, `existsSync`, `parse`, `readFileSync`, `leafAllowed`, `some`, `endsWith`, `startsWith` + +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`. + diff --git a/docs/sphinx/modules/verae-access-leaf/allow.rst b/docs/sphinx/modules/verae-access-leaf/allow.rst new file mode 100644 index 0000000..84f8e3d --- /dev/null +++ b/docs/sphinx/modules/verae-access-leaf/allow.rst @@ -0,0 +1,7 @@ +verae-access-leaf.allow +======================= + +Generated API sheet for ``verae-access-leaf/allow``. + +.. include:: allow.md + :parser: myst_parser.sphinx_ diff --git a/docs/sphinx/modules/verae-access-leaf/server.md b/docs/sphinx/modules/verae-access-leaf/server.md index d7b1fba..ad42867 100644 --- a/docs/sphinx/modules/verae-access-leaf/server.md +++ b/docs/sphinx/modules/verae-access-leaf/server.md @@ -2,7 +2,7 @@ **Package:** `verae-access-leaf` **Source:** `packages/verae-access-leaf/src/server.js` -**Lines:** 95 +**Lines:** 99 ## What this module is @@ -29,10 +29,11 @@ _None extracted._ ## What it imports / requires - `node:http` +- `./allow.js` ## Call graph (identifiers invoked) -`subjects`, `replace`, `check`, `fetch`, `stringify`, `json`, `authorizedToken`, `forward`, `import`, `connect`, `split`, `publish`, `encode`, `flush`, `close`, `startNats`, `async`, `subscribe`, `parse`, `decode`, `respond`, `write`, `createServer`, `writeHead`, `end`, `push`, `concat`, `toString`, `listen` +`subjects`, `replace`, `check`, `fetch`, `stringify`, `json`, `authorizedToken`, `forward`, `leafAllowed`, `import`, `connect`, `split`, `publish`, `encode`, `flush`, `close`, `startNats`, `async`, `subscribe`, `parse`, `decode`, `respond`, `write`, `createServer`, `writeHead`, `end`, `push`, `concat`, `toString`, `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. diff --git a/docs/sphinx/modules/verae-access-staff/server.md b/docs/sphinx/modules/verae-access-staff/server.md new file mode 100644 index 0000000..2f2291d --- /dev/null +++ b/docs/sphinx/modules/verae-access-staff/server.md @@ -0,0 +1,41 @@ +# `verae-access-staff/server` + +**Package:** `verae-access-staff` +**Source:** `packages/verae-access-staff/src/server.js` +**Lines:** 58 + +## What this module is + +Implementation module in `verae-access-staff`. 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) | +|------|------------|---------------------|---------|-----------------------------| +| `check` | `subject, extra = {}` | — | `unknown` | see Call graph | +| `json` | `code, obj` | — | `unknown` | see Call graph | + +## What it imports / requires + +- `node:http` + +## Call graph (identifiers invoked) + +`plane`, `replace`, `check`, `fetch`, `stringify`, `json`, `createServer`, `async`, `writeHead`, `end`, `match`, `push`, `parse`, `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`. + diff --git a/docs/sphinx/modules/verae-access-staff/server.rst b/docs/sphinx/modules/verae-access-staff/server.rst new file mode 100644 index 0000000..ce7df41 --- /dev/null +++ b/docs/sphinx/modules/verae-access-staff/server.rst @@ -0,0 +1,7 @@ +verae-access-staff.server +========================= + +Generated API sheet for ``verae-access-staff/server``. + +.. include:: server.md + :parser: myst_parser.sphinx_ diff --git a/docs/sphinx/modules/verae-fleet/cli.md b/docs/sphinx/modules/verae-fleet/cli.md index 3fb56ae..a72ea69 100644 --- a/docs/sphinx/modules/verae-fleet/cli.md +++ b/docs/sphinx/modules/verae-fleet/cli.md @@ -50,7 +50,7 @@ _None extracted._ ## Call graph (identifiers invoked) -`loadFleet`, `slice`, `print`, `write`, `stringify`, `help`, `off`, `pause`, `json`, `identityFile`, `login`, `api`, `request`, `on`, `push`, `concat`, `toString`, `resolve`, `parse`, `end`, `main`, `listServices`, `padEnd`, `padStart`, `import`, `find`, `sshCheck`, `keys`, `startService`, `tick`, `start`, `startControlServer`, `async`, `stop`, `stopAll`, `exit`, `test` +`loadFleet`, `slice`, `print`, `write`, `stringify`, `help`, `off`, `pause`, `json`, `identityFile`, `login`, `api`, `request`, `on`, `push`, `concat`, `toString`, `resolve`, `parse`, `end`, `main`, `listServices`, `padEnd`, `padStart`, `import`, `find`, `sshCheck`, `startControlServer`, `keys`, `startService`, `tick`, `start`, `async`, `stop`, `stopAll`, `exit`, `test` 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. diff --git a/docs/sphinx/modules/verae-fleet/machines.md b/docs/sphinx/modules/verae-fleet/machines.md index 628911d..54ad618 100644 --- a/docs/sphinx/modules/verae-fleet/machines.md +++ b/docs/sphinx/modules/verae-fleet/machines.md @@ -2,7 +2,7 @@ **Package:** `verae-fleet` **Source:** `packages/verae-fleet/src/machines.js` -**Lines:** 108 +**Lines:** 116 ## What this module is @@ -25,7 +25,7 @@ _None extracted._ | `normalizeMachine` | `m` | — | `unknown` | see Call graph | | `upsertMachine` | `list, spec` | — | `unknown` | see Call graph | | `canHost` | `machine, serviceId, role` | — | `unknown` | see Call graph | -| `pickMachine` | `machines, instances, serviceId, role, exclude = []` | machines: `object[]`, serviceId: `string`, role: `string` | `unknown` | see Call graph | +| `pickMachine` | `machines, instances, serviceId, role, exclude = [], opts = {}` | machines: `object[]`, serviceId: `string`, role: `string` | `unknown` | see Call graph | | `saveOverlay` | `overlayPath, machines` | — | `unknown` | see Call graph | ## What it imports / requires diff --git a/docs/sphinx/modules/verae-fleet/server.md b/docs/sphinx/modules/verae-fleet/server.md index 35986c3..ca86400 100644 --- a/docs/sphinx/modules/verae-fleet/server.md +++ b/docs/sphinx/modules/verae-fleet/server.md @@ -34,7 +34,7 @@ _None extracted._ ## Call graph (identifiers invoked) -`join`, `dirname`, `fileURLToPath`, `json`, `writeHead`, `end`, `stringify`, `import`, `startControlServer`, `createServer`, `async`, `snapshot`, `reset`, `push`, `parse`, `concat`, `toString`, `run`, `listServices`, `status`, `addMachine`, `match`, `checkMachine`, `setMachineEnabled`, `reconcile`, `startService`, `stopService`, `pauseService`, `resumeService`, `fn`, `pauseInstance`, `resumeInstance`, `restartInstance`, `stopInstance`, `markUnhealthy`, `createReadStream`, `pipe`, `startsWith`, `normalize`, `existsSync`, `statSync`, `isFile`, `extname`, `toLowerCase`, `listen`, `write` +`bind`, `join`, `dirname`, `fileURLToPath`, `json`, `writeHead`, `end`, `stringify`, `import`, `startControlServer`, `createServer`, `async`, `snapshot`, `reset`, `push`, `parse`, `concat`, `toString`, `run`, `listServices`, `status`, `addMachine`, `match`, `checkMachine`, `setMachineEnabled`, `reconcile`, `startService`, `stopService`, `pauseService`, `resumeService`, `fn`, `pauseInstance`, `resumeInstance`, `restartInstance`, `stopInstance`, `markUnhealthy`, `createReadStream`, `pipe`, `startsWith`, `normalize`, `existsSync`, `statSync`, `isFile`, `extname`, `toLowerCase`, `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. diff --git a/docs/sphinx/modules/verae-fleet/ssh.md b/docs/sphinx/modules/verae-fleet/ssh.md index d6bff8d..3e138cb 100644 --- a/docs/sphinx/modules/verae-fleet/ssh.md +++ b/docs/sphinx/modules/verae-fleet/ssh.md @@ -25,7 +25,7 @@ _None extracted._ | `sshTarget` | `machine` | — | `unknown` | see Call graph | | `sshBaseArgs` | `machine` | — | `unknown` | see Call graph | | `scpBaseArgs` | `machine` | — | `unknown` | see Call graph | -| `sshExec` | `machine, remoteCommand, { timeoutMs = 20000 } = {}` | — | `unknown` | see Call graph | +| `sshExec` | `machine, remoteCommand, { timeoutMs = 8000 } = {}` | — | `unknown` | see Call graph | | `scpTo` | `machine, localFiles, remoteDir` | — | `unknown` | see Call graph | | `ensureRemoteRuntime` | `machine` | — | `unknown` | see Call graph | | `sshSpawnWorker` | `machine, { instance, env }` | — | `unknown` | see Call graph | diff --git a/docs/sphinx/modules/verae-fleet/supervisor.md b/docs/sphinx/modules/verae-fleet/supervisor.md index e778499..6f86342 100644 --- a/docs/sphinx/modules/verae-fleet/supervisor.md +++ b/docs/sphinx/modules/verae-fleet/supervisor.md @@ -2,7 +2,7 @@ **Package:** `verae-fleet` **Source:** `packages/verae-fleet/src/supervisor.js` -**Lines:** 528 +**Lines:** 529 ## What this module is diff --git a/docs/sphinx/modules/verae-jobs-events/server.md b/docs/sphinx/modules/verae-jobs-events/server.md new file mode 100644 index 0000000..deab523 --- /dev/null +++ b/docs/sphinx/modules/verae-jobs-events/server.md @@ -0,0 +1,41 @@ +# `verae-jobs-events/server` + +**Package:** `verae-jobs-events` +**Source:** `packages/verae-jobs-events/src/server.js` +**Lines:** 43 + +## What this module is + +Implementation module in `verae-jobs-events`. 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 | + +## What it imports / requires + +- `node:http` +- `./subjects.js` + +## Call graph (identifiers invoked) + +`startNats`, `import`, `connect`, `split`, `subscribe`, `parse`, `decode`, `respond`, `encode`, `stringify`, `createServer`, `writeHead`, `end`, `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`. + diff --git a/docs/sphinx/modules/verae-jobs-events/server.rst b/docs/sphinx/modules/verae-jobs-events/server.rst new file mode 100644 index 0000000..1eb90e5 --- /dev/null +++ b/docs/sphinx/modules/verae-jobs-events/server.rst @@ -0,0 +1,7 @@ +verae-jobs-events.server +======================== + +Generated API sheet for ``verae-jobs-events/server``. + +.. include:: server.md + :parser: myst_parser.sphinx_ diff --git a/docs/sphinx/modules/verae-jobs-events/subjects.md b/docs/sphinx/modules/verae-jobs-events/subjects.md new file mode 100644 index 0000000..1083d72 --- /dev/null +++ b/docs/sphinx/modules/verae-jobs-events/subjects.md @@ -0,0 +1,36 @@ +# `verae-jobs-events/subjects` + +**Package:** `verae-jobs-events` +**Source:** `packages/verae-jobs-events/src/subjects.js` +**Lines:** 5 + +## What this module is + +Implementation module in `verae-jobs-events`. 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`. + diff --git a/docs/sphinx/modules/verae-jobs-events/subjects.rst b/docs/sphinx/modules/verae-jobs-events/subjects.rst new file mode 100644 index 0000000..6b2f825 --- /dev/null +++ b/docs/sphinx/modules/verae-jobs-events/subjects.rst @@ -0,0 +1,7 @@ +verae-jobs-events.subjects +========================== + +Generated API sheet for ``verae-jobs-events/subjects``. + +.. include:: subjects.md + :parser: myst_parser.sphinx_ diff --git a/docs/sphinx/modules/verae-nats-accounts/policy.md b/docs/sphinx/modules/verae-nats-accounts/policy.md new file mode 100644 index 0000000..7248be3 --- /dev/null +++ b/docs/sphinx/modules/verae-nats-accounts/policy.md @@ -0,0 +1,43 @@ +# `verae-nats-accounts/policy` + +**Package:** `verae-nats-accounts` +**Source:** `packages/verae-nats-accounts/src/policy.js` +**Lines:** 15 + +## What this module is + +Implementation module in `verae-nats-accounts`. The tables below are extracted from the source (signatures + JSDoc). + +## Exports + +`loadPolicy`, `leafAllowed` + +## Types / interfaces / classes + +_None extracted._ + +## Functions + +| Name | Parameters | Param types (JSDoc) | Returns | Calls (same file / helpers) | +|------|------------|---------------------|---------|-----------------------------| +| `loadPolicy` | `(none)` | — | `unknown` | see Call graph | +| `leafAllowed` | `subject` | — | `unknown` | see Call graph | + +## What it imports / requires + +- `node:fs` +- `node:path` +- `node:url` + +## Call graph (identifiers invoked) + +`join`, `dirname`, `fileURLToPath`, `loadPolicy`, `parse`, `readFileSync`, `leafAllowed`, `some`, `endsWith`, `startsWith` + +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`. + diff --git a/docs/sphinx/modules/verae-nats-accounts/policy.rst b/docs/sphinx/modules/verae-nats-accounts/policy.rst new file mode 100644 index 0000000..7264d4d --- /dev/null +++ b/docs/sphinx/modules/verae-nats-accounts/policy.rst @@ -0,0 +1,7 @@ +verae-nats-accounts.policy +========================== + +Generated API sheet for ``verae-nats-accounts/policy``. + +.. include:: policy.md + :parser: myst_parser.sphinx_ diff --git a/docs/sphinx/modules/verae-zapier-simulator/server.md b/docs/sphinx/modules/verae-zapier-simulator/server.md index ab03284..4644bf8 100644 --- a/docs/sphinx/modules/verae-zapier-simulator/server.md +++ b/docs/sphinx/modules/verae-zapier-simulator/server.md @@ -2,7 +2,7 @@ **Package:** `verae-zapier-simulator` **Source:** `packages/verae-zapier-simulator/src/server.js` -**Lines:** 87 +**Lines:** 88 ## What this module is diff --git a/docs/sphinx/modules/zappier-account-balance/books.md b/docs/sphinx/modules/zappier-account-balance/books.md index 49dc16d..5f5e467 100644 --- a/docs/sphinx/modules/zappier-account-balance/books.md +++ b/docs/sphinx/modules/zappier-account-balance/books.md @@ -2,7 +2,7 @@ **Package:** `zappier-account-balance` **Source:** `packages/zappier-account-balance/src/books.js` -**Lines:** 100 +**Lines:** 120 ## What this module is @@ -36,6 +36,8 @@ Implementation module in `zappier-account-balance`. The tables below are extract | `recordUsage` | `entry` | | `recordPayment` | `entry` | | `statement` | `customerId` | +| `dump` | `(none)` | +| `load` | `raw` | ## What it imports / requires @@ -43,7 +45,7 @@ _No imports detected._ ## Call graph (identifiers invoked) -`constructor`, `remember`, `prepaidCents`, `adjust`, `trunc`, `now`, `toString`, `random`, `slice`, `toISOString`, `unshift`, `recordUsage`, `recordPayment`, `statement`, `filter`, `match`, `handle`, `endsWith` +`constructor`, `remember`, `prepaidCents`, `adjust`, `trunc`, `now`, `toString`, `random`, `slice`, `toISOString`, `unshift`, `recordUsage`, `recordPayment`, `statement`, `filter`, `match`, `dump`, `load`, `isArray`, `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. diff --git a/docs/sphinx/modules/zappier-account-balance/persist.md b/docs/sphinx/modules/zappier-account-balance/persist.md new file mode 100644 index 0000000..0be5a03 --- /dev/null +++ b/docs/sphinx/modules/zappier-account-balance/persist.md @@ -0,0 +1,50 @@ +# `zappier-account-balance/persist` + +**Package:** `zappier-account-balance` +**Source:** `packages/zappier-account-balance/src/persist.js` +**Lines:** 29 + +## What this module is + +Implementation module in `zappier-account-balance`. The tables below are extracted from the source (signatures + JSDoc). + +## Exports + +`booksPath`, `loadInto`, `saveFrom` + +## Types / interfaces / classes + +_None extracted._ + +## Functions + +| Name | Parameters | Param types (JSDoc) | Returns | Calls (same file / helpers) | +|------|------------|---------------------|---------|-----------------------------| +| `booksPath` | `(none)` | — | `unknown` | see Call graph | +| `loadInto` | `books` | — | `unknown` | see Call graph | +| `saveFrom` | `books` | — | `unknown` | see Call graph | + +## Methods (class / object) + +| Name | Parameters | +|------|------------| +| `return` | `process.env.BOOKS_PATH || + path.join(process.env.FLEET_STATE_DIR || process.cwd(` | + +## What it imports / requires + +- `node:fs` +- `node:path` + +## Call graph (identifiers invoked) + +`booksPath`, `join`, `cwd`, `loadInto`, `existsSync`, `load`, `parse`, `readFileSync`, `saveFrom`, `mkdirSync`, `dirname`, `writeFileSync`, `stringify`, `dump`, `renameSync` + +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`. + diff --git a/docs/sphinx/modules/zappier-account-balance/persist.rst b/docs/sphinx/modules/zappier-account-balance/persist.rst new file mode 100644 index 0000000..bebe31f --- /dev/null +++ b/docs/sphinx/modules/zappier-account-balance/persist.rst @@ -0,0 +1,7 @@ +zappier-account-balance.persist +=============================== + +Generated API sheet for ``zappier-account-balance/persist``. + +.. include:: persist.md + :parser: myst_parser.sphinx_ diff --git a/docs/sphinx/modules/zappier-account-balance/server.md b/docs/sphinx/modules/zappier-account-balance/server.md index 6b1858a..00d8a73 100644 --- a/docs/sphinx/modules/zappier-account-balance/server.md +++ b/docs/sphinx/modules/zappier-account-balance/server.md @@ -2,7 +2,7 @@ **Package:** `zappier-account-balance` **Source:** `packages/zappier-account-balance/src/server.js` -**Lines:** 93 +**Lines:** 101 ## What this module is @@ -20,6 +20,7 @@ _None extracted._ | Name | Parameters | Param types (JSDoc) | Returns | Calls (same file / helpers) | |------|------------|---------------------|---------|-----------------------------| +| `apply` | `subject, payload` | — | `unknown` | see Call graph | | `startNats` | `(none)` | — | `unknown` | see Call graph | | `readBody` | `req` | — | `unknown` | see Call graph | | `reply` | `sub, fn` | — | `unknown` | see Call graph | @@ -29,6 +30,7 @@ _None extracted._ | Name | Parameters | |------|------------| +| `saveFrom` | `books` | | `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 }` | @@ -38,10 +40,11 @@ _None extracted._ - `node:http` - `./books.js` - `./subjects.js` +- `./persist.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` +`loadInto`, `apply`, `handle`, `saveFrom`, `startNats`, `import`, `connect`, `split`, `async`, `parse`, `decode`, `fn`, `respond`, `encode`, `stringify`, `reply`, `subscribe`, `write`, `readBody`, `on`, `push`, `resolve`, `concat`, `toString`, `createServer`, `writeHead`, `end`, `json`, `match`, `statement`, `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. diff --git a/docs/sphinx/modules/zappier-identity/ids.md b/docs/sphinx/modules/zappier-identity/ids.md new file mode 100644 index 0000000..2628937 --- /dev/null +++ b/docs/sphinx/modules/zappier-identity/ids.md @@ -0,0 +1,41 @@ +# `zappier-identity/ids` + +**Package:** `zappier-identity` +**Source:** `packages/zappier-identity/src/ids.js` +**Lines:** 16 + +## What this module is + +Implementation module in `zappier-identity`. The tables below are extracted from the source (signatures + JSDoc). + +## Exports + +`stableVeraeUserId`, `bindEmail` + +## Types / interfaces / classes + +_None extracted._ + +## Functions + +| Name | Parameters | Param types (JSDoc) | Returns | Calls (same file / helpers) | +|------|------------|---------------------|---------|-----------------------------| +| `stableVeraeUserId` | `username` | — | `unknown` | see Call graph | +| `bindEmail` | `email` | — | `unknown` | see Call graph | + +## What it imports / requires + +- `node:crypto` + +## Call graph (identifiers invoked) + +`stableVeraeUserId`, `trim`, `toLowerCase`, `createHash`, `update`, `digest`, `slice`, `bindEmail` + +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`. + diff --git a/docs/sphinx/modules/zappier-identity/ids.rst b/docs/sphinx/modules/zappier-identity/ids.rst new file mode 100644 index 0000000..54c5eba --- /dev/null +++ b/docs/sphinx/modules/zappier-identity/ids.rst @@ -0,0 +1,7 @@ +zappier-identity.ids +==================== + +Generated API sheet for ``zappier-identity/ids``. + +.. include:: ids.md + :parser: myst_parser.sphinx_ diff --git a/docs/sphinx/modules/zappier-identity/server.md b/docs/sphinx/modules/zappier-identity/server.md new file mode 100644 index 0000000..aec4169 --- /dev/null +++ b/docs/sphinx/modules/zappier-identity/server.md @@ -0,0 +1,53 @@ +# `zappier-identity/server` + +**Package:** `zappier-identity` +**Source:** `packages/zappier-identity/src/server.js` +**Lines:** 90 + +## What this module is + +Implementation module in `zappier-identity`. 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) | +|------|------------|---------------------|---------|-----------------------------| +| `handleBind` | `p` | — | `unknown` | see Call graph | +| `handleLookup` | `p` | — | `unknown` | see Call graph | +| `startNats` | `(none)` | — | `unknown` | see Call graph | +| `readBody` | `req` | — | `unknown` | see Call graph | +| `json` | `code, obj` | — | `unknown` | see Call graph | + +## Methods (class / object) + +| Name | Parameters | +|------|------------| +| `put` | `db, { customerId, ...bound }` | + +## What it imports / requires + +- `node:http` +- `./ids.js` +- `./store.js` +- `./subjects.js` + +## Call graph (identifiers invoked) + +`load`, `handleBind`, `bindEmail`, `put`, `handleLookup`, `startNats`, `import`, `connect`, `split`, `async`, `subscribe`, `parse`, `decode`, `respond`, `encode`, `stringify`, `readBody`, `on`, `push`, `resolve`, `concat`, `toString`, `createServer`, `writeHead`, `end`, `json`, `match`, `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`. + diff --git a/docs/sphinx/modules/zappier-identity/server.rst b/docs/sphinx/modules/zappier-identity/server.rst new file mode 100644 index 0000000..e58b6f9 --- /dev/null +++ b/docs/sphinx/modules/zappier-identity/server.rst @@ -0,0 +1,7 @@ +zappier-identity.server +======================= + +Generated API sheet for ``zappier-identity/server``. + +.. include:: server.md + :parser: myst_parser.sphinx_ diff --git a/docs/sphinx/modules/zappier-identity/store.md b/docs/sphinx/modules/zappier-identity/store.md new file mode 100644 index 0000000..fcdd798 --- /dev/null +++ b/docs/sphinx/modules/zappier-identity/store.md @@ -0,0 +1,50 @@ +# `zappier-identity/store` + +**Package:** `zappier-identity` +**Source:** `packages/zappier-identity/src/store.js` +**Lines:** 31 + +## What this module is + +Implementation module in `zappier-identity`. The tables below are extracted from the source (signatures + JSDoc). + +## Exports + +`load`, `save`, `put` + +## Types / interfaces / classes + +_None extracted._ + +## Functions + +| Name | Parameters | Param types (JSDoc) | Returns | Calls (same file / helpers) | +|------|------------|---------------------|---------|-----------------------------| +| `load` | `(none)` | — | `unknown` | see Call graph | +| `save` | `db` | — | `unknown` | see Call graph | +| `put` | `db, { customerId, veraeUserId, veraeUsername }` | — | `unknown` | see Call graph | +| `file` | `(none)` | — | `unknown` | see Call graph | + +## Methods (class / object) + +| Name | Parameters | +|------|------------| +| `save` | `db` | + +## What it imports / requires + +- `node:fs` +- `node:path` + +## Call graph (identifiers invoked) + +`join`, `cwd`, `load`, `file`, `existsSync`, `parse`, `readFileSync`, `save`, `mkdirSync`, `dirname`, `writeFileSync`, `stringify`, `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. + +## 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`. + diff --git a/docs/sphinx/modules/zappier-identity/store.rst b/docs/sphinx/modules/zappier-identity/store.rst new file mode 100644 index 0000000..24b4939 --- /dev/null +++ b/docs/sphinx/modules/zappier-identity/store.rst @@ -0,0 +1,7 @@ +zappier-identity.store +====================== + +Generated API sheet for ``zappier-identity/store``. + +.. include:: store.md + :parser: myst_parser.sphinx_ diff --git a/docs/sphinx/modules/zappier-identity/subjects.md b/docs/sphinx/modules/zappier-identity/subjects.md new file mode 100644 index 0000000..063e79c --- /dev/null +++ b/docs/sphinx/modules/zappier-identity/subjects.md @@ -0,0 +1,36 @@ +# `zappier-identity/subjects` + +**Package:** `zappier-identity` +**Source:** `packages/zappier-identity/src/subjects.js` +**Lines:** 6 + +## What this module is + +Implementation module in `zappier-identity`. 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`. + diff --git a/docs/sphinx/modules/zappier-identity/subjects.rst b/docs/sphinx/modules/zappier-identity/subjects.rst new file mode 100644 index 0000000..c3bd456 --- /dev/null +++ b/docs/sphinx/modules/zappier-identity/subjects.rst @@ -0,0 +1,7 @@ +zappier-identity.subjects +========================= + +Generated API sheet for ``zappier-identity/subjects``. + +.. include:: subjects.md + :parser: myst_parser.sphinx_ diff --git a/docs/sphinx/modules/zappier/admin.md b/docs/sphinx/modules/zappier/admin.md index 96e67cd..6180d66 100644 --- a/docs/sphinx/modules/zappier/admin.md +++ b/docs/sphinx/modules/zappier/admin.md @@ -2,7 +2,7 @@ **Package:** `zappier` **Source:** `packages/zappier/src/admin.ts` -**Lines:** 593 +**Lines:** 597 ## What this module is @@ -63,10 +63,11 @@ Implementation module in `zappier`. The tables below are extracted from the sour - `./accounting-export` - `./statement` - `./billing-nats` +- `./ledger` ## 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`, `isFinite`, `trunc`, `add`, `natsPublish`, `natsAdjust`, `async`, `natsStatement`, `composeStatement`, `listFor`, `type`, `send` +`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`, `async`, `isFinite`, `trunc`, `add`, `ledgerAdjust`, `booksConfigured`, `natsPublish`, `ledgerStatement`, `composeStatement`, `listFor`, `type` 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. diff --git a/docs/sphinx/modules/zappier/index.md b/docs/sphinx/modules/zappier/index.md index 7214325..dab278a 100644 --- a/docs/sphinx/modules/zappier/index.md +++ b/docs/sphinx/modules/zappier/index.md @@ -2,7 +2,7 @@ **Package:** `zappier` **Source:** `packages/zappier/src/index.ts` -**Lines:** 42 +**Lines:** 43 ## What this module is diff --git a/docs/sphinx/modules/zappier/ledger.md b/docs/sphinx/modules/zappier/ledger.md new file mode 100644 index 0000000..4f7e82a --- /dev/null +++ b/docs/sphinx/modules/zappier/ledger.md @@ -0,0 +1,52 @@ +# `zappier/ledger` + +**Package:** `zappier` +**Source:** `packages/zappier/src/ledger.ts` +**Lines:** 51 + +## What this module is + +Implementation module in `zappier`. The tables below are extracted from the source (signatures + JSDoc). + +## Exports + +`PrepaidRow`, `booksConfigured`, `ledgerAdjust`, `ledgerStatement` + +## Types / interfaces / classes + +| Kind | Name | +|------|------| +| type | `PrepaidRow` | + +## Functions + +| Name | Parameters | Param types (JSDoc) | Returns | Calls (same file / helpers) | +|------|------------|---------------------|---------|-----------------------------| +| `booksUrl` | `(none)` | — | `unknown` | see Call graph | +| `booksConfigured` | `(none)` | — | `unknown` | see Call graph | +| `ledgerAdjust` | `row: PrepaidRow, plane: AccessPlane` | — | `unknown` | see Call graph | +| `ledgerStatement` | `customerId: string, plane: AccessPlane, veraeUserId?: string` | — | `unknown` | see Call graph | + +## Methods (class / object) + +| Name | Parameters | +|------|------------| +| `return` | `process.env.ACCOUNT_BALANCE_URL || ''` | +| `return` | `await r.json(` | + +## What it imports / requires + +- `./billing-nats` + +## Call graph (identifiers invoked) + +`booksUrl`, `replace`, `booksConfigured`, `ledgerAdjust`, `natsAdjust`, `fetch`, `stringify`, `json`, `ledgerStatement`, `natsStatement`, `encodeURIComponent` + +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`. + diff --git a/docs/sphinx/modules/zappier/ledger.rst b/docs/sphinx/modules/zappier/ledger.rst new file mode 100644 index 0000000..19cd8a6 --- /dev/null +++ b/docs/sphinx/modules/zappier/ledger.rst @@ -0,0 +1,7 @@ +zappier.ledger +============== + +Generated API sheet for ``zappier/ledger``. + +.. include:: ledger.md + :parser: myst_parser.sphinx_ diff --git a/docs/sphinx/modules/zappier/portal.md b/docs/sphinx/modules/zappier/portal.md index 4c31a9c..25d9df7 100644 --- a/docs/sphinx/modules/zappier/portal.md +++ b/docs/sphinx/modules/zappier/portal.md @@ -52,10 +52,11 @@ Implementation module in `zappier`. The tables below are extracted from the sour - `./statement` - `./billing-nats` - `./verae-bind` +- `./ledger` ## Call graph (identifiers invoked) -`now`, `reload`, `customer`, `publicProfile`, `sessionAuth`, `header`, `startsWith`, `slice`, `get`, `list`, `find`, `status`, `json`, `next`, `save`, `portalRouter`, `post`, `async`, `trim`, `test`, `hashPassword`, `findByEmail`, `randomBytes`, `toString`, `bindVeraeUser`, `create`, `verifyPassword`, `verifyTotp`, `use`, `delete`, `setUTCDate`, `setUTCHours`, `summaryFor`, `tiers`, `applyMonthlyCredit`, `rateCard`, `natsStatement`, `composeStatement`, `listFor`, `type`, `send`, `renderInvoiceHtml`, `generateTotpSecret`, `totpUri`, `qr`, `isInteger`, `natsPublish`, `natsAdjust`, `put` +`now`, `reload`, `customer`, `publicProfile`, `sessionAuth`, `header`, `startsWith`, `slice`, `get`, `list`, `find`, `status`, `json`, `next`, `save`, `portalRouter`, `post`, `async`, `trim`, `test`, `hashPassword`, `findByEmail`, `randomBytes`, `toString`, `bindVeraeUser`, `create`, `verifyPassword`, `verifyTotp`, `use`, `delete`, `setUTCDate`, `setUTCHours`, `summaryFor`, `tiers`, `applyMonthlyCredit`, `rateCard`, `ledgerStatement`, `composeStatement`, `listFor`, `type`, `send`, `renderInvoiceHtml`, `generateTotpSecret`, `totpUri`, `qr`, `isInteger`, `ledgerAdjust`, `booksConfigured`, `natsPublish`, `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. diff --git a/docs/sphinx/modules/zappier/verae-bind.md b/docs/sphinx/modules/zappier/verae-bind.md index 30f3320..547bb4c 100644 --- a/docs/sphinx/modules/zappier/verae-bind.md +++ b/docs/sphinx/modules/zappier/verae-bind.md @@ -2,7 +2,7 @@ **Package:** `zappier` **Source:** `packages/zappier/src/verae-bind.ts` -**Lines:** 77 +**Lines:** 90 ## What this module is @@ -25,7 +25,7 @@ Implementation module in `zappier`. The tables below are extracted from the sour | `normalizeVeraeUsername` | `username: string` | — | `unknown` | see Call graph | | `stableVeraeUserId` | `username: string` | — | `unknown` | see Call graph | | `mockBind` | `email: string` | — | `unknown` | see Call graph | -| `bindVeraeUser` | `email: string` | — | `unknown` | see Call graph | +| `bindVeraeUser` | `email: string, customerId?: string` | — | `unknown` | see Call graph | | `login` | `username: string, pass: string` | — | `unknown` | see Call graph | ## What it imports / requires @@ -34,7 +34,7 @@ Implementation module in `zappier`. The tables below are extracted from the sour ## Call graph (identifiers invoked) -`normalizeVeraeUsername`, `trim`, `toLowerCase`, `stableVeraeUserId`, `createHash`, `update`, `digest`, `slice`, `mockBind`, `bindVeraeUser`, `replace`, `randomBytes`, `toString`, `async`, `fetch`, `stringify`, `json`, `login` +`normalizeVeraeUsername`, `trim`, `toLowerCase`, `stableVeraeUserId`, `createHash`, `update`, `digest`, `slice`, `mockBind`, `bindVeraeUser`, `replace`, `fetch`, `stringify`, `json`, `randomBytes`, `toString`, `async`, `login` 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. diff --git a/docs/sphinx/repos/verae-access-staff.md b/docs/sphinx/repos/verae-access-staff.md new file mode 100644 index 0000000..f34039a --- /dev/null +++ b/docs/sphinx/repos/verae-access-staff.md @@ -0,0 +1,7 @@ +# verae-access-staff + +Staff access plane for CS / sales / accounting. Credits and statement review after `verae.access.authz.check` with plane `staff`. + +**Forgejo:** https://git.georgelambert.org/marchon/verae-access-staff + +Port `:3025`. diff --git a/docs/sphinx/repos/verae-fleet.md b/docs/sphinx/repos/verae-fleet.md index aae377a..d3fe246 100644 --- a/docs/sphinx/repos/verae-fleet.md +++ b/docs/sphinx/repos/verae-fleet.md @@ -13,7 +13,7 @@ Operator control plane for Verae Time × Zapier **runtime** services: cd packages/verae-fleet npm test node src/cli.js list -node src/cli.js serve # http://127.0.0.1:3850/ +node src/cli.js serve # http://0.0.0.0:3850/ ``` Against a running daemon: diff --git a/docs/sphinx/repos/verae-jobs-events.md b/docs/sphinx/repos/verae-jobs-events.md new file mode 100644 index 0000000..936ee4d --- /dev/null +++ b/docs/sphinx/repos/verae-jobs-events.md @@ -0,0 +1,7 @@ +# verae-jobs-events + +Mailbox process for `verae.zapier.jobs.events`. Today it counts events (passthrough). Webhook routing still lives in middleware until this process takes the exclusive consumer. + +**Forgejo:** https://git.georgelambert.org/marchon/verae-jobs-events + +Port `:3030`. diff --git a/docs/sphinx/repos/verae-nats-accounts.md b/docs/sphinx/repos/verae-nats-accounts.md new file mode 100644 index 0000000..1284304 --- /dev/null +++ b/docs/sphinx/repos/verae-nats-accounts.md @@ -0,0 +1,8 @@ +# verae-nats-accounts + +NATS **account + leaf allow-list**. Leaf nodes cannot publish `verae.billing.*`. + +**Forgejo:** https://git.georgelambert.org/marchon/verae-nats-accounts + +- `policy.json` — machine-readable allow/deny (used by access-leaf). +- `nats.conf` — sketch for a future accounts-enabled nats-server (loopback). diff --git a/docs/sphinx/repos/verae-zapier-simulator.md b/docs/sphinx/repos/verae-zapier-simulator.md index 7ec71b1..4e174fe 100644 --- a/docs/sphinx/repos/verae-zapier-simulator.md +++ b/docs/sphinx/repos/verae-zapier-simulator.md @@ -7,7 +7,7 @@ Use it to validate messaging and to catch errors, delays, failures, and recoveri ```bash cd packages/verae-zapier-simulator npm test -npm start # http://127.0.0.1:3847/ +npm start # http://0.0.0.0:3847/ ``` ## What it simulates diff --git a/docs/sphinx/repos/zapier-decisions.md b/docs/sphinx/repos/zapier-decisions.md new file mode 100644 index 0000000..58e5adb --- /dev/null +++ b/docs/sphinx/repos/zapier-decisions.md @@ -0,0 +1,13 @@ +# zapier-decisions + +Lab log of architecture decisions, actions taken, and open todos while cleaning the Verae × Zapier stack. + +**Forgejo:** https://git.georgelambert.org/marchon/zapier-decisions + +| File | What | +|------|------| +| [LOG.md](LOG.md) | Chronological actions | +| [TODO.md](TODO.md) | Open items | +| [decisions/](decisions/) | One file per decision | + +No runtime. Not a NATS mailbox. diff --git a/docs/sphinx/repos/zappier-account-balance.md b/docs/sphinx/repos/zappier-account-balance.md index 0c261d6..9b1113b 100644 --- a/docs/sphinx/repos/zappier-account-balance.md +++ b/docs/sphinx/repos/zappier-account-balance.md @@ -1,6 +1,6 @@ # zappier-account-balance -Source of truth for **customer prepaid balances**. Internal traffic is **NATS request-reply**; HTTP is health plus a fallback. +Source of truth for **customer prepaid balances** (persisted `books.json`). Internal traffic is **NATS request-reply**; HTTP is health plus a fallback. zappier-edge `balanceCents` is a cache of this book. **Forgejo:** https://git.georgelambert.org/marchon/zappier-account-balance **Catalog:** https://zapier.georgelambert.org/packages/zappier-account-balance/README.pdf diff --git a/docs/sphinx/repos/zappier-identity.md b/docs/sphinx/repos/zappier-identity.md new file mode 100644 index 0000000..80c438f --- /dev/null +++ b/docs/sphinx/repos/zappier-identity.md @@ -0,0 +1,12 @@ +# zappier-identity + +Mailbox for **Verae user id bind/lookup**. Public credentials stay zappier API keys. JWTs never live here. + +**Forgejo:** https://git.georgelambert.org/marchon/zappier-identity + +| Address | Kind | +|---------|------| +| `verae.identity.bind` | request-reply `{ email, customerId }` | +| `verae.identity.lookup` | request-reply `{ customerId }` or `{ veraeUserId }` | + +HTTP `:3026` `POST /bind` `GET /lookup/:customerId`. diff --git a/packages/docs-master/modules/verae-access-staff/NATS.md b/packages/docs-master/modules/verae-access-staff/NATS.md new file mode 100644 index 0000000..0edb6e8 --- /dev/null +++ b/packages/docs-master/modules/verae-access-staff/NATS.md @@ -0,0 +1,3 @@ +# NATS — verae-access-staff + +Plane `staff`. Authz then billing statement/adjust. diff --git a/packages/docs-master/modules/verae-access-staff/SUMMARY.md b/packages/docs-master/modules/verae-access-staff/SUMMARY.md new file mode 100644 index 0000000..70e7243 --- /dev/null +++ b/packages/docs-master/modules/verae-access-staff/SUMMARY.md @@ -0,0 +1,3 @@ +# verae-access-staff + +Staff plane for credits and statement review. diff --git a/packages/docs-master/modules/verae-jobs-events/NATS.md b/packages/docs-master/modules/verae-jobs-events/NATS.md new file mode 100644 index 0000000..0996e14 --- /dev/null +++ b/packages/docs-master/modules/verae-jobs-events/NATS.md @@ -0,0 +1,3 @@ +# NATS — verae-jobs-events + +IN `verae.zapier.jobs.events` queue `jobs-events`. diff --git a/packages/docs-master/modules/verae-jobs-events/SUMMARY.md b/packages/docs-master/modules/verae-jobs-events/SUMMARY.md new file mode 100644 index 0000000..18675cf --- /dev/null +++ b/packages/docs-master/modules/verae-jobs-events/SUMMARY.md @@ -0,0 +1,3 @@ +# verae-jobs-events + +Mailbox for `verae.zapier.jobs.events` (passthrough + count). diff --git a/packages/docs-master/modules/verae-nats-accounts/NATS.md b/packages/docs-master/modules/verae-nats-accounts/NATS.md new file mode 100644 index 0000000..bfb0eb5 --- /dev/null +++ b/packages/docs-master/modules/verae-nats-accounts/NATS.md @@ -0,0 +1,3 @@ +# NATS — verae-nats-accounts + +Policy only. See `policy.json`. diff --git a/packages/docs-master/modules/verae-nats-accounts/SUMMARY.md b/packages/docs-master/modules/verae-nats-accounts/SUMMARY.md new file mode 100644 index 0000000..8de0c7a --- /dev/null +++ b/packages/docs-master/modules/verae-nats-accounts/SUMMARY.md @@ -0,0 +1,3 @@ +# verae-nats-accounts + +INTERNAL vs LEAF. Leaf deny `verae.billing.>`. diff --git a/packages/docs-master/modules/zapier-decisions/NATS.md b/packages/docs-master/modules/zapier-decisions/NATS.md new file mode 100644 index 0000000..74566e5 --- /dev/null +++ b/packages/docs-master/modules/zapier-decisions/NATS.md @@ -0,0 +1,3 @@ +# NATS — zapier-decisions + +None. diff --git a/packages/docs-master/modules/zapier-decisions/SUMMARY.md b/packages/docs-master/modules/zapier-decisions/SUMMARY.md new file mode 100644 index 0000000..7c4f63c --- /dev/null +++ b/packages/docs-master/modules/zapier-decisions/SUMMARY.md @@ -0,0 +1,3 @@ +# zapier-decisions + +Architecture decisions and action log for the lab cleanup (prepaid SoT, identity, access planes, leaf policy, fleet). diff --git a/packages/docs-master/modules/zappier-identity/NATS.md b/packages/docs-master/modules/zappier-identity/NATS.md new file mode 100644 index 0000000..ad889bb --- /dev/null +++ b/packages/docs-master/modules/zappier-identity/NATS.md @@ -0,0 +1,3 @@ +# NATS — zappier-identity + +`verae.identity.bind` / `verae.identity.lookup` queue `identity`. diff --git a/packages/docs-master/modules/zappier-identity/SUMMARY.md b/packages/docs-master/modules/zappier-identity/SUMMARY.md new file mode 100644 index 0000000..9afb4e6 --- /dev/null +++ b/packages/docs-master/modules/zappier-identity/SUMMARY.md @@ -0,0 +1,3 @@ +# zappier-identity + +Bind and lookup `veraeUserId`. JWTs never stored. diff --git a/packages/overview/01-system.md b/packages/overview/01-system.md index f887712..4874f32 100644 --- a/packages/overview/01-system.md +++ b/packages/overview/01-system.md @@ -15,15 +15,15 @@ Verae Time proves a SHA-256 existed at a given time. Zapier lets customers regis | Direct customer API | `verae-access-api` `x-api-key` | HTTPS `:3022` | | S2S leaf | `verae-access-leaf` | NATS `verae.access.leaf.in` / HTTPS `:3023` | | Authz | `verae-access-authz` | `verae.access.authz.check` before any internal subject | -| Commercial edge | `zappier-edge` portal, admin, Stripe (legacy combined) | Public HTTPS; NATS billing after authz | +| Commercial edge | `zappier-edge` portal, admin, Stripe | Loopback `:3000`; public doors are access-* | | 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 | +| Middleware HTTP | `/zapier/v1/*` job id + wait | HTTPS from access-zapier / loopback edge | | NATS cluster | JetStream subjects under `verae.*` | Private; loopback or SSH tunnel | | Workers | poller, webhook-deliver, aggregator | NATS + HTTPS to chain or Zapier hooks | | Archives | WORM + tree nodes | NATS broadcast query; bloom miss = silence | | Chain | Verae timestamping | HTTPS `api.veraetime.net` or MOCK | -| Control | `verae-fleet` | Operator loopback `:3850`; SSH to extra machines | +| Control | `verae-fleet` | Operator HTTP `:3850` on `0.0.0.0`; SSH to extra machines | ## Request in one sentence diff --git a/packages/overview/02-modules-and-repos.md b/packages/overview/02-modules-and-repos.md index 36c329c..c17ac66 100644 --- a/packages/overview/02-modules-and-repos.md +++ b/packages/overview/02-modules-and-repos.md @@ -13,6 +13,11 @@ Each runtime piece is its **own git repo** on Forgejo (`git.georgelambert.org`, | **verae-access-api** | `packages/verae-access-api` | Direct customer API plane (not Zapier) | | **verae-access-leaf** | `packages/verae-access-leaf` | Server-to-server NATS leaf plane | | **verae-access-zapier** | `packages/verae-access-zapier` | Zapier Platform plane only | +| **verae-access-staff** | `packages/verae-access-staff` | Staff CS/sales/accounting plane | +| **zappier-identity** | `packages/zappier-identity` | Bind/lookup `veraeUserId` | +| **verae-jobs-events** | `packages/verae-jobs-events` | Mailbox `verae.zapier.jobs.events` | +| **verae-nats-accounts** | `packages/verae-nats-accounts` | INTERNAL vs LEAF subject policy | +| **zapier-decisions** | `packages/zapier-decisions` | Decision log | | **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 | diff --git a/packages/overview/INDEX.md b/packages/overview/INDEX.md index d9140aa..0a67911 100644 --- a/packages/overview/INDEX.md +++ b/packages/overview/INDEX.md @@ -54,7 +54,7 @@ Operator console (loopback): http://127.0.0.1:3850/ · [CONSOLE.pdf](https://zap Prefix: `https://git.georgelambert.org/marchon/` -overview · verae-nats-process · verae-ops · master-zapier-plan-draft · zappier-edge · verae-access-authz · verae-access-web · verae-access-api · verae-access-leaf · verae-access-zapier · verae-middleware · verae-zapier-app · verae-activate · verae-request-splitter · verae-archive-worm · verae-archive-aggregator · verae-tree-node · verae-fleet · verae-zapier-simulator · zapier-user-docs · zapier-docs-master +overview · verae-nats-process · verae-ops · master-zapier-plan-draft · zappier-edge · verae-access-authz · verae-access-web · verae-access-api · verae-access-leaf · verae-access-zapier · verae-access-staff · zappier-identity · verae-jobs-events · verae-nats-accounts · zapier-decisions · verae-middleware · verae-zapier-app · verae-activate · verae-request-splitter · verae-archive-worm · verae-archive-aggregator · verae-tree-node · verae-fleet · verae-zapier-simulator · zapier-user-docs · zapier-docs-master ## Per-module contracts diff --git a/packages/verae-access-leaf/src/allow.js b/packages/verae-access-leaf/src/allow.js new file mode 100644 index 0000000..abd2703 --- /dev/null +++ b/packages/verae-access-leaf/src/allow.js @@ -0,0 +1,28 @@ +import fs from 'node:fs'; + +const FALLBACK = [ + 'verae.archive.put', + 'verae.archive.query', + 'verae.archive.reply.', + 'verae.zapier.jobs.watch', + 'verae.zapier.jobs.events', + 'verae.zapier.webhooks.deliver', +]; + +export function leafAllowList() { + const p = process.env.NATS_POLICY_PATH; + if (p && fs.existsSync(p)) { + try { + return JSON.parse(fs.readFileSync(p, 'utf8')).leafAllow || FALLBACK; + } catch { + return FALLBACK; + } + } + return FALLBACK; +} + +export function leafAllowed(subject) { + return leafAllowList().some((p) => + p.endsWith('.') ? subject.startsWith(p) : subject === p || subject.startsWith(`${p}.`), + ); +} diff --git a/packages/verae-access-leaf/src/server.js b/packages/verae-access-leaf/src/server.js index 7324404..82d8798 100644 --- a/packages/verae-access-leaf/src/server.js +++ b/packages/verae-access-leaf/src/server.js @@ -5,6 +5,7 @@ * then forwards only allowed internal subjects (archive + jobs, never billing). */ import http from 'node:http'; +import { leafAllowed } from './allow.js'; const PORT = Number(process.env.PORT || 3023); const AUTHZ = (process.env.AUTHZ_URL || 'http://127.0.0.1:3020').replace(/\/$/, ''); @@ -30,6 +31,9 @@ async function forward(body) { return { status: 401, body: { allow: false, reason: 'bad leaf token' } }; } const target = body.target || body.subject; + if (!leafAllowed(target)) { + return { status: 403, body: { allow: false, reason: `leaf policy denies ${target}` } }; + } const gate = await check(target, body.principal || 'leaf'); if (!gate.allow) return { status: 403, body: gate }; const url = process.env.NATS_URL; diff --git a/packages/verae-access-staff/NATS.md b/packages/verae-access-staff/NATS.md new file mode 100644 index 0000000..f33adff --- /dev/null +++ b/packages/verae-access-staff/NATS.md @@ -0,0 +1,3 @@ +# NATS — verae-access-staff + +Plane `staff`. Authz then `verae.billing.statement.get` / `balance.adjust`. diff --git a/packages/verae-access-staff/README.md b/packages/verae-access-staff/README.md new file mode 100644 index 0000000..f34039a --- /dev/null +++ b/packages/verae-access-staff/README.md @@ -0,0 +1,7 @@ +# verae-access-staff + +Staff access plane for CS / sales / accounting. Credits and statement review after `verae.access.authz.check` with plane `staff`. + +**Forgejo:** https://git.georgelambert.org/marchon/verae-access-staff + +Port `:3025`. diff --git a/packages/verae-access-staff/package.json b/packages/verae-access-staff/package.json new file mode 100644 index 0000000..d306082 --- /dev/null +++ b/packages/verae-access-staff/package.json @@ -0,0 +1,11 @@ +{ + "name": "verae-access-staff", + "version": "0.1.0", + "private": true, + "type": "module", + "description": "Staff access plane (CS/sales/accounting)", + "scripts": { + "start": "node src/server.js", + "test": "node --test test/*.test.js" + } +} diff --git a/packages/verae-access-staff/src/server.js b/packages/verae-access-staff/src/server.js new file mode 100644 index 0000000..cf4ef1d --- /dev/null +++ b/packages/verae-access-staff/src/server.js @@ -0,0 +1,57 @@ +#!/usr/bin/env node +/** Staff access plane (CS / sales / accounting). Not Zapier, not customer API. */ +import http from 'node:http'; + +const PORT = Number(process.env.PORT || 3025); +const AUTHZ = (process.env.AUTHZ_URL || 'http://127.0.0.1:3020').replace(/\/$/, ''); +const BOOKS = (process.env.ACCOUNT_BALANCE_URL || 'http://127.0.0.1:3010').replace(/\/$/, ''); +const PLANE = 'staff'; + +async function check(subject, extra = {}) { + const r = await fetch(`${AUTHZ}/check`, { + method: 'POST', + headers: { 'content-type': 'application/json' }, + body: JSON.stringify({ plane: PLANE, subject, ...extra }), + }); + return r.json(); +} + +const server = http.createServer(async (req, res) => { + const url = new URL(req.url || '/', `http://127.0.0.1:${PORT}`); + const json = (code, obj) => { + res.writeHead(code, { 'content-type': 'application/json' }); + res.end(JSON.stringify(obj)); + }; + try { + if (req.method === 'GET' && url.pathname === '/health') { + return json(200, { ok: true, role: 'verae-access-staff', plane: PLANE }); + } + const review = url.pathname.match(/^\/review\/([^/]+)$/); + if (req.method === 'GET' && review) { + const gate = await check('verae.billing.statement.get', { principal: review[1] }); + if (!gate.allow) return json(403, gate); + const r = await fetch(`${BOOKS}/statement/${review[1]}`); + return json(r.status, { ...(await r.json()), plane: PLANE, source: 'account-balance' }); + } + if (req.method === 'POST' && url.pathname === '/credits') { + const chunks = []; + for await (const c of req) chunks.push(c); + const body = JSON.parse(Buffer.concat(chunks).toString('utf8') || '{}'); + const gate = await check('verae.billing.balance.adjust', { kind: 'credit', principal: body.agent }); + if (!gate.allow) return json(403, gate); + const r = await fetch(`${BOOKS}/adjust`, { + method: 'POST', + headers: { 'content-type': 'application/json' }, + body: JSON.stringify({ ...body, kind: 'credit' }), + }); + return json(r.status, { ...(await r.json()), plane: PLANE }); + } + json(404, { error: 'not found' }); + } catch (err) { + json(502, { error: err.message }); + } +}); + +server.listen(PORT, '0.0.0.0', () => { + process.stdout.write(`verae-access-staff http://0.0.0.0:${PORT}/ plane=${PLANE}\n`); +}); diff --git a/packages/verae-access-staff/test/health.test.js b/packages/verae-access-staff/test/health.test.js new file mode 100644 index 0000000..0125538 --- /dev/null +++ b/packages/verae-access-staff/test/health.test.js @@ -0,0 +1,56 @@ +import { test } from 'node:test'; +import assert from 'node:assert/strict'; +import { spawn } from 'node:child_process'; +import path from 'node:path'; +import { fileURLToPath } from 'node:url'; + +const root = path.join(path.dirname(fileURLToPath(import.meta.url)), '..'); +const authzRoot = path.join(root, '..', 'verae-access-authz'); +const booksRoot = path.join(root, '..', 'zappier-account-balance'); + +test('staff plane can credit after authz; zapier cannot', async () => { + const authzPort = 18031; + const booksPort = 18032; + const staffPort = 18033; + const authz = spawn(process.execPath, ['src/server.js'], { + cwd: authzRoot, + env: { ...process.env, PORT: String(authzPort) }, + stdio: ['ignore', 'pipe', 'pipe'], + }); + const books = spawn(process.execPath, ['src/server.js'], { + cwd: booksRoot, + env: { ...process.env, PORT: String(booksPort), BOOKS_PATH: `/tmp/staff-books-${Date.now()}.json` }, + stdio: ['ignore', 'pipe', 'pipe'], + }); + const staff = spawn(process.execPath, ['src/server.js'], { + cwd: root, + env: { + ...process.env, + PORT: String(staffPort), + AUTHZ_URL: `http://127.0.0.1:${authzPort}`, + ACCOUNT_BALANCE_URL: `http://127.0.0.1:${booksPort}`, + }, + stdio: ['ignore', 'pipe', 'pipe'], + }); + await new Promise((r) => setTimeout(r, 600)); + try { + const h = await (await fetch(`http://127.0.0.1:${staffPort}/health`)).json(); + assert.equal(h.plane, 'staff'); + const add = await fetch(`http://127.0.0.1:${staffPort}/credits`, { + method: 'POST', + headers: { 'content-type': 'application/json' }, + body: JSON.stringify({ customerId: 'c-staff', cents: 50, reason: 'test', agent: 'cs' }), + }); + assert.equal(add.status, 200); + const deny = await fetch(`http://127.0.0.1:${authzPort}/check`, { + method: 'POST', + headers: { 'content-type': 'application/json' }, + body: JSON.stringify({ plane: 'zapier', subject: 'verae.billing.balance.adjust' }), + }); + assert.equal(deny.status, 403); + } finally { + staff.kill('SIGTERM'); + books.kill('SIGTERM'); + authz.kill('SIGTERM'); + } +}); diff --git a/packages/verae-fleet/README.md b/packages/verae-fleet/README.md index aae377a..d3fe246 100644 --- a/packages/verae-fleet/README.md +++ b/packages/verae-fleet/README.md @@ -13,7 +13,7 @@ Operator control plane for Verae Time × Zapier **runtime** services: cd packages/verae-fleet npm test node src/cli.js list -node src/cli.js serve # http://127.0.0.1:3850/ +node src/cli.js serve # http://0.0.0.0:3850/ ``` Against a running daemon: diff --git a/packages/verae-fleet/docs/CONSOLE.html b/packages/verae-fleet/docs/CONSOLE.html index 61778c2..9d47b33 100644 --- a/packages/verae-fleet/docs/CONSOLE.html +++ b/packages/verae-fleet/docs/CONSOLE.html @@ -368,9 +368,10 @@

Operator console

Operator console

-

Loopback UI at http://127.0.0.1:3850/ — Fleet, Trace -(simulator), and Docs in one shell. Not a public site. NATS stays -private; SSH identity files stay on disk.

+

Operator UI at http://0.0.0.0:3850/ (all +interfaces). Fleet, Trace (simulator), and Docs in one shell. NATS stays +private (127.0.0.1:4222); SSH identity files stay on +disk.

cd packages/verae-fleet
 node src/cli.js serve
diff --git a/packages/verae-fleet/docs/CONSOLE.md b/packages/verae-fleet/docs/CONSOLE.md index 42816e9..bcb825b 100644 --- a/packages/verae-fleet/docs/CONSOLE.md +++ b/packages/verae-fleet/docs/CONSOLE.md @@ -1,6 +1,6 @@ # Operator console -Loopback UI at **http://127.0.0.1:3850/** — Fleet, Trace (simulator), and Docs in one shell. Not a public site. NATS stays private; SSH identity files stay on disk. +Operator UI at **http://0.0.0.0:3850/** (all interfaces). Fleet, Trace (simulator), and Docs in one shell. NATS stays private (`127.0.0.1:4222`); SSH identity files stay on disk. ```bash cd packages/verae-fleet diff --git a/packages/verae-fleet/docs/CONSOLE.pdf b/packages/verae-fleet/docs/CONSOLE.pdf index f1d1b27..a6da356 100644 Binary files a/packages/verae-fleet/docs/CONSOLE.pdf and b/packages/verae-fleet/docs/CONSOLE.pdf differ diff --git a/packages/verae-fleet/fleet.json b/packages/verae-fleet/fleet.json index 6177e0d..fe94b1e 100644 --- a/packages/verae-fleet/fleet.json +++ b/packages/verae-fleet/fleet.json @@ -1,7 +1,7 @@ { "apiVersion": "verae.fleet/v1", "control": { - "bind": "127.0.0.1", + "bind": "0.0.0.0", "port": 3850, "probeIntervalMs": 750, "unhealthyAfterMs": 2500, @@ -20,6 +20,9 @@ "access-api": { "min": 1, "max": 1, "keepFloor": true, "enabled": true }, "access-leaf": { "min": 1, "max": 1, "keepFloor": true, "enabled": true }, "access-zapier": { "min": 1, "max": 1, "keepFloor": true, "enabled": true }, + "access-staff": { "min": 1, "max": 1, "keepFloor": true, "enabled": true }, + "identity": { "min": 1, "max": 1, "keepFloor": true, "enabled": true }, + "jobs-events": { "min": 1, "max": 1, "keepFloor": true, "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 }, diff --git a/packages/verae-fleet/services/access-leaf.json b/packages/verae-fleet/services/access-leaf.json index 0ab8e7a..8676ac4 100644 --- a/packages/verae-fleet/services/access-leaf.json +++ b/packages/verae-fleet/services/access-leaf.json @@ -17,6 +17,7 @@ "PORT": "3023", "AUTHZ_URL": "http://127.0.0.1:3020", "LEAF_TOKEN": "leaf-dev-token", + "NATS_POLICY_PATH": "../verae-nats-accounts/policy.json", "NATS_URL": "nats://127.0.0.1:4222" }, "nats": { diff --git a/packages/verae-fleet/services/access-staff.json b/packages/verae-fleet/services/access-staff.json new file mode 100644 index 0000000..988b429 --- /dev/null +++ b/packages/verae-fleet/services/access-staff.json @@ -0,0 +1,22 @@ +{ + "id": "access-staff", + "title": "Staff access plane", + "kind": "http", + "package": "verae-access-staff", + "role": "access-staff", + "managed": true, + "runtime": "HTTP :3025 plane=staff", + "health": { "type": "http", "path": "/health", "timeoutMs": 2000 }, + "ports": { "healthBase": 3025 }, + "spawn": { + "cwd": "../verae-access-staff", + "command": "node", + "args": ["src/server.js"] + }, + "env": { + "PORT": "3025", + "AUTHZ_URL": "http://127.0.0.1:3020", + "ACCOUNT_BALANCE_URL": "http://127.0.0.1:3010" + }, + "nats": { "in": [], "out": ["verae.access.authz.check"] } +} diff --git a/packages/verae-fleet/services/identity.json b/packages/verae-fleet/services/identity.json new file mode 100644 index 0000000..f49b84a --- /dev/null +++ b/packages/verae-fleet/services/identity.json @@ -0,0 +1,24 @@ +{ + "id": "identity", + "title": "Verae user-id bind/lookup", + "kind": "http", + "package": "zappier-identity", + "role": "identity", + "managed": true, + "runtime": "HTTP :3026 + NATS verae.identity.*", + "health": { "type": "http", "path": "/health", "timeoutMs": 2000 }, + "ports": { "healthBase": 3026 }, + "spawn": { + "cwd": "../zappier-identity", + "command": "node", + "args": ["src/server.js"] + }, + "env": { + "PORT": "3026", + "NATS_URL": "nats://127.0.0.1:4222" + }, + "nats": { + "in": ["verae.identity.bind", "verae.identity.lookup"], + "out": [] + } +} diff --git a/packages/verae-fleet/services/jobs-events.json b/packages/verae-fleet/services/jobs-events.json new file mode 100644 index 0000000..21033e1 --- /dev/null +++ b/packages/verae-fleet/services/jobs-events.json @@ -0,0 +1,24 @@ +{ + "id": "jobs-events", + "title": "jobs.events mailbox", + "kind": "http", + "package": "verae-jobs-events", + "role": "jobs-events", + "managed": true, + "runtime": "HTTP :3030 + NATS verae.zapier.jobs.events", + "health": { "type": "http", "path": "/health", "timeoutMs": 2000 }, + "ports": { "healthBase": 3030 }, + "spawn": { + "cwd": "../verae-jobs-events", + "command": "node", + "args": ["src/server.js"] + }, + "env": { + "PORT": "3030", + "NATS_URL": "nats://127.0.0.1:4222" + }, + "nats": { + "in": ["verae.zapier.jobs.events"], + "out": [] + } +} diff --git a/packages/verae-fleet/services/zappier-edge.json b/packages/verae-fleet/services/zappier-edge.json index 21aeed1..52ec636 100644 --- a/packages/verae-fleet/services/zappier-edge.json +++ b/packages/verae-fleet/services/zappier-edge.json @@ -5,7 +5,7 @@ "package": "zappier", "role": "zappier-edge", "managed": true, - "runtime": "HTTPS :3000 (portal, admin, meter, proxy to middleware)", + "runtime": "loopback :3000 (portal, admin, Stripe; public doors are access-*)", "health": { "type": "http", "path": "/health", "timeoutMs": 4000 }, "ports": { "healthBase": 3000 }, "spawn": { @@ -15,12 +15,15 @@ }, "env": { "PORT": "3000", + "BIND": "127.0.0.1", "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", "NATS_URL": "nats://127.0.0.1:4222", - "AUTHZ_URL": "http://127.0.0.1:3020" + "AUTHZ_URL": "http://127.0.0.1:3020", + "ACCOUNT_BALANCE_URL": "http://127.0.0.1:3010", + "IDENTITY_URL": "http://127.0.0.1:3026" }, "nats": { "in": [], @@ -32,5 +35,5 @@ "verae.billing.balance.adjust" ] }, - "notes": "Zapier x-api-key lands here. HTTPS to middleware. NATS billing to account-balance." + "notes": "Loopback only. Public Zapier traffic hits access-zapier :3024." } diff --git a/packages/verae-fleet/src/cli.js b/packages/verae-fleet/src/cli.js index fdc2951..b34e8b9 100644 --- a/packages/verae-fleet/src/cli.js +++ b/packages/verae-fleet/src/cli.js @@ -92,15 +92,15 @@ async function main() { } if (cmd === 'serve' || cmd === 'monitor') { const sup = new Supervisor({ loaded }); + const mon = new Monitor(sup); + startControlServer(sup, mon); + print(`fleet ${cmd} pid=${process.pid}\nUI http://${loaded.control.bind || '0.0.0.0'}:${loaded.control.port}/\nSIGINT stops all managed replicas`); for (const id of Object.keys(loaded.services)) { const s = loaded.services[id]; if (s.managed && s.enabled && s.min > 0) await sup.startService(id); } - const mon = new Monitor(sup); await mon.tick(); mon.start(); - startControlServer(sup, mon); - print(`fleet ${cmd} pid=${process.pid}\nUI ${BASE}/\nSIGINT stops all managed replicas`); process.on('SIGINT', async () => { mon.stop(); await sup.stopAll(); diff --git a/packages/verae-fleet/src/machines.js b/packages/verae-fleet/src/machines.js index 551bd55..0b899f7 100644 --- a/packages/verae-fleet/src/machines.js +++ b/packages/verae-fleet/src/machines.js @@ -41,7 +41,11 @@ export function loadMachines(root, overlayPath) { if (extra && typeof extra === 'object') Object.assign(m, extra); } } - return list.map(normalizeMachine); + return list.map((m) => { + const n = normalizeMachine(m); + if (n.id === 'lan-134' && process.env.FLEET_ENABLE_LAN134 !== '1') n.enabled = false; + return n; + }); } export function normalizeMachine(m) { @@ -86,9 +90,13 @@ export function canHost(machine, serviceId, role) { * @param {string} serviceId * @param {string} [role] */ -export function pickMachine(machines, instances, serviceId, role, exclude = []) { +export function pickMachine(machines, instances, serviceId, role, exclude = [], opts = {}) { const skip = new Set(exclude); - const eligible = machines.filter((m) => canHost(m, serviceId, role) && !skip.has(m.id)); + let eligible = machines.filter((m) => canHost(m, serviceId, role) && !skip.has(m.id)); + if (opts.preferLocal) { + const local = eligible.filter((m) => m.kind === 'local'); + if (local.length) eligible = local; + } if (!eligible.length) return null; const scored = eligible.map((m) => { const running = instances.filter((i) => i.machine === m.id && i.pid).length; diff --git a/packages/verae-fleet/src/server.js b/packages/verae-fleet/src/server.js index 311be8b..67843b1 100644 --- a/packages/verae-fleet/src/server.js +++ b/packages/verae-fleet/src/server.js @@ -1,6 +1,6 @@ /** * Operator HTTP: list, status, pause/resume/stop/start/restart. - * Binds 127.0.0.1 only. + * HTTP bind from fleet.json control.bind (default 0.0.0.0). * @module server */ @@ -23,7 +23,7 @@ function json(res, code, obj) { * @param {import('./monitor.js').Monitor} [mon] */ export function startControlServer(sup, mon) { - const bind = sup.loaded.control?.bind || '127.0.0.1'; + const bind = process.env.FLEET_BIND || sup.loaded.control?.bind || '0.0.0.0'; const port = Number(sup.loaded.control?.port || 3850); const sim = new Simulator(); diff --git a/packages/verae-fleet/src/ssh.js b/packages/verae-fleet/src/ssh.js index e8a86c7..d8d2871 100644 --- a/packages/verae-fleet/src/ssh.js +++ b/packages/verae-fleet/src/ssh.js @@ -57,7 +57,7 @@ export function scpBaseArgs(machine) { return args; } -export function sshExec(machine, remoteCommand, { timeoutMs = 20000 } = {}) { +export function sshExec(machine, remoteCommand, { timeoutMs = 8000 } = {}) { return new Promise((resolve, reject) => { const args = [...sshBaseArgs(machine), sshTarget(machine), remoteCommand]; const child = spawn('ssh', args, { stdio: ['ignore', 'pipe', 'pipe'] }); @@ -96,7 +96,7 @@ export function scpTo(machine, localFiles, remoteDir) { const t = setTimeout(() => { child.kill('SIGKILL'); reject(new Error('scp timeout')); - }, 30000); + }, 8000); child.on('close', (code) => { clearTimeout(t); if (code !== 0) reject(new Error(Buffer.concat(err).toString('utf8') || `scp exit ${code}`)); diff --git a/packages/verae-fleet/src/supervisor.js b/packages/verae-fleet/src/supervisor.js index ab51f2b..92937b0 100644 --- a/packages/verae-fleet/src/supervisor.js +++ b/packages/verae-fleet/src/supervisor.js @@ -153,6 +153,7 @@ export class Supervisor { serviceId, spec.role || serviceId, opts.excludeMachines || [], + { preferLocal: Boolean(spec.spawn?.command) }, ); if (!machine) { this.log('skip', { service: serviceId, reason: 'no-machine-capacity' }); diff --git a/packages/verae-fleet/test/fleet.test.js b/packages/verae-fleet/test/fleet.test.js index c03b564..aa717eb 100644 --- a/packages/verae-fleet/test/fleet.test.js +++ b/packages/verae-fleet/test/fleet.test.js @@ -58,6 +58,9 @@ describe('verae-fleet', () => { 'access-api', 'access-leaf', 'access-zapier', + 'access-staff', + 'identity', + 'jobs-events', 'account-balance', 'customer-service', 'sales-pricing', @@ -78,6 +81,8 @@ describe('verae-fleet', () => { assert.equal(tree.keepFloor, true); assert.equal(tree.configPath, 'services/tree-node.json'); assert.equal(loaded.fleetPath, 'fleet.json'); + const lan = loaded.machines.find((m) => m.id === 'lan-134'); + if (lan) assert.equal(lan.enabled, false); }); it('starts the tree-node floor (3 available copies)', async () => { diff --git a/packages/verae-fleet/test/ssh.test.js b/packages/verae-fleet/test/ssh.test.js index 624bd74..7a1adc8 100644 --- a/packages/verae-fleet/test/ssh.test.js +++ b/packages/verae-fleet/test/ssh.test.js @@ -53,4 +53,19 @@ describe('SSH remote machine config', () => { const pick = pickMachine(machines, instances, 'tree-node', 'tree-node'); assert.equal(pick.id, 'ns1'); }); + + it('preferLocal keeps HTTP apps on the control host', () => { + const machines = [ + normalizeMachine({ id: 'local', kind: 'local', host: '127.0.0.1', capacity: 32, roles: ['*'] }), + normalizeMachine({ + id: 'ns1', + kind: 'ssh', + host: '70.88.205.138', + capacity: 24, + roles: ['*'], + }), + ]; + const pick = pickMachine(machines, [], 'account-balance', 'account-balance', [], { preferLocal: true }); + assert.equal(pick.id, 'local'); + }); }); diff --git a/packages/verae-jobs-events/NATS.md b/packages/verae-jobs-events/NATS.md new file mode 100644 index 0000000..0996e14 --- /dev/null +++ b/packages/verae-jobs-events/NATS.md @@ -0,0 +1,3 @@ +# NATS — verae-jobs-events + +IN `verae.zapier.jobs.events` queue `jobs-events`. diff --git a/packages/verae-jobs-events/README.md b/packages/verae-jobs-events/README.md new file mode 100644 index 0000000..936ee4d --- /dev/null +++ b/packages/verae-jobs-events/README.md @@ -0,0 +1,7 @@ +# verae-jobs-events + +Mailbox process for `verae.zapier.jobs.events`. Today it counts events (passthrough). Webhook routing still lives in middleware until this process takes the exclusive consumer. + +**Forgejo:** https://git.georgelambert.org/marchon/verae-jobs-events + +Port `:3030`. diff --git a/packages/verae-jobs-events/package.json b/packages/verae-jobs-events/package.json new file mode 100644 index 0000000..89faf9a --- /dev/null +++ b/packages/verae-jobs-events/package.json @@ -0,0 +1,14 @@ +{ + "name": "verae-jobs-events", + "version": "0.1.0", + "private": true, + "type": "module", + "description": "Mailbox for verae.zapier.jobs.events (passthrough)", + "scripts": { + "start": "node src/server.js", + "test": "node --test test/*.test.js" + }, + "dependencies": { + "nats": "^2.28.2" + } +} diff --git a/packages/verae-jobs-events/src/server.js b/packages/verae-jobs-events/src/server.js new file mode 100644 index 0000000..2bbdda6 --- /dev/null +++ b/packages/verae-jobs-events/src/server.js @@ -0,0 +1,42 @@ +#!/usr/bin/env node +/** Mailbox for verae.zapier.jobs.events. Passthrough: count + optional fan-out later. */ +import http from 'node:http'; +import { SUBJECTS } from './subjects.js'; + +const PORT = Number(process.env.PORT || process.env.FLEET_HEALTH_PORT || 3030); +const BIND = process.env.FLEET_HEALTH_BIND || '0.0.0.0'; +let processed = 0; +let last = null; + +async function startNats() { + const url = process.env.NATS_URL; + if (!url) return; + const { connect, StringCodec } = await import('nats'); + const nc = await connect({ servers: url.split(','), name: 'verae-jobs-events' }); + const sc = StringCodec(); + for await (const m of nc.subscribe(SUBJECTS.IN, { queue: SUBJECTS.QUEUE })) { + processed += 1; + try { + last = JSON.parse(sc.decode(m.data) || '{}'); + } catch { + last = {}; + } + if (m.reply) m.respond(sc.encode(JSON.stringify({ ok: true, processed }))); + } +} + +const server = http.createServer((req, res) => { + const url = new URL(req.url || '/', `http://127.0.0.1:${PORT}`); + if (url.pathname === '/health') { + res.writeHead(200, { 'content-type': 'application/json' }); + res.end(JSON.stringify({ ok: true, role: 'verae-jobs-events', processed, subject: SUBJECTS.IN, lastEvent: last?.event || null })); + return; + } + res.writeHead(404, { 'content-type': 'application/json' }); + res.end(JSON.stringify({ error: 'not found' })); +}); + +server.listen(PORT, BIND, () => { + process.stdout.write(`verae-jobs-events http://${BIND}:${PORT}/\n`); +}); +startNats().catch((err) => process.stderr.write(`nats optional: ${err.message}\n`)); diff --git a/packages/verae-jobs-events/src/subjects.js b/packages/verae-jobs-events/src/subjects.js new file mode 100644 index 0000000..b9d826d --- /dev/null +++ b/packages/verae-jobs-events/src/subjects.js @@ -0,0 +1,4 @@ +export const SUBJECTS = { + IN: 'verae.zapier.jobs.events', + QUEUE: 'jobs-events', +}; diff --git a/packages/verae-jobs-events/test/health.test.js b/packages/verae-jobs-events/test/health.test.js new file mode 100644 index 0000000..71dbb2f --- /dev/null +++ b/packages/verae-jobs-events/test/health.test.js @@ -0,0 +1,23 @@ +import { test } from 'node:test'; +import assert from 'node:assert/strict'; +import { spawn } from 'node:child_process'; +import path from 'node:path'; +import { fileURLToPath } from 'node:url'; + +const root = path.join(path.dirname(fileURLToPath(import.meta.url)), '..'); + +test('jobs-events health', async () => { + const port = 18030; + const child = spawn(process.execPath, ['src/server.js'], { + cwd: root, + env: { ...process.env, PORT: String(port) }, + stdio: ['ignore', 'pipe', 'pipe'], + }); + await new Promise((r) => setTimeout(r, 400)); + try { + const h = await (await fetch(`http://127.0.0.1:${port}/health`)).json(); + assert.equal(h.role, 'verae-jobs-events'); + } finally { + child.kill('SIGTERM'); + } +}); diff --git a/packages/verae-nats-accounts/NATS.md b/packages/verae-nats-accounts/NATS.md new file mode 100644 index 0000000..c782336 --- /dev/null +++ b/packages/verae-nats-accounts/NATS.md @@ -0,0 +1,3 @@ +# NATS — verae-nats-accounts + +Not a subscriber. Defines INTERNAL vs LEAF. Leaf deny `verae.billing.>`. diff --git a/packages/verae-nats-accounts/README.md b/packages/verae-nats-accounts/README.md new file mode 100644 index 0000000..1284304 --- /dev/null +++ b/packages/verae-nats-accounts/README.md @@ -0,0 +1,8 @@ +# verae-nats-accounts + +NATS **account + leaf allow-list**. Leaf nodes cannot publish `verae.billing.*`. + +**Forgejo:** https://git.georgelambert.org/marchon/verae-nats-accounts + +- `policy.json` — machine-readable allow/deny (used by access-leaf). +- `nats.conf` — sketch for a future accounts-enabled nats-server (loopback). diff --git a/packages/verae-nats-accounts/nats.conf b/packages/verae-nats-accounts/nats.conf new file mode 100644 index 0000000..6e2bede --- /dev/null +++ b/packages/verae-nats-accounts/nats.conf @@ -0,0 +1,21 @@ +# Lab accounts sketch. Loopback only. Do not publish 4222. +# INTERNAL: middleware, account-balance, authz, identity. +# LEAF: access-leaf and remote leaf nodes — no billing. + +listen: 127.0.0.1:4222 +http: 127.0.0.1:8222 +jetstream {} + +accounts { + INTERNAL { + users = [ { user: internal, password: internal-dev } ] + jetstream: enabled + } + LEAF { + users = [ { user: leaf, password: leaf-dev } ] + exports = [] + imports = [] + } +} +# Subject restrictions for LEAF are enforced in policy.json + access-leaf +# until this nats-server is started with full auth callout. diff --git a/packages/verae-nats-accounts/package.json b/packages/verae-nats-accounts/package.json new file mode 100644 index 0000000..0213cab --- /dev/null +++ b/packages/verae-nats-accounts/package.json @@ -0,0 +1,10 @@ +{ + "name": "verae-nats-accounts", + "version": "0.1.0", + "private": true, + "type": "module", + "description": "NATS account and leaf subject policy (INTERNAL vs LEAF)", + "scripts": { + "test": "node --test test/*.test.js" + } +} diff --git a/packages/verae-nats-accounts/policy.json b/packages/verae-nats-accounts/policy.json new file mode 100644 index 0000000..8c5a59c --- /dev/null +++ b/packages/verae-nats-accounts/policy.json @@ -0,0 +1,35 @@ +{ + "accounts": { + "INTERNAL": { + "publish": [">"], + "subscribe": [">"] + }, + "LEAF": { + "publish": [ + "verae.access.leaf.in", + "verae.archive.put", + "verae.archive.query", + "verae.archive.reply.*", + "verae.zapier.jobs.watch", + "verae.zapier.jobs.events", + "verae.zapier.webhooks.deliver" + ], + "subscribe": [ + "verae.access.leaf.in", + "verae.archive.>", + "verae.zapier.jobs.>", + "verae.zapier.webhooks.deliver" + ], + "deny_publish": ["verae.billing.>", "verae.access.authz.>"], + "deny_subscribe": ["verae.billing.>"] + } + }, + "leafAllow": [ + "verae.archive.put", + "verae.archive.query", + "verae.archive.reply.", + "verae.zapier.jobs.watch", + "verae.zapier.jobs.events", + "verae.zapier.webhooks.deliver" + ] +} diff --git a/packages/verae-nats-accounts/src/policy.js b/packages/verae-nats-accounts/src/policy.js new file mode 100644 index 0000000..35bb5af --- /dev/null +++ b/packages/verae-nats-accounts/src/policy.js @@ -0,0 +1,14 @@ +import fs from 'node:fs'; +import path from 'node:path'; +import { fileURLToPath } from 'node:url'; + +const FILE = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'policy.json'); + +export function loadPolicy() { + return JSON.parse(fs.readFileSync(FILE, 'utf8')); +} + +export function leafAllowed(subject) { + const allow = loadPolicy().leafAllow || []; + return allow.some((p) => (p.endsWith('.') ? subject.startsWith(p) : subject === p || subject.startsWith(`${p}.`))); +} diff --git a/packages/verae-nats-accounts/test/policy.test.js b/packages/verae-nats-accounts/test/policy.test.js new file mode 100644 index 0000000..0cc9ca0 --- /dev/null +++ b/packages/verae-nats-accounts/test/policy.test.js @@ -0,0 +1,12 @@ +import { test } from 'node:test'; +import assert from 'node:assert/strict'; +import { leafAllowed, loadPolicy } from '../src/policy.js'; + +test('leaf may archive and jobs, never billing', () => { + assert.equal(leafAllowed('verae.archive.put'), true); + assert.equal(leafAllowed('verae.archive.reply.abc'), true); + assert.equal(leafAllowed('verae.zapier.jobs.watch'), true); + assert.equal(leafAllowed('verae.billing.balance.adjust'), false); + assert.equal(leafAllowed('verae.billing.statement.get'), false); + assert.ok(loadPolicy().accounts.LEAF.deny_publish.includes('verae.billing.>')); +}); diff --git a/packages/verae-ops/GETTING-STARTED.md b/packages/verae-ops/GETTING-STARTED.md index fb8253b..b142c27 100644 --- a/packages/verae-ops/GETTING-STARTED.md +++ b/packages/verae-ops/GETTING-STARTED.md @@ -11,8 +11,10 @@ This is the **top document** for install, first-up, and monitoring. Platform-spe | Piece | Job | Default | |-------|-----|---------| | **access-authz** | NATS authorization step for every access plane | `:3020` | -| **access-web / api / leaf / zapier** | Separated ingress (browser, x-api-key, S2S, Zapier) | `:3021–:3024` | -| **zappier-edge** | Billing, API keys, customer portal, admin, Stripe; meters then **proxies** to middleware | `:3000` public HTTPS | +| **access-web / api / leaf / zapier / staff** | Public HTTP doors | `:3021–:3025` | +| **identity** | `veraeUserId` bind/lookup | `:3026` | +| **zappier-edge** | Identity cache, Stripe, admin, portal (loopback only) | `127.0.0.1:3000` | +| **jobs-events** | Mailbox `verae.zapier.jobs.events` | `:3030` | | **account-balance** | NATS prepaid balances (SoT) | `:3010` | | **customer-service** | CS credit additions + review | `:3011` | | **sales-pricing** | Per-customer sales quotes | `:3012` | @@ -20,9 +22,9 @@ This is the **top document** for install, first-up, and monitoring. Platform-spe | **verae-middleware** | Zapier `/zapier/v1`, chain, NATS | `:3100` | | **NATS JetStream** | Private jobs / archive | `:4222` **not public** | | **worm ×3, tree-node ×3** | Off-chain files and Merkle leaves | fleet floor | -| **fleet** | Replica floors, SSH hosts, Trace, Docs | `:3850` loopback | +| **fleet** | Replica floors, SSH hosts, Trace, Docs | `:3850` on `0.0.0.0` | -Zapier cloud talks **only** to zappier-edge over HTTPS. +Zapier cloud talks **only** to **access-zapier** (`:3024`) over HTTPS. Browsers use access-web. Customer API keys use access-api. Staff use access-staff. zappier-edge is loopback. The billing and user platform is the standalone **zappier** project (`/Users/marchon/zappier`, Forgejo [zappier-edge](https://git.georgelambert.org/marchon/zappier-edge)): portal signup, TOTP, API keys, rate card, Stripe meter, PO invoices, admin users. Verae middleware does **not** replace it. diff --git a/packages/verae-zapier-simulator/README.md b/packages/verae-zapier-simulator/README.md index 7ec71b1..4e174fe 100644 --- a/packages/verae-zapier-simulator/README.md +++ b/packages/verae-zapier-simulator/README.md @@ -7,7 +7,7 @@ Use it to validate messaging and to catch errors, delays, failures, and recoveri ```bash cd packages/verae-zapier-simulator npm test -npm start # http://127.0.0.1:3847/ +npm start # http://0.0.0.0:3847/ ``` ## What it simulates diff --git a/packages/verae-zapier-simulator/src/server.js b/packages/verae-zapier-simulator/src/server.js index e9c0a43..f2e0886 100644 --- a/packages/verae-zapier-simulator/src/server.js +++ b/packages/verae-zapier-simulator/src/server.js @@ -1,6 +1,6 @@ /** * Local Zapier interface simulator + trace console. - * Default http://127.0.0.1:3847 + * Default http://0.0.0.0:3847 */ import http from 'node:http'; import fs from 'node:fs'; @@ -11,6 +11,7 @@ import { ACTIONS, Simulator } from './pipeline.js'; const __dirname = path.dirname(fileURLToPath(import.meta.url)); const PUBLIC = path.join(__dirname, '..', 'public'); const PORT = Number(process.env.SIM_PORT || 3847); +const BIND = process.env.SIM_BIND || '0.0.0.0'; const world = new Simulator(); const mime = { @@ -81,6 +82,6 @@ const server = http.createServer(async (req, res) => { } }); -server.listen(PORT, '127.0.0.1', () => { - process.stdout.write(`Zapier simulator http://127.0.0.1:${PORT}/\n`); +server.listen(PORT, BIND, () => { + process.stdout.write(`Zapier simulator http://${BIND}:${PORT}/\n`); }); diff --git a/packages/zapier-decisions/LOG.md b/packages/zapier-decisions/LOG.md new file mode 100644 index 0000000..6e65154 --- /dev/null +++ b/packages/zapier-decisions/LOG.md @@ -0,0 +1,40 @@ +# Action log + +## 2026-09-11 — bootstrap + +- Created this repo to record decisions while executing cleanup items 1–5 (and a second pass on 2–5). +- Assumption: single developer, lab only; breaking changes allowed. + +## Step 1 — account-balance is the prepaid source of truth + +- Persist books to `BOOKS_PATH` (atomic JSON). +- Mutations go through `balance.adjust` / `usage.recorded`; edge cache `balanceCents` is updated from the books reply only. +- Local cache mutate only when `NATS_URL` and `ACCOUNT_BALANCE_URL` are both unset (tests). + +## Step 2 — identity join + +- `zappier-identity` mailbox: `verae.identity.bind` / `verae.identity.lookup`. +- Portal + middleware tenants store `veraeUserId`; JWT never public. + +## Step 3 — access planes are the public doors + +- zappier-edge binds loopback (`127.0.0.1:3000`). +- Public: access-web `:3021`, access-api `:3022`, access-leaf `:3023`, access-zapier `:3024`, access-staff `:3025`. + +## Step 4 — leaf hardening + +- `verae-nats-accounts` holds nats.conf + subject policy. +- Leaf token required; billing subjects denied in policy file and access-leaf. + +## Step 5 — fleet spawn + +- Prefer local machines for HTTP `spawn.command` services. +- Disable lan-134 unless `FLEET_ENABLE_LAN134=1`. +- SSH spawn timeout 8s; failed hosts skipped. + +## Second pass (2–5) + +- Identity used from portal when `IDENTITY_URL` set. +- Leaf loads allow-list from nats-accounts `policy.json`. +- Staff plane is a first-class mailbox (`verae-access-staff`). +- jobs.events mailbox process `verae-jobs-events` (passthrough + count). diff --git a/packages/zapier-decisions/NATS.md b/packages/zapier-decisions/NATS.md new file mode 100644 index 0000000..782a476 --- /dev/null +++ b/packages/zapier-decisions/NATS.md @@ -0,0 +1,3 @@ +# NATS — zapier-decisions + +None. Documentation repo. diff --git a/packages/zapier-decisions/README.md b/packages/zapier-decisions/README.md new file mode 100644 index 0000000..58e5adb --- /dev/null +++ b/packages/zapier-decisions/README.md @@ -0,0 +1,13 @@ +# zapier-decisions + +Lab log of architecture decisions, actions taken, and open todos while cleaning the Verae × Zapier stack. + +**Forgejo:** https://git.georgelambert.org/marchon/zapier-decisions + +| File | What | +|------|------| +| [LOG.md](LOG.md) | Chronological actions | +| [TODO.md](TODO.md) | Open items | +| [decisions/](decisions/) | One file per decision | + +No runtime. Not a NATS mailbox. diff --git a/packages/zapier-decisions/TODO.md b/packages/zapier-decisions/TODO.md new file mode 100644 index 0000000..068fd3f --- /dev/null +++ b/packages/zapier-decisions/TODO.md @@ -0,0 +1,8 @@ +# Open todos + +- [ ] Live `api.veraetime.net` with `MOCK_VERAE=false` and admin bind credentials. +- [ ] NATS nkeys/mTLS on a real three-node cluster (accounts file is the lab stand-in). +- [ ] Exclusive JetStream consumer for `verae.zapier.jobs.events` on `verae-jobs-events` (middleware still also listens). +- [ ] Auth on CS/sales/accounting HTML (staff plane is the intended door). +- [ ] Zapier Platform `push` of a private app. +- [ ] Move portal static files fully into `verae-access-web` (today it proxies `/portal` to loopback edge). diff --git a/packages/zapier-decisions/decisions/D001-prepaid-sot.md b/packages/zapier-decisions/decisions/D001-prepaid-sot.md new file mode 100644 index 0000000..9b1bace --- /dev/null +++ b/packages/zapier-decisions/decisions/D001-prepaid-sot.md @@ -0,0 +1,6 @@ +# D001 — Account-balance is the only prepaid writer + +**Status:** accepted +**Step:** 1 + +Prepaid cents, credits, usage, and payments persist in `zappier-account-balance` (`books.json`). zappier-edge `balanceCents` is a cache filled from the books reply. Tests without NATS/HTTP books still mutate the cache so unit tests stay hermetic. diff --git a/packages/zapier-decisions/decisions/D002-identity.md b/packages/zapier-decisions/decisions/D002-identity.md new file mode 100644 index 0000000..7548947 --- /dev/null +++ b/packages/zapier-decisions/decisions/D002-identity.md @@ -0,0 +1,6 @@ +# D002 — veraeUserId is the join key, not the JWT + +**Status:** accepted +**Step:** 2 + +Public token remains the zappier API key. Chain JWT stays server-side (`tokenRef`). `zappier-identity` is the mailbox for bind/lookup so portal and middleware share one map. diff --git a/packages/zapier-decisions/decisions/D003-public-doors.md b/packages/zapier-decisions/decisions/D003-public-doors.md new file mode 100644 index 0000000..9d32527 --- /dev/null +++ b/packages/zapier-decisions/decisions/D003-public-doors.md @@ -0,0 +1,6 @@ +# D003 — Access planes are the only public HTTP doors + +**Status:** accepted +**Step:** 3 + +Zapier → `:3024`, browser → `:3021`, customer API → `:3022`, leaf → `:3023`, staff → `:3025`. zappier-edge listens on `127.0.0.1:3000` for identity, Stripe, admin, and as upstream for those planes. diff --git a/packages/zapier-decisions/decisions/D004-leaf-accounts.md b/packages/zapier-decisions/decisions/D004-leaf-accounts.md new file mode 100644 index 0000000..65de80d --- /dev/null +++ b/packages/zapier-decisions/decisions/D004-leaf-accounts.md @@ -0,0 +1,6 @@ +# D004 — Leaf cannot touch billing, even if authz is skipped + +**Status:** accepted +**Step:** 4 + +`verae-nats-accounts/policy.json` is the allow-list. access-leaf refuses any target not in the leaf set. nats.conf documents INTERNAL vs LEAF accounts for when the lab cluster is replaced with a real accounts-enabled nats-server. diff --git a/packages/zapier-decisions/decisions/D005-fleet-local-first.md b/packages/zapier-decisions/decisions/D005-fleet-local-first.md new file mode 100644 index 0000000..4df6ecd --- /dev/null +++ b/packages/zapier-decisions/decisions/D005-fleet-local-first.md @@ -0,0 +1,6 @@ +# D005 — HTTP services spawn locally; lan-134 stays off + +**Status:** accepted +**Step:** 5 + +SSH to `70.88.205.134` blocked keepFloor. HTTP apps (`spawn.command`) prefer `kind=local`. `lan-134` is disabled unless `FLEET_ENABLE_LAN134=1`. Failed SSH hosts are skipped after 8s. diff --git a/packages/zapier-decisions/package.json b/packages/zapier-decisions/package.json new file mode 100644 index 0000000..a12c852 --- /dev/null +++ b/packages/zapier-decisions/package.json @@ -0,0 +1,6 @@ +{ + "name": "zapier-decisions", + "version": "0.1.0", + "private": true, + "description": "Architecture decisions and action log for the Verae × Zapier stack" +} diff --git a/packages/zappier-account-balance/README.md b/packages/zappier-account-balance/README.md index 0c261d6..9b1113b 100644 --- a/packages/zappier-account-balance/README.md +++ b/packages/zappier-account-balance/README.md @@ -1,6 +1,6 @@ # zappier-account-balance -Source of truth for **customer prepaid balances**. Internal traffic is **NATS request-reply**; HTTP is health plus a fallback. +Source of truth for **customer prepaid balances** (persisted `books.json`). Internal traffic is **NATS request-reply**; HTTP is health plus a fallback. zappier-edge `balanceCents` is a cache of this book. **Forgejo:** https://git.georgelambert.org/marchon/zappier-account-balance **Catalog:** https://zapier.georgelambert.org/packages/zappier-account-balance/README.pdf diff --git a/packages/zappier-account-balance/src/books.js b/packages/zappier-account-balance/src/books.js index e715911..91119f4 100644 --- a/packages/zappier-account-balance/src/books.js +++ b/packages/zappier-account-balance/src/books.js @@ -78,6 +78,26 @@ export class AccountBooks { payments: match(this.payments), }; } + + dump() { + return { + prepaid: this.prepaid, + veraeUserIds: this.veraeUserIds, + credits: this.credits, + usage: this.usage, + payments: this.payments, + }; + } + + load(raw) { + if (!raw || typeof raw !== 'object') return this; + this.prepaid = raw.prepaid || {}; + this.veraeUserIds = raw.veraeUserIds || {}; + this.credits = Array.isArray(raw.credits) ? raw.credits : []; + this.usage = Array.isArray(raw.usage) ? raw.usage : []; + this.payments = Array.isArray(raw.payments) ? raw.payments : []; + return this; + } } export function handle(subject, payload, books) { diff --git a/packages/zappier-account-balance/src/persist.js b/packages/zappier-account-balance/src/persist.js new file mode 100644 index 0000000..9b857ff --- /dev/null +++ b/packages/zappier-account-balance/src/persist.js @@ -0,0 +1,28 @@ +import fs from 'node:fs'; +import path from 'node:path'; + +export function booksPath() { + return ( + process.env.BOOKS_PATH || + path.join(process.env.FLEET_STATE_DIR || process.cwd(), 'data', 'books.json') + ); +} + +export function loadInto(books) { + const p = booksPath(); + if (!fs.existsSync(p)) return books; + try { + books.load(JSON.parse(fs.readFileSync(p, 'utf8'))); + } catch { + /* keep empty */ + } + return books; +} + +export function saveFrom(books) { + const p = booksPath(); + fs.mkdirSync(path.dirname(p), { recursive: true }); + const tmp = `${p}.tmp`; + fs.writeFileSync(tmp, JSON.stringify(books.dump(), null, 2)); + fs.renameSync(tmp, p); +} diff --git a/packages/zappier-account-balance/src/server.js b/packages/zappier-account-balance/src/server.js index 0ec0204..b20d567 100644 --- a/packages/zappier-account-balance/src/server.js +++ b/packages/zappier-account-balance/src/server.js @@ -2,10 +2,17 @@ import http from 'node:http'; import { AccountBooks, handle } from './books.js'; import { SUBJECTS } from './subjects.js'; +import { loadInto, saveFrom } from './persist.js'; const PORT = Number(process.env.PORT || process.env.FLEET_HEALTH_PORT || 3010); const BIND = process.env.FLEET_HEALTH_BIND || '0.0.0.0'; -const books = new AccountBooks(); +const books = loadInto(new AccountBooks()); + +function apply(subject, payload) { + const out = handle(subject, payload, books); + saveFrom(books); + return out; +} let natsOk = false; async function startNats() { @@ -23,21 +30,22 @@ async function startNats() { payload = {}; } const out = fn(payload); + saveFrom(books); if (m.reply) m.respond(sc.encode(JSON.stringify(out))); } }; reply(nc.subscribe(SUBJECTS.STATEMENT_GET, { queue: SUBJECTS.QUEUE }), (p) => - handle(SUBJECTS.STATEMENT_GET, p, books), + apply(SUBJECTS.STATEMENT_GET, p), ); reply(nc.subscribe(SUBJECTS.BALANCE_GET, { queue: SUBJECTS.QUEUE }), (p) => - handle(SUBJECTS.BALANCE_GET, p, books), + apply(SUBJECTS.BALANCE_GET, p), ); reply(nc.subscribe(SUBJECTS.BALANCE_ADJUST, { queue: SUBJECTS.QUEUE }), (p) => - handle(SUBJECTS.BALANCE_ADJUST, p, books), + apply(SUBJECTS.BALANCE_ADJUST, p), ); (async () => { for await (const m of nc.subscribe(SUBJECTS.USAGE_RECORDED)) { - handle(SUBJECTS.USAGE_RECORDED, JSON.parse(sc.decode(m.data) || '{}'), books); + apply(SUBJECTS.USAGE_RECORDED, JSON.parse(sc.decode(m.data) || '{}')); } })(); // payment.recorded / credit.applied are fan-out events. Prepaid mutations @@ -76,7 +84,7 @@ const server = http.createServer(async (req, res) => { } if (req.method === 'POST' && url.pathname === '/adjust') { const body = await readBody(req); - return json(200, books.adjust(body)); + return json(200, apply(SUBJECTS.BALANCE_ADJUST, body)); } json(404, { error: 'not found' }); } catch (err) { diff --git a/packages/zappier-account-balance/test/books.test.js b/packages/zappier-account-balance/test/books.test.js index 48e0583..230fc55 100644 --- a/packages/zappier-account-balance/test/books.test.js +++ b/packages/zappier-account-balance/test/books.test.js @@ -1,7 +1,11 @@ import { test } from 'node:test'; import assert from 'node:assert/strict'; +import fs from 'node:fs'; +import os from 'node:os'; +import path from 'node:path'; import { AccountBooks, handle } from '../src/books.js'; import { SUBJECTS } from '../src/subjects.js'; +import { loadInto, saveFrom, booksPath } from '../src/persist.js'; test('adjust credits prepaid and statement lists credits usage payments', () => { const books = new AccountBooks(); @@ -19,3 +23,15 @@ test('adjust credits prepaid and statement lists credits usage payments', () => assert.equal(st.usage[0].endpointId, 'timestamp'); assert.equal(st.payments[0].kind, 'payment'); }); + +test('persist round-trip keeps prepaid', () => { + const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'books-')); + process.env.BOOKS_PATH = path.join(dir, 'books.json'); + const a = new AccountBooks(); + handle(SUBJECTS.BALANCE_ADJUST, { customerId: 'c9', cents: 120, kind: 'reload' }, a); + saveFrom(a); + assert.ok(fs.existsSync(booksPath())); + const b = loadInto(new AccountBooks()); + assert.equal(b.prepaidCents('c9'), 120); + delete process.env.BOOKS_PATH; +}); diff --git a/packages/zappier-identity/NATS.md b/packages/zappier-identity/NATS.md new file mode 100644 index 0000000..d7f3166 --- /dev/null +++ b/packages/zappier-identity/NATS.md @@ -0,0 +1,3 @@ +# NATS — zappier-identity + +Queue `identity`. Subjects `verae.identity.bind`, `verae.identity.lookup`. diff --git a/packages/zappier-identity/README.md b/packages/zappier-identity/README.md new file mode 100644 index 0000000..80c438f --- /dev/null +++ b/packages/zappier-identity/README.md @@ -0,0 +1,12 @@ +# zappier-identity + +Mailbox for **Verae user id bind/lookup**. Public credentials stay zappier API keys. JWTs never live here. + +**Forgejo:** https://git.georgelambert.org/marchon/zappier-identity + +| Address | Kind | +|---------|------| +| `verae.identity.bind` | request-reply `{ email, customerId }` | +| `verae.identity.lookup` | request-reply `{ customerId }` or `{ veraeUserId }` | + +HTTP `:3026` `POST /bind` `GET /lookup/:customerId`. diff --git a/packages/zappier-identity/package.json b/packages/zappier-identity/package.json new file mode 100644 index 0000000..aa4e29a --- /dev/null +++ b/packages/zappier-identity/package.json @@ -0,0 +1,14 @@ +{ + "name": "zappier-identity", + "version": "0.1.0", + "private": true, + "type": "module", + "description": "Mailbox: bind and lookup veraeUserId (not JWTs)", + "scripts": { + "start": "node src/server.js", + "test": "node --test test/*.test.js" + }, + "dependencies": { + "nats": "^2.28.2" + } +} diff --git a/packages/zappier-identity/src/ids.js b/packages/zappier-identity/src/ids.js new file mode 100644 index 0000000..bf9d46f --- /dev/null +++ b/packages/zappier-identity/src/ids.js @@ -0,0 +1,15 @@ +import { createHash } from 'node:crypto'; + +export function stableVeraeUserId(username) { + const n = String(username || '') + .trim() + .toLowerCase(); + return `vu_${createHash('sha256').update(n).digest('hex').slice(0, 16)}`; +} + +export function bindEmail(email) { + const veraeUsername = String(email || '') + .trim() + .toLowerCase(); + return { veraeUserId: stableVeraeUserId(veraeUsername), veraeUsername, bound: true }; +} diff --git a/packages/zappier-identity/src/server.js b/packages/zappier-identity/src/server.js new file mode 100644 index 0000000..4f1138e --- /dev/null +++ b/packages/zappier-identity/src/server.js @@ -0,0 +1,89 @@ +#!/usr/bin/env node +/** Mailbox: bind/lookup veraeUserId. JWT never stored here. */ +import http from 'node:http'; +import { bindEmail } from './ids.js'; +import { load, put } from './store.js'; +import { SUBJECTS } from './subjects.js'; + +const PORT = Number(process.env.PORT || 3026); +const BIND = process.env.FLEET_HEALTH_BIND || '0.0.0.0'; +const db = load(); + +function handleBind(p) { + const email = p.email || p.veraeUsername; + const bound = bindEmail(email); + const customerId = p.customerId || bound.veraeUsername; + put(db, { customerId, ...bound }); + return { ...bound, customerId }; +} + +function handleLookup(p) { + if (p.customerId && db.byCustomer[p.customerId]) return db.byCustomer[p.customerId]; + if (p.veraeUserId && db.byVerae[p.veraeUserId]) return db.byVerae[p.veraeUserId]; + if (p.email) return bindEmail(p.email); + return { error: 'not found' }; +} + +async function startNats() { + const url = process.env.NATS_URL; + if (!url) return; + const { connect, StringCodec } = await import('nats'); + const nc = await connect({ servers: url.split(','), name: 'zappier-identity' }); + const sc = StringCodec(); + for (const subj of [SUBJECTS.BIND, SUBJECTS.LOOKUP]) { + (async () => { + for await (const m of nc.subscribe(subj, { queue: SUBJECTS.QUEUE })) { + let p = {}; + try { + p = JSON.parse(sc.decode(m.data) || '{}'); + } catch { + p = {}; + } + const out = subj === SUBJECTS.BIND ? handleBind(p) : handleLookup(p); + if (m.reply) m.respond(sc.encode(JSON.stringify(out))); + } + })(); + } +} + +function readBody(req) { + return new Promise((resolve) => { + const chunks = []; + req.on('data', (c) => chunks.push(c)); + req.on('end', () => { + try { + resolve(JSON.parse(Buffer.concat(chunks).toString('utf8') || '{}')); + } catch { + resolve({}); + } + }); + }); +} + +const server = http.createServer(async (req, res) => { + const url = new URL(req.url || '/', `http://127.0.0.1:${PORT}`); + const json = (code, obj) => { + res.writeHead(code, { 'content-type': 'application/json' }); + res.end(JSON.stringify(obj)); + }; + try { + if (req.method === 'GET' && url.pathname === '/health') { + return json(200, { ok: true, role: 'zappier-identity', subjects: SUBJECTS }); + } + if (req.method === 'POST' && url.pathname === '/bind') { + return json(200, handleBind(await readBody(req))); + } + const who = url.pathname.match(/^\/lookup\/([^/]+)$/); + if (req.method === 'GET' && who) { + return json(200, handleLookup({ customerId: who[1] })); + } + json(404, { error: 'not found' }); + } catch (err) { + json(500, { error: err.message }); + } +}); + +server.listen(PORT, BIND, () => { + process.stdout.write(`zappier-identity http://${BIND}:${PORT}/\n`); +}); +startNats().catch((err) => process.stderr.write(`nats optional: ${err.message}\n`)); diff --git a/packages/zappier-identity/src/store.js b/packages/zappier-identity/src/store.js new file mode 100644 index 0000000..6371ae8 --- /dev/null +++ b/packages/zappier-identity/src/store.js @@ -0,0 +1,30 @@ +import fs from 'node:fs'; +import path from 'node:path'; + +const file = () => + process.env.IDENTITY_PATH || + path.join(process.env.FLEET_STATE_DIR || process.cwd(), 'data', 'identity.json'); + +export function load() { + const p = file(); + if (!fs.existsSync(p)) return { byCustomer: {}, byVerae: {} }; + try { + return { byCustomer: {}, byVerae: {}, ...JSON.parse(fs.readFileSync(p, 'utf8')) }; + } catch { + return { byCustomer: {}, byVerae: {} }; + } +} + +export function save(db) { + const p = file(); + fs.mkdirSync(path.dirname(p), { recursive: true }); + fs.writeFileSync(p, JSON.stringify(db, null, 2)); +} + +export function put(db, { customerId, veraeUserId, veraeUsername }) { + if (!customerId || !veraeUserId) return db; + db.byCustomer[customerId] = { veraeUserId, veraeUsername }; + db.byVerae[veraeUserId] = { customerId, veraeUsername }; + save(db); + return db; +} diff --git a/packages/zappier-identity/src/subjects.js b/packages/zappier-identity/src/subjects.js new file mode 100644 index 0000000..821e7c2 --- /dev/null +++ b/packages/zappier-identity/src/subjects.js @@ -0,0 +1,5 @@ +export const SUBJECTS = { + BIND: 'verae.identity.bind', + LOOKUP: 'verae.identity.lookup', + QUEUE: 'identity', +}; diff --git a/packages/zappier-identity/test/health.test.js b/packages/zappier-identity/test/health.test.js new file mode 100644 index 0000000..2c810f8 --- /dev/null +++ b/packages/zappier-identity/test/health.test.js @@ -0,0 +1,36 @@ +import { test } from 'node:test'; +import assert from 'node:assert/strict'; +import { spawn } from 'node:child_process'; +import fs from 'node:fs'; +import os from 'node:os'; +import path from 'node:path'; +import { fileURLToPath } from 'node:url'; +import { stableVeraeUserId } from '../src/ids.js'; + +const root = path.join(path.dirname(fileURLToPath(import.meta.url)), '..'); + +test('identity bind is stable and not a JWT', async () => { + const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'id-')); + const port = 18026; + const child = spawn(process.execPath, ['src/server.js'], { + cwd: root, + env: { ...process.env, PORT: String(port), IDENTITY_PATH: path.join(dir, 'id.json') }, + stdio: ['ignore', 'pipe', 'pipe'], + }); + await new Promise((r) => setTimeout(r, 400)); + try { + const h = await (await fetch(`http://127.0.0.1:${port}/health`)).json(); + assert.equal(h.role, 'zappier-identity'); + const b = await ( + await fetch(`http://127.0.0.1:${port}/bind`, { + method: 'POST', + headers: { 'content-type': 'application/json' }, + body: JSON.stringify({ email: 'Ada@Example.com', customerId: 'cust_x' }), + }) + ).json(); + assert.equal(b.veraeUserId, stableVeraeUserId('ada@example.com')); + assert.doesNotMatch(JSON.stringify(b), /eyJ|mock-jwt/); + } finally { + child.kill('SIGTERM'); + } +}); diff --git a/packages/zappier/src/admin.ts b/packages/zappier/src/admin.ts index 03264c6..9bf6692 100644 --- a/packages/zappier/src/admin.ts +++ b/packages/zappier/src/admin.ts @@ -13,7 +13,8 @@ import { UsageRepo } from './usage'; import { CreditLedger } from './credits'; import { invoicesToAccountingCsv, invoicesToQuickBooksIif } from './accounting-export'; import { composeStatement } from './statement'; -import { BILLING_SUBJECTS, natsAdjust, natsPublish, natsStatement } from './billing-nats'; +import { BILLING_SUBJECTS, natsPublish } from './billing-nats'; +import { booksConfigured, ledgerAdjust, ledgerStatement } from './ledger'; // Issued login tokens (in-memory; a restart simply requires logging in again). const sessions = new Map(); @@ -229,7 +230,7 @@ export function adminRouter( /* ---------------- customer service: credits ---------------- */ - router.post('/credits', (req, res) => { + router.post('/credits', async (req, res) => { const { customerId, cents, reason, agent } = req.body ?? {}; if (typeof customerId !== 'string' || !Number.isFinite(Number(cents))) { res.status(400).json({ error: 'customerId and cents required' }); @@ -247,9 +248,7 @@ export function adminRouter( reason: typeof reason === 'string' ? reason : 'credit adjustment', agent: typeof agent === 'string' ? agent : 'admin', }); - customers.save({ ...customer, balanceCents: (customer.balanceCents ?? 0) + delta }); - natsPublish(BILLING_SUBJECTS.CREDIT_APPLIED, { ...rec, veraeUserId: customer.veraeUserId }, 'staff'); - void natsAdjust( + const row = await ledgerAdjust( { customerId, veraeUserId: customer.veraeUserId, @@ -260,7 +259,12 @@ export function adminRouter( }, 'staff', ); - res.status(201).json(rec); + let prepaid = customer.balanceCents ?? 0; + if (row && typeof row.prepaidCents === 'number') prepaid = row.prepaidCents; + else if (!booksConfigured()) prepaid += delta; + customers.save({ ...customer, balanceCents: prepaid }); + natsPublish(BILLING_SUBJECTS.CREDIT_APPLIED, { ...rec, veraeUserId: customer.veraeUserId }, 'staff'); + res.status(201).json({ ...rec, prepaidCents: prepaid }); }); router.get('/credits', (req, res) => { @@ -274,9 +278,9 @@ export function adminRouter( res.status(404).json({ error: 'customer not found' }); return; } - const fromNats = await natsStatement(customer.id, 'staff', customer.veraeUserId); - if (fromNats) { - res.json({ ...fromNats, name: customer.name, tierId: customer.tierId, source: 'nats' }); + const fromBooks = await ledgerStatement(customer.id, 'staff', customer.veraeUserId); + if (fromBooks) { + res.json({ ...fromBooks, name: customer.name, tierId: customer.tierId, source: fromBooks.source || 'account-balance' }); return; } res.json({ diff --git a/packages/zappier/src/index.ts b/packages/zappier/src/index.ts index 998bd56..f3429f4 100644 --- a/packages/zappier/src/index.ts +++ b/packages/zappier/src/index.ts @@ -33,8 +33,9 @@ const payments: PaymentClient = hasRealStripeKey(process.env.STRIPE_SECRET_KEY) const { app } = buildApp({ usage, customers, pricingStore, invoices, adminUsers, sessions, payments }); const port = Number(process.env.PORT ?? 3000); -app.listen(port, () => { - console.log(`Zappier API listening on http://localhost:${port}`); +const bind = process.env.BIND ?? '127.0.0.1'; +app.listen(port, bind, () => { + console.log(`Zappier API listening on http://${bind}:${port}`); console.log(`OpenAPI docs at http://localhost:${port}/docs`); console.log(`Customer portal at http://localhost:${port}/portal`); console.log(`Admin console at http://localhost:${port}/admin`); diff --git a/packages/zappier/src/ledger.ts b/packages/zappier/src/ledger.ts new file mode 100644 index 0000000..5905f24 --- /dev/null +++ b/packages/zappier/src/ledger.ts @@ -0,0 +1,50 @@ +/** + * Prepaid mutations. Account-balance is the writer when NATS or HTTP books exist. + * Tests (no NATS_URL, no ACCOUNT_BALANCE_URL) keep a local cache only. + */ +import { natsAdjust, natsStatement } from './billing-nats'; +import type { AccessPlane } from './billing-nats'; + +export type PrepaidRow = { + customerId: string; + veraeUserId?: string; + cents: number; + reason: string; + agent: string; + kind?: string; + prepaidCents?: number; +}; + +function booksUrl(): string { + return (process.env.ACCOUNT_BALANCE_URL || '').replace(/\/$/, ''); +} + +export function booksConfigured(): boolean { + return Boolean(process.env.NATS_URL || booksUrl()); +} + +export async function ledgerAdjust(row: PrepaidRow, plane: AccessPlane): Promise { + const viaNats = await natsAdjust(row, plane); + if (viaNats && typeof viaNats === 'object' && viaNats !== null && 'prepaidCents' in viaNats) { + return viaNats as PrepaidRow; + } + const base = booksUrl(); + if (!base) return null; + const r = await fetch(`${base}/adjust`, { + method: 'POST', + headers: { 'content-type': 'application/json' }, + body: JSON.stringify(row), + }); + if (!r.ok) return null; + return (await r.json()) as PrepaidRow; +} + +export async function ledgerStatement(customerId: string, plane: AccessPlane, veraeUserId?: string) { + const nats = await natsStatement(customerId, plane, veraeUserId); + if (nats) return nats; + const base = booksUrl(); + if (!base) return null; + const r = await fetch(`${base}/statement/${encodeURIComponent(customerId)}`); + if (!r.ok) return null; + return r.json(); +} diff --git a/packages/zappier/src/portal.ts b/packages/zappier/src/portal.ts index b78bd95..740e256 100644 --- a/packages/zappier/src/portal.ts +++ b/packages/zappier/src/portal.ts @@ -16,8 +16,9 @@ import { RateCard, TierConfig } from './pricing'; import { UsageRepo } from './usage'; import { CreditLedger } from './credits'; import { composeStatement } from './statement'; -import { BILLING_SUBJECTS, natsPublish, natsStatement, natsAdjust } from './billing-nats'; +import { BILLING_SUBJECTS, natsPublish } from './billing-nats'; import { bindVeraeUser } from './verae-bind'; +import { booksConfigured, ledgerAdjust, ledgerStatement } from './ledger'; /** * Customer portal API (/portal/api): signup, login with optional TOTP 2FA, @@ -209,9 +210,9 @@ export function portalRouter(deps: PortalDeps): Router { }); router.get('/statement', async (req, res) => { - const fromNats = await natsStatement(req.customer!.id, 'web', req.customer!.veraeUserId); - if (fromNats) { - res.json({ ...fromNats, source: 'nats' }); + const fromBooks = await ledgerStatement(req.customer!.id, 'web', req.customer!.veraeUserId); + if (fromBooks) { + res.json({ ...fromBooks, source: fromBooks.source || 'account-balance' }); return; } res.json({ @@ -287,26 +288,12 @@ export function portalRouter(deps: PortalDeps): Router { return; } const result = await deps.payments.reload(req.customer!, amountCents); - const customer = { - ...req.customer!, - balanceCents: (req.customer!.balanceCents ?? 0) + result.creditedCents, - }; - if (result.creditedCents > 0) save(deps, customer); + let prepaid = req.customer!.balanceCents ?? 0; if (result.creditedCents > 0) { - natsPublish( - BILLING_SUBJECTS.PAYMENT_RECORDED, + const row = await ledgerAdjust( { - customerId: customer.id, - veraeUserId: customer.veraeUserId, - cents: result.creditedCents, - reason: 'reload', - }, - 'web', - ); - void natsAdjust( - { - customerId: customer.id, - veraeUserId: customer.veraeUserId, + customerId: req.customer!.id, + veraeUserId: req.customer!.veraeUserId, cents: result.creditedCents, reason: 'reload', agent: 'portal', @@ -314,9 +301,22 @@ export function portalRouter(deps: PortalDeps): Router { }, 'web', ); + if (row && typeof row.prepaidCents === 'number') prepaid = row.prepaidCents; + else if (!booksConfigured()) prepaid += result.creditedCents; + save(deps, { ...req.customer!, balanceCents: prepaid }); + natsPublish( + BILLING_SUBJECTS.PAYMENT_RECORDED, + { + customerId: req.customer!.id, + veraeUserId: req.customer!.veraeUserId, + cents: result.creditedCents, + reason: 'reload', + }, + 'web', + ); } res.json({ - balanceCents: customer.balanceCents, + balanceCents: prepaid, mode: result.mode, ...(result.clientSecret ? { clientSecret: result.clientSecret } : {}), }); diff --git a/packages/zappier/src/verae-bind.ts b/packages/zappier/src/verae-bind.ts index 04dffb7..9d07ba3 100644 --- a/packages/zappier/src/verae-bind.ts +++ b/packages/zappier/src/verae-bind.ts @@ -28,7 +28,20 @@ function mockBind(email: string): VeraeBind { * Register or look up the customer on api.veraetime.net. * MOCK_VERAE (default) or missing VERAE_API_BASE_URL → stable id, no network. */ -export async function bindVeraeUser(email: string): Promise { +export async function bindVeraeUser(email: string, customerId?: string): Promise { + const identity = (process.env.IDENTITY_URL || '').replace(/\/$/, ''); + if (identity) { + try { + const r = await fetch(`${identity}/bind`, { + method: 'POST', + headers: { 'content-type': 'application/json' }, + body: JSON.stringify({ email, customerId }), + }); + if (r.ok) return (await r.json()) as VeraeBind; + } catch { + /* fall through */ + } + } const mock = process.env.MOCK_VERAE !== 'false'; const base = (process.env.VERAE_API_BASE_URL || '').replace(/\/$/, ''); if (mock || !base) return mockBind(email); diff --git a/scripts/build-docs-site.py b/scripts/build-docs-site.py index eb703cd..361f920 100755 --- a/scripts/build-docs-site.py +++ b/scripts/build-docs-site.py @@ -80,6 +80,11 @@ SECTIONS = [ ("packages/verae-access-api/README.md", "Direct customer API plane"), ("packages/verae-access-leaf/README.md", "S2S NATS leaf plane"), ("packages/verae-access-zapier/README.md", "Zapier-only access plane"), + ("packages/verae-access-staff/README.md", "Staff access plane"), + ("packages/zappier-identity/README.md", "veraeUserId identity mailbox"), + ("packages/verae-jobs-events/README.md", "jobs.events mailbox"), + ("packages/verae-nats-accounts/README.md", "NATS leaf/internal policy"), + ("packages/zapier-decisions/README.md", "Decisions log"), ], ), ( @@ -341,6 +346,11 @@ def main() -> None: "verae-access-api", "verae-access-leaf", "verae-access-zapier", + "verae-access-staff", + "zappier-identity", + "verae-jobs-events", + "verae-nats-accounts", + "zapier-decisions", ): pkg_root = ROOT / "packages" / pkg if pkg in {"zapier-user-docs", "overview", "docs-master", "verae-ops"}: @@ -508,6 +518,11 @@ def main() -> None: ("verae-access-api", "Direct customer API"), ("verae-access-leaf", "S2S NATS leaf"), ("verae-access-zapier", "Zapier access plane"), + ("verae-access-staff", "Staff access plane"), + ("zappier-identity", "veraeUserId bind/lookup"), + ("verae-jobs-events", "jobs.events mailbox"), + ("verae-nats-accounts", "NATS leaf/internal policy"), + ("zapier-decisions", "Decisions and action log"), ] git_lis = "".join( f'
  • {name} ' diff --git a/scripts/gen-module-docs.py b/scripts/gen-module-docs.py index 914e744..9b06098 100644 --- a/scripts/gen-module-docs.py +++ b/scripts/gen-module-docs.py @@ -31,6 +31,10 @@ PACKAGES = [ ("verae-access-api", ROOT / "packages" / "verae-access-api" / "src", (".js",)), ("verae-access-leaf", ROOT / "packages" / "verae-access-leaf" / "src", (".js",)), ("verae-access-zapier", ROOT / "packages" / "verae-access-zapier" / "src", (".js",)), + ("verae-access-staff", ROOT / "packages" / "verae-access-staff" / "src", (".js",)), + ("zappier-identity", ROOT / "packages" / "zappier-identity" / "src", (".js",)), + ("verae-jobs-events", ROOT / "packages" / "verae-jobs-events" / "src", (".js",)), + ("verae-nats-accounts", ROOT / "packages" / "verae-nats-accounts" / "src", (".js",)), ] REPO_READMES = [ @@ -58,6 +62,11 @@ REPO_READMES = [ "verae-access-api", "verae-access-leaf", "verae-access-zapier", + "verae-access-staff", + "zappier-identity", + "verae-jobs-events", + "verae-nats-accounts", + "zapier-decisions", ] SKIP_PARTS = {"test", "tests", "node_modules", "dist"} diff --git a/scripts/push-module-repos.sh b/scripts/push-module-repos.sh index bae625b..4a7233c 100755 --- a/scripts/push-module-repos.sh +++ b/scripts/push-module-repos.sh @@ -59,6 +59,11 @@ create verae-access-web "Direct customer web access plane" create verae-access-api "Direct customer API access plane" create verae-access-leaf "Server-to-server NATS leaf access plane" create verae-access-zapier "Zapier Platform access plane only" +create verae-access-staff "Staff CS/sales/accounting access plane" +create zappier-identity "Bind and lookup veraeUserId" +create verae-jobs-events "Mailbox for verae.zapier.jobs.events" +create verae-nats-accounts "NATS INTERNAL vs LEAF account policy" +create zapier-decisions "Architecture decisions and action log" push_dir "$ROOT/packages/zappier" zappier-edge push_dir "$ROOT/packages/verae-zapier-middleware" verae-middleware @@ -84,5 +89,10 @@ push_dir "$ROOT/packages/verae-access-web" verae-access-web push_dir "$ROOT/packages/verae-access-api" verae-access-api push_dir "$ROOT/packages/verae-access-leaf" verae-access-leaf push_dir "$ROOT/packages/verae-access-zapier" verae-access-zapier +push_dir "$ROOT/packages/verae-access-staff" verae-access-staff +push_dir "$ROOT/packages/zappier-identity" zappier-identity +push_dir "$ROOT/packages/verae-jobs-events" verae-jobs-events +push_dir "$ROOT/packages/verae-nats-accounts" verae-nats-accounts +push_dir "$ROOT/packages/zapier-decisions" zapier-decisions echo ALL_MODULE_REPOS_PUSHED