Reports V2: 12개 대신 하나의 엔드포인트 - `/v1/reports/generate`

12 종류의 PDF 보고서 - natal, transit-yearly, synastry, business, career, love, money, child, lal-kitab, human-design, tarot, vedic-kundli - 최근까지 12개의 개별 경로로 존재했습니다. 각각은 자체 스키마, chart-payload, 가격 티어를 가지고 있습니다. 이는 REST 원칙에 따르는 것이지만, 두 가지 수준에서 DX 문제를 야기합니다:

1. SDK surface. TypeScript 클라이언트는 12개의 메서드 client.reports.natal(), client.reports.synastry(), …를 가집니다. 새로운 보고서 유형마다 public API SDK에서 breaking change(마이너 버전에 새 메서드 추가)가 발생합니다.
2. MCP catalog. 호스팅된 MCP 서버는 686개의 도구를 노출합니다: 12개 보고서 각각이 별개의 도구 항목을 차지합니다. MCP를 통해 통신하는 AI 에이전트는 올바른 도구를 선택하기 위해 12개의 도구 설명을 스캔해야 합니다. 이는 도구 선택 시 노이즈입니다.

새로운 엔드포인트 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 필드가 필요합니다. 디스패처는 handler에서 검증을 수행하고 타입화된 400을 반환합니다:

즉 report_type는 렌더링 경로뿐만 아니라 요청 본문의 검증 규칙도 제어합니다.

완전한 하위 호환성: 모든 12개의 유형별 엔드포인트는 계속 활성화됩니다. 새로운 /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에 따라 다릅니다. 직접 메서드는 더 나은 타입 좁힘을 제공합니다(TS 컴파일러는 client.reports.synastry.create()가 chart1 + chart2를 필요로 한다는 것을 알고 있습니다). 제네릭 디스패처는 동적 use-case(예: UI 드롭다운을 통해 사용자가 보고서 유형을 선택할 때)에 대해 더 작은 surface area를 제공합니다 - 클라이언트 코드에 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 에이전트가 “날짜 X에 대한 나탈 보고서를 생성해줘”라는 작업을 받으면, 겹치는 설명이 있는 12개 후보 대신 명확한 설명을 가진 단일 후보를 받습니다. 이는 에이전트 수준에서 도구 선택 정확도를 향상시킵니다.

디스패처는 별도의 비용을 추가하지 않습니다. 각 report_type은 자체적인 가격 티어를 가진 내부 렌더러로 전달됩니다:

• natal → TIER_7
• transit-yearly → TIER_8
• synastry, business, career, love, money, child, lal-kitab, human-design, vedic-kundli → 각각 해당 티어
• tarot → TIER_4

구체적인 크레딧 수는 Pricing 페이지에서 확인하세요. POST /v1/reports/generate를 report_type: "natal"로 호출하는 것은 직접적인 POST /v1/reports/natal 호출과 정확히 동일한 비용이 듭니다.

새로운 whitelabel: BrandingObject 인라인 모드(2026-05-19에 출시)는 변경 없이 제네릭 디스패처를 통해 작동합니다:

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

하나의 디스패치 + 하나의 인라인 whitelabel = 최소한의 SDK surface로 완전한 white-label 통합.

GenerateReport는 /v1/openapi.json의 별도 구성 요소입니다. 이는 report_type 디스크리미네이터를 사용한 oneOf를 사용하며, Python(Pydantic) 및 PHP(psalm/phpstan 스타일 힌트를 통한 타입화된 유니언)에서 올바른 codegen을 제공합니다.

다음 codegen 릴리스는 모든 세 패키지(TS / Python / PHP)에 client.reports.generate() 메서드를 추가합니다. 그 전까지는 SDK 내에서 일반 HTTP 클라이언트를 통해 호출할 수 있습니다 - 페이로드는 OpenAPI에 문서화되어 있습니다.

별도의 마이그레이션 긴급성은 없습니다 - direct 엔드포인트는 deprecated되지 않았습니다. 이는 12개 메서드 surface가 방해가 되는 개발자를 위한 순수한 DX 개선 사항입니다.