Reports V2: tek endpoint on iki yerine - `/v1/reports/generate`

12 PDF rapor türü - natal, transit-yearly, synastry, business, career, love, money, child, lal-kitab, human-design, tarot, vedic-kundli - yakın zamana kadar 12 ayrı rota olarak mevcuttu. Her birinin kendi şeması, kendi chart-payload’u ve kendi pricing tier’ı vardı. Bu, REST kanonuna göre adil olsa da, iki düzeyde bir DX (Developer Experience) sorunu yaratıyor:

1. SDK yüzeyi. TypeScript istemcisi client.reports.natal(), client.reports.synastry(), … gibi 12 yöntem taşır. Her yeni rapor türü = SDK’nın public API’sinde bir breaking change (yeni bir yöntemle minör sürüm).
2. MCP kataloğu. Hosted MCP sunucusu 686 araç sunar: 12 raporun her biri ayrı bir tool entry kaplar. MCP üzerinden çalışan bir AI ajanı, doğru olanı seçmek için 12 tool description’ı taramak zorundadır. Bu, tool selection’da bir gürültü yaratır.

Yeni POST /v1/reports/generate endpoint’i, report_type enum’ına sahip tek bir dispatcher’dır.

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

report_type için 12 geçerli değer: natal, transit-yearly, synastry, business, career, love, money, child, lal-kitab, human-design, tarot, vedic-kundli.

Farklı türler farklı payload alanları gerektirir. Dispatcher, handler’da doğrulama yapar ve tipize edilmiş bir 400 döndürür:

Yani report_type sadece render rotasını değil, aynı zamanda istek gövdesindeki doğrulama kurallarını da yönetir.

Geriye dönük uyumluluk tamdır: 12 türe özgü endpoint’in tamamı aktif kalır. Yeni /v1/reports/generate ek bir yüzeydir, bir değiştirme değildir. Bu, mevcut kodun bozulmayacağı, ancak yeni kodun daha kompakt yazılabileceği anlamına gelir:

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

Hangisinin daha iyi olduğu use-case’e bağlıdır. Direct yöntem daha iyi type narrowing sağlar (TS derleyicisi client.reports.synastry.create()’ın chart1 + chart2 gerektirdiğini bilir). Generic-dispatcher, dinamik use-case’ler için daha küçük bir yüzey alanı sunar - örneğin, kullanıcı bir UI açılır menüsünden rapor türünü seçtiğinde ve istemci kodunda 12 kez switch yapmak istemediğinizde.

Hosted MCP sunucusunda (mcp.astroway.info), her biri parametrelerin tam açıklamasına sahip 12 ayrı tool vardı. generate eklendikten sonra eskileri silmiyoruz (geri uyumluluk) - ancak yeni astroway_reports_generate tool’u report_type enum’ı ile tek bir açıklamaya sahiptir:

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

Bir AI ajanı, “X tarihi için bana bir natal raporu oluştur” görevini aldığında, çakışan açıklamalara sahip 12 aday yerine, açık bir descriptor’a sahip tek bir aday alır. Bu, ajan düzeyinde tool selection accuracy’yi artırır.

Dispatcher ek bir maliyet eklemez. Her report_type, kendi pricing tier’ına sahip dahili render’ına yönlendirilir:

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

Belirli credit sayıları için Pricing sayfasına bak. report_type: "natal" ile POST /v1/reports/generate çağrısı, doğrudan POST /v1/reports/natal çağrısı ile aynı maliyete sahiptir.

Yeni whitelabel: BrandingObject inline modu (2026-05-19 tarihinde yayınlandı) generic dispatcher aracılığıyla değişmeden çalışır:

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

Tek bir dispatch + tek bir inline whitelabel = minimum SDK yüzeyi ile tam teşekküllü bir white-label entegrasyonu.

GenerateReport, /v1/openapi.json içinde ayrı bir bileşendir. report_type discriminator’ı üzerinden oneOf kullanır, bu da Python (Pydantic) ve PHP’de (psalm/phpstan tarzı ipuçları aracılığıyla typed union’lar) doğru codegen sağlar.

SDK’nın bir sonraki codegen sürümü, client.reports.generate() yöntemini her üç pakete (TS / Python / PHP) ekleyecektir. O zamana kadar, SDK’nızdaki generic HTTP istemcisi aracılığıyla çağrı yapabilirsiniz - payload OpenAPI’de belgelenmiştir.

Ayrı bir migration aciliyeti yoktur - direct endpoint’ler deprecated değildir. Bu, 12 yöntemli yüzeyin kendilerine engel olduğunu düşünenler için tamamen bir DX iyileştirmesidir.