Initial import of zapier-docs-master from zapier monorepo

modules/overview/NATS.md

@@ -0,0 +1,3 @@
+# NATS — overview
+
+Documentation only. Describes the central 3-server cluster. Zapier never connects.

modules/overview/SUMMARY.md

@@ -0,0 +1,3 @@
+# overview
+
+High-level system map, 3-node NATS cluster, uptime, network failure, address routing. Repo: `overview`.

modules/verae-activate/NATS.md

@@ -0,0 +1,10 @@
+# NATS — verae-activate
+
+This Zapier Platform app **does not use NATS**.
+
+| Direction | Address | Peer | Body |
+|-----------|---------|------|------|
+| IN | Zapier UI / runtime | user Zap | `number1`, `number2`, `text`, `data` / `sha256` |
+| OUT HTTPS (optional) | zappier-edge `/v1/add` or `/v1/timestamp` | only if `api_base` + `api_key` set | JSON |
+
+Blank connection fields → local compute only.

modules/verae-activate/SUMMARY.md

@@ -0,0 +1,11 @@
+# verae-activate (Zapier Platform app)
+
+**Job:** Private Zapier integration you push first. Actions run in Zapier cloud.
+
+**Expects:** User connection (API key optional).
+
+**Sends:** nothing if fields blank (Add Numbers / Echo / SHA256 / Create Timestamp local mock). If `api_base` + `api_key`, HTTPS to zappier-edge.
+
+**Does not** speak NATS.
+
+**Test:** `npm test`; `zapier-platform validate`.

modules/verae-archive-aggregator/NATS.md

@@ -0,0 +1,8 @@
+# NATS — verae-archive-aggregator
+
+| Direction | Address | Peer | Body |
+|-----------|---------|------|------|
+| OUT | `verae.archive.query` | all WORM | `{ correlationId, sha256, tenantId, kinds[], traceId }` |
+| IN | `verae.archive.reply.<correlationId>` | WORM hits | `{ archiveId, sha256, records[] }` |
+
+Stop collecting at `WAIT_ARCHIVE_MS`. Silent archives are listed in `silent[]`, not errors.

modules/verae-archive-aggregator/SUMMARY.md

@@ -0,0 +1,11 @@
+# verae-archive-aggregator
+
+**Job:** If `includeAttached`, fan out archive query and merge replies into the job JSON.
+
+**Expects:** wait-path flag from middleware-http; replies on `verae.archive.reply.<correlationId>`.
+
+**Sends:** `verae.archive.query` to all WORM nodes.
+
+**Timeout:** missing archives omit slices; chain receipt still succeeds.
+
+**Test:** `npm test` — one silent bloom miss + one hit; merge seal + metadata-attach.

modules/verae-archive-worm/NATS.md

@@ -0,0 +1,9 @@
+# NATS — verae-archive-worm
+
+| Direction | Address | From / to | Body |
+|-----------|---------|-----------|------|
+| IN | `verae.archive.put` | splitter | `{ sha256, tenantId, kind, record, traceId }` |
+| IN | `verae.archive.query` | aggregator (broadcast) | `{ correlationId, sha256, tenantId, kinds[], traceId }` |
+| OUT | `verae.archive.reply.<correlationId>` | aggregator | `{ archiveId, sha256, records[], traceId }` **only if bloom.mightHave(sha256)** |
+
+Subscribe to query **without** a shared queue group so every archive sees every query.

modules/verae-archive-worm/SUMMARY.md

@@ -0,0 +1,14 @@
+# verae-archive-worm
+
+**Job:** Append-only WORM store of metadata and files. Bloom filter: miss → stay silent on NATS.
+
+**Expects:**
+- `verae.archive.put` — append record, add sha256 to bloom
+- `verae.archive.query` — `{ correlationId, sha256, tenantId, kinds[] }` (every node sees this; **not** a shared queue group)
+
+**Sends:**
+- `verae.archive.reply.<correlationId>` **only on bloom hit** — `{ archiveId, sha256, records[] }`
+
+**Does not** write to the blockchain.
+
+**Test:** `npm test` — miss is `null`; put then query returns records.

modules/verae-fleet/NATS.md

