From 56d7f9a4dec5f3be9ebca91d241a8988a0f5312b Mon Sep 17 00:00:00 2001 From: Till JS Date: Fri, 10 Apr 2026 22:38:23 +0200 Subject: [PATCH] docs(mana-sync): document billing middleware, new env vars, project structure - Add MANA_CREDITS_URL and MANA_SERVICE_KEY to configuration table - Document billing gate on sync endpoints (402 behavior, 5min cache, fail-open) - Add billing/check.go to project structure - Add stream endpoint to API table Co-Authored-By: Claude Opus 4.6 (1M context) --- services/mana-sync/CLAUDE.md | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/services/mana-sync/CLAUDE.md b/services/mana-sync/CLAUDE.md index a388e57f5..554c147d0 100644 --- a/services/mana-sync/CLAUDE.md +++ b/services/mana-sync/CLAUDE.md @@ -127,13 +127,16 @@ Result: title="Buy eggs", completed=true (merged — different fields) | Endpoint | Method | Auth | Description | |----------|--------|------|-------------| -| `POST /sync/{appId}` | POST | JWT | Push changes, get server delta | -| `GET /sync/{appId}/pull` | GET | JWT | Pull changes for a collection | +| `POST /sync/{appId}` | POST | JWT + Billing | Push changes, get server delta | +| `GET /sync/{appId}/pull` | GET | JWT + Billing | Pull changes for a collection | +| `GET /sync/{appId}/stream` | GET | JWT + Billing | SSE stream for real-time changes | | `GET /ws` | WS | JWT (in-band) | Unified real-time sync (all apps, one connection) | | `GET /ws/{appId}` | WS | JWT (in-band) | Legacy per-app sync notifications | | `GET /health` | GET | No | Health check with connection stats | | `GET /metrics` | GET | No | Prometheus metrics | +**Billing gate**: Push, pull, and stream endpoints are wrapped by a billing middleware that checks the user's sync subscription status via `mana-credits`. Returns **402 Payment Required** if sync is not active. Status is cached for 5 minutes per user. Fail-open: if mana-credits is unreachable, sync is allowed. + ## Database Schema Single table for all sync data: @@ -163,6 +166,8 @@ Indexes: `(user_id, app_id, created_at)`, `(table_name, record_id, created_at)`, | `DATABASE_URL` | `postgresql://...localhost:5432/mana_sync` | PostgreSQL connection | | `JWKS_URL` | `http://localhost:3001/api/auth/jwks` | mana-auth JWKS endpoint | | `CORS_ORIGINS` | `http://localhost:5173,...` | Comma-separated allowed origins | +| `MANA_CREDITS_URL` | `http://localhost:3061` | mana-credits service URL for billing checks | +| `MANA_SERVICE_KEY` | `dev-service-key` | Service-to-service auth key | ## Testing @@ -181,6 +186,7 @@ services/mana-sync/ ├── internal/ │ ├── auth/jwt.go — EdDSA JWT validation via JWKS │ ├── auth/jwt_test.go — Token extraction, validator tests +│ ├── billing/check.go — Sync billing status checker (cached, fail-open) │ ├── config/config.go — Environment variable loading │ ├── config/config_test.go — Config defaults and env override tests │ ├── store/postgres.go — PostgreSQL schema, queries @@ -195,6 +201,7 @@ services/mana-sync/ ## Security - JWT validated via EdDSA JWKS (same as NestJS backends) +- Sync endpoints gated by billing check (402 if subscription inactive) - WebSocket connections must authenticate within 10 seconds - Request body limited to 10 MB - Operation types validated (insert/update/delete only)