marchon/master-zapier-plan-draft
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1
master-zapier-plan-draft/docs/02-architecture/nats-subjects.md
George Lambert b4150c8250 Milestone 0: import zappier billing, Verae middleware, and Zapier research 
Compose-ready workspace: packages/zappier (rate card, portal, Stripe),
packages/verae-zapier-middleware (timestamp + NATS), packages/verae-zapier
(CLI app), vendor/zapier-platform, and research/zapier vendor corpus.

Gate 0 structure checks pass. Product code and research are not yet wired.
2026-09-09 02:37:36 -04:00

3.9 KiB
Raw Blame History

NATS Subject Topology

All subjects are prefixed with verae.zapier. to isolate this platform from other Verae messaging.

Streams

Stream Subjects Retention Purpose
ZAPIER_JOBS verae.zapier.jobs.watch Work queue Poll Verae for job status
ZAPIER_EVENTS verae.zapier.jobs.events Limits (time) Terminal job outcomes
ZAPIER_WEBHOOKS verae.zapier.webhooks.deliver Work queue POST to Zapier hook URLs
ZAPIER_USAGE (optional) verae.zapier.usage Limits Billing export

Subjects

verae.zapier.jobs.watch

Published by: HTTP edge after successful POST /api/timestamp (or batch item).
Consumed by: job-poller durable consumer (queue group).

Payload

Field Type Required Description
tenantId string yes Owning tenant
jobId string yes Verae job id
tokenRef string preferred Opaque ref to resolve Verae credentials (avoid raw JWT)
veraeToken string discouraged Only if tokenRef unavailable; redacted in logs
enqueuedAt ISO-8601 yes Enqueue time
attempt number yes Delivery attempt (0-based)
maxAttempts number yes Stop after this many polls
intervalMs number yes Suggested delay between polls
traceId string yes Correlation id for debug

verae.zapier.jobs.events

Published by: Job poller when status is completed, failed, or timeout.
Consumed by: Event router → webhook enqueue; optional waiters on HTTP edge.

Payload

Field Type Required Description
event string yes timestamp.completed | timestamp.failed | timestamp.timeout
tenantId string yes Tenant id
jobId string yes Job id
status object yes Verae StatusResponse shape (or synthetic timeout)
traceId string yes Correlation id
emittedAt ISO-8601 yes Event time

verae.zapier.webhooks.deliver

Published by: Event router for each matching subscription.
Consumed by: webhook-deliver queue group.

Payload

Field Type Required Description
hookId string yes Stored subscription id
tenantId string yes Tenant
targetUrl string yes Zapier REST Hook URL
event string yes Event name
payload object yes Body POSTed to Zapier
attempt number yes Attempt count
traceId string yes Correlation id

verae.zapier.usage (optional)

Field Type Description
tenantId string Tenant
action string timestamp | verify | status | …
amount number Increment
at ISO-8601 Timestamp

Consumers

Name Stream Mode Notes
job-poller ZAPIER_JOBS Pull, queue Nak with delay when still pending
event-webhook-router ZAPIER_EVENTS Push/pull Fan-out to deliver subjects
webhook-deliver ZAPIER_WEBHOOKS Pull, queue HTTP POST with backoff
usage-writer ZAPIER_USAGE Optional Persist metering

Ack semantics

Situation Action
Job still pending Nak with delay ≈ intervalMs or republish with attempt+1
Job terminal Publish event, Ack watch message
Webhook HTTP 2xx Ack
Webhook HTTP 5xx / network Nak / redelivery until max_deliver
Poison message Term after max_deliver; write DLQ log with DEBUG_VERAE=webhooks

Security rules

  1. Prefer tokenRef over embedding Verae JWTs in messages.
  2. NATS must use private network + auth (Phase 15: mTLS).
  3. Debug logs must redact tokens and targetUrl query secrets if any.
  4. Treat targetUrl as untrusted egress (timeouts, size limits, SSRF allowlist later).