# 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.