@sazuapp/client 0.1.0

package/README.md

@@ -0,0 +1,155 @@
+# @sazuapp/client
+
+[SAZU API](https://www.sazu.app/manse-api) 의 공식 **TypeScript SDK**.
+한 줄로 사주·만세력·합형충파해·격국·용신 등 **14개 명리 모듈** 을 분석합니다.
+
+> sazu.app 에서 제공하는 manse-api 이용자들을 위한 공식 TypeScript SDK 입니다.
+
+<br/><br/><br/>
+
+## 왜 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 코드 생성 친화.
+
+<br/><br/><br/>
+
+## 설치
+
+```bash
+npm install @sazuapp/client
+# 또는
+pnpm add @sazuapp/client
+yarn add @sazuapp/client
+```
+
+<br/><br/><br/>
+
+## 시작하기
+
+1. [https://www.sazu.app/manse-api](https://www.sazu.app/manse-api) — 서비스 소개·가격 확인
+2. [Pro 구독](https://www.sazu.app/manse-api/pricing) (선택, Free 도 사용 가능)
+3. [대시보드 → 키 발급](https://www.sazu.app/manse-api/dashboard/keys) — `SAZU_API_KEY` 환경변수에 설정
+
+<br/><br/><br/>
+
+## 기본 사용
+
+```ts
+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: 1979,
+  birthMonth: 2,
+  birthDay: 8,
+  birthHour: 18,
+  isFemale: false,
+  isLunar: false,
+  birthCity: '서울',
+})
+
+console.log(result.fourPillars)  // 연·월·일·시주
+console.log(result.elements)     // 오행 분포
+console.log(result.relationships) // 합형충파해 (Pro)
+```
+
+<br/><br/><br/>
+
+## 음/양력 변환
+
+```ts
+const solar = await sazu.calendar.convert({
+  year: 1990,
+  month: 4,
+  day: 8,
+  direction: 'toSolar', // 'toSolar' | 'toLunar'
+})
+
+console.log(solar) // { year, month, day, isLeapMonth }
+```
+
+<br/><br/><br/>
+
+## 에러 처리
+
+```ts
+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 가 이미 재시도 */ }
+  }
+}
+```
+
+<br/><br/><br/>
+
+## Next.js (App Router) 통합
+
+```ts
+// 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 })
+}
+```
+
+<br/><br/><br/>
+
+## ⚠ 서버 사이드 전용
+
+본 SDK 는 **서버 사이드에서만 사용**하세요. 브라우저 환경에서 import 하면 자동 경고가 출력되며, **API 키가 클라이언트 번들에 포함될 위험**이 있습니다.
+
+- ✅ Next.js: `app/api/*` 또는 Server Actions
+- ✅ Vite/SvelteKit: `+server.ts` / endpoint
+- ✅ Express·Fastify·Hono·Nest 백엔드
+- ❌ React 컴포넌트 안에서 직접 import 금지
+- ❌ `'use client'` 컴포넌트에서 사용 금지
+
+<br/><br/><br/>
+
+## 옵션
+
+```ts
+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': '...',
+  },
+})
+```
+
+<br/><br/><br/>
+
+## 문의
+
+contact@sazu.app

package/dist/client.d.ts

@@ -0,0 +1,55 @@
+/**
+ * SazuClient — SAZU API 의 TypeScript SDK.
+ *
+ * 사용 예 (서버 사이드):
+ *
+ *   import { SazuClient } from '@sazuapp/client'
+ *
+ *   const sazu = new SazuClient({ apiKey: process.env.SAZU_API_KEY! })
+ *
+ *   const me = await sazu.me()
+ *   console.log(me.tier) // 'free' | 'pro' | 'event'
+ *
+ *   const result = await sazu.calculate({
+ *     birthYear: 1979, birthMonth: 2, birthDay: 8, birthHour: 18,
+ *     isFemale: false, isLunar: false, birthCity: '서울',
+ *   })
+ *   console.log(result.fourPillars)
+ *
+ *   const calendar = await sazu.calendar.convert({
+ *     year: 1990, month: 4, day: 8, direction: 'toSolar',
+ *   })
+ */
+import { HttpClient, type ClientOptions } from './http.js';
+import type { CalculateInput, CalculateResult, CalendarConvertInput, CalendarConvertResult, MeData } from './types.js';
+export declare class SazuClient {
+    private http;
+    /** 음·양력 변환 도구. */
+    readonly calendar: CalendarApi;
+    constructor(opts: ClientOptions);
+    /**
+     * 현재 API 키의 tier·한도 조회.
+     *
+     * 용도: Pro 자격 사전 검증, 한도 표시 UI.
+     */
+    me(): Promise<MeData>;
+    /**
+     * 사주 계산 + 14개 모듈 분석.
+     *
+     * Free 플랜: 기본 5개 모듈 (fourPillars, decadeFortune, elements, summary, sinStrength)
+     * Pro 플랜: 14개 모듈 전체 (격국·용신·12운성·신살·허자·합형충파해 등)
+     */
+    calculate(input: CalculateInput): Promise<CalculateResult>;
+}
+declare class CalendarApi {
+    private http;
+    constructor(http: HttpClient);
+    /**
+     * 양력 ↔ 음력 변환.
+     *
+     * 200년 범위 만세력 기반, 윤달 처리 포함.
+     */
+    convert(input: CalendarConvertInput): Promise<CalendarConvertResult>;
+}
+export {};
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,UAAU,EAAE,KAAK,aAAa,EAAE,MAAM,WAAW,CAAA;AAC1D,OAAO,KAAK,EACV,cAAc,EACd,eAAe,EACf,oBAAoB,EACpB,qBAAqB,EACrB,MAAM,EACP,MAAM,YAAY,CAAA;AAEnB,qBAAa,UAAU;IACrB,OAAO,CAAC,IAAI,CAAY;IAExB,kBAAkB;IAClB,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAA;gBAElB,IAAI,EAAE,aAAa;IAK/B;;;;OAIG;IACG,EAAE,IAAI,OAAO,CAAC,MAAM,CAAC;IAI3B;;;;;OAKG;IACG,SAAS,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC;CAMjE;AAED,cAAM,WAAW;IACH,OAAO,CAAC,IAAI;gBAAJ,IAAI,EAAE,UAAU;IAEpC;;;;OAIG;IACG,OAAO,CAAC,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAAC,qBAAqB,CAAC;CAM3E"}

package/dist/client.js

@@ -0,0 +1,69 @@
+/**
+ * SazuClient — SAZU API 의 TypeScript SDK.
+ *
+ * 사용 예 (서버 사이드):
+ *
+ *   import { SazuClient } from '@sazuapp/client'
+ *
+ *   const sazu = new SazuClient({ apiKey: process.env.SAZU_API_KEY! })
+ *
+ *   const me = await sazu.me()
+ *   console.log(me.tier) // 'free' | 'pro' | 'event'
+ *
+ *   const result = await sazu.calculate({
+ *     birthYear: 1979, birthMonth: 2, birthDay: 8, birthHour: 18,
+ *     isFemale: false, isLunar: false, birthCity: '서울',
+ *   })
+ *   console.log(result.fourPillars)
+ *
+ *   const calendar = await sazu.calendar.convert({
+ *     year: 1990, month: 4, day: 8, direction: 'toSolar',
+ *   })
+ */
+import { HttpClient } from './http.js';
+export class SazuClient {
+    http;
+    /** 음·양력 변환 도구. */
+    calendar;
+    constructor(opts) {
+        this.http = new HttpClient(opts);
+        this.calendar = new CalendarApi(this.http);
+    }
+    /**
+     * 현재 API 키의 tier·한도 조회.
+     *
+     * 용도: Pro 자격 사전 검증, 한도 표시 UI.
+     */
+    async me() {
+        return this.http.request('/v1/me');
+    }
+    /**
+     * 사주 계산 + 14개 모듈 분석.
+     *
+     * Free 플랜: 기본 5개 모듈 (fourPillars, decadeFortune, elements, summary, sinStrength)
+     * Pro 플랜: 14개 모듈 전체 (격국·용신·12운성·신살·허자·합형충파해 등)
+     */
+    async calculate(input) {
+        return this.http.request('/v1/sazu/calculate', {
+            method: 'POST',
+            body: JSON.stringify(input),
+        });
+    }
+}
+class CalendarApi {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    /**
+     * 양력 ↔ 음력 변환.
+     *
+     * 200년 범위 만세력 기반, 윤달 처리 포함.
+     */
+    async convert(input) {
+        return this.http.request('/v1/calendar/convert', {
+            method: 'POST',
+            body: JSON.stringify(input),
+        });
+    }
+}

package/dist/errors.d.ts

@@ -0,0 +1,29 @@
+/**
+ * SAZU API 에러 클래스.
+ *
+ * 모든 API 호출이 실패하면 SazuApiError 를 throw 한다.
+ * - status: HTTP 상태 코드 (네트워크 실패 시 0)
+ * - code: 서버 측 에러 코드 (`INVALID_API_KEY`, `KEY_EXPIRED` 등)
+ * - message: 사람이 읽을 수 있는 메시지
+ * - responseId: 응답 fingerprint (forensics·고객 지원 시 사용)
+ */
+export declare class SazuApiError extends Error {
+    readonly status: number;
+    readonly code: string | undefined;
+    readonly responseId: string | undefined;
+    readonly retryAfterSec: number | undefined;
+    constructor(opts: {
+        status: number;
+        code?: string;
+        message: string;
+        responseId?: string;
+        retryAfterSec?: number;
+    });
+    /** 인증 실패 (401, 키 누락·만료·폐기) */
+    get isAuthError(): boolean;
+    /** Rate limit 초과 (429) — retryAfterSec 후 재시도 가능 */
+    get isRateLimited(): boolean;
+    /** 일시적 장애 (5xx) — 재시도 가능 */
+    get isTransient(): boolean;
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,qBAAa,YAAa,SAAQ,KAAK;IACrC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAA;IACjC,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAA;IACvC,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,SAAS,CAAA;gBAE9B,IAAI,EAAE;QAChB,MAAM,EAAE,MAAM,CAAA;QACd,IAAI,CAAC,EAAE,MAAM,CAAA;QACb,OAAO,EAAE,MAAM,CAAA;QACf,UAAU,CAAC,EAAE,MAAM,CAAA;QACnB,aAAa,CAAC,EAAE,MAAM,CAAA;KACvB;IASD,8BAA8B;IAC9B,IAAI,WAAW,IAAI,OAAO,CAEzB;IAED,mDAAmD;IACnD,IAAI,aAAa,IAAI,OAAO,CAE3B;IAED,4BAA4B;IAC5B,IAAI,WAAW,IAAI,OAAO,CAEzB;CACF"}

package/dist/errors.js

@@ -0,0 +1,35 @@
+/**
+ * SAZU API 에러 클래스.
+ *
+ * 모든 API 호출이 실패하면 SazuApiError 를 throw 한다.
+ * - status: HTTP 상태 코드 (네트워크 실패 시 0)
+ * - code: 서버 측 에러 코드 (`INVALID_API_KEY`, `KEY_EXPIRED` 등)
+ * - message: 사람이 읽을 수 있는 메시지
+ * - responseId: 응답 fingerprint (forensics·고객 지원 시 사용)
+ */
+export class SazuApiError extends Error {
+    status;
+    code;
+    responseId;
+    retryAfterSec;
+    constructor(opts) {
+        super(opts.message);
+        this.name = 'SazuApiError';
+        this.status = opts.status;
+        this.code = opts.code;
+        this.responseId = opts.responseId;
+        this.retryAfterSec = opts.retryAfterSec;
+    }
+    /** 인증 실패 (401, 키 누락·만료·폐기) */
+    get isAuthError() {
+        return this.status === 401;
+    }
+    /** Rate limit 초과 (429) — retryAfterSec 후 재시도 가능 */
+    get isRateLimited() {
+        return this.status === 429;
+    }
+    /** 일시적 장애 (5xx) — 재시도 가능 */
+    get isTransient() {
+        return this.status === 0 || this.status >= 500;
+    }
+}

package/dist/http.d.ts

@@ -0,0 +1,31 @@
+/**
+ * HTTP fetch wrapper — 서버 사이드 전용.
+ *
+ * 보안 정책:
+ *  - 브라우저 환경 감지 시 경고 (API 키 노출 방지)
+ *  - 모든 요청에 X-Client-Type: sdk 헤더 부착 (서버 측 통계 분리)
+ *  - 응답 _meta.responseId 자동 추출 → SazuApiError 에 포함
+ *  - 5xx / 0 (네트워크) 에러는 exponential backoff 로 재시도 (옵션)
+ */
+export interface ClientOptions {
+    /** SAZU API 키 (필수). 환경변수 SAZU_API_KEY 권장. */
+    apiKey: string;
+    /** API 베이스 URL. 기본 https://api.sazu.app */
+    baseUrl?: string;
+    /** 추가 HTTP 헤더 (재정의 금지: Authorization·x-api-key·X-Client-Type) */
+    headers?: Record<string, string>;
+    /** 재시도 횟수 (5xx·네트워크 에러). 기본 2. */
+    maxRetries?: number;
+    /** fetch 타임아웃 ms. 기본 30000. */
+    timeoutMs?: number;
+}
+export declare class HttpClient {
+    private apiKey;
+    private baseUrl;
+    private headers;
+    private maxRetries;
+    private timeoutMs;
+    constructor(opts: ClientOptions);
+    request<T>(path: string, init?: RequestInit): Promise<T>;
+}
+//# sourceMappingURL=http.d.ts.map

package/dist/http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,MAAM,WAAW,aAAa;IAC5B,6CAA6C;IAC7C,MAAM,EAAE,MAAM,CAAA;IACd,2CAA2C;IAC3C,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,iEAAiE;IACjE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAChC,kCAAkC;IAClC,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,+BAA+B;IAC/B,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AA8BD,qBAAa,UAAU;IACrB,OAAO,CAAC,MAAM,CAAQ;IACtB,OAAO,CAAC,OAAO,CAAQ;IACvB,OAAO,CAAC,OAAO,CAAwB;IACvC,OAAO,CAAC,UAAU,CAAQ;IAC1B,OAAO,CAAC,SAAS,CAAQ;gBAEb,IAAI,EAAE,aAAa;IAgBzB,OAAO,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,WAAgB,GAAG,OAAO,CAAC,CAAC,CAAC;CA8GnE"}

package/dist/http.js

@@ -0,0 +1,157 @@
+/**
+ * HTTP fetch wrapper — 서버 사이드 전용.
+ *
+ * 보안 정책:
+ *  - 브라우저 환경 감지 시 경고 (API 키 노출 방지)
+ *  - 모든 요청에 X-Client-Type: sdk 헤더 부착 (서버 측 통계 분리)
+ *  - 응답 _meta.responseId 자동 추출 → SazuApiError 에 포함
+ *  - 5xx / 0 (네트워크) 에러는 exponential backoff 로 재시도 (옵션)
+ */
+import { SazuApiError } from './errors.js';
+const DEFAULT_BASE_URL = 'https://api.sazu.app';
+const DEFAULT_MAX_RETRIES = 2;
+const DEFAULT_TIMEOUT_MS = 30_000;
+/**
+ * 클라이언트 브라우저 환경 감지 — API 키 유출 위험 경고.
+ *
+ * 1회만 경고 출력 (반복 호출 시 spam 방지).
+ */
+let warnedBrowser = false;
+function warnIfBrowser() {
+    if (warnedBrowser)
+        return;
+    if (typeof window !== 'undefined' && typeof window.document !== 'undefined') {
+        warnedBrowser = true;
+        // eslint-disable-next-line no-console
+        console.warn('[@sazuapp/client] ⚠ 브라우저 환경 감지. 본 SDK 는 서버 사이드 전용입니다.\n' +
+            '  API 키가 클라이언트 번들에 포함되면 외부에 노출됩니다.\n' +
+            '  Next.js: app/api/* 또는 server actions 안에서만 사용하세요.\n' +
+            '  Vite/SvelteKit: +server.ts 또는 endpoint 에서만 사용하세요.');
+    }
+}
+async function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export class HttpClient {
+    apiKey;
+    baseUrl;
+    headers;
+    maxRetries;
+    timeoutMs;
+    constructor(opts) {
+        if (!opts.apiKey || typeof opts.apiKey !== 'string') {
+            throw new SazuApiError({
+                status: 0,
+                code: 'NO_API_KEY',
+                message: 'apiKey 가 필요합니다. https://www.sazu.app/manse-api/dashboard/keys 에서 발급받으세요.',
+            });
+        }
+        this.apiKey = opts.apiKey;
+        this.baseUrl = (opts.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, '');
+        this.headers = opts.headers ?? {};
+        this.maxRetries = opts.maxRetries ?? DEFAULT_MAX_RETRIES;
+        this.timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    }
+    async request(path, init = {}) {
+        warnIfBrowser();
+        const url = `${this.baseUrl}${path.startsWith('/') ? path : `/${path}`}`;
+        const headers = {
+            'Content-Type': 'application/json',
+            ...this.headers,
+            // 아래 3개는 사용자가 override 불가
+            'x-api-key': this.apiKey,
+            'X-Client-Type': 'sdk',
+            'User-Agent': `@sazuapp/client/${PACKAGE_VERSION}`,
+        };
+        let lastError = null;
+        for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+            const controller = new AbortController();
+            const timeoutHandle = setTimeout(() => controller.abort(), this.timeoutMs);
+            try {
+                const res = await fetch(url, {
+                    ...init,
+                    headers,
+                    signal: controller.signal,
+                });
+                clearTimeout(timeoutHandle);
+                const text = await res.text();
+                let body = null;
+                try {
+                    body = text ? JSON.parse(text) : null;
+                }
+                catch {
+                    /* 비-JSON 응답 */
+                }
+                const responseId = body?._meta?.responseId ??
+                    res.headers.get('x-response-id') ??
+                    undefined;
+                if (!res.ok) {
+                    const errObj = body?.error;
+                    const retryAfterRaw = res.headers.get('retry-after');
+                    const retryAfterSec = retryAfterRaw ? Number(retryAfterRaw) : undefined;
+                    const err = new SazuApiError({
+                        status: res.status,
+                        code: errObj?.code,
+                        message: errObj?.message ?? `HTTP ${res.status}: ${text.slice(0, 200) || res.statusText}`,
+                        responseId,
+                        retryAfterSec: Number.isFinite(retryAfterSec) ? retryAfterSec : undefined,
+                    });
+                    // 재시도 가능한 케이스: 5xx, 429
+                    if (err.isTransient && attempt < this.maxRetries) {
+                        const backoffMs = Math.min(2 ** attempt * 500, 5000);
+                        lastError = err;
+                        await sleep(backoffMs);
+                        continue;
+                    }
+                    if (err.isRateLimited && err.retryAfterSec && attempt < this.maxRetries) {
+                        lastError = err;
+                        await sleep(Math.min(err.retryAfterSec * 1000, 30_000));
+                        continue;
+                    }
+                    throw err;
+                }
+                const success = body;
+                if (!success || success.success !== true) {
+                    throw new SazuApiError({
+                        status: res.status,
+                        code: 'UNEXPECTED_RESPONSE',
+                        message: '예상치 못한 응답 형식입니다.',
+                        responseId,
+                    });
+                }
+                return success.data;
+            }
+            catch (err) {
+                clearTimeout(timeoutHandle);
+                if (err instanceof SazuApiError) {
+                    if (err.isTransient && attempt < this.maxRetries) {
+                        lastError = err;
+                        const backoffMs = Math.min(2 ** attempt * 500, 5000);
+                        await sleep(backoffMs);
+                        continue;
+                    }
+                    throw err;
+                }
+                // 네트워크·timeout 등
+                const message = err instanceof Error ? err.message : String(err);
+                const netErr = new SazuApiError({
+                    status: 0,
+                    code: 'NETWORK_ERROR',
+                    message: `네트워크 호출 실패: ${message}`,
+                });
+                if (attempt < this.maxRetries) {
+                    lastError = netErr;
+                    const backoffMs = Math.min(2 ** attempt * 500, 5000);
+                    await sleep(backoffMs);
+                    continue;
+                }
+                throw netErr;
+            }
+        }
+        // 도달 불가 (loop 안에서 throw 함). 안전망.
+        throw lastError ?? new SazuApiError({ status: 0, code: 'UNKNOWN', message: '호출 실패.' });
+    }
+}
+// build 시점에 tsc 가 dist/index.js 의 import 가 필요. 패키지 버전은 빌드 산출물에서 가져옴.
+// 단순화 위해 const 로 fix — 패키지 메이저 변경 시 동기 갱신.
+const PACKAGE_VERSION = '0.1.0';

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @sazuapp/client — SAZU API TypeScript SDK
+ *
+ * 공식 문서: https://www.sazu.app/manse-api/docs
+ * 키 발급: https://www.sazu.app/manse-api/dashboard/keys
+ *
+ * 본 패키지는 SAZU REST API 의 얇은 wrapper 입니다.
+ * 명리 계산 알고리즘·비즈니스 로직은 포함하지 않으며, 모든 계산은 서버에서 수행됩니다.
+ */
+export { SazuClient } from './client.js';
+export { SazuApiError } from './errors.js';
+export type { ClientOptions } from './http.js';
+export type { PlanTier, Locale, DetailLevel, ResponseMeta, SuccessResponse, ErrorResponse, MeData, CalculateInput, CalculateResult, CalendarDirection, CalendarConvertInput, CalendarConvertResult, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AACxC,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAC1C,YAAY,EAAE,aAAa,EAAE,MAAM,WAAW,CAAA;AAC9C,YAAY,EAEV,QAAQ,EACR,MAAM,EACN,WAAW,EACX,YAAY,EACZ,eAAe,EACf,aAAa,EAEb,MAAM,EAEN,cAAc,EACd,eAAe,EAEf,iBAAiB,EACjB,oBAAoB,EACpB,qBAAqB,GACtB,MAAM,YAAY,CAAA"}

package/dist/index.js

@@ -0,0 +1,11 @@
+/**
+ * @sazuapp/client — SAZU API TypeScript SDK
+ *
+ * 공식 문서: https://www.sazu.app/manse-api/docs
+ * 키 발급: https://www.sazu.app/manse-api/dashboard/keys
+ *
+ * 본 패키지는 SAZU REST API 의 얇은 wrapper 입니다.
+ * 명리 계산 알고리즘·비즈니스 로직은 포함하지 않으며, 모든 계산은 서버에서 수행됩니다.
+ */
+export { SazuClient } from './client.js';
+export { SazuApiError } from './errors.js';

package/dist/types.d.ts

@@ -0,0 +1,110 @@
+/**
+ * SAZU API 입력·출력 타입.
+ *
+ * TypeScript 인터페이스만 정의 (런타임 zod 검증 안 함 — 의존성 0 유지).
+ * 응답 schema 는 공개 docs (https://www.sazu.app/manse-api/docs) 와 동기.
+ *
+ * 비공개 내부 구조는 노출하지 않는다 — 본 SDK 는 REST API 의 얇은 wrapper 일 뿐,
+ * sazu-logic 코드·계산 알고리즘은 절대 포함하지 않는다.
+ */
+export interface ResponseMeta {
+    /** forensics 추적용 응답 ID. 형식: `${ts36}-${keyHash8}-${rand8}` */
+    responseId: string;
+    /** 서버 응답 timestamp (ms) */
+    t: number;
+}
+export interface SuccessResponse<T> {
+    success: true;
+    data: T;
+    _meta?: ResponseMeta;
+}
+export interface ErrorResponse {
+    success: false;
+    error: {
+        code: string;
+        message: string;
+        [key: string]: unknown;
+    };
+    _meta?: ResponseMeta;
+}
+export type PlanTier = 'free' | 'pro' | 'event';
+export interface MeData {
+    tier: PlanTier;
+    keyPrefix: string;
+    rateLimitPerMinute?: number;
+    monthlyQuota?: number;
+}
+export type Locale = 'ko' | 'han';
+export type DetailLevel = 'minimal' | 'standard' | 'full';
+export interface CalculateInput {
+    /** 출생년도 (1900~2100) */
+    birthYear: number;
+    /** 출생월 (1~12) */
+    birthMonth: number;
+    /** 출생일 (1~31) */
+    birthDay: number;
+    /** 출생시 (0~23). 시간 미상이면 생략 또는 null. */
+    birthHour?: number | null;
+    /** 출생분 (0~59). 기본 0. */
+    birthMinute?: number;
+    /** 여성 여부 */
+    isFemale: boolean;
+    /** 음력 여부. 기본 false. */
+    isLunar?: boolean;
+    /** 출생 도시 (진태양시 보정용). 기본 '서울'. */
+    birthCity?: string;
+    /** 한글 또는 한자 출력. 기본 'ko'. */
+    locale?: Locale;
+    /** 포함할 모듈 ID 목록. 생략 시 플랜별 기본 모듈. */
+    modules?: string[];
+    /** 대운 개수 (13~20) */
+    decadeCount?: number;
+    /** 응답 상세 수준. 기본 'standard'. */
+    detail?: DetailLevel;
+}
+/**
+ * 사주 분석 결과.
+ *
+ * 모듈별 구조가 다양하므로 타입은 `Record<string, unknown>` 로 노출.
+ * 정확한 모듈별 schema 는 docs 페이지의 예시 참조.
+ * (https://www.sazu.app/manse-api/docs)
+ */
+export interface CalculateResult {
+    /** 사주 원국 (연·월·일·시주) */
+    fourPillars?: Record<string, unknown>;
+    /** 10년 단위 대운 흐름 */
+    decadeFortune?: Record<string, unknown>;
+    /** 오행 분포 */
+    elements?: Record<string, unknown>;
+    /** 분석 요약 */
+    summary?: Record<string, unknown>;
+    /** 신강/신약 */
+    sinStrength?: Record<string, unknown>;
+    /** Pro 모듈 — 신살 */
+    sinsal?: Record<string, unknown>;
+    /** Pro 모듈 — 합형충파해 (원국 + 허자 이중 분석) */
+    relationships?: Record<string, unknown>;
+    /** Pro 모듈 — 허자 분석 */
+    ghostElements?: Record<string, unknown>;
+    /** Pro 모듈 — 격국 */
+    gyeokguk?: Record<string, unknown>;
+    /** Pro 모듈 — 용신 */
+    yongsin?: Record<string, unknown>;
+    /** 기타 모듈 (확장 가능) */
+    [moduleId: string]: unknown;
+}
+export type CalendarDirection = 'toSolar' | 'toLunar';
+export interface CalendarConvertInput {
+    year: number;
+    month: number;
+    day: number;
+    direction: CalendarDirection;
+}
+export interface CalendarConvertResult {
+    year: number;
+    month: number;
+    day: number;
+    isLeapMonth?: boolean;
+    [key: string]: unknown;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,10 @@
+/**
+ * SAZU API 입력·출력 타입.
+ *
+ * TypeScript 인터페이스만 정의 (런타임 zod 검증 안 함 — 의존성 0 유지).
+ * 응답 schema 는 공개 docs (https://www.sazu.app/manse-api/docs) 와 동기.
+ *
+ * 비공개 내부 구조는 노출하지 않는다 — 본 SDK 는 REST API 의 얇은 wrapper 일 뿐,
+ * sazu-logic 코드·계산 알고리즘은 절대 포함하지 않는다.
+ */
+export {};

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@sazuapp/client",
+  "version": "0.1.0",
+  "description": "SAZU API 공식 TypeScript SDK — 사주·만세력·합형충파해·격국·용신 등 14개 명리 분석을 한 줄로.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "dev": "tsc -p tsconfig.json --watch"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "saju",
+    "sazu",
+    "fortune",
+    "manse",
+    "korean-fortune",
+    "korean-astrology",
+    "myeongni",
+    "sdk",
+    "typescript"
+  ],
+  "author": "Inavan",
+  "license": "MIT",
+  "homepage": "https://www.sazu.app/manse-api",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ainvention/sazu-app-manse-api.git",
+    "directory": "client"
+  },
+  "bugs": {
+    "url": "https://github.com/ainvention/sazu-app-manse-api/issues"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.0",
+    "@types/node": "^20.11.0"
+  }
+}