TypeScript 지원

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

타입 정의 파일

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

대응 SDK 버전

아래 타입 정의는 SDK 2.0.0 기준입니다. 사용 중인 SDK 버전을 올린 뒤에는 각 API 문서와 대조하여 타입 정의를 다시 확인하세요.

/** Klleon SDK 2.0.0 기준 타입 정의 */

/** SDK 연결 상태 */
type SDKStatus =
  | "IDLE"
  | "CONNECTING"
  | "SOCKET_CONNECTED"
  | "STREAMING_CONNECTED"
  | "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;
}

/** speak() 옵션 */
interface SpeakOption {
  text: string;
}

/** 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: (option: string | SpeakOption) => void;

  // 오디오 립싱크 전송
  sendSpeakAudio: (audio: string, sample_rate?: number) => 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 사용 시 타입 에러 방지 (React 18/19 모두 동작)
declare module "react" {
  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;
          // false를 지정하면 글자 수 카운터가 숨겨집니다.
          isShowCount?: boolean;
          // 스크롤바를 숨기려면 값을 넘기지 말고 prop 자체를 생략하세요.
          // HTML 속성으로 전달되면 "false"도 true로 해석됩니다.
          scrollbar?: boolean;
        },
        HTMLElement
      >;
    }
  }
}

export type {
  SDKStatus,
  LogLevel,
  LanguageCode,
  InitOption,
  SpeakOption,
  IncomingSignalData,
  ErrorData,
  KlleonSDK,
};

isShowCount, scrollbar의 boolean 해석 규칙은 chat-container 문서의 "boolean 속성 지정 방법"을 참고하세요.

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));