Reports V2: jeden endpoint místo dvanácti - `/v1/reports/generate`

12 typů PDF‑reportů - natal, transit-yearly, synastry, business, career, love, money, child, lal-kitab, human-design, tarot, vedic-kundli - doposud žily jako 12 samostatných routů. Každý má svůj schéma, svůj chart-payload, svůj pricing tier. To je podle REST‑kanónu v pořádku, ale vytváří DX‑problém na dvou úrovních:

1. SDK surface. TypeScript‑klient nese 12 metod client.reports.natal(), client.reports.synastry(), … Každý nový typ reportu = breaking change v public API SDK (menší verze s novou metodou).
2. MCP‑katalog. Hosted MCP‑server exponuje 686 nástrojů: každý z 12 reportů zabírá samostatný tool entry. AI‑agent, který prochází MCP, musí prozkoumat 12 tool descriptions, aby vybral ten správný. To je šum v tool selection.

Nový endpoint POST /v1/reports/generate – jeden dispatcher s 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 platných hodnot report_type: natal, transit-yearly, synastry, business, career, love, money, child, lal-kitab, human-design, tarot, vedic-kundli.

Různé typy vyžadují různá payload‑pole. Dispatcher provádí validaci v handleru a vrací typizovaný 400:

Takže report_type řídí nejen render‑route, ale i validační pravidla pro tělo požadavku.

Zpětná kompatibilita je úplná: všechny 12 type‑specific endpointy zůstávají živé. Nový /v1/reports/generate – additive surface, ne replacement. To znamená, že existující kód se nezlomí, ale nový kód může být psán kompaktněji:

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

Co je lepší – závisí na use‑case. Direct‑metoda dává lepší type narrowing (TS‑kompilátor ví, že client.reports.synastry.create() vyžaduje chart1 + chart2). Generic‑dispatcher poskytuje menší surface area pro dynamické use‑case’y – například když uživatel vybírá typ reportu přes UI dropdown a nechceš 12‑násobný switch v klientském kódu.

Na hosted MCP‑serveru (mcp.astroway.info) bylo 12 samostatných tools, každý s úplným popisem parametrů. Po přidání generate neodstraňujeme staré (zpětná kompatibilita) – ale nový tool astroway_reports_generate má jeden popis s 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

AI‑agent při získání úkolu „vygeneruj mi natal report pro datum X“ získá jednoho kandidáta s jasným descriptor, místo 12 kandidátů s překrývajícími se popisy. To zlepšuje tool selection accuracy na úrovni agenta.

Dispatcher nepřidává samostatnou cenu. Každý report_type je forwardován na svého interního renderera, který má svůj pricing tier:

• natal → TIER_7
• transit-yearly → TIER_8
• synastry, business, career, love, money, child, lal-kitab, human-design, vedic-kundli → odpovídající tiery
• tarot → TIER_4

Konkrétní credit‑čísla najdeš na stránce Cenová nabídka. Volání POST /v1/reports/generate s report_type: "natal" stojí přesně stejně jako přímé POST /v1/reports/natal.

Nový whitelabel: BrandingObject inline‑režim (vydaný 2026-05-19) funguje přes generic dispatcher bez změn:

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

Jeden dispatch + jeden inline whitelabel = plnohodnotná white‑label integrace s minimálním SDK surface.

GenerateReport – samostatná komponenta v /v1/openapi.json. Používá oneOf s report_type discriminator, což poskytuje korektní codegen v Python (Pydantic) a PHP (typed unions přes psalm/phpstan‑style hints).

Příští codegen‑release SDK přidá metodu client.reports.generate() ve všech třech balíčcích (TS / Python / PHP). Do té doby můžeš volat přes generic HTTP‑klient ve svém SDK – payload je dokumentován v OpenAPI.

Samostatná migrační urgentnost neexistuje – direct‑endpointy nejsou deprecated. Je to čistě DX‑vylepšení pro ty, kterým 12‑metodová surface vadí.