# Changelog Toutes les évolutions visibles côté reseller de l'API Yasmine. Le format suit [Keep a Changelog](https://keepachangelog.com/fr/1.1.0/) et la politique de versioning de `docs/versioning.md`. ## [Unreleased] ### Changed (BREAKING) - **Classification d'appel enrichie** : `result` simplifié à 3 valeurs (`confirmed` / `cancelled` / `requires_action`, en minuscules), nouveaux champs `result_detail`, `customer_mood`, `flags`, `preferences`, `next_action`, `summary` exposés dans `CallOut` (`POST /v1/calls`, `GET /v1/calls`, `GET /v1/calls/{call_id}`) et dans le payload `data` du webhook `call.ended`. **Fix** : un appel modifié (« oui mais en bleu ») est désormais classé `result=confirmed` + `result_detail=modified` et déclenche la transition `orders.status=CONFIRMED` — il était auparavant rangé en `UNCLEAR` sans transition. Un faux numéro ou un client qui nie la commande est désormais explicitement `result=cancelled` + `result_detail=wrong_number|denied_order` (avant : `UNCLEAR` indistinguable d'un audio inaudible). Le filtre `?result=` est ajouté à `GET /v1/calls`. Détails et exemples : `docs/webhooks.md` §7, `docs/getting-started.md` §4.5, `docs/examples.md` §3.5. - Schéma `CallOut` (réponse `POST /v1/calls`, `GET /v1/calls/{call_id}`, `GET /v1/calls`) refondu : ajout de `call_duration_seconds`, `meta_error_code`, `meta_error_title`. Renommage `billed_seconds` → `billable_duration_seconds`. Retrait du champ legacy `status` — utiliser `request_status` + `call_status` à la place. (Domaine `result` refondu cf entrée ci-dessus.) Ferme le drift contractuel où le polling `GET /v1/calls/{call_id}`, présenté comme fallback aux webhooks perdus, ne renvoyait pas le résultat métier de l'appel. - **Payload `POST /v1/calls` restructuré** en sous-objets nested (Phase 2-final) : `merchant_ref` racine → `merchant_external_id`, `amount`/`currency` racine → `order.amount`/`order.currency`, `purpose` racine → `call_params.purpose`. Nouveaux sous-blocs `shop_info`, `order`, `call_params`. Le sous-bloc `customer` (introduit Phase 2A) reste inchangé. Un payload plat legacy renvoie `422` avec rejets `extra_forbidden` sur les anciens champs et `missing` sur les nouveaux. - **Sous-objet `customer` obligatoire** sur `POST /v1/calls` (Phase 2A) : `customer_name` et `phone_number` à la racine deviennent `customer.{name, phone_number}`. Un payload legacy renvoie `422 extra_forbidden` + `missing customer`. ### Added - **Téléchargement de l'enregistrement audio d'un appel** via `GET /v1/calls/{call_id}/recording`. Stream le mix audio (client + agent) au format WAV mono 16 kHz, 16-bit PCM (~2 MB pour 60s). Auth Bearer identique aux autres endpoints `/v1`. Rate limit dédié 60 req/min (audio plus lourd que les endpoints JSON). Le `CallOut` (`POST /v1/calls`, `GET /v1/calls`, `GET /v1/calls/{id}`) et le payload `data` du webhook `call.ended` exposent désormais le champ `recording_url` (URL relative). Anti-énumération : 4 cas indistincts renvoient un 404 `call_not_found` byte-identique (UUID invalide, call inexistant, call autre reseller, audio pas encore produit). Rétention 30 jours, puis purge → 410 Gone avec le nouveau slug `recording_gone` (distinct de `call_not_found` pour différencier « jamais existé » vs « a existé mais purgé »). Détails et exemples curl : `docs/getting-started.md` §4.6, `docs/examples.md` §3.5, `docs/webhooks.md` §7. - **Valeur `unclear` ajoutée à l'enum `customer_mood`** (`CallOut.customer_mood`, payload `data.customer_mood` du webhook `call.ended`). Posée par le moteur conversationnel quand l'audio user est globalement incompréhensible (corrélé généralement avec `result_detail=unclear`). Avant : Gemini émettait `customer_mood='unclear'` qui était rejeté par la contrainte `CHECK` Postgres, le tool était retenté en boucle, l'appel s'éternisait sans réponse vocale (cas observé sur le call `f40ce003-...` du 2026-04-30, 4 invocations `end_call` rejetées en cascade). Migration alembic `0023`. Aucun changement de format JSON. Les clients qui parsent strictement l'enum doivent ajouter `unclear` à leur liste de valeurs attendues — sinon traiter comme valeur inconnue/par défaut. - **Pays + langue exposés sur les events terminaux** (`call.ended`, `call.cancelled`, `call.failed`) : `country` (`MA`/`DZ`/`TN`/`FR`) et `language` (`ar`/`fr`) dans le payload `data`. Pratique quand vous n'aviez pas spécifié `language` à la création — vous récupérez la langue locale du pays appliquée par défaut. Champs ajoutés en fin de payload, ordre des champs existants préservé. Aucun handler reseller existant ne casse. Détails : `docs/webhooks.md` §7. - **Choix de la langue d'appel (`POST /v1/calls`)** : nouveau champ optionnel `language` racine, valeurs `ar` ou `fr`. Un reseller dont le client préfère le français peut avoir un appel en français même depuis un pays maghrébin. Si omis, langue locale du pays appliquée automatiquement (rétro-compat stricte). Combinaisons supportées : `MA`/`DZ`/`TN` avec `ar` ou `fr`, `FR` uniquement avec `fr`. La combinaison `country=FR` + `language=ar` est rejetée en `422 language_not_supported_for_country`. - **Détail commande structuré sur `POST /v1/calls`** : champ optionnel `order.items` (tableau, max 50 entrées) — chaque entrée expose `name` (requis), `quantity` (défaut 1), `variant`, `unit_price` (optionnels). Cohabite avec `order.items_text` (résumé libre, max 500 chars). Quand les deux sont fournis, la liste structurée prime. Schéma `OrderItem` documenté dans `docs/openapi.yaml`. - **6 nouveaux events sortants** sur le cycle de vie de l'autorisation WhatsApp : `call.request.template_sent` / `_delivered` / `_read` / `_delivery_failed` (rail TEMPLATE), `call.request.permission_revoked` (révocation manuelle client) et `call.request.permission_auto_revoked` (révocation système après 4 NA). Le catalogue passe à 18 events `call.*`. - **Nouvel event `call.request.service_unavailable`** qui isole les problèmes système Yasmine (compte WhatsApp momentanément bloqué, template en révision, saturation passagère, token à renouveler) du `call.failed` générique. Inclut `retry_after_hint_minutes` (entier) — distingue un problème transitoire côté Yasmine d'un échec définitif côté client. - **Idempotence stricte** des nouveaux events : 1 dispatch par changement d'état observé, même sur retry réseau côté plateforme. L'envelope avec `id=evt_` reste l'identifiant définitif côté reseller pour la déduplication. - **`GET /v1/me`** expose 10 nouveaux champs profil société : `owner_name`, `owner_phone_e164`, `default_language`, `country`, `timezone`, `legal_name`, `tax_id`, `billing_address`, `business_type`, `website_url`. Tous nullables, retournés `null` tant que non renseignés. Pas d'endpoint d'update self-service (roadmap M4) — valeurs posées côté ops. - **Pré-création automatique des partitions mensuelles** (interne) : timer systemd `yasmine-partitions.timer` exécute mensuellement la création des partitions des 3 mois suivants. Évite l'échec d'INSERT si le buffer initial est consommé. Aucun impact contrat reseller. - **Header `X-Yasmine-Event`** ajouté aux webhooks sortants (dispatcher principal + endpoint de test). Permet de router/dédupliquer les events sans parser le body JSON. - **`docs/webhooks.md` synchronisé** vers le plugin `akidly/yasmine` au push master. - **`webhook.test` documenté** dans le catalogue `docs/webhooks.md` §7. Payload `{test: true, test_id, request_id}` — distingue le test d'un event métier (clé `test=true`). ### Fixed - **Détail commande désormais transmis intégralement à l'agent vocal** : adresse de livraison, articles, mode et zone de livraison, montants (sous-total, frais de livraison, remise), date estimée, numéro de commande et notes étaient acceptés et persistés mais ignorés pendant l'appel — l'agent appelait sans contexte. Tout ce détail remonte désormais jusqu'au dialogue. Si seul `order.items_text` est fourni (sans `order.items`), il est cité tel quel. - **Propagation du code de diagnostic dans `call.failed.data.failure_reason`** : auparavant `failure_reason` était `meta_` seul (ex. `meta_400`), désormais `meta_:` quand le code est connu (ex. `meta_400:131030`). Le code numérique était stocké uniquement en logs internes Yasmine. - **Statut `REJECTED` traité correctement** par le dispatcher : transition `call_status=failed` + `failure_reason=client_rejected` + event sortant `call.failed` émis (auparavant tombait en metadata `unknown_event_seen`, l'appel restait figé en état intermédiaire). - **Sérialisation correcte des notifications de progression d'appel** (RINGING, ACCEPTED) : verrou par appel maintenant pris à chaque dispatch, identique au comportement en place pour `connect`/`terminate`/`reject`. Avant, deux notifications concurrentes pouvaient s'exécuter en parallèle. - **Suppression d'un doublon de `call.started`** en course serrée entre origination interne et webhook plateforme. Seule la plateforme reste source d'émission. - **Normalisation des valeurs vides du payload IA** (`call.ended` + `CallOut`) : la chaîne `"null"` (4 chars) renvoyée parfois par le moteur conversationnel pour `next_action` / `summary` / `customer_mood` / `result_detail` est désormais convertie en `null` JSON propre. Idem pour les variantes `"none"` / `"n/a"` / `""` / espaces seuls (insensible à la casse). Filtre symétrique sur `flags` et `preferences` (éléments vides retirés). Aucun changement de schéma. - **Documentation webhooks** : alignement post-audit indépendant — suppression du wrapper `data.object` dans les exemples §2 et §3 (le code émet `data` à plat). Énumération des slugs réels d'erreur (`timeout`, `connect_error:*`, `http_error:*`, `unknown:*`) en §4 au lieu du `max_retries_exceeded` historique. - **Workflow `sync-plugin.yml`** : `DRY_RUN` fallback corrigé (le ternaire GHA `A && B || C` court-circuitait à `C` quand `B = 'false'` truthy). - **Documentation interne `doc/whatsapp.md §14.8`** alignée sur le code (fail-closed `503` HMAC). Sections §12 et `doc/call_flow_pipeline.md` §3.1/§9.4 propageaient la même information obsolète. - **OpenAPI path param** : renommage `{id}` → `{call_id}` sur `getCall` et `cancelCall` pour aligner sur le nom utilisé côté code et dans `docs/getting-started.md` / `docs/examples.md`. Les SDK générés depuis l'OpenAPI exposeront désormais `call_id` comme nom de paramètre. - **`docs/errors.md`** : ajout des slugs `bad_request` (400) et `rate_limited` (429) — slugs par défaut HTTP qui pouvaient apparaître sans entrée documentée. Alignement sur `docs/site/errors.html` qui les exposait déjà. - **`docs/site/errors.html`** : ajout des sections `language_not_supported_for_country` et `http_error` — symétrie avec `docs/errors.md`. ### Removed (BREAKING — schéma DB interne, aucun impact contrat API publique) - Suppression de 3 colonnes mortes sur `merchants` : `contact_email`, `contact_phone_e164`, `contact_whatsapp_e164` (doublon source de `shop_email_sav` / `shop_phone_sav` / `shop_whatsapp_sav`). Migration Alembic `0019`. `CallOut` et toutes les réponses reseller restent inchangés. ### Removed (OpenAPI cleanup) - Retrait des 5 endpoints `x-status: planned` de `docs/openapi.yaml` (`/v1/calls/{id}/events`, `/v1/calls/{id}/transcript`, `/v1/merchants` GET/POST, `/v1/merchants/{id}` PATCH). Ils ne sont pas implémentés — leur présence côté spec induisait des SDK clients à les coder pour rien. Réintégration au moment où ils seront livrés en `live`. Routes `/webhooks/whatsapp` (réception plateforme entrante) sorties de la spec publique : restent fonctionnelles dans le code, mais hors périmètre reseller. Schémas associés (`CallEventList`, `Transcript`, `Merchant*`) supprimés en cascade. ### Internal (visibilité reseller : aucune — pour traçabilité audit) - Refonte de la table d'historisation des envois de templates WhatsApp (PK interne autonome, persistance systématique des tentatives succès + échecs sync, capture du code de diagnostic, timestamp explicite de réponse client). Migration Alembic `0020`. - Cartographie des codes de diagnostic plateforme en 4 catégories (`service_unavailable` / `transient` / `client_side` / `unknown`) — source de vérité `agent/meta_error_codes.py`. Toute évolution requiert une validation produit. - Audit interne des échecs plateforme : 3 nouvelles colonnes internes (`calls.meta_error_code`, `calls.meta_error_title`, `calls.meta_error_details`) projetées depuis les webhooks `terminate FAILED`. Migration Alembic `0018`. - Observabilité livraison templates : `template_sends` remplit `delivered_at`, `read_at`, `failed_reason`, `billable`, `category`, `pricing_model` depuis le webhook plateforme entrant. Migration Alembic `0017`. - 2 nouvelles colonnes internes `calls` : `direction` (préparation inbound futur) + variante conversationnelle tracée par appel. Migration Alembic `0016`. ### Added (Lot 4 — CI auto-sync plugin) - `.github/workflows/sync-plugin.yml` : auto-sync docs sources → `akidly/yasmine` on `push master` (paths-filtered : `docs/openapi.yaml`, `docs/errors.md`, `docs/examples.md`, `docs/getting-started.md`, `CHANGELOG.md`) ou `workflow_dispatch`. - Bump patch auto des versions dans `plugin.json` et `marketplace.json` ; bump `minor`/`major` disponible via `workflow_dispatch` input. - Copies : 4 docs vers `skills/yasmine-api/*` + `CHANGELOG.md` à la racine publique. - Commit + tag `vX.Y.Z` poussés par le bot `akidly-sync-bot`. - Skip automatique si `git diff-index --quiet HEAD` (pas de commit vide). - Auth : PAT fine-grained `AKIDLY_PUBLISH_PAT` (scope `contents: write` sur `akidly/yasmine` uniquement, rotation 90j). - Premier run forcé en `dry_run=true` — cutover à `false` par défaut dans un commit ultérieur après validation. ### Fixed (Lot 3 — plugin MCP activation) - `akidly/yasmine` bumped to `v0.1.1` (commit `5627f92`, tag `v0.1.1`) : pattern `userConfig` + `${user_config.api_token}` (documenté dans `plugins-reference.md`) **non implémenté** en Claude Code CLI 2.1.116 — MCP server skippait silencieusement à l'init. Remplacé par le pattern officiel des plugins Anthropic (cf. `github` plugin) : `.mcp.json` séparé à la racine + substitution standard `${YASMINE_API_TOKEN}` (env var). Plugin minimal `plugin.json` (name/version/description/author). README mis à jour avec étape `export YASMINE_API_TOKEN=yk_...` avant install. v0.1.0 gardée comme artefact historique. ### Added (Lot 3 — Claude Code plugin `yasmine@akidly`) - Public plugin released at [akidly/yasmine](https://github.com/akidly/yasmine) `v0.1.0`. Install via `/plugin install yasmine@akidly/yasmine`. - Manifest in `.claude-plugin/plugin.json` with `mcpServers` inline (declares the prod `https://mcp.yasmine.akidly.com/mcp/` endpoint) + `userConfig.api_token` (`sensitive: true`, prompts user once, stored in OS keychain) + `userConfig.api_endpoint` (override-able for local dev). - Skill `yasmine-api` bundled (auth + ISO country/language codes + E.164 phone format + 5 RFC 7807 error slugs + pointer vers `explain_error()` for full detail). - README, LICENSE (MIT 2026 Akidly), .gitignore standard Python+IDE. - `plan-mcp-plugin.md §4.3` re-aligné sur la spec officielle Claude Code 2026 (audité Phase 0 du Lot 3). ### Added (Lot 2 — MCP introspection tools) - `yasmine_mcp/introspection.py` : 4 new MCP tools for API self-discovery by AI agents : - `list_endpoints` — enumerates 20 live API operations (filters `x-status: planned`) - `get_endpoint_spec(operation_id)` — returns full OpenAPI spec for an operation - `get_changelog(version=None)` — returns parsed changelog entries (default: Unreleased + latest released) - `explain_error(slug)` — returns structured error explanation with Causes/Remediation/Example - `yasmine_mcp/_openapi.py` : shared OpenAPI loader + `x-status: planned` filter (de-duplicates logic between `server.py` and `introspection.py`) - `docs/errors.md` : 5 slugs enriched with structured sections (`validation_error`, `rate_limit_exceeded`, `insufficient_balance`, `idempotency_key_conflict`, `invalid_cursor`). Markdown table untouched, section appended. - 14 new tests in `tests/yasmine_mcp/test_introspection.py`. ### Changed - `yasmine_mcp` server name : `Yasmine MCP (Lot 1)` → `Yasmine MCP (Lot 1+2)`. - `tests/yasmine_mcp/test_server.py` tool inventory : 4 → 8 expected. ### Fixed - `ops/deploy.sh` self-reload : guard `YASMINE_DEPLOY_RELOADED` env var pour casser la boucle infinie qu'introduisait l'`exec bash "$0"` du commit `9aaf0b2`. Sans guard, le script post-reset relançait `exec bash` indéfiniment (chaque relance lit la version disque qui ne change plus, mais re-exec quand même). Découvert sur le push Lot 2 (`093b7c5`) qui n'a jamais déclenché le restart de `yasmine-mcp.service`. Pattern `if [[ -z "${YASMINE_DEPLOY_RELOADED:-}" ]]; then export ...; exec bash "$0" "$@"; fi` — la 1re exec set la var puis exec, la 2e voit la var posée et continue à `pip install`. ### Chore - `ops/deploy.sh` : self-reload after `git reset` to pick up script updates from the same pull. - `ops/mcp-bootstrap.sh` : archive VPS one-shot bootstrap for reproducibility. - Docs cleanup : align `plan-mcp-plugin.md` + `CLAUDE.md` on post-Lot 1 state (`yasmine_mcp/` path, `fastmcp>=3.2.0`, `yk_` key format). - Remove `CLAUDE.md.bak.2026-04-19` (git history is the source of truth). ### Added - `respx` to `requirements.txt` (test dependency, was transitively installed). ### Added (Lot 1 — MCP remote `mcp.yasmine.akidly.com`) - `yasmine_mcp/` — MCP remote FastMCP (PyPI 3.x) pass-through vers l'API Yasmine, exposant **4 tools live** : `get_account` (→ `GET /v1/me`), `get_call` (→ `GET /v1/calls/{id}`), `create_call` (→ `POST /v1/calls`), `list_calls` (→ `GET /v1/calls`). Transport **Streamable HTTP** (spec MCP 2025-11-25), bind `127.0.0.1:9001`, **stateless** (pas de `MCP-Session-Id`). Auth = **passthrough Bearer** du client MCP vers l'API Yasmine via `httpx` event hook + `fastmcp.get_http_headers(include={"authorization"})`. `OriginGuard` middleware (anti DNS rebinding, spec MCP Security). Response hook convertit les 4xx/5xx RFC 7807 en `ToolError` lisible (`title: detail`, pas de stack trace). 2 préprocesseurs in-memory sur `docs/openapi.yaml` : `_strip_planned_operations` (filtre `x-status: planned` → masque `listMerchants`/`createMerchant` jusqu'à M4, réactivation non-breaking) et `_normalize_nullables` (convertit récursivement `nullable: true` OpenAPI 3.0 → `type: [X, null]` JSON Schema draft-07+, nécessaire pour `PaginatedCalls.next_cursor` entre autres). Le fichier `docs/openapi.yaml` sur disque reste en forme OpenAPI 3.0 canonique servable à Scalar. - `tests/yasmine_mcp/test_server.py` — 16 tests verts : inventaire (4 tools), 1 par tool via `respx` mock + `fastmcp.Client` in-process, régression nullable `next_cursor: None`, preuve que les planned ne fuient pas, forwarding Bearer (unit), Origin guard (3 cas), RFC 7807 → ToolError, masking header dans logs. `respx` ajoutée en dep de dev. - `ops/yasmine-mcp.service` — systemd unit (user `deploy`, `EnvironmentFile=/opt/yasmine/.env`, `ExecStart=/opt/yasmine/venv/bin/python -m yasmine_mcp.server`, `Restart=on-failure`). - `ops/nginx-mcp.conf` — bloc Nginx `mcp.yasmine.akidly.com` : port 80 + ACME challenge + proxy_pass `http://127.0.0.1:9001`, `proxy_buffering off` / `chunked_transfer_encoding on` / timeouts 3600 s pour supporter les SSE streams de Streamable HTTP. SSL posé par certbot `--nginx`. - `ops/deploy.sh` étendu : après le restart `yasmine.service`, le script copie la unit MCP en `/etc/systemd/system/`, `daemon-reload`, `enable`, `restart yasmine-mcp.service`, puis snapshot status. - `requirements.txt` : `fastmcp>=3.2.0`, `pyyaml>=6.0.1`. ### Fixed - `docs/openapi.yaml` : 2 plain scalars non-conformes YAML 1.2 strict (ligne 620 `description` commençant par `` ` ``, ligne 1180 `detail` contenant ` : `) encadrés en `"..."`. Scalar les tolérait, ni PyYAML ni ruamel.yaml ne les chargeaient. Sémantique inchangée. - `.claude/context/plan-mcp-plugin.md` + `roadmap.md` : rename `mcp/` → `yasmine_mcp/` (collision avec le package PyPI `mcp`, dépendance transitive de FastMCP — un dossier `mcp/` à la racine fait shadow sur l'import `mcp.types`). - `.claude/context/roadmap.md` : mention `FastMCP 2.x` → `FastMCP 3.x` (PyPI publie en 3.x désormais, la doc gofastmcp.com unifie sous "2.x+" mais les imports canoniques sont `fastmcp.server.providers.openapi.{MCPType, RouteMap}` / `fastmcp.server.dependencies.get_http_headers`). ### Known issues - 11 test failures in `tests/test_finalize_whatsapp.py` (pre-existing, introduced by `0d14a21` — signature mismatch on `_resolve_result`). Unrelated to Lot 1. Tracked separately. ### Changed (ops — source unique `ops/deploy.sh` + bascule GitHub Action) - `ops/deploy.sh` enrichi avec les 4 traces timestamps `echo "[$(date -Iseconds)] <étape>"` et format `set -a` / `. .env` / `set +a` sur 3 lignes — matche désormais byte-pour-byte le script live `/opt/yasmine/deploy.sh` qui tournait avant versionnage. Fidélité des logs GitHub Action préservée. - `.github/workflows/deploy.yml` : la step finale appelle `bash /opt/yasmine/ops/deploy.sh` au lieu de `bash /opt/yasmine/deploy.sh`. Aucune autre modif (secrets, triggers, concurrency identiques). - Ancien `/opt/yasmine/deploy.sh` racine supprimé côté VPS (`sudo rm`) — source unique canonique désormais **tracée en Git** sous `ops/deploy.sh`. Toute modif future du script live doit passer par un commit. - `docs/infrastructure.md` section "Script de déploiement" reformulée : fichier live VPS = `/opt/yasmine/ops/deploy.sh`, propagé par `git reset --hard` interne au script. ### Changed (doc infra — post-vérif VPS 2026-04-21) - `docs/infrastructure.md` : les blocs Nginx M3.4 (aliases `.md` bruts `getting-started`/`examples`/`webhooks`/`versioning`) et P1-10 (surface `/errors` + `/errors.html` + redirection `^/errors/([a-z_]+)$`) sont reformulés en **historique déployé** (plus de diff "à appliquer"). La vérification VPS `2026-04-21 14:42 UTC` confirme qu'ils servent depuis le déploiement correspondant. Fallback `location /` corrigé : `try_files $uri $uri/ =404` (état prod réel, plus strict que le `/index.html` documenté). - `docs/infrastructure.md` nouvelle section `## Script de déploiement` : pointe vers `ops/deploy.sh` comme source canonique, liste les 5 étapes (fetch+reset hard, pip, charge `.env`, `alembic upgrade head`, restart `yasmine.service`). Documente explicitement que les migrations Alembic tournent à chaque push — ne jamais merger sur `master` une migration non-réversible. ### Added (ops — deploy.sh versionné) - `ops/deploy.sh` (534 o, exécutable) : copie à l'identique du script live `/opt/yasmine/deploy.sh` qui n'était **pas versionné** auparavant. Toute modif future côté VPS est à reporter dans ce fichier pour code review. `CLAUDE.md` section Production pointe désormais dessus. ### Added (contexte — audits v3 + plan MCP/plugin) - `.claude/context/audit-2026-04-v3.md` — nouvel audit API 3 volets reflétant l'état post-P1 (P0 v2 tous fermés 2026-04-21 + 10 des 12 items P1 livrés même journée). Diff explicite avec l'audit v2 pour chaque item (statut ✅/⚠️/❌/➖). Surface live : 8 → 21 routes authentifiées. Nouveaux vecteurs identifiés : cursor HMAC clé globale sans `reseller_id`, DDoS amplifier via `/webhooks/test`, `last_used_ip` mono-valeur, URL webhook en logs + DB non purgée, collision de naming "P1-8" (webhook-rotate ≠ HMAC key hash). - `.claude/context/roadmap.md` refondue : P0 v3 vide (aucun bloquant vente externe restant), P1 v3 resserré à 7 items (HMAC key hash vrai, timestamp signature webhook, retention `webhook_deliveries`, `api_key.compromised` proactif, découpage `me.py`, OpenAPI YAML ré-aligné, DNS async dispatcher), P2 v3 à 20 items. Ancienne roadmap v2 conservée en section `## Archive — Roadmap v2`. - `.claude/context/docs-audit-2026-04.md` — audit AI-readability (sections 1-4-bis livrées) : état doc Markdown, infra Nginx vs VPS réel (drift levé), gap analysis 3 couches (llms.txt absent, aliases `.md` brut tous déployés, skill Claude Code à construire), pipeline update avec drift par artefact. §5 roadmap à générer. - `.claude/context/plan-mcp-plugin.md` — plan vivant du chantier MCP remote + plugin Claude Code public. Référence avant tout travail sur le dossier `mcp/` ou un repo de distribution. - `CLAUDE.md` section Documents de référence : pointe désormais `audit-2026-04-v3.md` comme source active (v2 + v1 en archive), ajoute les 2 nouveaux pointeurs `docs-audit-2026-04.md` et `plan-mcp-plugin.md`. - `.claude/context/docs-audit-2026-04.md` §5 — roadmap actionnable rédigée : synthèse gaps, vision cible, 5 lots MCP/plugin priorisés, scénarios de dégradation. Clôt l'audit AI-readability. - `.claude/context/roadmap.md` — sous-bloc `### Distribution AI-native (MCP remote + plugin Claude Code)` ajouté en P2 avec items `#P2-v3-MCP-1` à `#P2-v3-MCP-5` (total ~6 j). Légende volets étendue avec `Audit docs`. - `CLAUDE.md` section Production — correction pointeur `/opt/yasmine/deploy.sh` → `/opt/yasmine/ops/deploy.sh` aligné sur l'état live post-`6d81b7a`. ### Added (P1-8-bis — Dédup events côté reseller) - **Documentation explicite** que `X-Yasmine-Event-Id` (déjà émis depuis M3.6 C6) reste stable à travers les retries du dispatcher — usable côté reseller pour dédupliquer. `docs/webhooks.md §6` enrichi avec recette Redis `SET NX EX 86400` en plus de l'approche DB UNIQUE INDEX existante. TTL recommandé 24 h (> fenêtre max retry 5 min × 3 tentatives). - 3 tests dédiés (`tests/test_dispatcher_event_id.py`) verrouillent les invariants : header `X-Yasmine-Event-Id` == body.id, event_id préservé sur 3 POST retry (500, 500, 200), 2 dispatch successifs produisent 2 event_id distincts. Le 4e test du brief (signature couvre l'event_id) est déjà couvert par `test_webhook_dispatch.py::test_dispatch_success_happy_path`. Suite : 329 → 332 passed. - **Aucun code applicatif modifié** : l'infrastructure (`envelope["id"] = f"evt_{ulid.new().str}"` généré **hors** boucle retry, header + body top-level, colonne `webhook_deliveries.event_id` TEXT NOT NULL + index) existait depuis la migration 0006 (M3.6 C6 Phase 1) et le dispatcher Phase 2. ### Added (P1-8 — Rotation du signing secret webhook) - **`POST /v1/me/webhooks/rotate-secret`** (#P1-8) : nouvel endpoint qui rotate atomiquement le secret HMAC-SHA256 du webhook actif sans passer par `DELETE + POST`. Retourne 200 `{"secret": "whsec_...", "secret_prefix": "whsec_xxxxxx…", "rotated_at": "..."}`. **Secret visible une seule fois** dans la réponse — aucun endpoint ne la ré-expose. Rate-limit **5/min** (aligné sur `POST /v1/me/api-keys`). 404 `webhook_not_configured` si aucune config active. - **Format secret `whsec_<43 chars>`** (Stripe-like) pour les nouveaux secrets générés à la création ou à la rotation (`secrets.token_urlsafe(32)` + préfixe repère). Facilite le grep / secret scanning dans les logs et CI. Les secrets legacy pré-P1-8 (sans préfixe) restent fonctionnels — la fonction `sign_payload` est prefix-agnostique. - 7 nouveaux tests (`tests/test_webhook_rotate.py`) : format `whsec_`, unicité, endpoint 200/404, rate-limit 5/min, 2 rotations consécutives produisent 2 secrets distincts, invariant "l'ancien secret ne valide plus après rotate". ### Changed (P1-8 — Preview secret 12 chars au lieu de 6) - `GET /v1/me/webhooks` renvoie désormais `secret_prefix` sur **12 chars** + `…` (était 6 chars jusqu'au P1-8). Cohérent avec `key_prefix` des clés API (P1-4). Pour les nouveaux secrets format `whsec_xxxxxx…` (6 chars utiles après le préfixe). Pour les secrets legacy, 12 chars bruts — plus informatif qu'avant. - **Pas de migration DB** : la colonne `reseller_webhooks.secret` existait déjà depuis M3.6 C6. Le HMAC signing, le dispatcher et le header `X-Yasmine-Signature: sha256=` sont live en prod depuis M3.6 — seule la rotation atomique et le format `whsec_` sont nouveaux. - `docs/webhooks.md §1.4` réécrit pour pointer sur `POST /v1/me/webhooks/rotate-secret` en premier (pattern DELETE + POST documenté en legacy fallback). `docs/openapi.yaml` ajoute le path + schéma `WebhookSecretRotated`. ### Added (P1-9 — Rétention auto + audit trail `api_key_events`) - **Purge automatique de `api_key_events` après 180 jours** (#P1-9). Audit trail (events `created`, `revoked`, `rate_limited` écrits par P1-6) purge via `DELETE` — standard OAuth2/Stripe. Évite la croissance illimitée de la table (worst-case ~43k rows/mois/clé estimé en rapport P1-6). - Script `scripts/retention_purge.py` refondu en 3 fonctions indépendantes (`purge_webhook_raw`, `purge_call_events`, `purge_api_key_events`), chacune dans sa propre transaction. Une erreur sur une table ne bloque plus les autres. - **Logs JSON structurés** : une ligne INFO par table (`{"table":"","retention_days":,"purged":,"dry_run":}`) + une ligne summary en fin de run. Consommable direct par journalctl + tooling d'observabilité (Grafana Loki, etc.). - **Exit code 1** si au moins une table a raisé (visible dans `systemctl status yasmine-retention.service`). Exit 2 sur argument CLI invalide. - Nouveau flag CLI `--api-key-events-days` (défaut 180) pour overrider le seuil audit trail indépendamment du seuil court `--older-than-days` (webhook_raw + call_events, défaut 30). - 9 tests ajoutés (total retention : 2 → 11). Suite : 312 → 321 passed. ### Changed (P1-9 — Rétention désormais automatique) - Rétention PII `webhook_raw.payload` et `call_events.data.raw` désormais **quotidienne automatique** via systemd timer (`yasmine-retention.timer`, 02:00 UTC) au lieu d'un run mensuel manuel. Pas de migration de données — le passage de "mensuel manuel" à "quotidien auto" n'affecte que la fréquence du cleanup, pas le seuil 30 j. - Les 2 fichiers systemd (`yasmine-retention.service` + `.timer`) sont documentés dans `docs/infrastructure.md §Rétention auto — systemd timer` — à déposer manuellement sur le VPS (config système, hors repo). User `deploy` (identique à `yasmine.service`). - `webhook_deliveries` (P1-2) reste **hors scope** P1-9 — volume actuel faible, à revoir en P2 si un reseller live génère du trafic. ### Added (P1-7 — CORS middleware) - **Support CORS pour fronts web cross-origin** (#P1-7). `CORSMiddleware` de FastAPI enregistré en dernier dans la stack (donc le plus extérieur à l'exécution — les preflight `OPTIONS` sont interceptés avant tout autre traitement, y compris le rate-limit). Politique stricte : - **Liste blanche statique** via env `CORS_ALLOWED_ORIGINS` (URLs absolues séparées par virgules). Défaut : vide (aucune origine acceptée). Ajouter les URLs des fronts reseller au cas par cas côté `/opt/yasmine/.env`. - **Dev auto** : si `ENV=dev`, regex `^http://(localhost|127\.0\.0\.1)(:\d+)?$` autorise `localhost`/`127.0.0.1` sur n'importe quel port. Verrouillé strictement — aucune autre IP privée acceptée. - `allow_credentials=true` (Bearer Authorization cross-origin OK). Incompatible avec `*` côté spec, d'où la liste blanche explicite. - **Methods** : `GET`, `POST`, `DELETE`, `OPTIONS`. - **Headers client acceptés** : `Authorization`, `Content-Type`, `Idempotency-Key`, `X-Request-ID`. - **Headers exposés au front** : `X-Request-ID`, `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`, `Retry-After`. Permet au front de lire les en-têtes de rate-limit pour pacer ses requêtes. - **Preflight cache 10 min** (`max_age=600`). - Nouvelle variable `CORS_ALLOWED_ORIGINS` dans `.env.example` avec commentaire explicatif. **Aucune URL committée** (liste blanche reste vide dans le repo — les origines réelles vivent en `/opt/yasmine/.env`, hors git). - **Aucun header Nginx ajouté** côté `api.yasmine.akidly.com` : CORS géré entièrement côté application Python. Pas de risque de double injection. - 8 tests (`tests/test_cors.py`) : preflight whitelist/rejet, GET avec/sans origine, dev localhost accepté, prod localhost rejeté, garde-fou spec credentials+allow_origins spécifique. Suite : 304 → 312 passed, 0 régression. ### Added (P1-10 — Page d'erreurs humaine) - **`https://docs.yasmine.akidly.com/errors`** (#P1-10) : nouvelle page HTML listant les 28 slugs d'erreur émis par l'API, groupés par catégorie (Authentication, Validation, Idempotency, Billing, Rate limiting, Not found, Conflict, Webhooks, Size limits, Server). Chaque slug a sa propre `
` avec : explication, causes fréquentes, correctifs actionnables, exemple de réponse JSON. TOC latérale sticky, style cohérent avec Scalar dark theme. - **Rewrite Nginx `/errors/` → `/errors#`** (302) : les URLs `type` RFC 7807 émises par l'API (ex. `https://docs.yasmine.akidly.com/errors/insufficient_balance`) atterrissent désormais sur la bonne section de la page, sans changer le code back. Diff Nginx documenté dans `docs/infrastructure.md` — à appliquer manuellement sur le VPS (`nginx -t` + `systemctl reload nginx`). Compatible avec l'alias existant `/errors.md` (non-régression). - Test garde-fou `tests/test_errors_page_coverage.py` (4 tests) : parse le HTML et compare avec `api.v1.errors._KNOWN_V1_SLUGS`. Bloque toute dérive (slug émis sans section doc, section orpheline). Suite : 300 → 304 passed. - **4 slugs ajoutés à `_KNOWN_V1_SLUGS`** (étaient émis mais absents de l'allow-list documentaire) : `rate_limit_exceeded` (M3.6 C7), `webhook_url_rejected`, `webhook_already_configured`, `webhook_not_configured` (P1-2). Aucun impact runtime — allow-list strictement documentaire, `build_problem` accepte tout slug. - Note ajoutée en tête de `docs/errors.md` pointant vers la page détaillée ; section "Compatibilité" mise à jour (URLs désormais résolvables). ### Changed (P1-12 — Strict body validation `POST /v1/calls`) - **Audit** : `CallCreate` (schema public du POST) était **déjà** en `extra="forbid"` depuis M3.3 — les champs inconnus sont rejetés 422 avec body RFC 7807 `validation_error` + `errors[].type=extra_forbidden` + `loc` explicite. Smoke prod confirmé (`{"custommer_name":"typo", ...}` → 422). Aucun slug dédié ajouté (le body existant expose déjà `type=extra_forbidden` côté Pydantic, le gain clarté d'un slug custom est marginal). - **Défense en profondeur** : `CallRequest`, `ShopInfo`, `Product` (tous dans `api/schemas.py`, legacy interne jamais désérialisés depuis un body HTTP) patchés avec `model_config = ConfigDict(extra="forbid")`. Bloque un kwarg typo dans l'instanciation interne du handler `api/v1/calls.py::create_call` — exposition publique future protégée par défaut. - 10 tests ajoutés (`tests/test_schemas_extra_forbid.py`) couvrant CallCreate (typo top-level, extras multiples, optionnel omis, metadata dict libre, payload valide) + schemas legacy. Suite : 290 → 300 passed, 0 régression. - OpenAPI `docs/openapi.yaml` : déjà `additionalProperties: false` sur `CallCreate`, aucune modif nécessaire. - **Pas de breaking change effectif** : ce comportement est actif en prod depuis M3.3. Le chantier P1-12 consolide la couverture tests + documente le contrat strict. ### Added (P1-6 — Audit log clés API) - **`GET /v1/me/api-keys/{key_id}/events`** (#P1-6) : journal paginé des événements d'une clé API. Enveloppe `{data, next_cursor, has_more}`, réutilise le helper pagination P1-3 (curseur HMAC TTL 24 h, forward-only, tie-break stable sur `id DESC`). `limit` max 50 (Pydantic). Anti-énum : **404 `api_key_not_found` byte-identique** si la clé n'existe pas OU appartient à un autre reseller (pattern P0-2). 400 `invalid_key_id` si UUID malformé. Rate-limit 600/min global (pas de limite spécifique). - **3 events captés en fire-and-forget** depuis le code serveur : - `created` — POST `/v1/me/api-keys` réussi, `metadata={"label": "