5.0 KiB
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
- Lago-API-Client mit klarer Env-Konfiguration fuer Staging.
- Customer-Erstellung fuer Tenant.
- Plan-/Seat-Subscription erstellen und lesen.
- Invoice-/Subscription-Status abrufen.
- Lago-Webhook-Endpunkt oder Pull-Sync-Job definiert und idempotent.
- Outbox/Retry fuer ausgehende Billing-Sync-Aktionen.
- Fehlertexte klar und ohne Stacktrace.
- 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 ImplementierungLagoBillingGateway.- 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 typecheckpnpm --filter @hivegrid/billing testpnpm --filter @hivegrid/config testpnpm 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.tspnpm --filter @hivegrid/api typecheckpnpm 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-Commitba1e14c12 - Unsigned Probe HTTP
401 - Signierter Erstlauf
synced, Replayreplayed - Persistenz nach Replay:
1Idempotency-Key,1Audit-Event,1Activity
Fortschritt: BILL-03: 8/8 DoD = 100 % done.
Quellen
- AD-27
- Lago API Docs
BILL-01,BILL-02