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 الخاص به، وtier التسعير الخاص به. هذا يتوافق مع معايير REST، ولكنه ي creates مشكلة DX على مستويين:

1. سطح SDK. عميل TypeScript يحتوي على 12 طريقة client.reports.natal(), client.reports.synastry(), … كل نوع جديد من التقارير = تغيير breaking في public API SDK (إصدار أصغر مع طريقة جديدة).
2. دليل MCP. خادم المضيف MCP يعرض 686 أداة: كل واحد من 12 report يأخذ entry منفصل. AI-agent الذي يتصفح عبر MCP يجب أن يفحص 12 وصف أداة لاختيار الصحيح. هذا ضجيج في اختيار الأداة.

النقطة النهائية الجديدة POST /v1/reports/generate - dispatcher واحد مع report_type enum.

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 لا يتحكم فقط في route العرض، بل في قواعد التحقق من جسم الطلب أيضاً.

التوافق الكامل مع الإصدارات السابقة: كل 12 endpoint محدد النوع يبقى حياً. /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. الطريقة المباشرة تعطي type narrowing أفضل (مترجم TS يعرف أن client.reports.synastry.create() يتطلب chart1 + chart2). Generic-dispatcher يعطي مساحة سطح أصغر لل use-cases الديناميكية - على سبيل المثال، عندما يختار المستخدم نوع التقرير من خلال UI dropdown ولا تريد 12 switch في الكود العميل.

على خادم المضيف 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-agent على المهمة “أنشئ لي natal report للتاريخ X” فإنه يحصل على مرشح واحد مع descriptor واضح، بدلاً من 12 مرشح مع أوصاف متداخلة. هذا يحسن دقة اختيار الأداة على مستوى الوكيل.

Dispatcher لا يضيف تكلفة منفصلة. كل report_type يُوجَّه إلى renderer داخلي الخاص به والذي لديه tier التسعير الخاص به:

• natal → TIER_7
• transit-yearly → TIER_8
• synastry, business, career, love, money, child, lal-kitab, human-design, vedic-kundli → tiers متناظرة
• tarot → TIER_4

للحصول على أرقام الcredits المحددة، انظر صفحة Pricing. استدعاء POST /v1/reports/generate مع report_type: "natal" يكلف بالضبط نفس الشيء مثل POST /v1/reports/natal المباشر.

وضع whitelabel: BrandingObject الجديد (تم إطلاقه في 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 واحد + whitelabel inline واحد = تكامل white-label كامل مع مساحة SDK دنيا.

GenerateReport - مكون منفصل في /v1/openapi.json. يستخدم oneOf حسب report_type discriminator، مما يعطي codegen صحيح في Python (Pydantic) و PHP (typed unions عبر psalm/phpstan-style hints).

الإصدار التالي من codegen SDK سيضيف طريقة client.reports.generate() في الحزم الثلاث (TS / Python / PHP). حتى ذلك الوقت، يمكنك استدعاؤه عبر generic HTTP-client في SDK الخاص بك - payload موثق في OpenAPI.

لا يوجد إلحاح للmigration - direct-endpoints غير deprecated. هذا تحسين DX فقط لمن كانت مساحة الـ 12 طريقة عائقاً.