Reports V2: बारह के बजाय एक एंडपॉइंट - `/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(), … होते हैं। हर नया रिपोर्ट‑टाइप = public API SDK में breaking change (नए मेथड के साथ माइनर वर्ज़न)।
2. MCP‑catalog. Hosted MCP‑सर्वर 686 टूल्स एक्सपोज़ करता है: 12 रिपोर्ट्स में से हर एक एक अलग tool entry लेती है। AI‑एजेंट, जो MCP के माध्यम से चलता है, को सही टूल चुनने के लिए 12 tool descriptions स्कैन करनी पड़ती हैं। यह tool selection में शोर पैदा करता है।

नया endpoint POST /v1/reports/generate - report_type enum वाला एक 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": "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 endpoint जिंदा रहते हैं। नया /v1/reports/generate - additive surface, replacement नहीं है। इसका मतलब है कि मौजूदा कोड नहीं टूटेगा, लेकिन नया कोड अधिक कॉम्पैक्ट लिखा जा सकता है:

// Стара модель - 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‑कम्पाइलर जानता है कि client.reports.synastry.create() को chart1 + chart2 चाहिए)। Generic‑dispatcher डायनामिक use‑case के लिए छोटा surface area देता है - जैसे जब यूज़र UI dropdown से रिपोर्ट टाइप चुनता है और तुम क्लाइंट कोड में 12‑बार switch नहीं रखना चाहते।

Hosted MCP‑सर्वर (mcp.astroway.info) पर 12 अलग‑अलग टूल्स थे, हर एक के पास पैरामीटर का पूरा विवरण था। generate जोड़ने के बाद हम पुराने नहीं हटाते (बैकवर्ड कंपैटिबिलिटी) - लेकिन नया टूल astroway_reports_generate के पास report_type enum वाला एक ही विवरण है:

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‑एजेंट को जब टास्क मिलता है “मुझे डेट X के लिए natal रिपोर्ट जेनरेट करो” तो उसे एक ही कैंडिडेट मिलता है स्पष्ट descriptor के साथ, 12 कैंडिडेट्स के overlapping descriptions की जगह। यह एजेंट लेवल पर tool selection की सटीकता को बेहतर बनाता है।

Dispatcher अलग कीमत नहीं जोड़ता। हर report_type अपने अंदरूनी रेंडरर पर फॉरवर्ड होता है, जिसका अपना pricing tier है:

• natal → TIER_7
• transit-yearly → TIER_8
• synastry, business, career, love, money, child, lal-kitab, human-design, vedic-kundli → संबंधित टियर्स
• tarot → TIER_4

विशिष्ट credit‑संख्याएँ देखो पेज पर मूल्य निर्धारण. कॉल 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 surface के साथ।

GenerateReport - एक अलग कंपोनेंट है /v1/openapi.json में। यह report_type discriminator के आधार पर oneOf का उपयोग करता है, जो Python (Pydantic) और PHP (typed unions psalm/phpstan‑style hints के माध्यम से) में सही codegen देता है।

अगला codegen‑रिलीज़ SDK में client.reports.generate() मेथड सभी तीन पैकेजों (TS / Python / PHP) में जोड़ देगा। तब तक तुम generic HTTP‑क्लाइंट से अपने SDK में कॉल कर सकते हो - payload OpenAPI में डॉक्यूमेंटेड है।

कोई अलग migration‑इमरजेंसी नहीं है - direct‑endpoint डिप्रिकेट नहीं हुए। यह सिर्फ DX‑बेहतरता है उन लोगों के लिए जिन्हें 12‑मेथड वाली सतह परेशान करती है।