marchon/master-zapier-plan-draft
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1

Milestone 0: import zappier billing, Verae middleware, and Zapier research

Browse source 
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.
This commit is contained in:
George Lambert 2026-09-09 02:37:36 -04:00
commit b4150c8250
1364 changed files with 6814366 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

84
research/zapier/verae-zapier-api/README.md Normal file
View file

@ -0,0 +1,84 @@
# 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.