HUA SDK Lite v2.1.1

HUA Lite API를 위한 TypeScript SDK입니다. 감정 인식 AI 챗봇과 쉽게 통합할 수 있습니다.

English Documentation (README.en.md)

✨ 주요 기능 (2.1.1)

• 실제 서비스와 동일한 API 키 검증 (게스트: 64자리, 회원: hua_ 접두사)
• 스마트 재시도 로직 (502/503/504 등 서버 오류 자동 재시도)
• 강화된 에러 처리 (17개 테스트로 모든 예외 상황 검증)
• TypeScript 완벽 지원 & 개발자 경험 개선
• 감정 기반 응답, 다국어, 크레딧, 이벤트, 배치 처리 등

설치

npm install [email protected]

빠른 시작

import { HUALite } from 'hua-sdk-lite';

// SDK 초기화 (게스트 키 또는 회원가입 키)
const hua = new HUALite('hua_wut4p3hneulrt2ud3mi9rn'); // 회원가입 키 예시
// 또는
// const hua = new HUALite('ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_'); // 게스트 키 예시

// 챗봇과 대화
const response = await hua.chat({
  message: "오늘 하루 힘들었어, 위로해줘!",
  tone: "gentle",
  mode: "empathy",
  tier: 1.0,
  provider: "openai"
});

console.log(response.data.message);
// "정말 힘드셨겠어요... 오늘 하루도 잘 버텨내셨네요. 당신의 노력을 알아봐요. 내일은 더 좋은 하루가 될 거예요! 💕"

API 키 발급

// 게스트 API 키 발급 (64자리 랜덤)
const apiKey = await HUALite.issueKey();
console.log(apiKey); // 예: "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_"

고급 사용법

// 사용자 정의 설정
const hua = new HUALite('hua_wut4p3hneulrt2ud3mi9rn', {
  baseUrl: 'https://api.hua.ai.kr',
  timeout: 30000,
  retries: 2,
  retryDelay: 1000
});

// 다양한 감정 설정으로 대화
const responses = await Promise.all([
  hua.chat({ message: "안녕!", tone: "gentle", mode: "empathy" }),
  hua.chat({ message: "힘내!", tone: "cheerful", mode: "praise" }),
  hua.chat({ message: "고마워", tone: "warm", mode: "praise" })
]);

지원 옵션

Tone (톤)

• gentle - 부드럽고 따뜻한
• warm - 따뜻하고 친근한
• cheerful - 밝고 활기찬
• quirky - 독특하고 재미있는
• delicate - 섬세하고 정중한

Mode (모드)

• empathy - 공감적
• analysis - 분석적
• suggestion - 제안적
• praise - 칭찬적
• playful - 장난스러운

Tier (등급)

• 1.0 - 기본 (1 크레딧)
• 2.0 - 고급 (2 크레딧)
• 3.0 - 프리미엄 (3 크레딧)

응답 구조

interface ChatResponse {
  success: boolean;
  data: {
    message: string;
    usage: {
      total_tokens: number;
      input_tokens: number;
      output_tokens: number;
    };
    credits?: {
      used: number;
      remaining: number;
      tier: string;
    };
    tier: string;
    mode: string;
    tone: string;
    authenticated: boolean;
    userId?: string;
    note?: string;
  };
}

에러 처리 & 재시도

try {
  const response = await hua.chat({ message: "Hello!" });
} catch (error) {
  if (error.code === 'INSUFFICIENT_CREDITS') {
    console.log('크레딧이 부족합니다.');
  } else if (error.code === 'RATE_LIMIT_EXCEEDED') {
    console.log('요청 한도를 초과했습니다.');
  } else if (error.code === 'SERVER_ERROR') {
    console.log('서버 오류, 자동 재시도 중...');
  } else {
    console.error(error);
  }
}
```text
- 502/503/504 등 서버 오류는 자동 재시도 (config로 횟수/딜레이 조절)
- 모든 에러는 타입별로 구분되어 처리 가능

---

## 이벤트 시스템

```typescript
hua.on('request', (event) => {
  console.log('Request sent:', event.data.url);
});
hua.on('response', (event) => {
  console.log('Response received:', event.data.status);
});
hua.on('error', (event) => {
  console.log('Error occurred:', event.data.error);
});

입력값 검증

if (hua.validateTone('gentle')) {
  // 유효한 톤
}
if (hua.validateMode('empathy')) {
  // 유효한 모드
}
if (hua.validateTier(1.0)) {
  // 유효한 등급
}

테스트 & 품질

• Jest 기반 17+개 테스트로 모든 주요 기능/에러/재시도 검증
• 실제 서비스 환경과 동일한 조건에서 안전하게 사용 가능

문서

• API 문서
• 온라인 데모
• API 키 관리

라이선스

MIT License

지원

• 이슈: GitHub Issues
• 이메일: [email protected]