Reports V2: um endpoint em vez de doze - `/v1/reports/generate`

12 tipos de relatórios PDF - natal, transit-yearly, synastry, business, career, love, money, child, lal-kitab, human-design, tarot, vedic-kundli - até recentemente viviam como 12 rotas separadas. Cada um tem o seu esquema, o seu chart-payload, o seu pricing tier. Isto está de acordo com o canon REST, mas cria um problema de DX em dois níveis:

1. SDK surface. O cliente TypeScript tem 12 métodos client.reports.natal(), client.reports.synastry(), … Cada novo tipo de relatório = breaking change na public API SDK (versão menor com novo método).
2. MCP-каталог. O servidor MCP hospedado expõe 686 ferramentas: cada um dos 12 reports ocupa uma entrada de tool separada. O agente de IA que navega pelo MCP tem de analisar 12 descrições de tool para escolher a correta. Isto gera ruído na tool selection.

Novo endpoint POST /v1/reports/generate - um dispatcher com enum 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 valores válidos de report_type: natal, transit-yearly, synastry, business, career, love, money, child, lal-kitab, human-design, tarot, vedic-kundli.

Tipos diferentes requerem campos de payload diferentes. O dispatcher faz a validação no handler e devolve um 400 tipificado:

Ou seja, report_type controla não só a rota de render, mas também as regras de validação do corpo da requisição.

Compatibilidade retroativa completa: todos os 12 endpoints type-specific continuam ativos. O novo /v1/reports/generate - superfície aditiva, não substituição. Isto significa que o código existente não quebrará, mas o novo código pode ser escrito de forma mais compacta:

// 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" });

O que é melhor depende do use-case. O método Direct fornece um type narrowing melhor (o compilador TS sabe que client.reports.synastry.create() requer chart1 + chart2). O generic-dispatcher oferece uma superfície menor para use-cases dinâmicos - por exemplo, quando tu escolhes o tipo de relatório através de um dropdown UI e tu não queres um switch de 12 casos no código cliente.

No servidor MCP hospedado (mcp.astroway.info) havia 12 tools separados, cada um com a descrição completa dos parâmetros. Após a adição de generate nós não removemos os antigos (compatibilidade retroativa) - mas o novo tool astroway_reports_generate tem uma única descrição com enum 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

O agente de IA ao receber a tarefa “gera-me um relatório natal para a data X” recebe um candidato com descriptor óbvio, em vez de 12 candidatos com descrições sobrepostas. Isto melhora a precisão da tool selection ao nível do agente.

O dispatcher não adiciona custo separado. Cada report_type é encaminhado para o seu renderizador interno, que tem o seu pricing tier:

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

Vê os números de credit específicos na página Preços. A chamada POST /v1/reports/generate com report_type: "natal" custa exatamente o mesmo que o POST /v1/reports/natal direto.

O novo whitelabel: BrandingObject modo inline (lançado em 2026-05-19) funciona através de generic dispatcher sem alterações:

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

Um dispatch + um inline whitelabel = integração white-label completa com superfície SDK mínima.

GenerateReport - componente separado em /v1/openapi.json. Ele usa oneOf com discriminador report_type, o que fornece codegen correto em Python (Pydantic) e PHP (typed unions via psalm/phpstan-style hints).

O próximo release de codegen do SDK adicionará o método client.reports.generate() em todos os três pacotes (TS / Python / PHP). Até lá, podes chamar através de um cliente HTTP genérico no teu SDK - o payload está documentado no OpenAPI.