Reports V2: 12個のendpointの代わりに1つ - `/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の問題を2つのレベルで引き起こす：

1. SDK surface. TypeScriptクライアントは12個のメソッド client.reports.natal(), client.reports.synastry(), … を持つ。新しいレポートタイプが追加されるたびに public API SDK に breaking change が発生する（新しいメソッドでマイナーバージョンが上がる）。
2. MCPカタログ。 ホストされたMCPサーバーは686個のツールを公開している：12個のレポートそれぞれが別々の tool エントリを占める。MCPを通るAIエージェントは正しいものを選ぶために12件の tool 説明をスキャンしなければならない。これは tool selection のノイズになる。

新しいエンドポイント POST /v1/reports/generate は 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 フィールドを必要とする。ディスパッチャーはハンドラ内でバリデーションを行い、型付けされた 400 を返す：

つまり report_type はレンダリングルートだけでなく、リクエストボディのバリデーションルールも制御する。

後方互換性は完全です：12の type-specific エンドポイントは そのまま残ります。新しい /v1/reports/generate は additive なサーフェスで、置き換えではありません。つまり既存コードは壊れず、新しいコードはよりコンパクトに書けます：

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

どちらが良いかはユースケース次第です。Direct メソッドは優れた type narrowing を提供します（TS コンパイラは client.reports.synastry.create() が chart1 と chart2 を必要とすることを認識します）。Generic ディスパッチャーは動的ユースケース向けにサーフェスエリアを小さくします - 例えば、ユーザーが UI のドロップダウンでレポートタイプを選択し、クライアントコードで12個の switch を書きたくない場合です。

ホストされた MCP サーバー（mcp.astroway.info）には12個の個別ツールがあり、各々がパラメータの完全な説明を持っていました。generate を追加した後、古いものは 削除せず（後方互換性） - しかし 新しい tool 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 を持つ1つの候補 を取得し、重複した説明を持つ12の候補ではなくなります。これによりエージェントレベルでの tool selection 精度が向上します。

ディスパッチャーは 追加料金を課さず。各 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

具体的なクレジット数はページ Pricing を参照してください。report_type: "natal" の POST /v1/reports/generate 呼び出しは、直接の POST /v1/reports/natal と同じ料金です。

新しい whitelabel: BrandingObject インラインモード（2026-05-19 にリリース）は、generic ディスパッチャーを通じて変更なしで動作します：

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

1つのディスパッチ + 1つのインライン whitelabel = 最小限の SDK サーフェスでフルホワイトラベル統合が実現します。

GenerateReport は /v1/openapi.json の個別コンポーネントです。report_type ディスクリミネータによる oneOf を使用し、Python（Pydantic）や PHP（psalm/phpstan スタイルのヒントによる typed unions）で正確な codegen が得られます。

次の codegen リリースで SDK は 3 つのパッケージ（TS / Python / PHP）すべてに client.reports.generate() メソッドを追加します。それまでの間は、SDK の generic HTTP クライアントを通じて呼び出すことができ、payload は OpenAPI に記載されています。

特別な migration の緊急性はありません - direct エンドポイントは非推奨ではありません。これは 12 メソッドのサーフェスが邪魔だと感じる人向けの純粋な DX 改善です。