Reports V2: één endpoint in plaats van twaalf - `/v1/reports/generate`

12 soorten PDF-rapporten - natal, transit-yearly, synastry, business, career, love, money, child, lal-kitab, human-design, tarot, vedic-kundli - tot voor kort leefden ze als 12 afzonderlijke routes. Elk heeft zijn eigen schema, zijn eigen chart-payload, zijn eigen pricing tier. Dat is volgens de REST-canon correct, maar veroorzaakt een DX-probleem op twee niveaus:

1. SDK surface. De TypeScript-client draagt 12 methoden client.reports.natal(), client.reports.synastry(), … Elke nieuwe rapporttype = breaking change in de public API SDK (minor versie met een nieuwe methode).
2. MCP-catalogus. De gehoste MCP-server exposeert 686 instrumenten: elk van de 12 rapporten neemt een aparte tool entry in beslag. Een AI-agent die via MCP loopt, moet 12 tool‑descriptions scannen om de juiste te kiezen. Dat is ruis bij tool selection.

De nieuwe endpoint POST /v1/reports/generate - één dispatcher met een report_type enum.

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 geldige waarden voor report_type: natal, transit-yearly, synastry, business, career, love, money, child, lal-kitab, human-design, tarot, vedic-kundli.

Verschillende types vereisen verschillende payload-velden. De dispatcher voert validatie uit in de handler en retourneert een getypeerde 400:

Dus report_type bepaalt niet alleen de render‑route, maar ook de validatieregels voor de request‑body.

Volledige backward compatibility: alle 12 type‑specific endpoints blijven bestaan. De nieuwe /v1/reports/generate is een additive surface, geen vervanging. Dat betekent dat bestaande code niet breekt, maar nieuwe code kan compacter geschreven worden:

// Стара модель - 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" });

Wat beter is, hangt af van de use‑case. Een direct‑methode geeft betere type narrowing (de TS‑compiler weet dat client.reports.synastry.create() chart1 + chart2 vereist). Een generic‑dispatcher heeft een kleinere surface area voor dynamische use‑cases – bijvoorbeeld wanneer de gebruiker een rapporttype kiest via een UI‑dropdown en je geen 12‑voudige switch in de client‑code wilt.

Op de gehoste MCP‑server (mcp.astroway.info) waren er 12 afzonderlijke tools, elk met een volledige beschrijving van de parameters. Na het toevoegen van generate verwijderen we de oude niet (backward compatibility) – maar de nieuwe tool astroway_reports_generate heeft één beschrijving met een report_type enum:

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

Een AI‑agent die de taak krijgt “genereer een natal‑rapport voor datum X” krijgt één kandidaat met een duidelijke descriptor, in plaats van 12 kandidaten met overlappende beschrijvingen. Dit verbetert de tool‑selection accuracy op agentniveau.

De dispatcher voegt geen extra kosten toe. Elke report_type wordt doorgestuurd naar zijn eigen interne renderer, die zijn eigen pricing tier heeft:

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

Zie de concrete credit‑cijfers op de pagina Pricing. Een call POST /v1/reports/generate met report_type: "natal" kost precies evenveel als de directe POST /v1/reports/natal.

De nieuwe whitelabel: BrandingObject inline‑mode (gelanceerd 2026-05-19) werkt via een generic dispatcher zonder wijzigingen:

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"
    }
  }'

Één dispatch + één inline whitelabel = een volledige white‑label integratie met een minimaal SDK surface.

GenerateReport - een afzonderlijk component in /v1/openapi.json. Het gebruikt oneOf met een report_type discriminator, wat correcte codegen oplevert in Python (Pydantic) en PHP (typed unions via psalm/phpstan‑style hints).

De volgende codegen‑release van de SDK zal de methode client.reports.generate() toevoegen in alle drie de pakketten (TS / Python / PHP). Tot die tijd kun je het aanroepen via een generic HTTP‑client in je SDK – de payload is gedocumenteerd in OpenAPI.

Er is geen aparte migratie‑urgentie – direct‑endpoints zijn niet deprecated. Het is puur een DX‑verbetering voor wie de 12‑methoden surface hinderlijk vindt.