Reports V2: jeden endpoint zamiast dwunastu - `/v1/reports/generate`

12 typów PDF-raportów - natal, transit-yearly, synastry, business, career, love, money, child, lal-kitab, human-design, tarot, vedic-kundli - do niedawna żyły jako 12 oddzielnych routów. Każdy ma swój schemat, swój chart-payload, swój pricing tier. To jest zgodne z REST-kanonem, ale tworzy problem DX na dwóch poziomach:

1. SDK surface. Klient TypeScript nosi 12 metod client.reports.natal(), client.reports.synastry(), … Każdy nowy typ raportu = breaking change w public API SDK (mniejsza wersja z nową metodą).
2. MCP-katalog. Hosted MCP-serwer eksponuje 686 narzędzi: każdy z 12 raportów zajmuje oddzielny wpis tool. AI-agent, który przechodzi przez MCP, musi przeskanować 12 opisów tool, aby wybrać właściwy. To szum w wyborze tool.

Nowy endpoint POST /v1/reports/generate - jeden dispatcher z enumem 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 prawidłowych wartości report_type: natal, transit-yearly, synastry, business, career, love, money, child, lal-kitab, human-design, tarot, vedic-kundli.

Różne typy wymagają różnych pól payload. Dispatcher wykonuje walidację w handlerze i zwraca typowany 400:

To znaczy, że report_type steruje nie tylko trasą renderowania, ale także regułami walidacji ciała żądania.

Pełna kompatybilność wsteczna: wszystkie 12 endpointów type-specific pozostają aktywne. Nowy /v1/reports/generate - additive surface, nie replacement. To oznacza, że istniejący kod się nie zepsuje, ale nowy kod może być pisany bardziej kompaktowo:

// Стара модель - 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 lepsze - zależy od use-case. Direct-metoda daje lepsze type narrowing (kompilator TS wie, że client.reports.synastry.create() wymaga chart1 + chart2). Generic-dispatcher daje mniejszy surface area dla dynamicznych use-case’ów - na przykład, gdy użytkownik wybiera typ raportu przez UI dropdown i nie chcesz 12-krotnego switch w kodzie klienta.

Na hostowanym MCP-serwerze (mcp.astroway.info) było 12 oddzielnych narzędzi, każde z pełnym opisem parametrów. Po dodaniu generate nie usuwamy starych (kompatybilność wsteczna) - ale nowe narzędzie astroway_reports_generate ma jeden opis z enumem 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

AI-agent przy otrzymaniu zadania „wygeneruj mi raport natalny dla daty X” otrzymuje jednego kandydata z oczywistym descriptor, zamiast 12 kandydatów z overlapping descriptions. To poprawia dokładność wyboru tool na poziomie agenta.

Dispatcher nie dodaje osobnej ceny. Każdy report_type jest forwardowany do swojego wewnętrznego renderera, który ma swój pricing tier:

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

Konkretne liczby creditów zobacz na stronie Pricing. Wywołanie POST /v1/reports/generate z report_type: "natal" kosztuje dokładnie tyle samo, co bezpośrednie POST /v1/reports/natal.

Nowy whitelabel: BrandingObject inline-mode (wydany 2026-05-19) działa przez generic dispatcher bez zmian:

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 = pełnoprawna white-label integracja z minimalnym SDK surface.

GenerateReport - oddzielny komponent w /v1/openapi.json. Używa oneOf za report_type discriminator, co daje poprawny codegen w Python (Pydantic) oraz PHP (typed unions przez psalm/phpstan-style hints).

Następny codegen-release SDK doda metodę client.reports.generate() we wszystkich trzech pakietach (TS / Python / PHP). Do tego czasu możesz wywoływać przez generic HTTP-client w swoim SDK - payload udokumentowany w OpenAPI.

Nie ma osobnej pilności migracji - direct-endpointy nie są deprecated. To czyste ulepszenie DX dla tych, którym 12-metodowa powierzchnia przeszkadza.