# BILL-03 ยท Lago-Gateway fuer Customers, Plans, Subscriptions und Invoices | | | | ----------------- | ------------------------------ | | **Typ** | Dev (Code) | | **Owner** | Raffael | | **Phase** | Billing-Recut nach AD-27 | | **Cycle/Fenster** | nach `BILL-01`/`BILL-02` | | **Status** | Umgesetzt / bereit fuer Review | ## Abhaengigkeiten & Parallelitaet - **Blocked by:** `BILL-01`, `BILL-02` - **Blocks:** `BILL-05`, `BILL-06`, `BILL-07` ## Was wir bauen Ein serverseitiges Lago-Gateway in HiveGrid. HiveGrid erstellt/liest Customers, Plans, Subscriptions und Invoice-Status ueber Lago, aber UI-Komponenten sprechen nie direkt mit Lago. ## Definition of Done - [x] Lago-API-Client mit klarer Env-Konfiguration fuer Staging. - [x] Customer-Erstellung fuer Tenant. - [x] Plan-/Seat-Subscription erstellen und lesen. - [x] Invoice-/Subscription-Status abrufen. - [x] Lago-Webhook-Endpunkt oder Pull-Sync-Job definiert und idempotent. - [x] Outbox/Retry fuer ausgehende Billing-Sync-Aktionen. - [x] Fehlertexte klar und ohne Stacktrace. - [x] Tests gegen Mock/Fixture der Lago-API. **Fortschritt:** `BILL-03`: 8/8 DoD = 100 % done. ## Nicht im Scope - Mollie-Zahlung. - Usage Events. - Customer-facing Billing UI. ## Technische Bausteine - `BillingGateway`-Interface, konkrete Implementierung `LagoBillingGateway`. - Zod-Schemas fuer Lago-Antworten. - Redaction fuer API-Keys und Payment-/Invoice-IDs in Logs. ## Umsetzungsnotiz 2026-07-04: Server-Gateway fuer Lago umgesetzt. Neues Package `@hivegrid/billing` enthaelt das `BillingGateway`-Interface, `LagoBillingGateway`, Zod-Response-Schemas, Redaction-Helfer, Webhook-Event-Parsing und idempotente Outbox-Args fuer `billing.lago.sync`. Die API-Konfiguration kennt jetzt `LAGO_API_URL`, `LAGO_API_KEY`, `LAGO_WEBHOOK_SECRET` und `LAGO_TIMEOUT_MS`; `.env.example` ist aktualisiert. Bewusst noch nicht gebaut: Customer-facing UI und Mollie-Zahlung. Der ausgehende Pull-Sync ist als Outbox-Event-Kontrakt definiert und wird in `BILL-05` konsumiert. 2026-07-28: Den zuvor nur als Parser-/Outbox-Vertrag vorhandenen Lago-Webhook als echte API-Grenze `POST /v1/billing/lago/webhooks` geschlossen. Die Route verarbeitet das reale Lago-v1.50-Format mit verschachteltem `subscription`-/`invoice`-/`customer`-Objekt, prueft den Base64-HMAC ueber den unveraenderten Request-Body in konstanter Zeit und verlangt `X-Lago-Signature-Algorithm` sowie `X-Lago-Unique-Key`. Rate-Limits laufen vor Body-Parsing; erst nach erfolgreicher Signatur wird der eingebettete Tenant per RLS gebunden. Basisplan-Subscription-Events landen replay-sicher in `IdempotencyKey(scope=billing:provider-sync)`. Pending-, Invoice-, Customer-, unbekannte Plan- und Add-on-Events werden ohne Subscription-Mutation bestaetigt; damit kann ein generisches Lago-Event weder den Basisplan ersetzen noch den separaten, Mollie-gezaeunten Product-Acquisition-Ledger umgehen. OpenAPI, Route-/CSRF-Inventar und Klartext-Fehler wurden nachgezogen. Proof: - `pnpm --filter @hivegrid/billing typecheck` - `pnpm --filter @hivegrid/billing test` - `pnpm --filter @hivegrid/config test` - `pnpm exec vitest run packages/db/src/billing-sync.server.test.ts apps/api/src/billing/lago-webhook-route.test.ts apps/api/src/route-access-inventory.test.ts apps/api/src/route-access-inventory-doc.test.ts apps/api/src/csrf-inventory.test.ts apps/api/src/openapi.test.ts packages/billing/src/sync-outbox.test.ts` - `pnpm --filter @hivegrid/api typecheck` - `pnpm exec eslint packages/billing/src/webhook.ts packages/billing/src/sync-outbox.test.ts apps/api/src/billing/lago-webhook-route.ts apps/api/src/billing/lago-webhook-route.test.ts apps/api/src/public-ingress-rate-limit.ts apps/api/src/app.ts apps/api/src/openapi.ts apps/api/src/openapi.test.ts apps/api/src/route-access-inventory.ts apps/api/src/route-access-inventory.test.ts apps/api/src/csrf-inventory.test.ts --max-warnings=0` 2026-07-29: Den Lago-v1.50-Webhook auf Staging ausgerollt und den Provider-Vertrag live geschlossen. Der Lago Workspace hat genau einen HMAC-Webhook-Endpunkt. Ein signierter `subscription.started`-Event fuer die kanonische aktive `business`-Subscription von `demo-pro-crm` wurde einmal synchronisiert; der identische Replay wurde als Replay quittiert. Danach existierten exakt ein Idempotency-Datensatz, ein Audit-Event und ein Activity-Eintrag, der lokale Zustand blieb `business|active`. Vor dem Live-Proof wurden sechs veraltete synthetische Parallel-Subscriptions ohne Abschlussrechnung oder Gutschrift terminiert. Genau eine aktive `business`-Subscription bleibt; der Rechnungsbestand blieb bei `27`. Der Cleanup ist ueber den verschluesselten Post-Upgrade-Snapshot wiederherstellbar. Live-Proof: - PR `#287`, Merge-Commit `ba1e14c12` - Unsigned Probe HTTP `401` - Signierter Erstlauf `synced`, Replay `replayed` - Persistenz nach Replay: `1` Idempotency-Key, `1` Audit-Event, `1` Activity **Fortschritt:** `BILL-03`: 8/8 DoD = 100 % done. ## Quellen - AD-27 - Lago API Docs - `BILL-01`, `BILL-02`