master-zapier-plan-draft/docs/developer/modules/function-reference.md

Function Reference — All Modules

Canonical I/O contracts for the Verae Zapier middleware and Zapier app.
Source of truth for reviewers; keep in sync with JSDoc in code.

Namespaces for debug: auth, billing, http, nats, jobs, webhooks, trace, app.

---

config.js

loadEnvFile()

For	Load .env into process.env if keys are unset
Input	none (reads file next to package root)
Output	void

config (exported object)

Field	Type	Description
port	number	HTTP port
host	string	Bind address
veraeApiBaseUrl	string	Upstream Verae base URL (no trailing slash)
mockVerae	boolean	Use mock client
natsEnabled	boolean	Use JetStream workers
natsUrl	string	NATS connection URL
tokenSecret	string	HMAC secret for zmt_ tokens
jobPollIntervalMs	number	Poll delay
jobPollMaxAttempts	number	Max poll attempts
storePath	string	Absolute path to store file
upgradeUrl	string	Billing upgrade link for 402 bodies
adminSecret	string	Admin route secret

PLAN_LIMITS

Map of plan name → { timestamps, verifications, batch, batchMaxItems, requestsPerMinute }.
null means unlimited.

---

errors.js

class AppError extends Error

For	Structured operational errors returned as JSON
Constructor	(message: string, { status?, code?, details? })
Properties	status: number, code: string, details: unknown

asyncHandler(fn)

For	Wrap async Express handlers so rejections hit error middleware
Input	(req, res, next) => Promise<any>
Output	Express middleware function

sendError(res, err)

For	Write JSON error response; log 5xx with debug
Input	Express res, Error|AppError
Output	void

---

app.js / index.js

createApp()

