George Lambert
b4150c8250
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.
84 lines
3 KiB
Markdown
84 lines
3 KiB
Markdown
# Verae Zapier Platform
|
||
|
||
Integration stack connecting **Zapier** to the Verae Timestamping Service (`https://api.veraetime.net`) via a hybrid **HTTP middleware edge + NATS JetStream workers**.
|
||
|
||
## Architecture (bottom line)
|
||
|
||
```text
|
||
Users → Zapier UI
|
||
Zapier cloud runs verae-zapier (CLI app)
|
||
→ HTTPS → verae-zapier-middleware /zapier/v1/*
|
||
→ (sync) HTTPS → api.veraetime.net
|
||
→ (async) NATS JetStream → workers → api.veraetime.net
|
||
→ Zapier REST Hook URLs
|
||
```
|
||
|
||
- Zapier **never** connects to NATS.
|
||
- Middleware HTTP handles auth, billing, and the public API surface.
|
||
- NATS owns job watching, completion events, and reliable webhook delivery.
|
||
|
||
## Packages
|
||
|
||
| Path | Role |
|
||
|------|------|
|
||
| `verae-zapier-middleware/` | Express proxy + NATS workers (you host) |
|
||
| `verae-zapier/` | Zapier Platform CLI app (runs on Zapier) |
|
||
| `docs/` | Architecture + developer function reference |
|
||
| `TODO.md` | Dependency-ordered plan with **test gates** |
|
||
|
||
## Quick start
|
||
|
||
```bash
|
||
cd /Users/marchon/datacubes/verae-zapier-api
|
||
|
||
# Install (middleware)
|
||
cd verae-zapier-middleware && npm install && cd ..
|
||
|
||
# Run documentation/structure gate
|
||
npm run gate:0
|
||
|
||
# Run debug facility tests (Phase 1)
|
||
npm run gate:1
|
||
|
||
# Enable failure tracing at runtime (examples)
|
||
export DEBUG_VERAE=1 # all namespaces
|
||
export DEBUG_VERAE=auth,nats,jobs # selected
|
||
export DEBUG_VERAE_LEVEL=debug # debug | info | warn | error
|
||
```
|
||
|
||
## Implementation order
|
||
|
||
Work **only** in the order defined in [TODO.md](TODO.md). Each phase ends with a **GATE** that must pass before the next phase.
|
||
|
||
```bash
|
||
npm run gate:all # phases 0–12 in order; stops on first failure
|
||
```
|
||
|
||
## Documentation map
|
||
|
||
| Document | Contents |
|
||
|----------|----------|
|
||
| [TODO.md](TODO.md) | Phased plan, dependencies, gates |
|
||
| [docs/architecture/overview.md](docs/architecture/overview.md) | System design |
|
||
| [docs/architecture/nats-subjects.md](docs/architecture/nats-subjects.md) | Subjects, streams, payloads |
|
||
| [docs/developer/debugging.md](docs/developer/debugging.md) | Runtime debug tracing |
|
||
| [docs/developer/modules/](docs/developer/modules/) | Function I/O reference per module |
|
||
| [docs/plans/phase-gates.md](docs/plans/phase-gates.md) | Gate commands and acceptance criteria |
|
||
|
||
## Environment (middleware)
|
||
|
||
| Variable | Default | Purpose |
|
||
|----------|---------|---------|
|
||
| `PORT` | `3100` | HTTP listen port |
|
||
| `VERAE_API_BASE_URL` | `http://localhost:8080` | Upstream Verae API |
|
||
| `MOCK_VERAE` | `false` | Local mock of Verae HTTP API |
|
||
| `NATS_URL` | `nats://127.0.0.1:4222` | NATS server |
|
||
| `NATS_ENABLED` | `false` | Use JetStream workers vs in-process poller |
|
||
| `TOKEN_SECRET` | dev secret | HMAC for middleware session tokens |
|
||
| `DEBUG_VERAE` | unset | Runtime debug namespaces |
|
||
| `DEBUG_VERAE_LEVEL` | `debug` | Minimum log level when debug enabled |
|
||
| `STORE_PATH` | `./data/store.json` | MVP tenant/usage store |
|
||
|
||
## License
|
||
|
||
UNLICENSED — internal Verae platform work.
|