Reports V2: un endpoint au lieu de douze - `/v1/reports/generate`

12 types de rapports PDF - natal, transit-yearly, synastry, business, career, love, money, child, lal-kitab, human-design, tarot, vedic-kundli - vivaient jusqu’à récemment comme 12 routes séparées. Chaque un a son schéma, son chart-payload, son niveau de tarification. C’est conforme au canon REST, mais crée un problème de DX à deux niveaux :

1. SDK surface. Le client TypeScript porte 12 méthodes client.reports.natal(), client.reports.synastry(), … Chaque nouveau type de rapport = breaking change dans l’API publique du SDK (version mineure avec une nouvelle méthode).
2. MCP-каталог. Le serveur MCP hébergé expose 686 outils : chaque rapport parmi les 12 occupe une entrée d’outil séparée. L’agent IA qui parcourt le MCP doit scanner les 12 descriptions d’outil pour choisir le bon. C’est du bruit dans la sélection d’outil.

Le nouveau endpoint POST /v1/reports/generate - un seul dispatcher avec l’enum report_type.

curl -X POST https://api.astroway.info/v1/reports/generate \
  -H "X-Api-Key: aw_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "report_type": "natal",
    "chart": {
      "date": "1990-05-15",
      "time": "14:30:00",
      "timezoneOffset": 3,
      "latitude": 50.45,
      "longitude": 30.52,
      "name": "Test"
    },
    "language": "uk",
    "whitelabel": {
      "themeColor": "#ff5500",
      "reportName": "My Cosmic Map"
    }
  }'

12 valeurs valides pour report_type : natal, transit-yearly, synastry, business, career, love, money, child, lal-kitab, human-design, tarot, vedic-kundli.

Différents types nécessitent différents champs de payload. Le dispatcher fait la validation dans le handler et renvoie un 400 typé :

Ainsi, report_type contrôle non seulement le route de rendu, mais aussi les règles de validation du corps de la requête.

La rétrocompatibilité est totale : les 12 endpoints spécifiques au type restent actifs. Le nouveau /v1/reports/generate - surface additive, pas de remplacement. Cela signifie que le code existant ne se cassera pas, mais le nouveau code peut être écrit de façon plus compacte :

// Стара модель - direct method per type
const pdf1 = await client.reports.natal.create({ chart, whitelabel });
const pdf2 = await client.reports.synastry.create({ chart1, chart2 });
const pdf3 = await client.reports.tarot.create({ seed: "abc" });

// V2 - generic dispatcher
const pdf1 = await client.reports.generate({ report_type: "natal", chart, whitelabel });
const pdf2 = await client.reports.generate({ report_type: "synastry", chart1, chart2 });
const pdf3 = await client.reports.generate({ report_type: "tarot", seed: "abc" });

Ce qui est mieux dépend du cas d’usage. La méthode Direct donne un meilleur type narrowing (le compilateur TS sait que client.reports.synastry.create() nécessite chart1 + chart2). Le dispatcher générique offre une surface plus petite pour les cas d’usage dynamiques - par exemple, quand l’utilisateur choisit le type de rapport via un menu déroulant UI et que tu ne veux pas de switch 12 fois dans le code client.

Sur le serveur MCP hébergé (mcp.astroway.info) il y avait 12 outils séparés, chacun avec une description complète des paramètres. Après l’ajout de generate nous ne supprimons pas les anciens (rétrocompatibilité) - mais le nouvel outil astroway_reports_generate possède une seule description avec l’enum report_type :

Tool: astroway_reports_generate
Description: Generates a PDF/HTML astrology report. Pass report_type to select template.
Parameters:
  report_type (enum): "natal" | "transit-yearly" | "synastry" | "business" | ...
  chart (object, required for most types): birth chart data
  chart1, chart2 (objects, required for synastry)
  language (string): "uk" | "en" | ...
  whitelabel (boolean | object): branding override

L’agent IA, lorsqu’il reçoit la tâche « génère-moi un rapport natal pour la date X », obtient un seul candidat avec un descripteur évident, au lieu de 12 candidats avec des descriptions qui se chevauchent. Cela améliore la précision de la sélection d’outil au niveau de l’agent.

Le dispatcher n’ajoute pas de coût séparé. Chaque report_type est acheminé vers son moteur de rendu interne, qui a son niveau de tarification :

• natal → TIER_7
• transit-yearly → TIER_8
• synastry, business, career, love, money, child, lal-kitab, human-design, vedic-kundli → tiers correspondants
• tarot → TIER_4

Voir les nombres de crédits concrets sur la page Pricing. L’appel POST /v1/reports/generate avec report_type: "natal" coûte exactement le même que le POST /v1/reports/natal direct.

Le nouveau mode inline whitelabel: BrandingObject (publié le 2026-05-19) fonctionne via le dispatcher générique sans modifications :

curl -X POST https://api.astroway.info/v1/reports/generate \
  -H "X-Api-Key: aw_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "report_type": "synastry",
    "chart1": { ... },
    "chart2": { ... },
    "whitelabel": {
      "companyName": "Acme Astrology",
      "logoUrl": "https://cdn.example.com/logo.png",
      "themeColor": "#ff5500"
    }
  }'

Un dispatch + un whitelabel inline = une intégration white‑label complète avec une surface SDK minimale.

GenerateReport - composant séparé dans /v1/openapi.json. Il utilise oneOf avec le discriminateur report_type, ce qui fournit un codegen correct en Python (Pydantic) et en PHP (unions typées via les hints style psalm/phpstan).

Le prochain release de codegen du SDK ajoutera la méthode client.reports.generate() dans les trois paquets (TS / Python / PHP). D’ici là, tu peux appeler via un client HTTP générique dans ton SDK - le payload est documenté dans OpenAPI.

Il n’y a pas d’urgence de migration - les endpoints directs ne sont pas dépréciés. C’est simplement une amélioration DX pour ceux à qui la surface à 12 méthodes gêne.