Reports V2: un endpoint în loc de douăsprezece - `/v1/reports/generate`

12 tipuri de rapoarte PDF - natal, transit-yearly, synastry, business, career, love, money, child, lal-kitab, human-design, tarot, vedic-kundli - până recent trăiau ca 12 rute separate. Fiecare are propria schemă, propriul chart-payload, propriul pricing tier. E corect conform canonului REST, dar creează o problemă DX la două niveluri:

1. Suprafața SDK. Clientul TypeScript are 12 metode client.reports.natal(), client.reports.synastry(), … Fiecare tip nou de raport = breaking change în public API SDK (versiune minoră cu metodă nouă).
2. Catalog MCP. Serverul MCP găzduit expune 686 instrumente: fiecare dintre cele 12 rapoarte ocupă o intrare de tool separată. Agentul AI, care interacționează prin MCP, trebuie să scaneze 12 descrieri de tool-uri pentru a alege pe cel corect. E zgomot în selecția de tool-uri.

Noul endpoint POST /v1/reports/generate - un singur dispatcher cu enum-ul 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 valori valide pentru report_type: natal, transit-yearly, synastry, business, career, love, money, child, lal-kitab, human-design, tarot, vedic-kundli.

Tipuri diferite necesită câmpuri payload diferite. Dispatcher efectuează validarea în handler și returnează un 400 tipizat:

Adică report_type controlează nu doar ruta de render, ci și regulile de validare pentru corpul cererii.

Compatibilitatea inversă este completă: toate cele 12 endpoint-uri type-specific rămân active. Noul /v1/reports/generate - suprafață aditivă, nu un înlocuitor. Asta înseamnă că codul existent nu se va rupe, dar codul nou poate fi scris mai compact:

// Old model - 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 e mai bine - depinde de use-case. Metoda Direct oferă un type narrowing mai bun (compilatorul TS știe că client.reports.synastry.create() necesită chart1 + chart2). Generic-dispatcher oferă o suprafață mai mică pentru use-case-uri dinamice - de exemplu, când utilizatorul alege tipul raportului printr-un dropdown UI și nu vrei un switch de 12 de ramuri în codul clientului.

Pe serverul MCP găzduit (mcp.astroway.info) erau 12 tool-uri separate, fiecare cu o descriere completă a parametrilor. După adăugarea generate noi nu ștergem pe cele vechi (compatibilitate inversă) - dar noul tool astroway_reports_generate are o singură descriere cu enum-ul 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

Agentul AI, la primirea sarcinii “generează-mi raportul natal pentru data X”, primește un singur candidat cu un descriptor evident, în loc de 12 candidați cu descrieri suprapuse. Asta îmbunătățește acuratețea selecției de tool-uri la nivel de agent.

Dispatcher nu adaugă costuri separate. Fiecare report_type este redirecționat către propriul său renderer intern, care are propriul său pricing tier:

• natal → TIER_7
• transit-yearly → TIER_8
• synastry, business, career, love, money, child, lal-kitab, human-design, vedic-kundli → tier-urile corespunzătoare
• tarot → TIER_4

Vezi numerele concrete de credite pe pagina Prețuri. Apelul POST /v1/reports/generate cu report_type: "natal" costă exact la fel ca POST /v1/reports/natal direct.

Noul whitelabel: BrandingObject inline-mod (lansat 2026-05-19) funcționează prin generic dispatcher fără modificări:

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 inline whitelabel = integrare white-label completă cu suprafață SDK minimă.

GenerateReport - componentă separată în /v1/openapi.json. Folosește oneOf cu discriminator report_type, ceea ce oferă codegen corect în Python (Pydantic) și PHP (typed unions prin indicii de tip psalm/phpstan).

Următorul release de codegen al SDK-ului va adăuga metoda client.reports.generate() în toate cele trei pachete (TS / Python / PHP). Până atunci poți apela printr-un client HTTP generic în SDK-ul tău - payload-ul este documentat în OpenAPI.

Nu există o urgență de migrare separată - endpoint-urile direct nu sunt deprecated. E pur și simplu o îmbunătățire DX pentru cei cărora suprafața cu 12 metode îi deranjează.