TypeScript 지원

Klleon Chat SDK는 TypeScript 프로젝트에서 원활한 개발 경험과 타입 안정성을 제공하기 위해 타입 정의 파일 (.d.ts)을 지원합니다. 이 가이드는 SDK의 타입 정의를 프로젝트에 적용하는 방법을 안내합니다.

타입 정의 파일 (KlleonSDK.d.ts)

KlleonSDK.d.ts

type BaseStatus =
  | "IDLE"
  | "CONNECTING"
  | "CONNECTING_FAILED"
  | "SOCKET_CONNECTED"
  | "SOCKET_FAILED"
  | "STREAMING_CONNECTED"
  | "STREAMING_FAILED"
  | "CONNECTED_FINISH"
  | "VIDEO_LOAD"
  | "VIDEO_CAN_PLAY";

type BaseLogLevelType = "debug" | "info" | "warn" | "error" | "silent";
type BaseVoiceCodeType = "ko_kr" | "en_us" | "ja_jp" | "id_id";
type BaseSubtitleCodeType = "ko_kr" | "en_us" | "ja_jp" | "id_id";

enum ResponseChatType {
  TEXT = "TEXT",
  STT_RESULT = "STT_RESULT",
  STT_ERROR = "STT_ERROR",
  WAIT = "WAIT",
  WARN_SUSPENDED = "WARN_SUSPENDED",
  DISABLED_TIME_OUT = "DISABLED_TIME_OUT",
  TEXT_ERROR = "TEXT_ERROR",
  TEXT_MODERATION = "TEXT_MODERATION",
  ERROR = "ERROR",
  PREPARING_RESPONSE = "PREPARING_RESPONSE",
  RESPONSE_IS_ENDED = "RESPONSE_IS_ENDED",
  RESPONSE_OK = "RESPONSE_OK",
  WORKER_DISCONNECTED = "WORKER_DISCONNECTED",
  EXCEED_CONCURRENT_QUOTA = "EXCEED_CONCURRENT_QUOTA",
  START_LONG_WAIT = "START_LONG_WAIT",
  USER_SPEECH_STARTED = "USER_SPEECH_STARTED",
  USER_SPEECH_STOPPED = "USER_SPEECH_STOPPED",
}

export type Status = BaseStatus;
export type LogLevelType = BaseLogLevelType;
export type VoiceCodeType = BaseVoiceCodeType;
export type SubtitleCodeType = BaseSubtitleCodeType;

export interface InitOption {
  sdk_key: string;
  avatar_id: string;
  voice_code?: VoiceCodeType;
  subtitle_code?: SubtitleCodeType;
  voice_tts_speech_speed?: number;
  enable_microphone?: boolean;
  log_level?: LogLevelType;
  custom_id?: string;
  user_key?: string;
}

export interface ChatData {
  message: string;
  chat_type: ResponseChatType;
  time: string;
  id: string;
}

export interface ChangeAvatarOption {
  avatar_id: string;
  subtitle_code?: SubtitleCodeType;
  voice_code?: VoiceCodeType;
  voice_tts_speech_speed?: number; // 0.5 ~ 2.0
}

export interface KlleonChat {
  init: (option: InitOption) => Promise<void>;
  destroy: () => void;
  onChatEvent: (callback: (data: ChatData) => void) => void;
  onStatusEvent: (callback: (status: Status) => void) => void;
  sendTextMessage: (message: string) => void;
  startStt: () => void;
  endStt: () => void;
  cancelStt: () => void;
  echo: (message: string) => void;
  startAudioEcho: (audio: string) => void;
  endAudioEcho: () => void;
  changeAvatar: (option: ChangeAvatarOption) => Promise<void>;
  clearMessageList: () => void;
  stopSpeech: () => void;
}

// 전역 window 객체에 KlleonChat 타입 선언
declare global {
  interface Window {
    KlleonChat: KlleonChat;
  }

  namespace JSX {
    interface IntrinsicElements {
      "avatar-container": React.DetailedHTMLProps<
        Omit<React.HTMLAttributes<HTMLElement>, "className"> & {
          class?: string;
        },
        HTMLElement
      >;
      "chat-container": React.DetailedHTMLProps<
        Omit<React.HTMLAttributes<HTMLElement>, "className"> & {
          class?: string;
        },
        HTMLElement
      >;
    }
  }
}

tsconfig.json 설정

생성한 타입 정의 파일 (KlleonSDK.d.ts)을 TypeScript 컴파일러가 인식하도록 tsconfig.json 파일의 include 배열에 해당 파일 경로를 추가합니다.

tsconfig.json

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