# 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, Mollie-Zahlung und echte Worker-Ausfuehrung des Syncs. Der idempotente Pull/Webhook-Sync ist als Outbox-Event-Kontrakt definiert und wird in `BILL-05` konsumiert. Proof: - `pnpm --filter @hivegrid/billing typecheck` - `pnpm --filter @hivegrid/billing test` - `pnpm --filter @hivegrid/config test` ## Quellen - AD-27 - Lago API Docs - `BILL-01`, `BILL-02`