For	Build Express application (no listen)
Input	none
Output	express.Application
Mounts	GET /health, /zapier/*, error handler, traceMiddleware

main() (index.js)

For	Boot store, optional NATS, workers, listen
Input	none
Output	Promise<void>

---

store/db.js

loadStore()

For	Load JSON store into memory
Output	store object

getStore()

For	Access in-memory store
Output	{ tenants, apiKeys, usage, webhooks, jobWatchers }

persist()

For	Flush store to disk
Output	void

---

store/tenants.js

getTenant(tenantId)

| Input | tenantId: string | | Output | Tenant\|null |

getTenantByApiKey(apiKey)

| Input | apiKey: string | | Output | Tenant\|null |

listTenants()

| Output | Tenant[] |

createTenant({ id, name, plan, veraeUsername, veraePassword, contract?, apiKey?, metadata? })

| Output | { tenant: Tenant, apiKey: string } |

resolveLimits(tenant)

| Output | Effective limits including enterprise contract overrides |

---

store/usage.js

getUsage(tenantId)

| Output | counters for current period |

getUsageSummary(tenantId)

| Output | public-safe usage + limits snapshot |

incrementUsage(tenantId, metric, amount?)

| For | Atomically increment a counter and persist |

---

store/webhooks.js

createWebhook({ tenantId, targetUrl, event })

| Output | { id, tenantId, targetUrl, event, createdAt } |

deleteWebhook({ tenantId, hookId?, targetUrl? })

| Output | boolean removed |

getActiveWebhooks(tenantId, event)

| Output | Webhook[] |

listWebhooksForTenant(tenantId)

| Output | Webhook[] |

---

lib/tokens.js

issueSessionToken({ tenantId, veraeToken, expiresAt })

| Output | string (zmt_…) |

parseSessionToken(token)

| Output | { tenantId, veraeToken, expiresAt, nonce }\|null |

generateApiKey()

| Output | string (zmw_…) |

isApiKey(value)

| Output | boolean |

extractBearerToken(header)

| Input | Authorization header string | | Output | token string or null |

---

clients/veraeClient.js

All methods that hit the network log under DEBUG_VERAE=http.

veraeClient.login(credentials)

| Input | { username, password } | | Output | { token, expiresAt, user } |

veraeClient.validate(token)

| Input | Verae JWT | | Output | validation object |

veraeClient.createTimestamp(token, body)

| Input | JWT, { data, hashAlg? } | | Output | { jobId } |

veraeClient.createBatchTimestamp(token, body)

| Input | JWT, { items: [{ data, hashAlg? }] } | | Output | { jobIds: string[] } |

veraeClient.getStatus(token, jobId)

| Output | StatusResponse |

veraeClient.getBatchStatus(token, body)

| Input | { jobIds: string[] } | | Output | { results } |

veraeClient.verify(token, body)

| Input | { certificate } | | Output | { valid, timestamp?, blockIndex? } |

veraeClient.verifyBatch(token, body)

| Input | { certificates: string[] } | | Output | { results } |

veraeClient.waitForJob(token, jobId, { maxAttempts, intervalMs })

| Output | terminal StatusResponse or throws GATEWAY_TIMEOUT |

---

services/authService.js

Debug namespace: auth.

loginWithCredentials({ username, password, tenant? })

| Output | { accessToken, expiresAt, tenant, user } |

loginWithApiKey(apiKey)

| Output | same as loginWithCredentials after tenant lookup |

resolveAuthContext(rawToken)

| Input | API key or session token | | Output | { tenantId, tenant, veraeToken, authMethod } |

validateSession(rawToken)

| Output | { valid, tenantId, authMethod, user } |

---

services/entitlementService.js

Debug namespace: billing.

checkEntitlement(tenantId, action, { amount? })

| Actions | timestamp, verify, batch_timestamp | | Throws | 402 QUOTA_EXCEEDED, 403 PLAN_UPGRADE_REQUIRED | | Output | { tenant, limits, usage } |

recordUsage(tenantId, action, { amount? })

| Output | void |

---

middleware/authenticate.js

authenticate(req, res, next)

| For | Populate req.auth via resolveAuthContext | | Reads | Authorization: Bearer or x-api-key |

middleware/rateLimit.js

rateLimit(req, res, next)

| For | Enforce plan requestsPerMinute | | Throws | 429 RATE_LIMITED |

---

services/timestampService.js

Debug: jobs, billing, http.

createTimestamp(ctx, body)

| Input | auth context, { data, hashAlg? } | | Output | { jobId } | | Side effects | usage++, enqueue watch (NATS or in-process) |

createTimestampAndWait(ctx, body)

| Output | StatusResponse (or pending on timeout when NATS wait enabled) |

createBatchTimestamp(ctx, body)

| Output | { jobIds } |

getJobStatus(ctx, jobId) / getBatchJobStatus / getJobVerification

| Output | status payloads from Verae |

---

services/verifyService.js

verifyTimestamp(ctx, body) / verifyBatch(ctx, body)

| Output | verify results; records usage |

---

services/webhookService.js

Debug: webhooks.

subscribe(ctx, { targetUrl, event })

| Output | webhook record |

unsubscribe(ctx, { hookId?, targetUrl? })

| Output | { removed: true } |

deliverWebhook(targetUrl, payload)

| Output | { ok: boolean, status: number } |

---

services/tenantService.js

selfServeSignup({ email, name, veraeUsername, veraePassword })

| Output | { tenant, apiKey, zapierSetup } |

provisionTenant({ id?, name, plan, veraeUsername, veraePassword, contract?, metadata?, audience? })

| Output | { tenant, apiKey } |

listProvisionedTenants()

| Output | public tenant summaries (no passwords) |

---

nats/subjects.js

Constants

SUBJECTS.JOBS_WATCH, JOBS_EVENTS, WEBHOOKS_DELIVER, USAGE
STREAMS.ZAPIER_JOBS, ZAPIER_EVENTS, ZAPIER_WEBHOOKS

---

nats/connection.js

connectNats(url?)

| Output | { nc, js, jsm } NATS connection handles |

ensureStreams(jsm)

| For | Idempotent stream create | | Output | Promise<void> |

closeNats()

| Output | Promise<void> |

---

nats/publishers.js

enqueueWatch(jobWatchPayload)

| Input | see architecture/nats-subjects.md | | Output | Promise<{ seq }> |

publishJobEvent(eventPayload)

| Output | Promise<void> |

enqueueWebhook(deliverPayload)

| Output | Promise<void> |

---

workers/jobPollerWorker.js

startJobPollerWorker()

| For | Pull-consume watch queue; poll Verae; emit events | | Output | stop handle { stop() } |

workers/webhookWorker.js

startWebhookWorker()

| For | Deliver POSTs to Zapier with retry via JetStream | | Output | { stop() } |

workers/inProcessJobPoller.js

startInProcessJobPoller() / stopInProcessJobPoller()

| For | Phase 6 fallback when NATS_ENABLED=false |

---

Routes (all under /zapier)

Method	Path	Handler purpose
POST	/v1/auth/login	Credentials or api_key → session
GET	/v1/auth/me	Validate connection for Zapier
POST	/v1/timestamp	Async create
POST	/v1/timestamp/wait	Create and wait
POST	/v1/timestamp/batch	Batch create
POST	/v1/verify	Verify certificate
GET	/v1/status/:jobId	Job status
POST	/v1/webhooks/subscribe	REST Hook subscribe
DELETE	/v1/webhooks/unsubscribe	REST Hook unsubscribe
POST	/v1/signup	Self-serve tenant
POST	/v1/admin/tenants	Admin provision

---

Zapier app modules

authentication.test / fields

| Input from user | api_key | | Test URL | GET {MIDDLEWARE_BASE_URL}/zapier/v1/auth/me |

beforeRequest: addApiKey

| Sets | Authorization: Bearer ${bundle.authData.api_key} |

Creates

Key	Middleware path
timestamp_and_wait	POST /zapier/v1/timestamp/wait
create_timestamp	POST /zapier/v1/timestamp
verify_timestamp	POST /zapier/v1/verify
batch_timestamp	POST /zapier/v1/timestamp/batch

Search job_status

| Path | GET /zapier/v1/status/{jobId} |

Trigger timestamp_completed

| Subscribe | POST /zapier/v1/webhooks/subscribe | | Unsubscribe | DELETE /zapier/v1/webhooks/unsubscribe | | Perform | return [bundle.cleanedRequest] |