Reports V2: ένα endpoint αντί για δώδεκα - `/v1/reports/generate`

12 τύποι PDF-αναφορών - natal, transit-yearly, synastry, business, career, love, money, child, lal-kitab, human-design, tarot, vedic-kundli - μέχρι πρόσφατα ζούσαν ως 12 ξεχωριστές διαδρομές. Κάθε ένας έχει το δικό του σχήμα, το δικό του chart-payload, το δικό του pricing tier. Αυτό είναι σύμφωνο με το REST‑κανόνα, αλλά δημιουργεί πρόβλημα DX σε δύο επίπεδα:

1. SDK surface. Ο πελάτης TypeScript φέρει 12 μεθόδους client.reports.natal(), client.reports.synastry(), … Κάθε νέος τύπος αναφοράς = breaking change στο public API SDK (μικρή έκδοση με νέα μέθοδο).
2. MCP‑κατάλογος. Ο hosted MCP‑server εκθέτει 686 εργαλεία: κάθε μία από τις 12 αναφορές καταλαμβάνει ξεχωριστή καταχώρηση εργαλείου. Ο AI‑agent που περνάει από το MCP πρέπει να σαρώσει 12 περιγραφές εργαλείων για να επιλέξει το σωστό. Αυτό είναι θόρυβος στην επιλογή εργαλείου.

Το νέο endpoint POST /v1/reports/generate - ένας dispatcher με 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 έγκυρες τιμές report_type: natal, transit-yearly, synastry, business, career, love, money, child, lal-kitab, human-design, tarot, vedic-kundli.

Διαφορετικοί τύποι απαιτούν διαφορετικά πεδία payload. Ο dispatcher κάνει επικύρωση στον handler και επιστρέφει τυποποιημένο 400:

Δηλαδή το report_type ελέγχει όχι μόνο τη διαδρομή render, αλλά και τους κανόνες επικύρωσης για το σώμα του αιτήματος.

Η πλήρης αντίστροφη συμβατότητα: όλα τα 12 type‑specific endpoints παραμένουν ενεργά. Το νέο /v1/reports/generate - προσθετική επιφάνεια, όχι αντικατάσταση. Αυτό σημαίνει ότι ο υπάρχων κώδικας δεν θα σπάσει, αλλά ο νέος κώδικας μπορεί να γραφτεί πιο συμπαγής:

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

Τι είναι καλύτερο - εξαρτάται από το use‑case. Η Direct‑μέθοδος δίνει καλύτερο type narrowing (ο TS‑compiler ξέρει ότι το client.reports.synastry.create() απαιτεί chart1 + chart2). Ο Generic‑dispatcher προσφέρει μικρότερη επιφάνεια για δυναμικά use‑case - π.χ. όταν ο χρήστης επιλέγει τύπο αναφοράς μέσω UI dropdown και δεν θέλεις ένα 12‑πλανά switch στον κώδικα του πελάτη.

Στον hosted MCP‑server (mcp.astroway.info) υπήρχαν 12 ξεχωριστά εργαλεία, το καθένα με πλήρη περιγραφή παραμέτρων. Μετά την προσθήκη του generate δεν διαγράφουμε τα παλιά (αντίστροφη συμβατότητα) - αλλά το νέο εργαλείο astroway_reports_generate έχει μία περιγραφή με 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

Ο AI‑agent όταν λαμβάνει το έργο «δημιούργησε μου μια natal αναφορά για την ημερομηνία X» λαμβάνει έναν υποψήφιο με προφανή descriptor, αντί για 12 υποψηφίους με overlapping περιγραφές. Αυτό βελτιώνει την ακρίβεια επιλογής εργαλείου σε επίπεδο agent.

Ο dispatcher δεν προσθέτει ξεχωριστό κόστος. Κάθε report_type προωθείται στον εσωτερικό renderer του, ο οποίος έχει το δικό του pricing tier:

• natal → TIER_7
• transit-yearly → TIER_8
• synastry, business, career, love, money, child, lal-kitab, human-design, vedic-kundli → αντίστοιχοι tiers
• tarot → TIER_4

Δες τους συγκεκριμένους αριθμούς credit στη σελίδα Pricing. Η κλήση POST /v1/reports/generate με report_type: "natal" κοστίζει ακριβώς όσο το άμεσο POST /v1/reports/natal.

Το νέο whitelabel: BrandingObject inline‑mode (κυκλοφόρησε 2026-05-19) λειτουργεί μέσω generic dispatcher χωρίς αλλαγές:

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

Ένα dispatch + ένα inline whitelabel = πλήρης white‑label ενσωμάτωση με ελάχιστη επιφάνεια SDK.

GenerateReport - ξεχωριστό component στο /v1/openapi.json. Χρησιμοποιεί oneOf με discriminator report_type, που παρέχει σωστό codegen σε Python (Pydantic) και PHP (typed unions μέσω psalm/phpstan‑style hints).

Η επόμενη έκδοση codegen του SDK θα προσθέσει τη μέθοδο client.reports.generate() σε όλα τα τρία πακέτα (TS / Python / PHP). Μέχρι τότε μπορείτε να καλέσετε μέσω generic HTTP‑client στο SDK σας - το payload τεκμηριώνεται στο OpenAPI.