@@ -0,0 +1,3 @@
+# NATS — verae-fleet
+
+Does not subscribe. Records which workers should. NATS remains loopback.

modules/verae-fleet/SUMMARY.md

@@ -0,0 +1,5 @@
+# verae-fleet
+
+**Job:** Service catalog, per-service configs, monitor, restart, pause/on/off, keep tree-node replica floor.
+
+**Config:** `fleet.json` (min/max) + `machines.json` (hosts) + `services/<id>.json`. Operator console at `:3850` (Fleet · Trace · Docs).

modules/verae-nats-process/NATS.md

@@ -0,0 +1,3 @@
+# NATS — verae-nats-process
+
+IN `verae.example.process.in` (queue `example-process`). OUT `.out` and `.reply.<id>`.

modules/verae-nats-process/SUMMARY.md

@@ -0,0 +1,3 @@
+# verae-nats-process
+
+Template for a new `verae.<area>.<resource>.*` worker. Copy this repo to expand.

modules/verae-ops/NATS.md

@@ -0,0 +1,3 @@
+# verae-ops NATS
+
+Documentation only. Runtime NATS bind stays private. See https://zapier.georgelambert.org/packages/verae-ops/06-linking-services.pdf

modules/verae-ops/SUMMARY.md

@@ -0,0 +1,3 @@
+# verae-ops
+
+Install and maintenance documentation: Docker, Proxmox, VMs, dedicated hardware, linking services.

modules/verae-request-splitter/NATS.md

@@ -0,0 +1,8 @@
+# NATS — verae-request-splitter
+
+| Direction | Address | To | Body |
+|-----------|---------|-----|------|
+| OUT | `verae.archive.put` | each WORM | one message per publicMeta / privateMeta / file |
+| OUT | (in-process) chain | middleware | `{ sha256, hashAlg, data? }` |
+
+No inbound NATS in the in-process embedding.

modules/verae-request-splitter/SUMMARY.md

@@ -0,0 +1,13 @@
+# verae-request-splitter
+
+**Job:** Peel a request into (1) chain hash and (2) off-chain archive puts.
+
+**Expects messages from:** middleware-http (in-process call today; later NATS `verae.splitter.in` if split out).
+
+**Sends messages to:**
+- Chain path: `{ sha256, hashAlg, data? }`
+- `verae.archive.put` for each `publicMeta` / `privateMeta` / `file`
+
+**Does not talk to Zapier or NATS job poller.**
+
+**Test:** `npm test` — hash-only has zero puts; two files + public meta → 3 puts.

modules/verae-tree-node/NATS.md

@@ -0,0 +1,7 @@
+# NATS — verae-tree-node
+
+| Direction | Address | From / to | Body |
+|-----------|---------|-----------|------|
+| IN | `verae.archive.put` | merkle builder | `{ sha256, kind: "tree", record: { merkleRoot, proof, leafIndex, chainSealJobId } }` |
+| IN | `verae.archive.query` | aggregator (broadcast) | `{ correlationId, sha256, kinds: ["tree", …] }` |
+| OUT | `verae.archive.reply.<correlationId>` | aggregator | only if bloom.mightHave(sha256) |

modules/verae-tree-node/SUMMARY.md

@@ -0,0 +1,9 @@
+# verae-tree-node
+
+**Job:** Hold inclusion proofs for SHA-256 leaves that were registered only as part of a bulk Merkle summary. The main Verae chain itemizes the **root**, not each leaf.
+
+**Expects messages from:** middleware batch path (`verae.archive.put` kind `tree`); aggregator (`verae.archive.query`).
+
+**Sends messages to:** `verae.archive.reply.<correlationId>` on bloom hit.
+
+**Does not talk to Zapier.** Same bloom-silence rule as `verae-archive-worm`.

modules/verae-zapier-middleware/NATS.md

@@ -0,0 +1,9 @@
+# NATS — verae-middleware
+
+| Direction | Address | Peer | Body |
+|-----------|---------|------|------|
+| OUT | `verae.zapier.jobs.watch` | job-poller | job watch payload |
+| IN | `verae.zapier.jobs.events` | waiter | terminal status |
+| OUT | (via aggregator) `verae.archive.query` | WORM | attached lookup |
+
+HTTP remains the only Zapier-facing surface.

