Milestone 3: NATS wait (gate 9), hash lookup, zappier timestamp, NS1 tunnel

Wait-via-NATS returns completed or pending+jobId (GATE 9). Mock SHA256
idempotent register + GET /hashes/{sha256}. Zappier commercial edge has
POST /v1/timestamp and hash-lookup. GATE 12 smoke (signup + wait) passes.

NS1 NATS is 127.0.0.1:4222 on 70.88.205.138; SSH tunnel :14222. Local
nats-server -js used for isolated tests. Activate app adds Echo Text.

Learned: JetStream on NS1 is loopback-only; do not bind 4222 public.
This commit is contained in:
George Lambert 2026-09-09 02:54:02 -04:00
parent 10c663cc0c
commit 51ae79b75f
75 changed files with 1114 additions and 123 deletions

View file

@ -1,21 +1,6 @@
Verae × Zapier module reference
=================================
.. toctree::
:maxdepth: 1
:caption: Models
models/PriceRule
models/TierConfig
models/RateCard
models/Quote
models/CallUsage
models/Customer
models/AddNumbersResult
models/TimestampRequest
models/TimestampResponse
models/StatusResponse
.. toctree::
:maxdepth: 2
:caption: Modules
@ -61,7 +46,9 @@ Verae × Zapier module reference
modules/verae-zapier-middleware/nats/connection
modules/verae-zapier-middleware/nats/publishers
modules/verae-zapier-middleware/nats/subjects
modules/verae-zapier-middleware/nats/wait
modules/verae-zapier-middleware/routes/authRoutes
modules/verae-zapier-middleware/routes/hashRoutes
modules/verae-zapier-middleware/routes/index
modules/verae-zapier-middleware/routes/statusRoutes
modules/verae-zapier-middleware/routes/tenantRoutes
@ -84,6 +71,7 @@ Verae × Zapier module reference
modules/verae-zapier-middleware/workers/webhookWorker
modules/verae-activate/authentication
modules/verae-activate/creates/add_numbers
modules/verae-activate/creates/echo
modules/verae-activate/index
modules/verae-zapier/authentication
modules/verae-zapier/creates/add_numbers
@ -92,5 +80,6 @@ Verae × Zapier module reference
modules/verae-zapier/creates/timestamp_and_wait
modules/verae-zapier/creates/verify_timestamp
modules/verae-zapier/index
modules/verae-zapier/searches/hash_lookup
modules/verae-zapier/searches/job_status
modules/verae-zapier/triggers/timestamp_completed

View file

