TypeScript 지원

Klleon SDK는 UMD 번들로 제공되므로 TypeScript 프로젝트에서 사용하려면 타입 정의 파일을 추가해야 합니다.

타입 정의 파일

프로젝트 루트에 KlleonSDK.d.ts 파일을 생성합니다.

/** SDK 연결 상태 */
type SDKStatus =
  | "IDLE"
  | "CONNECTING"
  | "CONNECTING_FAILED"
  | "SOCKET_CONNECTED"
  | "SOCKET_FAILED"
  | "STREAMING_CONNECTED"
  | "STREAMING_FAILED"
  | "CONNECTED_FINISH";

type LogLevel = "debug" | "info" | "warn" | "error" | "silent";
type LanguageCode = "ko_kr" | "en_us" | "ja_jp" | "id_id";

/** init() 옵션 */
interface InitOption {
  sdk_key: string;
  avatar_id: string;
  log_level?: LogLevel;
  language?: LanguageCode;
  enable_microphone?: boolean;
  auto_send?: boolean;
  stt_only?: boolean;
}

/** onSignal 콜백 파라미터 */
interface IncomingSignalData {
  signal: string;
  payload?: Record<string, unknown>;
  id: string;
  type: "SESSION" | "INPUT" | "OUTPUT";
}

/** onError 콜백 파라미터 */
interface ErrorData {
  code: string;
  message?: string;
}

/** SDK 인터페이스 */
interface KlleonSDK {
  // 생명주기
  init: (option: InitOption) => Promise<void>;
  destroy: () => Promise<void>;
  // 이벤트
  onSignal: (cb: (data: IncomingSignalData) => void) => void;
  onStatus: (cb: (status: SDKStatus) => void) => void;
  onError: (cb: (error: ErrorData) => void) => void;

  // 텍스트
  sendMessage: (text: string) => void;
  speak: (text: string) => void;

  // 오디오 에코
  sendSpeakAudio: (audio: string) => void;
  endSpeakAudio: () => void;

  // 음성
  startListening: () => void;
  endListening: () => void;
  cancelListening: () => void;

  // 아바타 제어
  stopSpeaking: () => void;

  // 미디어
  setVolume: (volume: number) => void;

  // 상태 조회
  getStatus: () => SDKStatus;
  clearMessages: () => void;
}

declare global {
  interface Window {
    KlleonSDK: KlleonSDK;
  }

  // React에서 Web Component 사용 시 타입 에러 방지
  namespace JSX {
    interface IntrinsicElements {
      "avatar-container": React.DetailedHTMLProps<
        React.HTMLAttributes<HTMLElement> & {
          volume?: number;
          fit?: "cover" | "contain" | "fill";
        },
        HTMLElement
      >;
      "chat-container": React.DetailedHTMLProps<
        React.HTMLAttributes<HTMLElement> & {
          type?: "text" | "voice";
          delay?: number;
          isShowCount?: boolean;
          scrollbar?: boolean;
        },
        HTMLElement
      >;
    }
  }
}

export {};

tsconfig.json 설정

타입 정의 파일을 TypeScript가 인식하도록 include에 추가합니다.

{
  "compilerOptions": {
    "jsx": "react-jsx"
  },
  "include": ["src", "KlleonSDK.d.ts"]
}

사용 예시

타입 정의를 추가하면 window.KlleonSDK에 대한 자동 완성과 타입 검사가 동작합니다.

const SDK = window.KlleonSDK;

SDK.onStatus((status) => console.log(status));
SDK.onSignal((data) => console.log(data.signal, data.payload));

SDK.init({
  sdk_key: 'YOUR_SDK_KEY',
  avatar_id: 'YOUR_AVATAR_ID',
}).catch((e) => console.error(e.message));