modules/verae-zapier-middleware/SUMMARY.md

@@ -0,0 +1,15 @@
+# verae-middleware (HTTP edge)
+
+**Job:** Public `/zapier/v1/*`. Auth, entitlements, timestamp/wait, hash lookup, objects, receipts. Publishes NATS jobs; waits on events.
+
+**Expects HTTPS from:** zappier-edge (or Zapier if pointed here).
+
+**Sends:**
+- HTTPS to verae-chain-client (`/api/timestamp`, `/api/status`, `/api/verify`)
+- `verae.zapier.jobs.watch` after create
+- waits `verae.zapier.jobs.events`
+- splitter + aggregator when attachments / `includeAttached`
+
+**Returns to requestor:** 202 `{ jobId }` or wait JSON (completed / pending+jobId).
+
+**NATS:** never exposed to Zapier.

modules/verae-zapier-simulator/NATS.md

@@ -0,0 +1,3 @@
+# NATS — verae-zapier-simulator
+
+In-process replay of `jobs.watch`, `jobs.events`, `archive.put`, `archive.query`, `archive.reply.*`. No live subscribe.

modules/verae-zapier-simulator/SUMMARY.md

@@ -0,0 +1,7 @@
+# verae-zapier-simulator
+
+**Job:** Zapier-like UI + hop-by-hop trace console to validate messaging, assumptions, delays, failures, recoveries, and suggested modifications before `zapier-platform push`.
+
+**Expects:** HTTP `:3847` or `Simulator.run` in tests.
+
+**Sends:** nothing to live NATS / Zapier / Verae.

modules/verae-zapier/NATS.md

@@ -0,0 +1,10 @@
+# NATS — verae-zapier-app
+
+This Zapier Platform app **does not use NATS**.
+
+| Direction | Address | Peer | Body |
+|-----------|---------|------|------|
+| IN | Zapier runtime | user Zap | create/search/trigger fields |
+| OUT HTTPS | middleware `/zapier/v1/timestamp`, `/wait`, `/verify`, `/status/{id}`, `/hashes/{sha256}`, REST Hook subscribe | verae-middleware | Bearer `zmw_` |
+
+Job completion is a REST Hook HTTP POST from webhook-deliver, not a NATS client in Zapier.

modules/verae-zapier/SUMMARY.md

@@ -0,0 +1,9 @@
+# verae-zapier-app
+
+**Job:** Full Zapier CLI app: timestamp, wait, verify, batch, job status, hash lookup, REST Hook.
+
+**Expects:** `zmw_` middleware key (today) or zappier key after composition.
+
+**Sends:** HTTPS to middleware `/zapier/v1/*`.
+
+**Does not** speak NATS.

modules/zapier-user-docs/NATS.md

@@ -0,0 +1,3 @@
+# NATS — zapier-user-docs
+
+Static docs. Users never configure NATS in Zapier.

modules/zapier-user-docs/SUMMARY.md

@@ -0,0 +1,3 @@
+# zapier-user-docs
+
+**Job:** Customer guide from signup through register, central-chain lookup, and tree-node lookup of bulk-summary leaves.

modules/zappier/NATS.md

@@ -0,0 +1,10 @@
+# NATS — zappier-edge
+
+This process **does not subscribe or publish** on NATS.
+
+| Direction | Address | Peer | Body |
+|-----------|---------|------|------|
+| IN HTTPS | `/v1/*` | Zapier Platform app | JSON + `x-api-key` |
+| OUT HTTPS | middleware `/zapier/v1/*` | verae-middleware | same tenant request |
+
+NATS is private to middleware workers and archives.

modules/zappier/SUMMARY.md

@@ -0,0 +1,11 @@
+# zappier-edge
+
+**Job:** Metered commercial API, portal, admin, Stripe. Zapier’s only public HTTPS hop.
+
+**Expects:** Zapier Platform app with `x-api-key`.
+
+**Sends:** HTTPS to middleware `/zapier/v1/*` (or local mock `/v1/timestamp`, `/v1/add`, `/v1/hashes`, `/v1/receipts`).
+
+**Does not** speak NATS or `api.veraetime.net`.
+
+**Test:** `npm test` (Jest, 177+).