@ -0,0 +1,40 @@
# `verae-activate/creates/echo`
**Package:** `verae-activate`
**Source:** `packages/verae-activate/creates/echo.js`
**Lines:** 30
## What this module is
Implementation module in `verae-activate`. The tables below are extracted from the source (signatures + JSDoc).
## Exports
`key`, `noun`, `display`, `label`, `description`
## Types / interfaces / classes
_None extracted._
## Functions
| Name | Parameters | Param types (JSDoc) | Returns | Calls (same file / helpers) |
|------|------------|---------------------|---------|-----------------------------|
| `perform` | `_z, bundle` | — | `unknown` | see Call graph |
## What it imports / requires
_No imports detected._
## Call graph (identifiers invoked)
`action`, `async`
Each identifier is a call site in this file. Follow the import list to see the defining module; open that modules 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`.

View file

@ -0,0 +1,7 @@
verae-activate.creates.echo
===========================
Generated API sheet for ``verae-activate/creates/echo``.
.. include:: echo.md
:literal:

View file

@ -2,7 +2,7 @@
**Package:** `verae-activate`
**Source:** `packages/verae-activate/index.js`
**Lines:** 21
**Lines:** 23
## What this module is
@ -10,7 +10,7 @@ Implementation module in `verae-activate`. The tables below are extracted from t
## Exports
`version`, `platformVersion`, `authentication`, `creates`, `addNumbers`
`version`, `platformVersion`, `authentication`, `creates`, `addNumbers`, `echo`
## Types / interfaces / classes
@ -24,6 +24,7 @@ _No top-level functions extracted._
- `./authentication`
- `./creates/add_numbers`
- `./creates/echo`
- `./package.json`
- `zapier-platform-core`

View file

@ -2,7 +2,7 @@
**Package:** `verae-zapier-middleware`
**Source:** `packages/verae-zapier-middleware/src/clients/veraeClient.js`
**Lines:** 288
**Lines:** 351
## What this module is
@ -10,7 +10,7 @@ Implementation module in `verae-zapier-middleware`. The tables below are extract
## Exports
`veraeClient`, `clearMockJobs`
`sha256Hex`, `veraeClient`, `clearMockJobs`
## Types / interfaces / classes
@ -20,11 +20,13 @@ _None extracted._
| Name | Parameters | Param types (JSDoc) | Returns | Calls (same file / helpers) |
|------|------------|---------------------|---------|-----------------------------|
| `sha256Hex` | `data` | data: `string` | `string` | see Call graph |
| `delay` | `ms` | ms: `number` | `Promise<void>` | see Call graph |
| `mockLogin` | `{ username, password }` | ms: `number` | `Promise<void>` | see Call graph |
| `mockValidate` | `token` | — | `unknown` | see Call graph |
| `mockCreateTimestamp` | `{ data, hashAlg }` | — | `unknown` | see Call graph |
| `mockCreateTimestamp` | `{ data, hashAlg, sha256, publicMetadata, privateMetadata }` | — | `unknown` | see Call graph |
| `mockGetStatus` | `jobId` | — | `unknown` | see Call graph |
| `mockLookupHash` | `sha256` | — | `unknown` | see Call graph |
| `mockVerify` | `{ certificate }` | — | `unknown` | see Call graph |
| `request` | `path, { method = 'GET', token, body } = {}` | path: `string` | `Promise<any>` | see Call graph |
| `clearMockJobs` | `(none)` | — | `void` | see Call graph |
@ -37,6 +39,7 @@ _None extracted._
| `login` | `credentials` |
| `validate` | `token` |
| `createTimestamp` | `token, body` |
| `lookupHash` | `token, sha256` |
| `createBatchTimestamp` | `token, body` |
| `getStatus` | `token, jobId` |
| `getBatchStatus` | `token, body` |
@ -54,7 +57,7 @@ _None extracted._
## Call graph (identifiers invoked)
`net`, `createDebugger`, `delay`, `setTimeout`, `mockLogin`, `now`, `toISOString`, `randomUUID`, `includes`, `mockValidate`, `startsWith`, `replace`, `mockCreateTimestamp`, `set`, `get`, `mockGetStatus`, `mockVerify`, `request`, `debug`, `fetch`, `stringify`, `text`, `parse`, `error`, `client`, `login`, `validate`, `createTimestamp`, `createBatchTimestamp`, `push`, `getStatus`, `encodeURIComponent`, `getBatchStatus`, `verify`, `verifyBatch`, `getJobVerification`, `waitForJob`, `jobs`, `clearMockJobs`, `clear`
`net`, `createDebugger`, `sha256Hex`, `createHash`, `update`, `digest`, `delay`, `setTimeout`, `mockLogin`, `now`, `toISOString`, `randomUUID`, `includes`, `mockValidate`, `startsWith`, `replace`, `mockCreateTimestamp`, `toLowerCase`, `get`, `set`, `mockGetStatus`, `mockLookupHash`, `mockVerify`, `request`, `debug`, `fetch`, `stringify`, `text`, `parse`, `error`, `client`, `login`, `validate`, `createTimestamp`, `lookupHash`, `createBatchTimestamp`, `push`, `getStatus`, `encodeURIComponent`, `getBatchStatus`, `verify`, `verifyBatch`, `getJobVerification`, `waitForJob`, `jobs`, `clearMockJobs`, `clear`
Each identifier is a call site in this file. Follow the import list to see the defining module; open that modules MD for parameter and return types.

View file

@ -2,7 +2,7 @@
**Package:** `verae-zapier-middleware`
**Source:** `packages/verae-zapier-middleware/src/config.js`
**Lines:** 143
**Lines:** 145
## What this module is

View file

@ -2,7 +2,7 @@
**Package:** `verae-zapier-middleware`
**Source:** `packages/verae-zapier-middleware/src/nats/connection.js`
**Lines:** 112
**Lines:** 117
## What this module is
@ -10,7 +10,7 @@ Implementation module in `verae-zapier-middleware`. The tables below are extract
## Exports
`connectNats`, `ensureStreams`, `closeNats`, `getJetStream`, `isNatsConnected`
`connectNats`, `getNatsConnection`, `ensureStreams`, `closeNats`, `getJetStream`, `isNatsConnected`
## Types / interfaces / classes
@ -21,6 +21,7 @@ _None extracted._
| Name | Parameters | Param types (JSDoc) | Returns | Calls (same file / helpers) |
|------|------------|---------------------|---------|-----------------------------|
| `connectNats` | `url = config.natsUrl` | url: `string` | `Promise<{ nc: import('nats').NatsConnection, js: import('nats').JetStreamClient, jsm: import('nats').JetStreamManager ` — >} | see Call graph |
| `getNatsConnection` | `(none)` | — | `import('nats').NatsConnection|null` | see Call graph |
| `ensureStreams` | `manager` | manager: `import('nats').JetStreamManager` | `Promise<void>` | see Call graph |
| `closeNats` | `(none)` | — | `Promise<void>` | see Call graph |
| `getJetStream` | `(none)` | — | `import('nats').JetStreamClient|null` | see Call graph |
@ -34,7 +35,7 @@ _None extracted._
## Call graph (identifiers invoked)
`createDebugger`, `import`, `connectNats`, `debug`, `disabled`, `info`, `connect`, `jetstream`, `jetstreamManager`, `ensureStreams`, `add`, `closeNats`, `drain`, `getJetStream`, `isNatsConnected`, `isClosed`
`createDebugger`, `import`, `connectNats`, `debug`, `disabled`, `info`, `connect`, `jetstream`, `jetstreamManager`, `getNatsConnection`, `ensureStreams`, `add`, `closeNats`, `drain`, `getJetStream`, `isNatsConnected`, `isClosed`
Each identifier is a call site in this file. Follow the import list to see the defining module; open that modules MD for parameter and return types.

View file

@ -0,0 +1,44 @@
# `verae-zapier-middleware/nats/wait`
**Package:** `verae-zapier-middleware`
**Source:** `packages/verae-zapier-middleware/src/nats/wait.js`
**Lines:** 60
## What this module is
Implementation module in `verae-zapier-middleware`. The tables below are extracted from the source (signatures + JSDoc).
## Exports
`waitForJobEvent`
## Types / interfaces / classes
_None extracted._
## Functions
| Name | Parameters | Param types (JSDoc) | Returns | Calls (same file / helpers) |
|------|------------|---------------------|---------|-----------------------------|
| `waitForJobEvent` | `jobId, timeoutMs` | jobId: `string`, timeoutMs: `number` | `Promise<object|null>` — event payload or null on timeout | see Call graph |
| `firstMatch` | `async (` | — | `unknown` | see Call graph |
## What it imports / requires
- `../debug/logger.js`
- `../debug/trace-context.js`
- `./subjects.js`
- `./connection.js`
## Call graph (identifiers invoked)
`createDebugger`, `waitForJobEvent`, `getNatsConnection`, `connectNats`, `subscribe`, `getTraceId`, `debug`, `setTimeout`, `resolve`, `async`, `parse`, `string`, `race`, `unsubscribe`
Each identifier is a call site in this file. Follow the import list to see the defining module; open that modules 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`.

View file

@ -0,0 +1,7 @@
verae-zapier-middleware.nats.wait
=================================
Generated API sheet for ``verae-zapier-middleware/nats/wait``.
.. include:: wait.md
:literal:

View file

@ -0,0 +1,46 @@
# `verae-zapier-middleware/routes/hashRoutes`
**Package:** `verae-zapier-middleware`
**Source:** `packages/verae-zapier-middleware/src/routes/hashRoutes.js`
**Lines:** 22
## What this module is
Implementation module in `verae-zapier-middleware`. The tables below are extracted from the source (signatures + JSDoc).
## Exports
`hashRoutes`
## Types / interfaces / classes
_None extracted._
## Functions
_No top-level functions extracted._
## Methods (class / object)
| Name | Parameters |
|------|------------|
| `asyncHandler` | `async (req, res` |
## What it imports / requires
- `express`
- `../errors.js`
- `../services/timestampService.js`
## Call graph (identifiers invoked)
`get`, `asyncHandler`, `async`, `test`, `lookupHash`, `json`
Each identifier is a call site in this file. Follow the import list to see the defining module; open that modules 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`.

View file

@ -0,0 +1,7 @@
verae-zapier-middleware.routes.hashRoutes
=========================================
Generated API sheet for ``verae-zapier-middleware/routes/hashRoutes``.
.. include:: hashRoutes.md
:literal:

View file

@ -2,7 +2,7 @@
**Package:** `verae-zapier-middleware`
**Source:** `packages/verae-zapier-middleware/src/routes/index.js`
**Lines:** 34
**Lines:** 36
## What this module is
@ -29,6 +29,7 @@ _No top-level functions extracted._
- `./statusRoutes.js`
- `./webhookRoutes.js`
- `./tenantRoutes.js`
- `./hashRoutes.js`
- `../middleware/authenticate.js`
- `../middleware/rateLimit.js`

View file

@ -2,7 +2,7 @@
**Package:** `verae-zapier-middleware`
**Source:** `packages/verae-zapier-middleware/src/routes/timestampRoutes.js`
**Lines:** 50
**Lines:** 62
## What this module is

View file

@ -2,7 +2,7 @@
**Package:** `verae-zapier-middleware`
**Source:** `packages/verae-zapier-middleware/src/services/timestampService.js`
**Lines:** 123
**Lines:** 160
## What this module is
@ -10,7 +10,7 @@ Implementation module in `verae-zapier-middleware`. The tables below are extract
## Exports
`createTimestamp`, `createTimestampAndWait`, `createBatchTimestamp`, `getJobStatus`, `getBatchJobStatus`, `getJobVerification`
`createTimestamp`, `createTimestampAndWait`, `createBatchTimestamp`, `getJobStatus`, `getBatchJobStatus`, `getJobVerification`, `lookupHash`
## Types / interfaces / classes
@ -21,12 +21,13 @@ _None extracted._
| Name | Parameters | Param types (JSDoc) | Returns | Calls (same file / helpers) |
|------|------------|---------------------|---------|-----------------------------|
| `enqueueWatchForJob` | `ctx, jobId` | ctx: `object`, jobId: `string` | `unknown` | see Call graph |
| `createTimestamp` | `ctx, body` | ctx: `object` | `Promise<{ jobId: string ` — >} | see Call graph |
| `createTimestamp` | `ctx, body` | ctx: `object` | `Promise<{ jobId: string, sha256?: string, existing?: boolean ` — >} | see Call graph |
| `createTimestampAndWait` | `ctx, body` | ctx: `object` | `Promise<object>` — StatusResponse | see Call graph |
| `createBatchTimestamp` | `ctx, body` | ctx: `object` | `unknown` | see Call graph |
| `getJobStatus` | `ctx, jobId` | ctx: `object`, jobId: `string` | `unknown` | see Call graph |
| `getBatchJobStatus` | `ctx, body` | ctx: `object` | `unknown` | see Call graph |
| `getJobVerification` | `ctx, jobId` | ctx: `object`, jobId: `string` | `unknown` | see Call graph |
| `lookupHash` | `ctx, sha256` | ctx: `object`, sha256: `string` | `unknown` | see Call graph |
## Methods (class / object)
@ -40,12 +41,12 @@ _None extracted._
}` |
| `checkEntitlement` | `ctx.tenantId, 'timestamp'` |
| `recordUsage` | `ctx.tenantId, 'timestamp'` |
| `recordUsage` | `ctx.tenantId, 'status'` |
| `checkEntitlement` | `ctx.tenantId, 'batch_timestamp', { amount: itemCount }` |
| `recordUsage` | `ctx.tenantId, 'batch_timestamp', { amount: itemCount }` |
| `recordUsage` | `ctx.tenantId, 'status'` |
| `recordUsage` | `ctx.tenantId, 'status', { amount: body.jobIds?.length ?? 1 }` |
| `recordUsage` | `ctx.tenantId, 'status'` |
| `recordUsage` | `ctx.tenantId, 'status'` |
## What it imports / requires
@ -58,7 +59,7 @@ _None extracted._
## Call graph (identifiers invoked)
`createDebugger`, `enqueueWatchForJob`, `getTraceId`, `import`, `enqueueWatch`, `debug`, `enqueueJob`, `createTimestamp`, `checkEntitlement`, `recordUsage`, `createTimestampAndWait`, `waitForJob`, `createBatchTimestamp`, `getJobStatus`, `getStatus`, `getBatchJobStatus`, `getBatchStatus`, `getJobVerification`
`createDebugger`, `enqueueWatchForJob`, `getTraceId`, `import`, `enqueueWatch`, `debug`, `enqueueJob`, `createTimestamp`, `checkEntitlement`, `recordUsage`, `createTimestampAndWait`, `waitForJobEvent`, `getStatus`, `waitForJob`, `createBatchTimestamp`, `getJobStatus`, `getBatchJobStatus`, `getBatchStatus`, `getJobVerification`, `lookupHash`
Each identifier is a call site in this file. Follow the import list to see the defining module; open that modules MD for parameter and return types.

View file

@ -2,7 +2,7 @@
**Package:** `verae-zapier`
**Source:** `packages/verae-zapier/index.js`
**Lines:** 79
**Lines:** 81
## What this module is
@ -32,6 +32,7 @@ _None extracted._
- `./creates/batch_timestamp`
- `./creates/add_numbers`
- `./searches/job_status`
- `./searches/hash_lookup`
- `./triggers/timestamp_completed`
- `zapier-platform-core`
- `./package.json`

View file

@ -0,0 +1,41 @@
# `verae-zapier/searches/hash_lookup`
**Package:** `verae-zapier`
**Source:** `packages/verae-zapier/searches/hash_lookup.js`
**Lines:** 35
## What this module is
Implementation module in `verae-zapier`. The tables below are extracted from the source (signatures + JSDoc).
## Exports
`key`, `noun`, `display`, `label`, `description`
## Types / interfaces / classes
_None extracted._
## Functions
| Name | Parameters | Param types (JSDoc) | Returns | Calls (same file / helpers) |
|------|------------|---------------------|---------|-----------------------------|
| `base` | `(none)` | — | `unknown` | see Call graph |
| `perform` | `z, bundle` | — | `unknown` | see Call graph |
## What it imports / requires
_No imports detected._
## Call graph (identifiers invoked)
`async`, `request`, `base`, `encodeURIComponent`, `digest`
Each identifier is a call site in this file. Follow the import list to see the defining module; open that modules 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`.

View file

@ -0,0 +1,7 @@
verae-zapier.searches.hash_lookup
=================================
Generated API sheet for ``verae-zapier/searches/hash_lookup``.
.. include:: hash_lookup.md
:literal:

View file

@ -2,7 +2,7 @@
**Package:** `zappier`
**Source:** `packages/zappier/src/app.ts`
**Lines:** 203
**Lines:** 237
## What this module is
@ -47,7 +47,7 @@ Implementation module in `zappier`. The tables below are extracted from the sour
## Call graph (identifiers invoked)
`join`, `next`, `parse`, `status`, `json`, `buildApp`, `seeded`, `seedAdminUsersFromEnv`, `rateCard`, `getRateCard`, `tiers`, `getTiers`, `express`, `use`, `load`, `setup`, `adminLoginRouter`, `adminAuth`, `adminRouter`, `static`, `async`, `import`, `toDataURL`, `portalRouter`, `apiKeyAuth`, `middleware`, `get`, `meter`, `post`, `toUpperCase`, `isFinite`, `randomUUID`, `map`, `toISOString`, `unshift`, `filter`, `setUTCDate`, `setUTCHours`, `summaryFor`, `find`, `applyMonthlyCredit`
`join`, `next`, `parse`, `status`, `json`, `buildApp`, `seeded`, `seedAdminUsersFromEnv`, `rateCard`, `getRateCard`, `tiers`, `getTiers`, `express`, `use`, `load`, `setup`, `adminLoginRouter`, `adminAuth`, `adminRouter`, `static`, `async`, `import`, `toDataURL`, `portalRouter`, `apiKeyAuth`, `middleware`, `get`, `meter`, `post`, `toUpperCase`, `toLowerCase`, `createHash`, `update`, `digest`, `randomUUID`, `toISOString`, `set`, `isFinite`, `map`, `unshift`, `filter`, `setUTCDate`, `setUTCHours`, `summaryFor`, `find`, `applyMonthlyCredit`
Each identifier is a call site in this file. Follow the import list to see the defining module; open that modules MD for parameter and return types.

View file

@ -2,7 +2,7 @@
**Package:** `zappier`
**Source:** `packages/zappier/src/pricing.ts`
**Lines:** 171
**Lines:** 173
## What this module is