TypeScript Support

Klleon SDK is provided as a UMD bundle, so you need to add a type definition file to use it in TypeScript projects.

Type Definition File

Create a KlleonSDK.d.ts file in your project root.

Supported SDK version

The type definitions below are based on SDK 2.0.0. After upgrading your SDK version, re-check them against each API page.

/** Type definitions for Klleon SDK 2.0.0 */

/** SDK connection status */
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() options */
interface InitOption {
  sdk_key: string;
  avatar_id: string;
  log_level?: LogLevel;
  language?: LanguageCode;
  enable_microphone?: boolean;
  auto_send?: boolean;
  stt_only?: boolean;
}

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

/** onSignal callback parameter */
interface IncomingSignalData {
  signal: string;
  payload?: Record<string, unknown>;
  id: string;
  type: "SESSION" | "INPUT" | "OUTPUT";
}

/** onError callback parameter */
interface ErrorData {
  code: string;
  message?: string;
}

/** SDK interface */
interface KlleonSDK {
  // Lifecycle
  init: (option: InitOption) => Promise<void>;
  destroy: () => Promise<void>;
  // Events
  onSignal: (cb: (data: IncomingSignalData) => void) => void;
  onStatus: (cb: (status: SDKStatus) => void) => void;
  onError: (cb: (error: ErrorData) => void) => void;

  // Text
  sendMessage: (text: string) => void;
  speak: (option: string | SpeakOption) => void;

  // Audio echo
  sendSpeakAudio: (audio: string, sample_rate?: number) => void;
  endSpeakAudio: () => void;

  // Voice
  startListening: () => void;
  endListening: () => void;
  cancelListening: () => void;

  // Avatar control
  stopSpeaking: () => void;

  // Media
  setVolume: (volume: number) => void;

  // Status query
  getStatus: () => SDKStatus;
  clearMessages: () => void;
}

declare global {
  interface Window {
    KlleonSDK: KlleonSDK;
  }
}

// Prevent type errors when using Web Components in React (works with both React 18 and 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;
          // Set false to hide the character counter.
          isShowCount?: boolean;
          // To hide the scrollbar, omit the prop entirely instead of passing a value.
          // When it reaches the element as an HTML attribute, even "false" is read as true.
          scrollbar?: boolean;
        },
        HTMLElement
      >;
    }
  }
}

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

For how isShowCount and scrollbar interpret boolean values, see "Setting Boolean Attributes" on the chat-container page.

tsconfig.json Configuration

Add the type definition file to include so TypeScript recognizes it.

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

Usage Example

After adding the type definitions, autocomplete and type checking will work for 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));