@klever-one/web-sdk
Version:
Web SDK for integrating real-time room management and streaming functionality into web applications
384 lines (383 loc) • 12.8 kB
TypeScript
import { Message, ConversationEventData, AvatarData } from '../types';
import { KleverOneClientConfig, ClientState, ClientMetrics } from '../types/client.types';
/**
* Klever One SDK의 메인 클라이언트 클래스
*
* 이 클래스는 실시간 방 관리, 스트리밍, AI 대화 기능을 통합하여
* 개발자가 쉽게 사용할 수 있도록 단일 인터페이스를 제공합니다.
*
* 주요 기능:
* - 방 연결 및 관리 (WebSocket)
* - 스트리밍 연결 및 아바타 제어
* - AI와의 텍스트/음성 대화
* - 음성 녹음 및 전송
* - 상태 관리 및 메트릭 추적
*
* 사용 예제:
* ```typescript
* const client = new KleverOneClient({
* apiKey: 'your-api-key',
* container: document.getElementById('streaming-container')
* });
*
* await client.connect();
* await client.sendText('안녕하세요!');
* ```
*/
export declare class KleverOneClient {
/** 실제 사용되는 설정 (기본값이 모두 적용된 상태) */
private readonly config;
/** API 인증에 사용되는 키 */
private readonly apiKey;
/** 스트리밍 화면이 들어갈 HTML 엘리먼트 */
private readonly container;
/** 사용자가 설정한 이벤트 콜백 함수들 */
private readonly callbacks;
/** 방 연결과 WebSocket 연결을 관리 */
private readonly roomManager;
/** 스트리밍 연결과 아바타 제어를 관리 */
private readonly streamingOrchestrator;
/** AI와의 대화 처리를 관리 */
private readonly conversationManager;
/** 각 서비스 간 이벤트 통신을 담당 */
private readonly eventBus;
/** 음성 녹음을 관리 */
private readonly recorderService;
/** 메시지 델타 처리를 위한 이전 content 저장소 */
private readonly messageContentCache;
/** 아바타와 대화 시스템 초기화 완료 여부 */
private isInitialized;
/** 마지막 대화 완료 상태 추적 */
private lastCompletionState;
/** 이벤트 리스너 해제를 위한 함수들 */
private eventUnsubscribeFunctions;
/** 스트리밍 컨테이너 크기 변경을 감지 */
private resizeObserver;
/** 기본 음성 ID (아바타 목소리) */
private static readonly DEFAULT_VOICE_ID;
/** 기본 언어 설정 */
private static readonly DEFAULT_LANGUAGE;
/** TTS(텍스트 음성 변환) 서비스 */
private static readonly DEFAULT_TTS_SERVICE;
/** 아바타의 기본 인사말 */
private static readonly DEFAULT_GREETING;
/** 에러 발생 시 기본 응답 */
private static readonly DEFAULT_ERROR_MESSAGE;
/** 금지된 주제들 */
private static readonly DEFAULT_FORBIDDEN_WORDS;
/** 사용자 기본 위치 */
private static readonly DEFAULT_USER_LOCATION;
/** 현재 클라이언트의 연결, 녹음, 준비 상태를 추적 */
private _state;
/** 사용량 및 성능 지표를 추적하는 메트릭 */
private _metrics;
/**
* KleverOneClient 생성자
*
* @param config - 클라이언트 설정 객체
* @throws {Error} API 키가 없거나 컨테이너 엘리먼트가 없을 때
*/
constructor(config: KleverOneClientConfig);
/**
* 서버에 연결을 시도합니다.
*
* 연결 순서:
* 1. 방 연결 요청 (WebSocket)
* 2. 방 정보 수신 대기
* 3. 스트리밍 연결
* 4. AI 대화 시스템 초기화
*
* @throws {Error} 연결 실패 시 오류 발생
*/
connect(): Promise<void>;
/**
* 내부 이벤트 리스너들을 설정합니다.
*/
private setupInternalEventListeners;
/**
* 내부 이벤트 리스너들을 정리합니다.
* 메모리 누수를 방지하기 위해 모든 이벤트 리스너를 해제합니다.
*/
private cleanupInternalEventListeners;
/**
* 방 정보 업데이트 이벤트를 처리합니다.
*
* 작업 순서:
* 1. 방 정보 검증
* 2. 스트리밍 컨테이너 설정
* 3. 스트리밍 서버 연결
* 4. 콜백 호출
*/
private handleRoomInfoUpdated;
/**
* 모든 연결을 종료하고 리소스를 정리합니다.
*
* 정리 작업:
* 1. 녹음 중인 경우 중지
* 2. 대화 내역 삭제
* 3. 스트리밍 연결 종료
* 4. 방 WebSocket 연결 종료
* 5. 이벤트 리스너 정리
* 6. 상태 초기화
*/
disconnect(): void;
/**
* 서버에 재연결을 시도합니다.
* 내부적으로 disconnect 후 connect를 호출합니다.
*/
reconnect(): Promise<void>;
/**
* AI에게 텍스트 메시지를 전송합니다.
*
* @param message - 전송할 텍스트 메시지
* @throws {Error} 연결되지 않은 상태에서 호출 시
*/
sendText(message: string): Promise<void>;
/**
* TTS(텍스트 음성 변환)를 통해 아바타가 말하게 합니다.
* 단일 텍스트 또는 텍스트 배열을 지원합니다.
*
* @param input - 아바타가 말할 텍스트 (단일 문자열)
* @throws {Error} 연결되지 않은 상태에서 호출 시
*/
speak(input: string): void;
/**
* TTS(텍스트 음성 변환)를 통해 아바타가 말하게 합니다.
* 단일 텍스트 또는 텍스트 배열을 지원합니다.
*
* @param input - 아바타가 말할 텍스트 배열
* @throws {Error} 연결되지 않은 상태에서 호출 시
*/
speak(input: string[]): void;
/**
* 음성 녹음을 시작합니다.
*
* 작업 순서:
* 1. 마이크 접근 권한 요청
* 2. MediaRecorder 설정
* 3. 녹음 시작
* 4. 상태 업데이트
*
* @throws {Error} 마이크 접근 배수 또는 녹음 오류 시
*/
startRecording(): Promise<void>;
/**
* 녹음을 중지하고 AI에게 전송합니다.
*
* 작업 순서:
* 1. 녹음 중지
* 2. 음성 데이터 변환
* 3. AI 서버로 전송
*/
stopRecording(): Promise<void>;
/**
* 현재 녹음 중인지 확인합니다.
*
* @returns 녹음 중이면 true, 아니면 false
*/
isRecording(): boolean;
/**
* 현재 클라이언트 상태를 반환합니다.
*
* @returns 연결, 녹음, 준비 상태 등을 포함한 전체 상태
*/
getState(): Readonly<ClientState>;
/**
* 클라이언트 사용량 메트릭을 반환합니다.
*
* @returns 메시지 수, 녹음 세션 수, 오류 수 등 성능 지표
*/
getMetrics(): Readonly<ClientMetrics>;
/**
* 클라이언트 메트릭을 초기화합니다.
*/
private resetMetrics;
/**
* 클라이언트가 AI와 대화할 준비가 되었는지 확인합니다.
*
* 모든 준비가 되어야 하는 조건:
* - 방 연결 완료
* - 스트리밍 준비 완료
* - AI 대화 시스템 준비 완료
*
* @returns 모두 준비되면 true, 아니면 false
*/
isReady(): boolean;
/**
* 현재 AI 대화의 상세 상태를 반환합니다.
*
* @returns 대화 상태와 메시지 내역
*/
getConversationState(): ConversationEventData;
/**
* 현재 AI와 나눔 대화의 모든 메시지 내역을 반환합니다.
*
* @returns 사용자와 AI의 메시지 리스트 (시간 순 정렬)
*/
getMessages(): Message[];
/**
* 스트리밍 화면 크기를 조정합니다.
*
* @param width - 너비 (픽셀)
* @param height - 높이 (픽셀)
*/
resize(width: number, height: number): void;
/**
* 아바타 번호를 설정합니다.
*
* @param avatarNum - 아바타 번호 또는 ID
*/
sendAvatarNum(avatarNum: number | string): void;
/**
* 아바타 외형을 변경합니다.
*
* @param avatarData - 아바타 외형 데이터
*/
sendAvatarAppearanceChange(avatarData: AvatarData): void;
/**
* 배경을 변경합니다.
*
* @param id - 배경 ID
*/
sendPlaceBackgroundChange(id: string): void;
/**
* 음성 설정을 변경합니다.
*
* @param voiceId - 음성 ID
*/
sendVoiceSetting(voiceId: string): void;
/**
* UI 상호작용 데이터를 전송합니다.
*
* @param data - 상호작용 데이터
*/
/**
* UI 상호작용 데이터를 전송합니다.
*
* @deprecated 이 메서드는 내부용으로만 사용됩니다.
* 대신 sendText(), speak(), sendAvatarNum() 등 특정 메서드를 사용하세요.
*
* @param data - 상호작용 데이터
* @internal
*/
/**
* 웹소켓을 통해 원시 메시지를 전송합니다.
*
* @param message - 전송할 메시지 (문자열, 객체, ArrayBuffer, Blob)
*/
sendMessage(message: string | object | ArrayBuffer | Blob): void;
/**
* 대용량 데이터를 청크로 나누어 전송합니다.
*
* @param params - 전송 매개변수
* @param params.payload - 전송할 데이터 (Uint8Array)
* @param params.actionName - 액션 이름
* @param params.chunkSize - 청크 크기 (선택적, 기본값: 64KB)
*/
sendDataInChunks(params: {
payload: Uint8Array;
actionName: string;
chunkSize?: number;
}): Promise<void>;
/**
* 스트리밍 연결 완료 이벤트를 처리합니다.
*
* 작업 순서:
* 1. 컨테이너에서 로딩 메시지 제거
* 2. 스트리밍 UI를 컨테이너에 추가
* 3. 아바타 초기화 (준비된 경우)
*/
private handleStreamingConnected;
private handleStreamingAllocating;
private handleRoomDisconnected;
private handleStreamingStatusChange;
private handleIsReadyToSendChange;
private handleRecorderStatusChange;
private handleStreamerListUpdated;
private handleStreamingFailed;
private handleStreamingReconnecting;
private handleRecorderError;
private handleRoomSessionTimeout;
private initializeSizeObserver;
/**
* 아바타 초기화를 수행합니다.
*
* 설정 작업:
* 1. 아바타 외모 설정
* 2. 음성 설정
*/
private initializeAvatar;
/**
* 아바타 외모를 초기화합니다.
*
* 설정 작업:
* 1. 아바타 외모 ID를 기반으로 외모 변경 이벤트 전송
*/
private initializeAvatarAppearance;
/**
* 배경을 초기화합니다.
*
* 설정 작업:
* 1. roomInfo의 backgroundSetting(JSON)에서 selectedId를 파싱하여 배경 변경 이벤트 전송
*/
private initializeBackground;
/**
* AI 대화 시스템을 초기화합니다.
*
* 설정 작업:
* 1. 대화 설정 생성 (음성, 언어, AI 모델 등)
* 2. 대화 매니저 초기화
* 3. AI 응답 수신 이벤트 등록
* 4. 전체 시스템 준비 완료 처리
*/
private initializeConversationManager;
/**
* ConversationManager 초기화를 위한 config 객체를 생성합니다.
*/
private createConversationConfig;
/**
* 아바타의 직업 설명을 생성합니다.
*/
private buildJobDescription;
/**
* 클라이언트 상태를 업데이트하고 관련 콜백을 호출합니다.
*
* @param updates - 업데이트할 상태 항목들
*/
private updateState;
/**
* 클라이언트 상태를 초기화합니다.
*
* 수행 작업:
* 1. connection, recording, streaming, conversation 상태를 기본값으로 초기화
* 2. MediaRecorder 및 녹음된 Blob 참조 제거
* 3. 초기화 여부 플래그(isInitialized) false로 설정
* 4. container의 DOM 내용을 비움
* 5. 메시지 content 캐시 초기화
*/
private resetState;
/**
* 에러를 처리합니다.
*
* 수행 작업:
* 1. 에러 카운트 및 마지막 에러 발생 시간 갱신
* 2. 콘솔과 내부 로그에 에러 메시지 출력
* 3. connection 상태를 "error"로 업데이트
* 4. onError 콜백 호출 (외부에서 에러를 처리할 수 있도록 전달)
*
* @param error 발생한 에러 객체
*/
private handleError;
private handleConverSationError;
private handleRoomError;
/**
* 로그 메시지를 출력합니다.
*
* 수행 작업:
* 1. 콘솔에 로그 메시지 출력
* 2. onLog 콜백 호출 (외부에서 로그를 수집하거나 표시 가능)
*
* @param message 출력할 로그 메시지
*/
private log;
}