Reports V2: satu endpoint alih-alih dua belas - `/v1/reports/generate`

12 tipe laporan PDF - natal, transit-yearly, synastry, business, career, love, money, child, lal-kitab, human-design, tarot, vedic-kundli - sampai baru-baru ini hidup sebagai 12 route terpisah. Setiap memiliki skema sendiri, chart-payload sendiri, tier harga sendiri. Ini memang sesuai dengan kanon REST, tapi menciptakan masalah DX pada dua level:

1. SDK surface. Klien TypeScript membawa 12 metode client.reports.natal(), client.reports.synastry(), … Setiap tipe laporan baru = breaking change pada public API SDK (versi minor dengan metode baru).
2. MCP-katalog. Server MCP yang di-host mengekspose 686 alat: setiap dari 12 laporan mengambil entri tool terpisah. Agen AI yang berjalan melalui MCP harus memindai 12 deskripsi tool untuk memilih yang tepat. Ini menimbulkan kebisingan dalam pemilihan tool.

Endpoint baru POST /v1/reports/generate - satu dispatcher dengan 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 nilai valid report_type: natal, transit-yearly, synastry, business, career, love, money, child, lal-kitab, human-design, tarot, vedic-kundli.

Berbagai tipe membutuhkan bidang payload yang berbeda. Dispatcher melakukan validasi di handler dan mengembalikan 400 yang ter-typed:

Jadi report_type mengatur tidak hanya route render, tetapi juga aturan validasi pada body permintaan.

Kompatibilitas mundur penuh: semua 12 endpoint tipe-spesifik tetap hidup. /v1/reports/generate baru - additive surface, bukan pengganti. Ini berarti kode yang ada tidak akan rusak, tetapi kode baru dapat ditulis lebih ringkas:

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

Mana yang lebih baik - tergantung pada use-case. Metode Direct memberikan type narrowing yang lebih baik (kompiler TS tahu bahwa client.reports.synastry.create() membutuhkan chart1 + chart2). Generic-dispatcher memberikan surface area yang lebih kecil untuk use-case dinamis - misalnya, ketika pengguna memilih tipe laporan melalui dropdown UI dan kamu tidak ingin switch 12 kali di kode klien.

Di server MCP yang di-host (mcp.astroway.info) ada 12 tool terpisah, masing-masing dengan deskripsi parameter lengkap. Setelah menambahkan generate kami tidak menghapus yang lama (kompatibilitas mundur) - tetapi tool baru astroway_reports_generate memiliki satu deskripsi dengan 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

Agen AI saat menerima tugas “generate laporan natal untuk tanggal X” mendapatkan satu kandidat dengan deskripsi yang jelas, alih-alih 12 kandidat dengan deskripsi yang tumpang tindih. Ini meningkatkan akurasi pemilihan tool pada level agen.

Dispatcher tidak menambahkan biaya terpisah. Setiap report_type diteruskan ke renderer internalnya masing-masing, yang memiliki tier harga sendiri:

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

Lihat angka credit spesifik di halaman Pricing. Panggilan POST /v1/reports/generate dengan report_type: "natal" biaya persis sama dengan POST /v1/reports/natal langsung.

whitelabel: BrandingObject mode inline baru (dirilis pada 2026-05-19) bekerja melalui generic dispatcher tanpa perubahan:

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

Satu dispatch + satu inline whitelabel = integrasi white-label lengkap dengan surface SDK minimal.

GenerateReport - komponen terpisah di /v1/openapi.json. Ia menggunakan oneOf dengan discriminator report_type, yang memberikan codegen yang tepat di Python (Pydantic) dan PHP (typed unions melalui petunjuk psalm/phpstan-style).

Rilis codegen SDK berikutnya akan menambahkan metode client.reports.generate() di ketiga paket (TS / Python / PHP). Sampai saat itu kamu dapat memanggil melalui generic HTTP client di SDK-mu - payload didokumentasikan di OpenAPI.

Tidak ada urgensi migrasi khusus - endpoint direct tidak deprecated. Ini hanyalah perbaikan DX bagi mereka yang terganggu oleh surface dengan 12 metode.