Reports V2: un endpoint invece di dodici - `/v1/reports/generate`

12 tipi di PDF-report - natal, transit-yearly, synastry, business, career, love, money, child, lal-kitab, human-design, tarot, vedic-kundli - fino a poco tempo fa vivevano come 12 route separate. Ognuno ha il suo schema, il suo chart-payload, il suo pricing tier. È corretto secondo il canone REST, ma crea un problema di DX su due livelli:

1. SDK surface. Il client TypeScript espone 12 metodi client.reports.natal(), client.reports.synastry(), … Ogni nuovo tipo di report = breaking change nella public API SDK (versione minore con nuovo metodo).
2. MCP-каталог. Il server MCP hosted espone 686 strumenti: ognuno dei 12 report occupa una voce tool separata. L’agente AI, che attraversa MCP, deve scansionare 12 descrizioni tool per scegliere quella corretta. È rumore nella tool selection.

Il nuovo endpoint POST /v1/reports/generate - un unico dispatcher con 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 valori validi report_type: natal, transit-yearly, synastry, business, career, love, money, child, lal-kitab, human-design, tarot, vedic-kundli.

Tipi diversi richiedono campi payload diversi. Il dispatcher esegue la validazione nell’handler e restituisce un 400 tipizzato:

Quindi report_type controlla non solo il percorso di render, ma anche le regole di validazione per il corpo della richiesta.

Compatibilità retroattiva completa: tutti i 12 endpoint type-specific rimangono attivi. Il nuovo /v1/reports/generate è una surface additiva, non un replacement. Questo significa che il codice esistente non si romperà, ma il nuovo codice può essere scritto in modo più compatto:

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

Qual è meglio dipende dal caso d’uso. Il metodo Direct fornisce un migliore type narrowing (il compilatore TS sa che client.reports.synastry.create() richiede chart1 + chart2). Il generic-dispatcher offre una surface area più piccola per i casi d’uso dinamici - ad esempio, quando l’utente sceglie il tipo di report tramite un dropdown UI e non vuoi uno switch a 12 vie nel codice client.

Sul server MCP hosted (mcp.astroway.info) c’erano 12 tool separati, ognuno con una descrizione completa dei parametri. Dopo aver aggiunto generate noi non rimuoviamo i vecchi (compatibilità retroattiva) - ma il nuovo tool astroway_reports_generate ha una singola descrizione con 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

L’agente AI, quando riceve il compito “genera un report natale per la data X”, ottiene un solo candidato con un descriptor evidente, invece di 12 candidati con descrizioni sovrapposte. Questo migliora la precisione della tool selection a livello di agente.

Il dispatcher non aggiunge costi separati. Ogni report_type viene inoltrato al proprio renderer interno, che ha il proprio pricing tier:

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

I numeri specifici di credit li trovi nella pagina Pricing. La chiamata POST /v1/reports/generate con report_type: "natal" costa esattamente lo stesso di POST /v1/reports/natal diretto.

Il nuovo whitelabel: BrandingObject modalità inline (rilasciato 2026-05-19) funziona tramite generic dispatcher senza modifiche:

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 = integrazione white-label completa con una surface SDK minima.

GenerateReport - componente separato in /v1/openapi.json. Usa oneOf con discriminatore report_type, fornendo un codegen corretto in Python (Pydantic) e PHP (typed unions tramite hint in stile psalm/phpstan).

Il prossimo rilascio codegen dell’SDK aggiungerà il metodo client.reports.generate() in tutti e tre i pacchetti (TS / Python / PHP). Fino ad allora puoi chiamare tramite un client HTTP generic nel tuo SDK - il payload è documentato in OpenAPI.