@sazuapp/client

SAZU API 의 공식 TypeScript SDK (서버 사이드 전용). 한 줄로 사주·만세력·합형충파해·격국·용신 등 14개 명리 모듈 을 분석합니다.

sazu.app 에서 제공하는 manse-api 이용자들을 위한 공식 TypeScript SDK 입니다.

ℹ️ 이름에 대해: client 는 SAZU API 의 클라이언트 (= API 를 호출하는 라이브러리) 라는 의미입니다. 브라우저(client-side) 전용이라는 뜻이 아닙니다. Node.js·서버 사이드에서만 사용하세요. (@aws-sdk/client-s3·@supabase/supabase-js 같은 업계 관용 네이밍을 따릅니다.)

왜 SAZU SDK 인가

사주·만세력·운세 관련 서비스를 만들고 있다면, 직접 명리 엔진을 구현하지 마세요.

• 🚀 3줄 연동 — new SazuClient({ apiKey }) → sazu.calculate({...}) → 끝.
• 🎯 14개 명리 모듈 — 사주팔자·합형충파해·격국·용신·12운성·신살·허자·대운 한 번에.
• 📅 200년 범위 만세력 — 1900~2100 음/양력 변환, 절기 기반 월주 판별, 진태양시 보정.
• ⚡ 50ms 이하 응답 — 챗봇·앱·웹사이트에 즉시 통합. 사용자 경험 손실 0.
• 🛡 자동 재시도 — 네트워크·5xx 에러에 exponential backoff. 429 에 Retry-After 자동 준수.
• 🔒 서버 사이드 전용 가드 — 브라우저 환경 감지 시 자동 경고 (API 키 유출 방지).
• 📦 의존성 0 — native fetch 만 사용. 번들 크기 최소.
• ✨ 완벽한 TypeScript 타입 — IDE 자동완성 + AI 코드 생성 친화.

설치

npm install @sazuapp/client
# 또는
pnpm add @sazuapp/client
yarn add @sazuapp/client

시작하기

1. https://www.sazu.app/manse-api — 서비스 소개·가격 확인
2. Pro 구독 (선택, Free 도 사용 가능)
3. 대시보드 → 키 발급 — SAZU_API_KEY 환경변수에 설정

기본 사용

import { SazuClient } from '@sazuapp/client'

const sazu = new SazuClient({ apiKey: process.env.SAZU_API_KEY! })

// 현재 키의 tier·한도 확인
const me = await sazu.me()
console.log(me.tier) // 'free' | 'pro' | 'event'

// 사주 분석
const result = await sazu.calculate({
  birthYear: 1990,
  birthMonth: 3,
  birthDay: 15,
  birthHour: 14,
  isFemale: false,
  isLunar: false,
  birthCity: '서울',
})

console.log(result.fourPillars)  // 연·월·일·시주
console.log(result.elements)     // 오행 분포
console.log(result.relationships) // 합형충파해 (Pro)

음/양력 변환

const solar = await sazu.calendar.convert({
  year: 1990,
  month: 4,
  day: 8,
  direction: 'toSolar', // 'toSolar' | 'toLunar'
})

console.log(solar) // { year, month, day, isLeapMonth }

에러 처리

import { SazuClient, SazuApiError } from '@sazuapp/client'

try {
  const result = await sazu.calculate({ ... })
} catch (err) {
  if (err instanceof SazuApiError) {
    console.error(err.code, err.message, err.responseId)
    if (err.isAuthError) { /* 키 재발급 안내 */ }
    if (err.isRateLimited) { /* err.retryAfterSec 후 재시도 */ }
    if (err.isTransient) { /* 일시 장애, SDK 가 이미 재시도 */ }
  }
}

Next.js (App Router) 통합

// app/api/saju/route.ts
import { NextResponse } from 'next/server'
import { SazuClient } from '@sazuapp/client'

const sazu = new SazuClient({ apiKey: process.env.SAZU_API_KEY! })

export async function POST(req: Request) {
  const body = await req.json()
  const result = await sazu.calculate(body)
  return NextResponse.json({ ok: true, data: result })
}

⚠ 서버 사이드 전용

본 SDK 는 서버 사이드에서만 사용하세요. 브라우저 환경에서 import 하면 자동 경고가 출력되며, API 키가 클라이언트 번들에 포함될 위험이 있습니다.

• ✅ Next.js: app/api/* 또는 Server Actions
• ✅ Vite/SvelteKit: +server.ts / endpoint
• ✅ Express·Fastify·Hono·Nest 백엔드
• ❌ React 컴포넌트 안에서 직접 import 금지
• ❌ 'use client' 컴포넌트에서 사용 금지

옵션

const sazu = new SazuClient({
  apiKey: process.env.SAZU_API_KEY!,
  baseUrl: 'https://api.sazu.app',  // 기본값
  maxRetries: 2,                     // 기본 2 (5xx·네트워크 에러)
  timeoutMs: 30000,                  // 기본 30s
  headers: {                         // 추가 헤더 (선택)
    'X-Trace-Id': '...',
  },
})

문의

[email protected]