Refresh HiveGrid Cloud reference snapshot

This commit is contained in:
david committed 2026-08-03 15:31:14 +02:00
1 parent 5e99e14772
commit 7f88026f79
5955 files changed
+1177325 -188362

No files matched your search

@@ -6,9 +6,12 @@
| **Owner** | Raffael |
| **Phase** | Phase 33 (v2-P11) — Telefonie-Erweiterung (Vorlauf) |
| **Cycle/Fenster** | Backlog/agil (Trigger, Ziel 2026-07-29) |
| **Status** | geplant · 🟠 **block-2 (Partner-API offen, agil — Spec offen)** |
| **Status** | umgesetzt · API-Vertrag mit Test-Account erhoben |
> 🟠 **block-2 — Partner-API offen, agil (Spec offen):** Dies ist der Vorlauf-Task, der den Spec-Gap von HalloPetra schließt. HalloPetra kommt in **keiner Spec** vor — M12 ist eine reine AirCall-Spec. Mechanisch ist HalloPetra ein zweiter Telefonie-Provider hinter dem v1-`TelephonyProviderInterface`, inhaltlich aber unspezifiziert. Agil vorziehbar, sobald der API-Vertrag steht.
> ✅ **Spec-Gap geschlossen (2026-08-01):** Vertrag über den bereitgestellten Test-Account, die
> authentifizierte HalloPetra-Oberfläche und kontrollierte API-Probes erhoben. Es gibt derzeit keine
> öffentlich auffindbare OpenAPI-/Swagger-Referenz. Deshalb trennt diese Spec beobachtete Verträge klar von
> nicht belegten Fähigkeiten; spätere Herstelleränderungen werden fixture-first nachgezogen.
## Was zu tun
Den **HalloPetra-API-Vertrag erheben** und auf das vorhandene `TelephonyProviderInterface` mappen. Konkret klären:
@@ -29,13 +32,132 @@ Ohne den erhobenen API-Vertrag ist der HalloPetra-Adapter (VR-P33) nicht baubar
- **Parallel:** v1-`TelephonyProviderInterface` + AirCall-Adapter (AK-P15a) stehen als Referenz bereit.
## Definition of Done
- [ ] **HalloPetra-API-Vertrag erhoben** (Auth/Webhook-Events/Recording/Call-Lifecycle)
- [ ] **auf `TelephonyProviderInterface` gemappt** (connect/triggerOutboundCall/subscribeToWebhooks/verifyWebhookSignature/parseWebhookEvent/getRecordingUrl)
- [ ] Vorlauf-Spec abgelegt, VR-P33 baufähig markiert
- [x] **HalloPetra-API-Vertrag erhoben** (Auth/Webhook-Events/Recording/Call-Lifecycle)
- [x] **auf `TelephonyProviderInterface` gemappt** (connect/triggerOutboundCall/subscribeToWebhooks/verifyWebhookSignature/parseWebhookEvent/getRecordingUrl)
- [x] Vorlauf-Spec abgelegt, VR-P33 baufähig markiert
## Erhobener Vertrag (Test-Account, 2026-08-01)
### Produktgrenze
HalloPetra ist für HiveGrid **kein zweiter Cold-Calling-Carrier wie Aircall**, sondern ein
Inbound-/Office-Assistant. Der erste Integrationsschnitt ist daher:
1. API-Key als Apps-Engine-Credential,
2. Post-Call-Webhook für Anruf-Match, Logging und Automation,
3. später optional Pre-Call-Anreicherung für Anrufererkennung.
HalloPetra bietet daneben im Produkt unter anderem E-Mail, Website, WhatsApp, Formulare, Outbound und
Routinen. Diese Funktionen sind **nicht** Teil des Telefonie-Tickets `VR-P33` und werden nicht still über
den Adapter-Scope gezogen.
### Auth und API-Key
- Schlüssel werden im HalloPetra-Dashboard unter
`/dashboard/settings/integrations/api-keys` erstellt und nur einmal angezeigt.
- API-Basis: `https://api.hallopetra.de`.
- Authentifizierungsheader: `Authorization: Bearer <api-key>`. `x-api-key` wurde vom Gateway abgewiesen.
- Kontrollprobe: Das Gateway authentifiziert den `/v1/*`-Namensraum vor dem Routing. Ohne/mit falschem Key
antwortet `/v1/health` mit `401`; der gültige Test-Key erreicht das Routing und antwortet derzeit mit
`404`, weil kein öffentlicher Health-Handler existiert. Der Adapter akzeptiert diesen beobachteten
Auth-Gateway-Vertrag sowie einen künftigen `2xx`-Health-Handler; Provider-Bodies werden nie geloggt.
- Es wurde kein OAuth2-Flow, Refresh-Token oder öffentlicher Account-/Identity-Endpunkt gefunden.
### Webhook-Konfiguration
Webhooks werden derzeit **manuell** im HalloPetra-Dashboard unter
`/dashboard/settings/integrations/webhooks` angelegt. Konfigurierbar sind Name, HTTPS-URL, frei definierbare
Header und Variablen. Für `pre_call`/`post_call` gibt es `ALWAYS` oder `ON_DEMAND`.
Beobachtete Webhook-Typen:
| Typ | Zweck | VR-P33-Verarbeitung |
|---|---|---|
| `pre_call` | Anrufer vor Annahme erkennen/anreichern | dokumentiert, separater synchroner Nachzug |
| `post_call` | Anruf-ID, Dauer, Rufnummer, Thema, Zusammenfassung, Nachrichten und gesammelte Daten liefern | **jetzt** auf terminales Inbound-Event mappen |
| `during_call` | Laufzeit-Funktion mit Parametern; Antwort kann gesprochen oder still sein und Kontakt aktualisieren | außerhalb Telefonie-Scope |
| `form_submission` | Formular-, Kontakt- und optionaler Call-Kontext | außerhalb Telefonie-Scope |
Post-Call-Kernpayload (HalloPetra stellt das Beispiel teils mit einer zusätzlichen `body`-Hülle dar; der
Parser akzeptiert beide Varianten):
```json
{
"webhook_id": "<webhook-id>",
"data": {
"id": "<call-id>",
"duration": 95,
"phone": "+49301234567",
"topic": "Terminwunsch",
"summary": "Kurzfassung",
"messages": [{ "role": "assistant | user", "content": "..." }],
"collected_data": { "field": "value" },
"main_task_id": "<task-id>",
"email_send_to": "<email>",
"forwarded_to": "<phone>",
"previous_webhook_calls": []
}
}
```
Der dokumentierte Post-Call-Payload enthält keine garantierte Eventzeit. Der HiveGrid-Ingress ergänzt
deshalb seine serverseitige Empfangszeit. Falls HalloPetra künftig `date`, `ended_at` oder `start_time`
mitsendet, haben diese Felder Vorrang. `duration` rekonstruiert ersatzweise den Startzeitpunkt.
### Webhook-Authentisierung
- Es wurde **keine native HalloPetra-HMAC-Signatur** oder ein vom Provider erzeugtes Webhook-Secret gefunden.
- HalloPetra erlaubt frei definierbare Request-Header. HiveGrid erzeugt daher ein **separates zufälliges
Webhook-Secret** und erwartet `Authorization: Bearer <webhook-secret>`.
- Das Secret wird per Apps Engine verschlüsselt gespeichert; `TelephonyConnection.webhookTokenHash` enthält
nur SHA-256 für den öffentlichen RLS-Bootstrap. Vergleich erfolgt konstantzeitlich.
- API-Key und Webhook-Secret bleiben getrennt, damit ein Webhook-Konfigurationsleck nicht automatisch den
HalloPetra-API-Zugriff kompromittiert.
### Recording und Call-Lifecycle
- Der beobachtete `post_call`-Vertrag enthält **keine Recording-URL**. `getRecordingUrl` liefert deshalb
`null`; ein optionales zukünftiges HTTPS-Feld `recording_url` kann ohne Persistenzumbau übernommen werden.
- HalloPetra liefert in diesem Vertrag nur den abgeschlossenen Inbound-Anruf. Eigenständige
`ringing`/`answered`/`missed`/`voicemail`-Events wurden nicht gefunden.
- Kein öffentlicher Outbound-Trigger-Endpunkt wurde gefunden. Obwohl HalloPetra ein eigenes Outbound-Modul
besitzt, darf der Telefonie-Adapter daraus keinen API-Vertrag erfinden. `triggerOutboundCall` meldet die
Fähigkeit explizit als nicht unterstützt; Click-to-Call bleibt für HalloPetra `tel:`-Fallback. Aircall
bleibt der Cold-Calling-Provider.
## Mapping auf `TelephonyProviderInterface`
| Methode | HalloPetra-Vertrag |
|---|---|
| `connect` / `probe` | API-Key per Bearer gegen authentifizierten `/v1`-Gateway prüfen |
| `disconnect` | lokal Credentials widerrufen; Dashboard-Webhook manuell entfernen |
| `listProviderUsers` / `listUserNumbers` | keine öffentliche Ressource gefunden, daher leere Liste |
| `triggerOutboundCall` | `capability_unsupported`; kein erfundener Endpoint |
| `subscribeToWebhooks` | `capability_unsupported`; manuelle Dashboard-Einrichtung mit URL + Custom Header |
| `validateWebhook` | separates Custom-Header-Secret konstantzeitlich vergleichen |
| `parseWebhookEvent` | `post_call` → `ended`, `inbound`, E.164, dedupe über Webhook-/Call-ID |
| `getRecordingUrl` | aktuell `null`, optionales HTTPS-`recording_url` vorbereitet |
## Quellen und Reproduzierbarkeit
- Anbieter-Seite: `https://www.hallopetra.de/`
- Authentifizierte Test-Account-Seiten: API-Key- und Webhook-Verwaltung (keine Credentials persistiert oder
in Logs ausgegeben)
- API-Probes gegen `https://api.hallopetra.de` mit bereitgestelltem Test-Key; ausschließlich Read-/Auth-
Probes, keine Providerdaten verändert
- Versionierte, synthetische Fixtures und Contract-Tests unter
`packages/integrations/src/hallopetra/`
## Umsetzungs-Notiz
- **2026-08-01 · 3/3 DoD = 100 % done:** Auth, Webhook-Typen, Signaturgrenze, Recording und Lifecycle mit
dem bereitgestellten Test-Account erhoben, auf das vorhandene Provider-Interface gemappt und als
synthetische Fixtures/Tests festgehalten. Der Testzugang wurde nur read-only untersucht; weder Schlüssel
noch Webhooks oder Testanrufe wurden im Anbieter-Account verändert. Adapter-/Fixture-Proof:
`001f56a6e`. `VR-P33` ist damit baufähig.
## Quellen (granular)
- `ROADMAP-V2.md` → §v2-P11 (Telefonie-Teil) + §Zwei Gaps (HalloPetra M105) + §Offene Vorlauf-Tasks #2
- `ROADMAP.md` → Phase 33 · `PHASE-SOURCES.md` → Phase 33 (M105, Block-2)
- `ROADMAP.md` → Phase 33 · Milestones: (M105, Block-2)
- `designer-briefs/P33-telefonie-hallopetra.md` (Provider-Interface-Methodensatz, Vorlauf-Hinweis)
- `_bmad-output/specs/M12-telefonie.md` (AirCall als Referenz, Provider-Pattern)
- abhängig-für: `ticket-docs/VR-P33.md`