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