Reports V2: egy végpont tizenkettő helyett - `/v1/reports/generate`

12 típusú PDF-jelentés - natal, transit-yearly, synastry, business, career, love, money, child, lal-kitab, human-design, tarot, vedic-kundli - eddig 12 különálló útvonalként éltek. Mindegyiknek saját sémája, saját chart-payload-ja, saját pricing tier-je van. Ez tisztességes a REST-kanon szerint, de DX-problémát okoz két szinten:

1. SDK surface. A TypeScript kliens 12 metódust hordoz client.reports.natal(), client.reports.synastry(), … Minden új jelentéstípus = breaking change a public API SDK-ben (minor verzió új metódussal).
2. MCP-katalógus. A hosted MCP-szerver 686 eszközt exponál: a 12 jelentés mindegyike külön tool entry-t foglal el. Az AI-ügynök, amely az MCP-n keresztül jár, le kell, hogy szkennelje a 12 tool leírást, hogy a megfelelőt válassza. Ez zaj a tool selection-ben.

Az új endpoint POST /v1/reports/generate - egy dispatcher a report_type enum-mal.

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 érvényes report_type érték: natal, transit-yearly, synastry, business, career, love, money, child, lal-kitab, human-design, tarot, vedic-kundli.

A különböző típusok különböző payload mezőket igényelnek. A dispatcher a handlerben validál, és egy tipizált 400-at ad vissza:

Tehát a report_type nem csak a render útvonalat irányítja, hanem a kérés testére vonatkozó validációs szabályokat is.

A visszafelé kompatibilitás teljes: az összes 12 típus-specifikus endpoint élő marad. Az új /v1/reports/generate - additív felület, nem helyettesítő. Ez azt jelenti, hogy a meglévő kód nem fog eltörni, de az új kód kompaktabban írható:

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

Mi a jobb – a use-case-től függ. A Direct-módszer jobb type narrowing-et ad (a TS-compiler tudja, hogy a client.reports.synastry.create() chart1 + chart2-t igényel). A Generic-dispatcher kisebb felületet biztosít dinamikus use-case-ekhez – például amikor a felhasználó a UI dropdownból választja ki a jelentéstípust, és nem akarsz 12-es switch-t a klienskódban.

A hosted MCP-szerveren (mcp.astroway.info) 12 különálló tool volt, mindegyik teljes paraméterleírással. A generate hozzáadása után nem töröljük a régi (visszafelé kompatibilitás) – de a új tool astroway_reports_generate egy leírást tartalmaz a report_type enum-mal:

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

Az AI-ügynök, amikor megkapja a „generálj nekem egy natal jelentést a X dátumra” feladatot, egy jelöltet kap egy nyilvánvaló descriptorral, a 12 átfedő leírású jelölt helyett. Ez javítja a tool selection pontosságát az ügynöki szinten.

A dispatcher nem ad hozzá külön költséget. Minden report_type a saját belső renderelőjére továbbítódik, amelynek saját pricing tier-je van:

• natal → TIER_7
• transit-yearly → TIER_8
• synastry, business, career, love, money, child, lal-kitab, human-design, vedic-kundli → megfelelő tier-ek
• tarot → TIER_4

A konkrét credit számokat lásd a Pricing oldalon. A POST /v1/reports/generate hívás report_type: "natal" pontosan ugyanannyit kerül, mint a közvetlen POST /v1/reports/natal.

Az új whitelabel: BrandingObject inline-mód (kiadva 2026-05-19) a generic dispatcher-en keresztül változtatás nélkül működik:

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

Egy dispatch + egy inline whitelabel = teljes körű white-label integráció minimális SDK felülettel.

GenerateReport - egy külön komponens a /v1/openapi.json-ban. oneOf-t használ a report_type diszkriminátor alapján, ami helyes codegen-t ad Pythonban (Pydantic) és PHP-ben (typed unions a psalm/phpstan-stílusú hint-ekkel).

A következő codegen kiadás az SDK-ban hozzáadja a client.reports.generate() metódust mindhárom csomagban (TS / Python / PHP). Addig hívhatod a generic HTTP kliensen keresztül a saját SDK-dban – a payload dokumentálva van az OpenAPI-ban.

Nincs külön migration sürgősség – a direct endpointok nem deprecated. Ez tisztán DX-javítás azoknak, akiket a 12-módszeres felület zavar.