@vibexnpm/talkx 2.3.1

package/types/index.d.ts

@@ -0,0 +1,1771 @@
+// Type definitions for @vibexnpm/talkflow
+// TalkFlow SDK - Chat & WebRTC unified client
+//
+// 본 파일은 공개 API 의 정적 타입 계약을 정의합니다.
+// 소스 ({@code src/*.js}) 는 JavaScript + JSDoc 으로 작성되어 있으며,
+// 여기 정의는 README 에 명시된 공개 API 를 기준으로 유지합니다.
+//
+// 수정 시 주의: 소스의 공개 메서드/이벤트가 추가되거나 시그니처가 바뀌면 이 파일도 함께 갱신.
+//
+// ESM (package.json "type": "module") — default export + named exports.
+
+// ============================================================================
+// Constants (enum-like readonly records)
+// ============================================================================
+
+export const ConnectionState: {
+    readonly DISCONNECTED: 'disconnected';
+    readonly CONNECTING: 'connecting';
+    readonly CONNECTED: 'connected';
+    readonly RECONNECTING: 'reconnecting';
+    readonly ERROR: 'error';
+};
+export type ConnectionStateValue = typeof ConnectionState[keyof typeof ConnectionState];
+
+export const ErrorTypes: {
+    readonly CONNECTION_FAILED: 'CONNECTION_FAILED';
+    readonly CONNECTION_LOST: 'CONNECTION_LOST';
+    readonly CONNECTION_TIMEOUT: 'CONNECTION_TIMEOUT';
+    readonly JWT_INVALID: 'JWT_INVALID';
+    readonly JWT_EXPIRED: 'JWT_EXPIRED';
+    readonly JWT_PARSE_FAILED: 'JWT_PARSE_FAILED';
+    readonly UNAUTHORIZED: 'UNAUTHORIZED';
+    readonly API_ERROR: 'API_ERROR';
+    readonly API_TIMEOUT: 'API_TIMEOUT';
+    readonly CHAT_ROOM_NOT_FOUND: 'CHAT_ROOM_NOT_FOUND';
+    readonly CHAT_MESSAGE_FAILED: 'CHAT_MESSAGE_FAILED';
+    readonly CHAT_SUBSCRIPTION_FAILED: 'CHAT_SUBSCRIPTION_FAILED';
+    readonly MEDIA_ACCESS_DENIED: 'MEDIA_ACCESS_DENIED';
+    readonly SCREEN_SHARE_DENIED: 'SCREEN_SHARE_DENIED';
+    readonly PEER_CONNECTION_FAILED: 'PEER_CONNECTION_FAILED';
+    readonly ICE_CONNECTION_FAILED: 'ICE_CONNECTION_FAILED';
+    readonly SIGNALING_FAILED: 'SIGNALING_FAILED';
+    readonly DEVICE_SWITCH_FAILED: 'DEVICE_SWITCH_FAILED';
+    readonly ENUMERATE_DEVICES_FAILED: 'ENUMERATE_DEVICES_FAILED';
+    readonly CALL_ROOM_NOT_FOUND: 'CALL_ROOM_NOT_FOUND';
+    readonly INVALID_STATE: 'INVALID_STATE';
+    readonly UNKNOWN_ERROR: 'UNKNOWN_ERROR';
+};
+export type ErrorTypeValue = typeof ErrorTypes[keyof typeof ErrorTypes];
+
+export const SignalTypes: {
+    readonly CALL_OFFER: 'call_offer';
+    readonly CALL_ANSWER: 'call_answer';
+    readonly ICE_CANDIDATE: 'ice_candidate';
+    readonly JOIN_ROOM: 'join_room';
+    readonly LEAVE_ROOM: 'leave_room';
+    readonly PEER_JOINED: 'peer_joined';
+    readonly PEER_LEFT: 'peer_left';
+    readonly VIDEO_STATE_CHANGED: 'video_state_changed';
+    readonly AUDIO_STATE_CHANGED: 'audio_state_changed';
+    readonly SCREEN_SHARE_STARTED: 'screen_share_started';
+    readonly SCREEN_SHARE_ENDED: 'screen_share_ended';
+    readonly CALL_REQUEST: 'call_request';
+    readonly CALL_ACCEPT: 'call_accept';
+    readonly CALL_REJECT: 'call_reject';
+    readonly CALL_CANCEL: 'call_cancel';
+    readonly CALL_END: 'call_end';
+    readonly CALL_INVITATION: 'call_invitation';
+    readonly CALL_BUSY: 'call_busy';
+};
+
+/**
+ * SDK 가 런타임에 export 하는 ChatMessageType 상수.
+ * <p><b>런타임 소스와 정확히 일치</b>: {@code src/constants.js} 에 정의된 6개 값만 포함.
+ * {@code DOCUMENT / GALLERY} 는 SDK 상수에 없음 — 서버 응답 메시지의 {@code chatMessageType}
+ * 필드로는 수신될 수 있으므로 {@link ChatMessageTypeValue} 는 해당 값을 포함한 union.</p>
+ */
+export const ChatMessageType: {
+    readonly TEXT: 'TEXT';
+    readonly IMAGE: 'IMAGE';
+    readonly FILE: 'FILE';
+    readonly VIDEO: 'VIDEO';
+    readonly AUDIO: 'AUDIO';
+    readonly SYSTEM: 'SYSTEM';
+};
+
+/**
+ * 서버가 보낼 수 있는 메시지 타입 값 전체.
+ * <p>SDK 상수 ({@link ChatMessageType}) 의 6개 값 + 서버에서만 쓰는 {@code DOCUMENT / GALLERY}.
+ * 수신 {@link ChatMessage#chatMessageType} 비교 시 이 union 을 사용.</p>
+ */
+export type ChatMessageTypeValue =
+    | 'TEXT' | 'IMAGE' | 'FILE' | 'VIDEO' | 'AUDIO' | 'SYSTEM'
+    | 'DOCUMENT' | 'GALLERY';
+
+export const ChatRoomType: {
+    readonly DIRECT: 'DIRECT';
+    readonly GROUP: 'GROUP';
+    readonly PRIVATE_GROUP: 'PRIVATE_GROUP';
+    /** 팀 채팅방 — 초대 전용 + 입장 시점 무관 전체 히스토리. 비참여자에게 목록 비노출. 비밀번호 없음. */
+    readonly TEAM: 'TEAM';
+};
+export type ChatRoomTypeValue = typeof ChatRoomType[keyof typeof ChatRoomType];
+
+export const AssistantMode: {
+    readonly GENERAL: 'GENERAL';
+    readonly PEOPLE_ONLY: 'PEOPLE_ONLY';
+    readonly CALL_ONLY: 'CALL_ONLY';
+};
+export type AssistantModeValue = typeof AssistantMode[keyof typeof AssistantMode];
+
+/**
+ * 방의 AI 사용 방식 (상위 SSOT) — 서버 {@code RoomAiType} enum 과 일치.
+ * <p>{@link CreateGroupRoomData.roomAiType} 으로 방 생성 시 의도를 명시. 미지정 시 서버가 키 권한 + 페르소나로 파생.</p>
+ */
+export const RoomAiType: {
+    /** AI 미사용 — 순수 사람 채팅. persona/assistantMode 동시 지정 불가. */
+    readonly NONE: 'NONE';
+    /** 다중 페르소나, LLM 이 판단해 호출. {@code assistantMode} 로 세부 제어. (현재 유일 활성) */
+    readonly PERSONA_MULTI: 'PERSONA_MULTI';
+    /** PM + 백스테이지. PM 단일 응답 구현됨 — {@code engagementIntensity} 로 개입 강도 제어. 백스테이지 위임은 후속. */
+    readonly PM_BACKSTAGE: 'PM_BACKSTAGE';
+};
+export type RoomAiTypeValue = typeof RoomAiType[keyof typeof RoomAiType];
+
+/**
+ * PM_BACKSTAGE 방의 PM 개입 강도 — 서버 {@code EngagementIntensity} enum 과 일치.
+ * <p>PM_BACKSTAGE 방 전용(그 외 타입에 지정 시 서버 거절). 14인 PERSONA_MULTI 는 쿨다운+Planner 자동이라 무관.</p>
+ */
+export const EngagementIntensity: {
+    /** 보수적 — 명확한 질문/도움 요청에만 PM 응답. */
+    readonly QUIET: 'QUIET';
+    /** 기본 — 업무 신호에 응답, 잡담엔 침묵. */
+    readonly NORMAL: 'NORMAL';
+    /** 적극 — 가벼운 신호에도 응답. */
+    readonly ACTIVE: 'ACTIVE';
+};
+export type EngagementIntensityValue = typeof EngagementIntensity[keyof typeof EngagementIntensity];
+
+/**
+ * PM 프롬프트 레이어 차원 — 서버 {@code PmPromptLayerScope} enum 과 일치.
+ * <p>전역 PM 프롬프트 위에 합성되는 추가 지시문 2종 (합성 순서: 전역 → PROJECT → ROOM).
+ * SDK 가 다루는 것은 ROOM(방 레이어)이며 PROJECT(회사 레이어)는 어드민 콘솔 영역.</p>
+ */
+export const PmPromptLayerScope: {
+    /** 회사(프로젝트) 레이어 — 어드민 콘솔(PROJECT_ADMIN) 관리. */
+    readonly PROJECT: 'PROJECT';
+    /** 방 레이어 — 방 주인(OWNER) 관리. PM_BACKSTAGE 방 전용. */
+    readonly ROOM: 'ROOM';
+};
+export type PmPromptLayerScopeValue = typeof PmPromptLayerScope[keyof typeof PmPromptLayerScope];
+
+/** PM 프롬프트 레이어 수정 주체 (감사 추적) — 서버 {@code PmPromptLayerEditorType} enum 과 일치. */
+export const PmPromptLayerEditorType: {
+    /** 플랫폼 운영자 (대리 수정). */
+    readonly SUPER_ADMIN: 'SUPER_ADMIN';
+    /** 회사 관리자 — PROJECT 레이어. */
+    readonly PROJECT_ADMIN: 'PROJECT_ADMIN';
+    /** 방 주인(OWNER) — ROOM 레이어. */
+    readonly ROOM_OWNER: 'ROOM_OWNER';
+};
+export type PmPromptLayerEditorTypeValue = typeof PmPromptLayerEditorType[keyof typeof PmPromptLayerEditorType];
+
+/** 방 AI 메타 — 현재 키로 생성 가능한 roomAiType 목록 ({@link ChatClient.getRoomAiMeta}). 키 권한으로 결정. */
+export interface RoomAiMetaResponse {
+    /** 생성 가능한 roomAiType — {@code 'NONE'} 항상, {@code 'PERSONA_MULTI'}/{@code 'PM_BACKSTAGE'} 는 권한 보유 시.
+     *  고른 타입은 {@link CreateGroupRoomData.roomAiType} 으로 명시 전송 필수 (미전송 시 PM 전용 키는 NONE 으로 파생). */
+    availableRoomAiTypes: RoomAiTypeValue[];
+}
+
+/**
+ * 메시지 발신자 타입 — 서버 {@code SenderType} enum 과 일치.
+ *
+ * <p>USER 메시지는 응답에서 senderType 이 생략될 수 있음 (서버가 {@code NON_NULL} 직렬화).
+ * 어시스턴트 메시지에만 {@code 'ASSISTANT'} 값으로 표시 — 클라이언트는 이 값으로 어시 메시지 마킹.</p>
+ */
+export const SenderType: {
+    readonly USER: 'USER';
+    readonly ASSISTANT: 'ASSISTANT';
+};
+export type SenderTypeValue = typeof SenderType[keyof typeof SenderType];
+
+/** 어시스턴트 페르소나 분류 — 서버 {@code PersonaRole} enum 과 일치 (14개). {@code PM} 은 PM_BACKSTAGE 단일 PM 전용. */
+export const PersonaRole: {
+    readonly LEGAL_ADVISOR: 'LEGAL_ADVISOR';
+    readonly MARKETING: 'MARKETING';
+    readonly PRODUCT_PLANNING: 'PRODUCT_PLANNING';
+    readonly HR: 'HR';
+    readonly FINANCE: 'FINANCE';
+    readonly CUSTOMER_SUPPORT: 'CUSTOMER_SUPPORT';
+    readonly SALES: 'SALES';
+    readonly ENGINEERING: 'ENGINEERING';
+    readonly DATA_ANALYST: 'DATA_ANALYST';
+    readonly PROJECT_MANAGEMENT: 'PROJECT_MANAGEMENT';
+    readonly RESEARCH: 'RESEARCH';
+    readonly TRANSLATION: 'TRANSLATION';
+    readonly DESIGN: 'DESIGN';
+    /** PM_BACKSTAGE 전용 — PM Front 단일 응답 (PERSONA_MULTI 14인과 별개). */
+    readonly PM: 'PM';
+};
+export type PersonaRoleValue = typeof PersonaRole[keyof typeof PersonaRole];
+
+/**
+ * 채팅 요약 포맷 — 서버 {@code SummarizeFormat} enum 과 일치 (5개).
+ * {@link ChatClient.summarizeWithAssistant} 의 {@code format} 인자. 미지정 시 서버 기본값 {@code SHORT}.
+ */
+export const SummarizeFormat: {
+    /** 회의록 — 참석/안건/핵심 논의/결정사항. */
+    readonly MINUTES: 'MINUTES';
+    /** 짧은 요약 — 몇 문장 핵심. 기본값. */
+    readonly SHORT: 'SHORT';
+    /** 시간순 타임라인. */
+    readonly TIMELINE: 'TIMELINE';
+    /** 액션 아이템 — task/owner/기한. */
+    readonly ACTIONS: 'ACTIONS';
+    /** 옵션 비교 — 논의된 선택지별 장단점. */
+    readonly OPTIONS: 'OPTIONS';
+};
+export type SummarizeFormatValue = typeof SummarizeFormat[keyof typeof SummarizeFormat];
+
+/**
+ * 어시스턴트 응답 — {@link ChatClient.getAssistants} 반환 항목.
+ *
+ * <p>방 생성 시 {@code id} 를 {@link CreateGroupRoomData#invitedAssistantPersonaIds} 로 전달.</p>
+ */
+export interface AssistantPersonaResponse {
+    /** 어시스턴트 식별자. 방에 추가할 때 이 값을 전달. */
+    id: string;
+    /** UI 표시명. 멘션 대상 (예: {@code @법률자문관}). */
+    displayName: string;
+    /** 영문 alias. 멘션 대상 (예: {@code @legal}). */
+    mentionKey: string;
+    /** 분류 (UI 카테고리 / 정렬 등). */
+    role: PersonaRoleValue;
+}
+
+/**
+ * 어시스턴트 도구 실행 결과 — 서버 {@code AssistantToolResult}.
+ * {@link ChatClient.summarizeWithAssistant} / {@link ChatClient.translateWithAssistant} 반환.
+ */
+export interface AssistantToolResult {
+    /**
+     * 실행 결과.
+     * <ul>
+     *   <li>{@code 'EMITTED'} — 어시스턴트 메시지 생성됨 ({@code messageId} 존재).</li>
+     *   <li>{@code 'SKIPPED'} — 정책상 미실행 ({@code detail} 에 사유).</li>
+     *   <li>{@code 'FAILED'} — 실행 실패 ({@code detail} 에 사유).</li>
+     * </ul>
+     */
+    outcome: 'EMITTED' | 'SKIPPED' | 'FAILED';
+    /** 생성된 메시지 ID. {@code outcome === 'EMITTED'} 일 때만 존재, 그 외 null. */
+    messageId: string | null;
+    /** SKIPPED / FAILED 사유. EMITTED 일 때 null. */
+    detail: string | null;
+}
+
+/** {@link ChatClient.summarizeWithAssistant} 옵션 — 서버 {@code SummarizeToolRequest}. */
+export interface SummarizeToolRequest {
+    /** 요약을 수행할 어시스턴트 ID ({@link AssistantPersonaResponse.id}). 필수. */
+    personaId: string;
+    /** 요약 포맷. 미지정 시 서버 기본값 {@code SHORT}. */
+    format?: SummarizeFormatValue;
+    /** 요약 대상 최근 메시지 수 (1~50). 미지정 시 서버 기본값. */
+    messageCount?: number;
+}
+
+/** {@link ChatClient.translateWithAssistant} 옵션 — 서버 {@code TranslateToolRequest}. */
+export interface TranslateToolRequest {
+    /** 번역을 수행할 어시스턴트 ID ({@link AssistantPersonaResponse.id}). 필수. */
+    personaId: string;
+    /** 번역 대상 메시지의 {@code messageId}. 필수. */
+    sourceMessageId: string;
+    /** 목표 언어 (예: {@code 'en'}). 미지정 시 서버 정책. */
+    targetLang?: string;
+}
+
+/**
+ * PM 프롬프트 레이어 — 서버 {@code PmPromptLayerResponse}.
+ *
+ * <p>전역 PM 프롬프트에 <b>합성</b>되는 추가 지시문 (교체 아님). SDK 의 방 레이어 메서드
+ * ({@link ChatClient.getRoomPmPrompt} 등)는 {@code scope === 'ROOM'} 인 레이어만 다룬다.
+ * PM_BACKSTAGE 방 전용 — PM(role=PM) 응답에만 반영.</p>
+ */
+export interface PmPromptLayerResponse {
+    /** 레이어 식별자. */
+    id: string;
+    /** 레이어 차원 — 방 레이어 API 에서는 항상 {@code 'ROOM'}. */
+    scope: PmPromptLayerScopeValue;
+    /** 소속 프로젝트(회사) ID. */
+    projectId: string;
+    /** 방 ID — {@code scope === 'ROOM'} 일 때 존재. PROJECT 레이어는 필드 생략(서버 NON_NULL 직렬화). */
+    roomId?: string;
+    /** 레이어 본문 (방 레이어 한도 2,000자). */
+    content: string;
+    /** 합성 포함 여부 — {@code false} 면 보존된 채 합성에서만 제외(soft delete). */
+    active: boolean;
+    /** 현재 라이브 본문에 해당하는 활성 버전 번호. 이력이 없는 레거시 데이터는 생략될 수 있다. */
+    activeVersion?: number;
+    /** 마지막 수정 주체. */
+    editorType: PmPromptLayerEditorTypeValue;
+    /** 마지막 수정 시각 (ISO-8601 문자열). */
+    updatedAt: string;
+}
+
+/** PM 프롬프트 레이어 버전 이력 항목 — 서버 {@code PmPromptLayerVersionResponse}. */
+export interface PmPromptLayerVersionResponse {
+    /** 버전 번호 (1부터 증가). {@link ChatClient.activateRoomPmPromptVersion} 에 전달. */
+    version: number;
+    /** 해당 버전의 본문. */
+    content: string;
+    /** 현재 활성 버전이면 {@code true}(layerId 당 1개). 실제 합성 적용 여부는 단건 응답의 active 와 함께 판단. */
+    active: boolean;
+    /** 해당 버전을 만든 주체. */
+    editorType: PmPromptLayerEditorTypeValue;
+    /** 버전 생성 시각 (ISO-8601 문자열). */
+    createdAt: string;
+}
+
+/**
+ * PM 프롬프트 합성 미리보기 — 서버 {@code PmPromptPreviewResponse}.
+ * <p>전역(+회사)(+방) 레이어 합성 결과 SYSTEM 본문. 컨텍스트 정책 등 런타임 부착분은 미포함.</p>
+ */
+export interface PmPromptPreviewResponse {
+    /** 합성된 최종 프롬프트 본문. */
+    composedPrompt: string;
+}
+
+/**
+ * {@link ChatClient.inviteToGroupRoom} 의 신규 형식 입력. 회원 / 어시스턴트 동시 초대 지원.
+ * 둘 중 하나 이상 필수.
+ */
+export interface InviteToRoomData {
+    /** 초대할 회원 ID 배열 (max 50). */
+    userIds?: string[];
+    /** 추가할 어시스턴트 ID 배열 (max 10). {@link ChatClient.getAssistants} 결과의 {@code id}. */
+    assistantPersonaIds?: string[];
+}
+
+export const RoomListEventType: {
+    readonly MESSAGE_RECEIVED: 'MESSAGE_RECEIVED';
+    readonly MESSAGE_DELETED: 'MESSAGE_DELETED';
+    readonly MESSAGE_UPDATED: 'MESSAGE_UPDATED';
+    readonly ROOM_CREATED: 'ROOM_CREATED';
+    readonly ROOM_JOINED: 'ROOM_JOINED';
+    readonly ROOM_LEFT: 'ROOM_LEFT';
+    readonly ROOM_UPDATED: 'ROOM_UPDATED';
+    readonly ROOM_KICKED: 'ROOM_KICKED';
+    readonly ROOM_BANNED: 'ROOM_BANNED';
+    readonly MESSAGE_RETENTION_CLEANUP: 'MESSAGE_RETENTION_CLEANUP';
+};
+export type RoomListEventTypeValue = typeof RoomListEventType[keyof typeof RoomListEventType];
+
+export const LogLevel: {
+    readonly DEBUG: 0;
+    readonly INFO: 1;
+    readonly WARN: 2;
+    readonly ERROR: 3;
+    readonly NONE: 4;
+};
+export type LogLevelValue = typeof LogLevel[keyof typeof LogLevel];
+
+export const Environment: {
+    readonly DEVELOPMENT: 'development';
+    readonly STAGING: 'staging';
+    readonly PRODUCTION: 'production';
+};
+export type EnvironmentValue = typeof Environment[keyof typeof Environment];
+
+export const Endpoints: Record<EnvironmentValue, { serverUrl: string; wsEndpoint: string }>;
+
+export const WebSocketPaths: {
+    readonly SOCKJS_ENDPOINT: string;
+    readonly NATIVE_ENDPOINT: string;
+    readonly APP_PREFIX: string;
+    readonly TOPIC_PREFIX: string;
+    readonly QUEUE_PREFIX: string;
+    readonly USER_PREFIX: string;
+    getChatDestination(roomId: string): string;
+    getChatReadDestination(roomId: string): string;
+    getChatTypingDestination(roomId: string): string;
+    readonly ROOM_LIST_USER_DESTINATION: string;
+    getWebRTCDestination(roomId: string): string;
+    getWebRTCUserDestination(): string;
+    readonly CHAT_SEND: string;
+    readonly CHAT_READ: string;
+    readonly CHAT_TYPING: string;
+    readonly WEBRTC_SIGNAL: string;
+};
+
+export const DefaultConfig: {
+    readonly environment: EnvironmentValue;
+    readonly reconnectDelay: number;
+    readonly maxReconnectAttempts: number;
+    readonly heartbeatIncoming: number;
+    readonly heartbeatOutgoing: number;
+    readonly apiTimeout: number;
+    readonly iceServers: RTCIceServer[];
+    readonly logLevel: LogLevelValue;
+};
+
+export function getServerUrl(env: EnvironmentValue | string): string;
+
+// ============================================================================
+// Domain / DTO types
+// ============================================================================
+
+/**
+ * JSON 호환 값 — string / number / boolean / null / 중첩 배열·객체.
+ * <p>{@code Date} / {@code Map} / {@code Set} / 함수 / {@code undefined} / 순환 객체는 컴파일 타임에 거부.</p>
+ */
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | JsonValue[] | { [key: string]: JsonValue };
+
+/**
+ * 고객사 UI 용 opaque pass-through metadata.
+ *
+ * <p>서버는 해석하지 않고 저장 / 응답·이벤트로 그대로 반환한다. 스티커 / 커스텀 첨부 타입 /
+ * 렌더링 힌트처럼 SDK·서버가 의미를 몰라도 되는 값을 자유 schema 로 주고받는 용도.</p>
+ *
+ * <p><b>제약</b>:</p>
+ * <ul>
+ *   <li>JSON 직렬화 가능한 값만 — {@link JsonValue} 로 컴파일 타임 강제</li>
+ *   <li>키에 {@code "."} 포함 또는 {@code "$"} 시작 금지 — Mongo BSON 제약. 위반 시 서버 400</li>
+ *   <li>권장 사이즈: 파일 1개당 직렬화 후 1-2KB. 서버 상한 4KB 초과 시 400</li>
+ *   <li>멱등 retry 시 첫 호출의 metadata 가 유지됨</li>
+ * </ul>
+ */
+export type FileCustomMetadata = { [key: string]: JsonValue };
+
+/** 파일 메타데이터 (이미지/영상/오디오/문서). */
+export interface FileMetaData {
+    fileUrl: string;
+    fileName?: string;
+    fileSize?: number;
+    contentType?: string;
+    imageInfo?: {
+        width?: number;
+        height?: number;
+        /**
+         * 업로드 시 자동 생성된 JPEG 썸네일 URL (최대 변 300px, 품질 85%, EXIF 회전/알파 배경 처리 완료).
+         * 생성 실패 (초고해상도 / 서버 부하 / 디코드 오류) 시 undefined —
+         * 클라는 `thumbnailUrl ?? fileUrl` fallback 으로 원본 사용.
+         */
+        thumbnailUrl?: string;
+    };
+    videoInfo?: {
+        duration?: number;
+        width?: number;
+        height?: number;
+        thumbnailUrl?: string;
+    };
+    audioInfo?: {
+        duration?: number;
+    };
+    documentInfo?: {
+        pageCount?: number;
+        thumbnailUrl?: string;
+    };
+    /**
+     * 고객사 pass-through metadata. {@link FileCustomMetadata} 참고.
+     *
+     * <p>업로드 응답에는 보통 비어 있으며, 고객사가 메시지 전송 시 채워서 보내면
+     * 메시지 응답·수신 이벤트의 {@code fileMetaDataList[i].metadata} 로 동일 값이 돌아온다.</p>
+     */
+    metadata?: FileCustomMetadata;
+}
+
+/** 리액션 항목 — 이모지 + 누른 사용자들. */
+export interface ReactionResponse {
+    emoji: string;
+    users: Array<{
+        userId: string;
+        nickName?: string | null;
+        profileUrl?: string | null;
+    }>;
+}
+
+/** 답글 대상 원본 메시지 snapshot. */
+export interface ReplyToSnapshot {
+    messageId: string;
+    senderId: string;
+    senderName: string;
+    contentPreview: string;
+    messageType: ChatMessageTypeValue;
+    sentAt: number;
+    fileUrl?: string | null;
+}
+
+/**
+ * 실시간 WebSocket 이벤트에만 실리는 이벤트 종류 식별자.
+ * <p>REST 히스토리 응답에는 이 필드가 없음. 클라이언트는 실시간 분기에만 사용.</p>
+ */
+export type ChatMessageEventTypeValue =
+    | 'MESSAGE_CREATED'
+    | 'MESSAGE_UPDATED'
+    | 'MESSAGE_DELETED'
+    | 'REACTION_CHANGED'
+    | 'LINK_PREVIEW_ATTACHED'
+    | 'MESSAGE_TRANSLATED';
+
+/**
+ * 링크 미리보기 snapshot.
+ * <p>REST/WebSocket 공통. 서버가 비동기로 채우며, OG 파싱 실패 시 도메인 + favicon 기반
+ * 최소 카드가 내려올 수 있다. 유효하지 않거나 안전하지 않은 URL 은 필드 자체가 부재.</p>
+ */
+export interface LinkPreviewResponse {
+    url: string;
+    title?: string | null;
+    description?: string | null;
+    imageUrl?: string | null;
+    siteName?: string | null;
+    type?: string | null;
+    previewSource?: 'OG' | 'FAVICON_FALLBACK' | null;
+}
+
+/** 수동 링크 미리보기 조회 응답. */
+export interface FetchLinkPreviewResponse extends LinkPreviewResponse {
+    finalUrl: string;
+    fetchedAt: string;
+    /** @deprecated 서버는 imageUrl 을 사용합니다. */
+    image?: string | null;
+}
+
+/** 단일 메시지 DTO. */
+export interface ChatMessage {
+    id: string;
+    messageId: string;
+    roomId: string;
+    userId: string;
+    /**
+     * 발신자 타입. {@code 'USER'} 메시지에는 서버가 이 필드를 응답에서 생략 (NON_NULL).
+     * {@code 'ASSISTANT'} 면 {@code userId} 가 페르소나 ID 이며 클라이언트는 어시 메시지로 마킹.
+     */
+    senderType?: SenderTypeValue;
+    /** 발신자 표시명. 서버가 응답 시 enrich (NON_NULL — 없으면 생략). */
+    nickName?: string;
+    /** 발신자 프로필 이미지 URL. */
+    profileUrl?: string | null;
+    /** 발신자의 프로젝트 스코프 사용자 ID. */
+    projectUserId?: string;
+    content: string | null;
+    chatMessageType: ChatMessageTypeValue;
+    chatType: string;
+    roomType: ChatRoomTypeValue;
+    sentAt: number;
+    unreadCount?: number | null;
+    fileMetaDataList?: FileMetaData[] | null;
+    deletedStatus?: 'DELETED' | null;
+    edited?: boolean;
+    editedAt?: number | null;
+    reactions?: ReactionResponse[];
+    replyTo?: ReplyToSnapshot | null;
+    /** WebSocket 이벤트에만 존재 — REST 응답에는 없음. */
+    eventType?: ChatMessageEventTypeValue;
+    /** Open Graph 미리보기. 서버가 비동기 첨부 성공 시 값 존재, 실패/미첨부 시 null/undefined. */
+    linkPreview?: LinkPreviewResponse | null;
+    /** 감지된 원문 언어 (BCP-47). 서버가 비동기 번역 후 채움 (다국어). 미번역 시 부재. */
+    sourceLang?: string | null;
+    /**
+     * 언어 코드 → 번역문 맵. 서버가 비동기 번역 후 채우고 {@code MESSAGE_TRANSLATED} 로 패치.
+     * <p>표시: {@code translations[myLang] ?? content} (원문 토글 권장). 같은 언어/원문 수신자는 키 부재 →
+     * {@code content} fallback. {@code MESSAGE_UPDATED}(편집) 수신 시 서버가 비워 보내므로 교체/클리어 필요.</p>
+     */
+    translations?: Record<string, string> | null;
+    /** 번역 당시 content 해시 — stale 판별용 (내부). */
+    translationsOf?: string | null;
+}
+
+/** 채팅방 참가자. */
+export interface ParticipantResponse {
+    userId: string;
+    nickName?: string;
+    profileUrl?: string | null;
+    projectUserId?: string;
+    /**
+     * 참가자 역할 — 서버 {@code ParticipantRole} enum 과 일치.
+     * <ul>
+     *   <li>{@code OWNER} — 방 주인 (그룹방 생성자, 방당 1명). 방장 기능 + PM 프롬프트 레이어 쓰기 전용 권한.</li>
+     *   <li>{@code ADMIN} — 위임 관리자. 방장 기능(설정/추방/차단/고정/초대)은 OWNER 와 동일하나
+     *       PM 프롬프트 레이어 쓰기는 불가. (승급 API 는 후속 — 현재 신규 부여 경로 없음)</li>
+     *   <li>{@code MEMBER} — 일반 사용자</li>
+     *   <li>{@code ASSISTANT} — 어시스턴트 페르소나 ({@code userId} = personaId). UI 에서 봇 배지 등 별도 표시 권장.</li>
+     * </ul>
+     * <p>기존(OWNER 도입 전) 생성 방의 생성자는 서버 부팅 시 backfill 로 OWNER 전환된다 —
+     * 과도기 동안 {@code ADMIN} 생성자가 보일 수 있으나 권한은 동일.</p>
+     */
+    role: 'OWNER' | 'ADMIN' | 'MEMBER' | 'ASSISTANT';
+    joinedAt: string;
+}
+
+/** 채팅방 last message preview. */
+export interface LastMessageResponse {
+    messageId: string;
+    senderId: string;
+    senderName: string;
+    senderProfileUrl?: string | null;
+    content: string;
+    messageType: string;
+    sentAt: string;
+    /**
+     * 파일 메시지일 때 첫 파일의 사용자 metadata (opaque pass-through).
+     * <p>고객사가 파일 업로드 시 함께 보낸 데이터 (스티커 ID 등) 가 채팅방 리스트에서도 식별 가능하도록 보존.
+     * 텍스트/시스템 메시지에서는 undefined.</p>
+     */
+    metadata?: Record<string, unknown> | null;
+    /**
+     * IMAGE / GALLERY / VIDEO / DOCUMENT 메시지의 첫 파일 썸네일 URL.
+     * <p>채팅방 리스트에서 카톡식 작은 미리보기 이미지로 사용. 텍스트/AUDIO/FILE/SYSTEM 또는
+     * 썸네일 생성 실패 시 undefined.</p>
+     */
+    thumbnailUrl?: string | null;
+}
+
+/** 채팅방 DTO. */
+export interface ChatRoomResponse {
+    id: string;
+    projectId: string;
+    roomType: ChatRoomTypeValue;
+    /** 어시스턴트 참여 모드. 구버전 서버 응답에서는 없을 수 있음. */
+    assistantMode?: AssistantModeValue;
+    /** 방 AI 사용 방식 (상위 SSOT). 구버전 서버 응답에서는 없을 수 있음. */
+    roomAiType?: RoomAiTypeValue;
+    /** PM 개입 강도 (PM_BACKSTAGE 방 전용). 그 외 방 타입/구버전 응답에서는 없을 수 있음. */
+    engagementIntensity?: EngagementIntensityValue;
+    roomName: string;
+    description?: string;
+    creatorId: string;
+    unreadCount?: number | null;
+    isParticipating?: boolean | null;
+    activeParticipantCount: number;
+    messageRetentionHours?: number | null;
+    anyoneCanInvite: boolean;
+    pinnedMessageId?: string | null;
+    participants?: ParticipantResponse[];
+    lastMessage?: LastMessageResponse | null;
+    lastMessageAt?: string | null;
+    createdAt: string;
+}
+
+/** 커서 페이지네이션 응답. */
+export interface CursorPageResponse<T> {
+    content: T[];
+    size: number;
+    hasNext: boolean;
+    lastId?: string | null;
+    lastSortValue?: number | string | null;
+}
+
+/**
+ * 서버 공통 성공 응답 래퍼 — 일부 메서드({@link ChatClient.getMessages})는 unwrap 하지 않고
+ * 이 래퍼째 반환한다 (기존 소비자의 {@code result.data.*} 접근 호환 유지).
+ */
+export interface ApiEnvelope<T> {
+    /** 실제 페이로드. */
+    data: T;
+    /** 서버 응답 코드/메시지 (존재 시). */
+    code?: string;
+    message?: string;
+}
+
+// ============================================================================
+// Event payloads
+// ============================================================================
+
+/**
+ * ROOM_UPDATED 이벤트의 방 메타 snapshot.
+ * <p>클라이언트는 {@link #roomListRoomUpdated} 수신 시 {@code event.room} 을 로컬 방 객체에 그대로 merge 하면 됨.
+ * 재조회(getRoomInfo) 불필요.</p>
+ */
+export interface RoomMeta {
+    roomName: string;
+    description: string | null;
+    messageRetentionHours: number | null;
+    anyoneCanInvite: boolean;
+    pinnedMessageId: string | null;
+    roomType: ChatRoomTypeValue;
+    /** ROOM_UPDATED 메타에 포함되는 어시스턴트 참여 모드. */
+    assistantMode?: AssistantModeValue;
+    /** ROOM_UPDATED 메타의 방 AI 사용 방식 (상위 SSOT). */
+    roomAiType?: RoomAiTypeValue;
+    /** ROOM_UPDATED 메타의 PM 개입 강도 (PM_BACKSTAGE 방 전용). */
+    engagementIntensity?: EngagementIntensityValue;
+}
+
+/** 채팅방 리스트 실시간 업데이트 이벤트. */
+export interface RoomListUpdateEvent {
+    eventType: RoomListEventTypeValue;
+    roomId: string;
+    actorId?: string;
+    cutoffTime?: number;
+    /** {@code ROOM_UPDATED} 전용 — 저장된 최신 메타 snapshot. 다른 eventType 에서는 undefined. */
+    room?: RoomMeta;
+    /**
+     * {@code MESSAGE_RECEIVED} 의 파일 메시지에 한해 채워지는 첫 파일의 사용자 metadata.
+     * 그 외 이벤트 또는 텍스트/시스템 메시지에서는 undefined.
+     */
+    lastMessageMetadata?: Record<string, unknown> | null;
+    /**
+     * {@code MESSAGE_RECEIVED} 의 IMAGE/GALLERY/VIDEO/DOCUMENT 메시지에 한해 채워지는 썸네일 URL.
+     * 클라가 채팅방 리스트에서 카톡식 작은 미리보기로 사용.
+     */
+    lastMessageThumbnailUrl?: string | null;
+    /**
+     * {@code MESSAGE_RECEIVED} / {@code MESSAGE_DELETED} / {@code MESSAGE_UPDATED} 일 때 메시지 ID.
+     * SDK 내부에서 같은 메시지의 중복 수신 (서버측 멱등 race 복구 등) dedup 용도. 다른 eventType 에서는 undefined.
+     */
+    messageId?: string;
+    [extra: string]: unknown;
+}
+
+/** 포그라운드 푸시 알림 payload. */
+export interface PushNotificationPayload {
+    title: string;
+    body: string;
+    data?: {
+        roomId?: string;
+        [k: string]: string | undefined;
+    };
+}
+
+/**
+ * 타이핑 이벤트.
+ *
+ * 두 종류 — `senderType` 으로 분기:
+ * - `USER` (default): 다른 사용자의 키 입력 표시. 호출자 클라이언트가 `startTyping()` 호출 시 발신.
+ * - `ASSISTANT`: 어시스턴트 응답 준비 중 신호. 서버는 `typing=true` 만 발행하며 `typing=false` 는 SDK 가
+ *   (1) 어시 메시지 도착 시 즉시 (2) client-side timeout (default 30초) 만료 시 자동 emit.
+ *   `userId` 는 generic marker (`__assistant__`), `userName` 은 "AI" 통칭.
+ */
+export interface TypingEvent {
+    roomId: string;
+    userId: string;
+    userName: string;
+    typing: boolean;
+    senderType: 'USER' | 'ASSISTANT';
+}
+
+// ============================================================================
+// Options — constructor & method
+// ============================================================================
+
+export interface TalkFlowClientOptions {
+    /** Client API 키 (브라우저 노출 안전). */
+    apiKey: string;
+    /** 프로젝트 ID. */
+    projectId: string;
+    /** JWT 토큰 — 고객사 backend 에서 발급 받아 전달. */
+    jwtToken?: string;
+    /** 환경. 기본 'production'. */
+    env?: EnvironmentValue | string;
+    /** 서버 URL 직접 지정 (env 무시). */
+    serverUrl?: string;
+    /** SockJS 사용 여부. 기본 true. */
+    useSockJS?: boolean;
+    /** 재연결 지연 (ms). 기본 5000. */
+    reconnectDelay?: number;
+    /** 최대 재연결 시도. 기본 10. */
+    maxReconnectAttempts?: number;
+    /** WebRTC ICE 서버. */
+    iceServers?: RTCIceServer[];
+    /** connect() 시 채팅방 리스트 자동 구독. 기본 true. */
+    autoSubscribeRoomList?: boolean;
+    /** 로그 레벨. 기본 WARN. */
+    logLevel?: LogLevelValue;
+}
+
+export interface ConnectOptions {
+    /** connect 와 동시에 푸시 활성화. 기본 false. */
+    enablePush?: boolean;
+}
+
+export interface EnablePushOptions {
+    /** Firebase 앱 설정 (고급). 기본 TalkFlow 내장. */
+    firebaseConfig?: Record<string, unknown>;
+    /** FCM VAPID 공개키. 기본 TalkFlow 내장. */
+    vapidKey?: string;
+    /** 서비스 워커 경로. 기본 '/firebase-messaging-sw.js'. */
+    serviceWorkerPath?: string;
+}
+
+export interface CursorPageParams {
+    /** 페이지 크기. 기본 50, max 100. */
+    size?: number;
+    /** 마지막 항목 ID. */
+    lastId?: string;
+    /** 마지막 정렬값 (epoch millis 등). */
+    lastSortValue?: number | string;
+    /** 방 리스트에서 타입 필터. */
+    type?: ChatRoomTypeValue;
+}
+
+/**
+ * 그룹 채팅방 생성 요청 body.
+ * <p>런타임 ({@code ChatClient.createGroupRoom}) 에서 실제로 읽는 필드와 이름/기본값 일치.</p>
+ */
+export interface CreateGroupRoomData {
+    /** 방 이름. 필수. max 100자. */
+    roomName: string;
+    /** 설명. 선택. max 500자. */
+    description?: string;
+    /** 초대할 사용자 내부 ID 배열. 선택. max 50명. */
+    invitedUserIds?: string[];
+    /**
+     * 방 타입. 생략 시 {@code 'GROUP'}.
+     * <p>{@code 'TEAM'} = 초대 전용(직접 join 불가) + 멤버는 입장 시점 무관 전체 히스토리 열람 +
+     * 비참여자에게 탐색/전체 목록 비노출. 비밀번호 금지.</p>
+     */
+    roomType?: ChatRoomTypeValue;
+    /** 비밀번호. {@code roomType === 'PRIVATE_GROUP'} 일 때만 의미 있고, 이 경우 필수 (SDK 가 사전 검증). 4~50자. {@code 'GROUP'}/{@code 'TEAM'} 에는 금지. */
+    password?: string;
+    /** 메시지 보관 기간 (시간). 1~8760. 미설정 시 무제한. */
+    messageRetentionHours?: number;
+    /**
+     * 방 생성 시 함께 추가할 어시스턴트 페르소나 ID 배열. max 10개.
+     * {@link ChatClient.getAssistants} 결과의 {@code id} 를 전달.
+     */
+    invitedAssistantPersonaIds?: string[];
+    /** 어시스턴트 참여 모드. 생략 시 서버 기본값 {@code GENERAL}. */
+    assistantMode?: AssistantModeValue;
+    /**
+     * 방 AI 사용 방식 (intent). 미지정 시 서버가 API 키 권한 + 첨부 페르소나로 파생 (레거시 호환).
+     * <p>{@code 'NONE'} 이면 {@code invitedAssistantPersonaIds}/{@code assistantMode} 동시 지정 불가 (서버 400).
+     * {@code 'PM_BACKSTAGE'} 는 PM 자동부착 — {@code invitedAssistantPersonaIds}/{@code assistantMode} 지정 불가,
+     * 대신 {@code engagementIntensity} 로 개입 강도 제어. 권한 없는 값 지정 시 403.</p>
+     * <p><b>함정:</b> PERSONA_MULTI 권한이 없는 PM 전용 키는 생략 시 파생이 {@code 'NONE'}(사람 방)으로 떨어진다
+     * (PM_BACKSTAGE 자동 승격 없음). {@link ChatClient.getRoomAiMeta} 로 확인한 타입을 반드시 명시 전송할 것.</p>
+     */
+    roomAiType?: RoomAiTypeValue;
+    /**
+     * PM 개입 강도. {@code 'PM_BACKSTAGE'} 방 전용 — 그 외 타입에 지정 시 서버 거절. 미지정 시 서버 기본값 {@code NORMAL}.
+     */
+    engagementIntensity?: EngagementIntensityValue;
+}
+
+/**
+ * 그룹 채팅방 설정 수정 body. null/undefined 필드는 변경 안 함.
+ * <p>런타임 ({@code ChatClient.updateGroupRoom}) 이 data 를 그대로 PUT 하므로 다른 필드는 무시됨.</p>
+ */
+export interface UpdateGroupRoomData {
+    roomName?: string;
+    description?: string;
+    /**
+     * 공개/비공개 전환 ({@code 'GROUP'} ↔ {@code 'PRIVATE_GROUP'}). 생략 시 변경 안 함.
+     * <p>{@code 'PRIVATE_GROUP'} 으로 전환 시 {@code password} 필수, {@code 'GROUP'} 으로 전환 시
+     * 기존 비밀번호는 서버가 제거한다. partial update 라 비번 필수 검증은 현재 방 상태 기준으로 서버가 수행한다
+     * ({@code 'PRIVATE_GROUP'} 전환에는 항상 새 {@code password} 필요 — 기존 해시 재사용 불가).</p>
+     * <p>{@code 'TEAM'} 은 전환 대상/타깃 모두 불가 — 타깃으로 보내면 400, TEAM 방 자체에
+     * roomType/password 변경 요청도 400 (멤버 히스토리 가시성 시맨틱 충돌로 미지원).</p>
+     */
+    roomType?: ChatRoomTypeValue;
+    /** PRIVATE_GROUP 비밀번호 변경/설정 시 사용. 공백만으로는 설정 불가. 4~50자. */
+    password?: string;
+    messageRetentionHours?: number;
+    /** 누구나 초대 가능 여부. */
+    anyoneCanInvite?: boolean;
+    /** 어시스턴트 참여 모드. */
+    assistantMode?: AssistantModeValue;
+    /** PM 개입 강도 ({@code 'PM_BACKSTAGE'} 방 전용). PM 참여 레벨 변경 — 키 PM_BACKSTAGE 권한 필요. */
+    engagementIntensity?: EngagementIntensityValue;
+}
+
+export interface SendMessageData {
+    /** @deprecated SDK 가 내부에서 UUID 를 자동 생성합니다. 지정해도 런타임에서 무시됩니다. */
+    messageId?: string;
+    message?: string;
+    fileInfos?: FileMetaData[];
+    separateFiles?: boolean;
+    replyToMessageId?: string;
+}
+
+export interface SendMessageResult {
+    duplicate: boolean;
+    messages: ChatMessage[];
+}
+
+/**
+ * Optimistic prediction 검증 메타데이터 — {@link OptimisticSendMessageResult} 에 첨부.
+ *
+ * <p>{@code predictionMatched: false} 면 서버의 파일 분류 규칙이 SDK 와 어긋난 것이며,
+ * 호출자는 placeholder 들을 제거하고 {@code actualMessageIds} 기준으로 재구성해야 한다.</p>
+ */
+export interface OptimisticPredictionInfo {
+    /** SDK 가 호출 시점에 예측한 messageId 배열. */
+    predictedMessageIds: string[];
+    /** 서버 응답의 실제 messageId 배열 — {@code result.messages.map(m => m.messageId)} 와 동일. */
+    actualMessageIds: string[];
+    /** 길이 + 값/순서가 모두 일치하는지 여부. {@code false} 면 drift 발생 — fallback reconcile 필요. */
+    predictionMatched: boolean;
+}
+
+/**
+ * Optimistic 계열 메서드의 promise 가 resolve 하는 타입.
+ * <p>일반 {@link SendMessageResult} 에 {@code optimistic} 메타데이터가 항상 첨부된다.</p>
+ */
+export interface OptimisticSendMessageResult extends SendMessageResult {
+    optimistic: OptimisticPredictionInfo;
+}
+
+/**
+ * Optimistic UI 핸들 — {@code sendMessageOptimistic} / {@code sendTextMessageOptimistic} /
+ * {@code sendReplyOptimistic} / {@code sendFileMessageOptimistic} 의 반환 타입.
+ *
+ * <p>SDK 가 서버의 messageId derivation 규칙 (텍스트=base, 파일=base#N) 을 mirror 하여
+ * 응답 {@code messages} 배열과 1-1 매칭되는 ID 배열을 promise 시작 전 동기 반환한다.</p>
+ *
+ * <p><b>Drift 방어</b>: 서버 파일 분류 규칙이 변경되면 prediction 이 어긋날 수 있으며,
+ * 이 경우 SDK 가 warn 로그를 남기고 promise 결과의 {@code optimistic.predictionMatched: false}
+ * 로 알린다. 호출자는 {@code result.optimistic.actualMessageIds} 로 fallback reconcile 한다.</p>
+ */
+export interface OptimisticSendMessageHandle {
+    /** SDK 가 생성한 base messageId — 서버 멱등 키. 응답 첫 메시지가 텍스트면 이 값과 동일. */
+    baseMessageId: string;
+    /**
+     * 예측된 전체 messageId 배열 — 응답 {@code messages} 와 같은 순서/길이.
+     * <ul>
+     *   <li>텍스트 단건: {@code [base]}</li>
+     *   <li>파일 1개 (text 없음): {@code [base]}</li>
+     *   <li>텍스트 + 파일들: {@code [base, base#0, base#1, ...]}</li>
+     *   <li>분리 다파일 (text 없음): {@code [base#0, base#1, ...]}</li>
+     * </ul>
+     */
+    messageIds: string[];
+    /**
+     * 실제 전송 promise — 일반 결과 + {@code optimistic} 메타데이터.
+     * {@code result.optimistic.predictionMatched} 가 {@code false} 면 drift fallback 필요.
+     */
+    promise: Promise<OptimisticSendMessageResult>;
+}
+
+/**
+ * 파일 업로드 진행률 payload.
+ * <p>런타임 {@code ChatClient.uploadFile} 이 {@code onProgress} 에 넘기는 단일 객체 인자.</p>
+ */
+export interface UploadProgressEvent {
+    loaded: number;
+    total: number;
+    percent: number;
+}
+
+/**
+ * {@code ChatClient.uploadFile} 옵션 — 단일 파일 업로드.
+ */
+export interface FileUploadOptions {
+    /**
+     * 단일 객체 인자를 받는 콜백 — 런타임 구현과 일치.
+     * <p>이전 공개 예시 "두 인자 (loaded, total)" 는 잘못된 계약이었으며 수정됨.</p>
+     */
+    onProgress?: (event: UploadProgressEvent) => void;
+    signal?: AbortSignal;
+}
+
+/**
+ * 다중 파일 진행률 payload — 단일 파일 {@link UploadProgressEvent} 에 {@code fileIndex} 추가.
+ */
+export interface SendFileMessageProgressEvent extends UploadProgressEvent {
+    /** 병렬 업로드 중인 파일의 0-based index. 단일 파일도 0. */
+    fileIndex: number;
+}
+
+/**
+ * {@code ChatClient.sendFileMessage} 옵션 — 업로드 + 메시지 전송 통합.
+ * <p>진행률 콜백 이름이 {@code onUploadProgress} 로 {@link FileUploadOptions#onProgress} 와 다름.
+ * 이 계약은 런타임 구현과 일치.</p>
+ */
+export interface SendFileMessageOptions {
+    /** 함께 보낼 텍스트. */
+    message?: string;
+    /** 파일별 개별 메시지 분리 여부. */
+    separateFiles?: boolean;
+    /** 답글 대상 원본 메시지의 서버 messageId. */
+    replyToMessageId?: string;
+    /** 업로드 중 취소용 AbortSignal. */
+    signal?: AbortSignal;
+    /**
+     * 파일별 진행률 콜백 — {@code fileIndex} 포함 단일 객체 인자.
+     * 이름이 {@code onProgress} 가 아님에 주의.
+     */
+    onUploadProgress?: (event: SendFileMessageProgressEvent) => void;
+    /**
+     * 고객사 pass-through metadata — 업로드 결과 {@link FileMetaData} 의 {@code metadata} 에 병합되어 전송된다.
+     *
+     * <ul>
+     *   <li>객체 1개: 모든 파일에 동일 metadata 부여 (broadcast)</li>
+     *   <li>배열: index 별 파일에 매핑. 빈 슬롯 ({@code null} / {@code undefined}) 은 해당 파일에 metadata 미부여</li>
+     * </ul>
+     *
+     * <p>{@code separateFiles: false} 로 묶이는 경우에도 각 파일의 {@code metadata} 는 자신의 값을 유지하므로,
+     * 그룹 메시지의 {@code fileMetaDataList[i].metadata} 가 i 별로 다를 수 있다.</p>
+     */
+    metadata?: FileCustomMetadata | Array<FileCustomMetadata | undefined | null>;
+}
+
+/** 메시지 삭제 종류. */
+export type DeleteType = 'ALL' | 'SELF';
+
+// ============================================================================
+// EventEmitter 기반 — on/off/emit
+// ============================================================================
+
+export interface SdkEventEmitter<EventMap> {
+    on<K extends keyof EventMap>(event: K, listener: (payload: EventMap[K]) => void): () => void;
+    once<K extends keyof EventMap>(event: K, listener: (payload: EventMap[K]) => void): () => void;
+    off<K extends keyof EventMap>(event: K, listener: (payload: EventMap[K]) => void): void;
+    emit<K extends keyof EventMap>(event: K, ...payload: EventMap[K] extends void ? [] : [EventMap[K]]): void;
+    removeAllListeners(event?: keyof EventMap): void;
+    listenerCount(event: keyof EventMap): number;
+}
+
+/**
+ * 각 클래스의 이벤트 payload 는 소스에서 실제 {@code this.emit(...)} 호출되는 그대로 반영.
+ * 런타임과 일치 보장이 목표이며, 새로 발견한 이벤트는 이 파일에 추가해야 함.
+ *
+ * <p><b>주의</b>: TalkFlowClient / ChatClient / WebRTCClient 는 각자 독립 이벤트 맵을 가짐.
+ * 같은 이벤트 이름이라도 다른 클래스에서는 payload 가 다를 수 있음 (특히 ChatClient 의
+ * {@code message} vs TalkFlowClient 의 {@code chatMessage}).</p>
+ */
+export interface ChatMessageReceivedPayload {
+    roomId: string;
+    message: ChatMessage;
+}
+
+export interface MemberChangePayload {
+    roomId: string;
+    members: Array<{ userId: string; nickname?: string; profileUrl?: string | null }>;
+    participantCount: number;
+    timestamp?: number;
+}
+
+/** 방 영구 차단 사용자 정보 (getBannedMembers 응답). */
+export interface BannedMemberInfo {
+    userId: string;
+    nickname: string | null;
+    profileUrl: string | null;
+}
+
+/**
+ * 읽음 이벤트 payload — {@code ChatClient._handleReadEvent} 가 실제로 emit 하는 shape.
+ * 배치/단일 이벤트 둘 다 동일 필드 이름 사용.
+ */
+export interface MessageReadEventPayload {
+    roomId: string;
+    messageId: string;
+    /** 읽은 사용자. 배치 이벤트의 경우 이벤트 전체에 대한 공통 값. */
+    userId?: string;
+    /** 해당 메시지의 남은 미읽음 사용자 수. 런타임 필드명 {@code remainingUnreadCount}. */
+    remainingUnreadCount?: number;
+}
+
+export interface RetentionCleanupPayload {
+    roomId: string;
+    cutoffTime: number;
+    eventType?: 'MESSAGE_RETENTION_CLEANUP';
+}
+
+/**
+ * TalkFlowClient 이벤트 맵 — 런타임 {@code TalkFlowClient.js} 의 {@code this.emit(...)} 호출 기반.
+ *
+ * <p><b>Connection 관련</b>: stateChange, connected, disconnected, reconnecting, connectionError, tokenSet, loggedOut</p>
+ * <p><b>Chat 관련 (ChatClient 이벤트를 이 이름으로 re-emit)</b>: chatMessage, newChatMessage, messageUpdated, messageDeleted, reactionChanged, linkPreviewAttached, messageRead, typing, memberJoined, memberLeft, roomSubscribed, roomUnsubscribed, roomListSubscribed, roomListUnsubscribed, roomListUpdate, roomListMessage, roomListCreated, roomListJoined, roomListLeft, roomListSelfLeft, roomListRoomUpdated, retentionCleanup</p>
+ * <p><b>Push 관련</b>: pushEnabled, pushFailed, pushNotification</p>
+ * <p><b>WebRTC 관련</b>: localStreamStarted, localStreamStopped, remoteTrack, screenShareStarted, screenShareEnded, deviceChange, mediaStateChanged, callStarted, callEnded, callRequested, callAccepted, callRejected, callCancelled, callInvitation, callBusy, incomingCall, incomingCallWhileBusy, userJoined, userLeft, participantLeft, participantMediaState, peerConnected, peerDisconnected, peerClosed, webrtcError</p>
+ */
+export interface TalkFlowClientEvents {
+    // Connection
+    stateChange: { state: ConnectionStateValue; prevState: ConnectionStateValue };
+    connected: unknown;
+    disconnected: unknown;
+    reconnecting: { attempt: number };
+    connectionError: unknown;
+    tokenSet: { userId: string };
+    loggedOut: void;
+
+    // Chat (re-emit from ChatClient with prefixed names)
+    chatMessage: ChatMessageReceivedPayload;
+    newChatMessage: ChatMessageReceivedPayload;
+    /** 메시지 수정 (eventType=MESSAGE_UPDATED) — 이름 변환 없이 그대로 re-emit. */
+    messageUpdated: ChatMessageReceivedPayload;
+    /** "모두에게 삭제" (eventType=MESSAGE_DELETED). */
+    messageDeleted: ChatMessageReceivedPayload;
+    /** 이모지 리액션 토글 (eventType=REACTION_CHANGED). */
+    reactionChanged: ChatMessageReceivedPayload;
+    /** OG 링크 미리보기 서버 비동기 첨부 완료 (eventType=LINK_PREVIEW_ATTACHED). */
+    linkPreviewAttached: ChatMessageReceivedPayload;
+    /** 다국어 번역 서버 비동기 첨부 완료 (eventType=MESSAGE_TRANSLATED) — message.translations 머지. */
+    messageTranslated: ChatMessageReceivedPayload;
+    messageRead: MessageReadEventPayload;
+    typing: TypingEvent;
+    memberJoined: MemberChangePayload;
+    memberLeft: MemberChangePayload;
+    roomSubscribed: { roomId: string };
+    roomUnsubscribed: { roomId: string };
+    roomListSubscribed: Record<string, unknown>;
+    roomListUnsubscribed: Record<string, unknown>;
+    roomListUpdate: RoomListUpdateEvent;
+    roomListMessage: RoomListUpdateEvent;
+    roomListMessageDeleted: RoomListUpdateEvent;
+    /** 현재 lastMessage 가 편집됨 (MESSAGE_UPDATED) — preview 새 content 로 갱신. */
+    roomListMessageUpdated: RoomListUpdateEvent;
+    roomListCreated: RoomListUpdateEvent;
+    roomListJoined: RoomListUpdateEvent;
+    roomListLeft: RoomListUpdateEvent;
+    roomListSelfLeft: RoomListUpdateEvent;
+    /** 방장이 누군가를 단순 추방함 (ROOM_KICKED). members 에 추방된 사용자. */
+    roomListKicked: RoomListUpdateEvent;
+    /** 본인이 추방당함 — UI 에서 "추방됨" 표시 + 리스트 제거. */
+    roomListSelfKicked: RoomListUpdateEvent;
+    /** 방장이 누군가를 영구 차단함 (ROOM_BANNED). members 에 차단된 사용자. */
+    roomListBanned: RoomListUpdateEvent;
+    /** 본인이 영구 차단당함. */
+    roomListSelfBanned: RoomListUpdateEvent;
+    roomListRoomUpdated: RoomListUpdateEvent;
+    retentionCleanup: RetentionCleanupPayload;
+
+    // Push
+    pushEnabled: void;
+    /**
+     * 푸시 활성화 실패. {@code enablePushNotifications()} 가 어떤 사유든 실패할 때 emit.
+     *
+     * <p>호출자가 await 결과를 받지 않는 fire-and-forget 패턴 (예: {@code connect(jwt, { enablePush: true })})
+     * 으로 호출했을 때, 실패 사실을 알리는 유일한 통보 채널이다.</p>
+     *
+     * <p><b>중요</b>: 자동 활성화 경로를 쓰는 경우 {@code connect()} <b>전에</b> 리스너를 등록해야
+     * 즉시 emit 되는 실패 (예: PERMISSION_DENIED) 를 놓치지 않는다.</p>
+     */
+    pushFailed: PushFailedPayload;
+    pushNotification: PushNotificationPayload;
+
+    // WebRTC (re-emit from WebRTCClient)
+    localStreamStarted: unknown;
+    localStreamStopped: unknown;
+    remoteTrack: unknown;
+    screenShareStarted: unknown;
+    screenShareEnded: unknown;
+    deviceChange: unknown;
+    mediaStateChanged: unknown;
+    callStarted: unknown;
+    callEnded: unknown;
+    callRequested: unknown;
+    callAccepted: unknown;
+    callRejected: unknown;
+    callCancelled: unknown;
+    callInvitation: unknown;
+    callBusy: unknown;
+    incomingCall: unknown;
+    incomingCallWhileBusy: unknown;
+    userJoined: unknown;
+    userLeft: unknown;
+    participantLeft: unknown;
+    participantMediaState: unknown;
+    peerConnected: unknown;
+    peerDisconnected: unknown;
+    peerClosed: unknown;
+    webrtcError: unknown;
+}
+
+/**
+ * ChatClient 가 직접 emit 하는 이벤트 맵.
+ * <p>TalkFlowClient 를 거치지 않고 {@code client.chat.on(...)} 로 직접 구독할 때 사용.
+ * TalkFlowClient 이벤트와 <b>이름/payload 가 다를 수 있음</b> — 특히 {@code message} vs {@code chatMessage}.</p>
+ */
+export interface ChatClientEvents {
+    message: ChatMessageReceivedPayload;
+    newMessage: ChatMessageReceivedPayload;
+    /** 메시지 수정 (eventType=MESSAGE_UPDATED). */
+    messageUpdated: ChatMessageReceivedPayload;
+    /** "모두에게 삭제" (eventType=MESSAGE_DELETED). */
+    messageDeleted: ChatMessageReceivedPayload;
+    /** 이모지 리액션 토글 (eventType=REACTION_CHANGED). */
+    reactionChanged: ChatMessageReceivedPayload;
+    /** OG 링크 미리보기 서버 비동기 첨부 완료 (eventType=LINK_PREVIEW_ATTACHED). */
+    linkPreviewAttached: ChatMessageReceivedPayload;
+    /** 다국어 번역 서버 비동기 첨부 완료 (eventType=MESSAGE_TRANSLATED) — message.translations 머지. */
+    messageTranslated: ChatMessageReceivedPayload;
+    roomSubscribed: { roomId: string };
+    roomUnsubscribed: { roomId: string };
+    memberJoined: MemberChangePayload;
+    memberLeft: MemberChangePayload;
+    roomListSubscribed: Record<string, unknown>;
+    roomListUnsubscribed: Record<string, unknown>;
+    roomListUpdate: RoomListUpdateEvent;
+    roomListMessage: RoomListUpdateEvent;
+    roomListMessageDeleted: RoomListUpdateEvent;
+    /** 현재 lastMessage 가 편집됨 (MESSAGE_UPDATED) — preview 새 content 로 갱신. */
+    roomListMessageUpdated: RoomListUpdateEvent;
+    roomListCreated: RoomListUpdateEvent;
+    roomListJoined: RoomListUpdateEvent;
+    roomListLeft: RoomListUpdateEvent;
+    roomListSelfLeft: RoomListUpdateEvent;
+    /** 방장이 누군가를 단순 추방함 (ROOM_KICKED). */
+    roomListKicked: RoomListUpdateEvent;
+    /** 본인이 추방당함. */
+    roomListSelfKicked: RoomListUpdateEvent;
+    /** 방장이 누군가를 영구 차단함 (ROOM_BANNED). */
+    roomListBanned: RoomListUpdateEvent;
+    /** 본인이 영구 차단당함. */
+    roomListSelfBanned: RoomListUpdateEvent;
+    roomListRoomUpdated: RoomListUpdateEvent;
+    retentionCleanup: RetentionCleanupPayload;
+    messageRead: MessageReadEventPayload;
+    typing: TypingEvent;
+}
+
+/**
+ * WebRTCClient 가 직접 emit 하는 이벤트 맵.
+ */
+export interface WebRTCClientEvents {
+    localStreamStarted: unknown;
+    localStreamStopped: unknown;
+    screenShareStarted: unknown;
+    screenShareEnded: unknown;
+    remoteTrack: unknown;
+    peerConnected: unknown;
+    peerDisconnected: unknown;
+    peerClosed: unknown;
+    error: unknown;
+    callStarted: unknown;
+    callEnded: unknown;
+    callRequested: unknown;
+    callAccepted: unknown;
+    callRejected: unknown;
+    callCancelled: unknown;
+    callInvitation: unknown;
+    callBusy: unknown;
+    incomingCall: unknown;
+    incomingCallWhileBusy: unknown;
+    userJoined: unknown;
+    userLeft: unknown;
+    participantLeft: unknown;
+    participantMediaState: unknown;
+    mediaStateChanged: unknown;
+    deviceChange: unknown;
+}
+
+// ============================================================================
+// Sub-clients
+// ============================================================================
+
+export class ChatClient implements SdkEventEmitter<ChatClientEvents> {
+    on<K extends keyof ChatClientEvents>(event: K, listener: (payload: ChatClientEvents[K]) => void): () => void;
+    once<K extends keyof ChatClientEvents>(event: K, listener: (payload: ChatClientEvents[K]) => void): () => void;
+    off<K extends keyof ChatClientEvents>(event: K, listener: (payload: ChatClientEvents[K]) => void): void;
+    emit<K extends keyof ChatClientEvents>(event: K, ...payload: ChatClientEvents[K] extends void ? [] : [ChatClientEvents[K]]): void;
+    removeAllListeners(event?: keyof ChatClientEvents): void;
+    listenerCount(event: keyof ChatClientEvents): number;
+
+    getRooms(params?: CursorPageParams): Promise<CursorPageResponse<ChatRoomResponse>>;
+    getRoom(roomId: string): Promise<ChatRoomResponse>;
+    getRoomInfo(roomId: string): Promise<ChatRoomResponse>;
+    /** 내 방 언어 설정 (다국어) — 'ko'/'en' 등 BCP-47 / 'OFF'(원문) / null·''(해제). 갱신된 방 반환. */
+    setMyRoomLanguage(roomId: string, language: string | null): Promise<ChatRoomResponse>;
+    createOneToOneRoom(friendId: string): Promise<ChatRoomResponse>;
+    createGroupRoom(data: CreateGroupRoomData): Promise<ChatRoomResponse>;
+    /**
+     * 호출자 프로젝트에서 사용 가능한 어시스턴트 페르소나 리스트.
+     * GLOBAL + PROJECT + OVERRIDE (OVERRIDE 가 GLOBAL 가림).
+     */
+    getAssistants(): Promise<AssistantPersonaResponse[]>;
+    /** 현재 키로 생성 가능한 roomAiType 조회 (discovery). */
+    getRoomAiMeta(): Promise<RoomAiMetaResponse>;
+    /** 어시스턴트 메시지 평점 등록 (1~5점). 어시 메시지({@code senderType === 'ASSISTANT'})에만 의미. */
+    rateAssistantMessage(roomId: string, messageId: string, rating: number, comment?: string): Promise<void>;
+    /** 어시스턴트로 대화 요약 (버튼 진입점, 동기). */
+    summarizeWithAssistant(roomId: string, options: SummarizeToolRequest): Promise<AssistantToolResult>;
+    /** 어시스턴트로 특정 메시지 번역 (버튼 진입점, 동기). */
+    translateWithAssistant(roomId: string, options: TranslateToolRequest): Promise<AssistantToolResult>;
+    /** 방 PM 프롬프트 레이어 조회 — PM_BACKSTAGE 방 전용, 참여자 전체. 미등록 시 404. */
+    getRoomPmPrompt(roomId: string): Promise<PmPromptLayerResponse>;
+    /** 방 PM 프롬프트 레이어 등록/수정 (upsert, 새 버전 자동 기록) — 방 주인(OWNER) 전용. content 1~2,000자. */
+    upsertRoomPmPrompt(roomId: string, content: string): Promise<PmPromptLayerResponse>;
+    /** 방 PM 프롬프트 레이어 합성 복귀 — 방 주인(OWNER) 전용. */
+    activateRoomPmPrompt(roomId: string): Promise<PmPromptLayerResponse>;
+    /** 방 PM 프롬프트 레이어 합성 제외 (soft delete — 본문/이력 보존) — 방 주인(OWNER) 전용. */
+    deactivateRoomPmPrompt(roomId: string): Promise<PmPromptLayerResponse>;
+    /** 방 PM 프롬프트 레이어 버전 이력 — 참여자 전체. */
+    getRoomPmPromptVersions(roomId: string): Promise<PmPromptLayerVersionResponse[]>;
+    /** 방 PM 프롬프트 레이어 버전 활성화 (active 포인터 이동 — 새 버전 미기록) — 방 주인(OWNER) 전용. */
+    activateRoomPmPromptVersion(roomId: string, version: number): Promise<PmPromptLayerResponse>;
+    /** PM 프롬프트 합성 미리보기 (전역+회사+방) — 참여자 전체. */
+    previewRoomPmPrompt(roomId: string): Promise<PmPromptPreviewResponse>;
+    joinGroupRoom(roomId: string, password?: string): Promise<ChatRoomResponse>;
+    leaveRoom(roomId: string): Promise<void>;
+    updateGroupRoom(roomId: string, data: UpdateGroupRoomData): Promise<ChatRoomResponse>;
+    inviteToGroupRoom(roomId: string, userIds: string[]): Promise<ChatRoomResponse>;
+    inviteToGroupRoom(roomId: string, data: InviteToRoomData): Promise<ChatRoomResponse>;
+
+    /** 단순 추방 — 재입장 가능. 방 관리자(OWNER/ADMIN) 만. */
+    kickMember(roomId: string, userId: string): Promise<void>;
+    /** 추방 + 영구 차단. 방 관리자(OWNER/ADMIN) 만. */
+    banMember(roomId: string, userId: string): Promise<void>;
+    /** 영구 차단 해제. 방 관리자(OWNER/ADMIN) 만. */
+    unbanMember(roomId: string, userId: string): Promise<void>;
+    /** 차단 사용자 목록 조회. 방장(ADMIN) 만. */
+    getBannedMembers(roomId: string): Promise<BannedMemberInfo[]>;
+
+    getAvailableGroupRooms(params?: CursorPageParams): Promise<CursorPageResponse<ChatRoomResponse>>;
+    getAllGroupRooms(params?: CursorPageParams): Promise<CursorPageResponse<ChatRoomResponse>>;
+
+    enterRoom(roomId: string): Promise<ChatRoomResponse>;
+
+    /**
+     * 메시지 목록 (커서 페이징) — 반환은 envelope 째({@code result.data.content}).
+     * <p>타임스탬프(sentAt/editedAt/replyTo.sentAt)는 SDK 가 epoch millis(number)로 정규화한다 —
+     * WebSocket 이벤트와 동일 형 (REST 원시 응답은 ISO 문자열).</p>
+     */
+    getMessages(roomId: string, params?: CursorPageParams): Promise<ApiEnvelope<CursorPageResponse<ChatMessage>>>;
+    fetchLinkPreview(url: string): Promise<FetchLinkPreviewResponse | null>;
+    sendMessage(roomId: string, data: SendMessageData): Promise<SendMessageResult>;
+    /** Optimistic UI 버전 — 응답 전 base/예측 messageIds 동기 반환. */
+    sendMessageOptimistic(roomId: string, data: SendMessageData): OptimisticSendMessageHandle;
+    sendTextMessage(roomId: string, message: string): Promise<SendMessageResult>;
+    sendTextMessageOptimistic(roomId: string, message: string): OptimisticSendMessageHandle;
+    sendReply(roomId: string, message: string, replyToMessageId: string): Promise<SendMessageResult>;
+    sendReplyOptimistic(roomId: string, message: string, replyToMessageId: string): OptimisticSendMessageHandle;
+
+    uploadFile(roomId: string, file: File, options?: FileUploadOptions): Promise<FileMetaData>;
+    sendFileMessage(roomId: string, files: File | File[], options?: SendFileMessageOptions): Promise<SendMessageResult>;
+    /**
+     * 파일 메시지 Optimistic UI 버전 — 업로드 시작 전에 messageIds 를 동기 반환.
+     * 파일 검증 실패는 promise 가 만들어지기 전 동기 throw.
+     */
+    sendFileMessageOptimistic(roomId: string, files: File | File[], options?: SendFileMessageOptions): OptimisticSendMessageHandle;
+
+    editMessage(roomId: string, messageId: string, message: string): Promise<void>;
+    deleteMessage(roomId: string, messageId: string, deleteType?: DeleteType): Promise<void>;
+    /** 메시지 읽음 처리 — sync. 연결 상태 or send 결과에 따라 boolean 반환. */
+    markAsRead(roomId: string, messageId: string): boolean;
+    pinMessage(roomId: string, messageId: string): Promise<void>;
+    unpinMessage(roomId: string): Promise<void>;
+
+    /**
+     * 이모지 리액션 토글.
+     * 한 사용자는 메시지당 하나의 이모지만 보유. 같은 이모지 재호출 시 해제, 다른 이모지 시 교체.
+     */
+    toggleReaction(roomId: string, messageId: string, emoji: string): Promise<void>;
+
+    /** STOMP 3 개 destination 구독 — 내부 connectionManager.subscribe 가 async. */
+    subscribeRoom(roomId: string): Promise<void>;
+    unsubscribeRoom(roomId: string): void;
+    unsubscribeAllRooms(): void;
+    setActiveRoom(roomId: string): void;
+    clearActiveRoom(): void;
+    getActiveRoom(): string | null;
+    /** 방 리스트 전역 구독 — 내부 connectionManager.subscribe 가 async. */
+    subscribeRoomList(): Promise<void>;
+    unsubscribeRoomList(): void;
+    isRoomListSubscribed(): boolean;
+    getSubscribedRooms(): string[];
+    isSubscribed(roomId: string): boolean;
+
+    startTyping(roomId: string): void;
+    stopTyping(roomId: string): void;
+}
+
+export class WebRTCClient implements SdkEventEmitter<WebRTCClientEvents> {
+    on<K extends keyof WebRTCClientEvents>(event: K, listener: (payload: WebRTCClientEvents[K]) => void): () => void;
+    once<K extends keyof WebRTCClientEvents>(event: K, listener: (payload: WebRTCClientEvents[K]) => void): () => void;
+    off<K extends keyof WebRTCClientEvents>(event: K, listener: (payload: WebRTCClientEvents[K]) => void): void;
+    emit<K extends keyof WebRTCClientEvents>(event: K, ...payload: WebRTCClientEvents[K] extends void ? [] : [WebRTCClientEvents[K]]): void;
+    removeAllListeners(event?: keyof WebRTCClientEvents): void;
+    listenerCount(event: keyof WebRTCClientEvents): number;
+
+    initializeIceServers(): Promise<RTCIceServer[]>;
+    getTurnCredentials(): Promise<{ iceServers: RTCIceServer[] }>;
+
+    createCallRoom(data: unknown): Promise<unknown>;
+    getCallRoom(roomId: string): Promise<unknown>;
+    joinCallRoomApi(roomId: string): Promise<unknown>;
+    leaveCallRoomApi(roomId: string): Promise<unknown>;
+
+    /** 수신 call 구독 활성화 — 내부 WebSocket subscribe 가 async. */
+    enableIncomingCalls(): Promise<void>;
+    disableIncomingCalls(): void;
+    isIncomingCallsEnabled(): boolean;
+
+    startCall(options: { targetUserId?: string; roomId?: string; mediaConstraints?: MediaStreamConstraints }): Promise<void>;
+    callUser(targetUserId: string, mediaConstraints?: MediaStreamConstraints): Promise<void>;
+    acceptCall(callerId: string, mediaConstraints?: MediaStreamConstraints): Promise<void>;
+    rejectCall(callerId: string): void;
+    cancelCall(): void;
+    endCall(): void;
+
+    toggleVideo(): boolean;
+    toggleAudio(): boolean;
+    setVideoEnabled(enabled: boolean): void;
+    setAudioEnabled(enabled: boolean): void;
+    startScreenShare(): Promise<MediaStream>;
+    stopScreenShare(): void;
+    getLocalStream(): MediaStream | null;
+
+    getDevices(): Promise<{ videoInputs: MediaDeviceInfo[]; audioInputs: MediaDeviceInfo[]; audioOutputs: MediaDeviceInfo[] }>;
+    switchDevice(deviceId: string, kind: 'video' | 'audio' | 'audiooutput'): Promise<void>;
+    startDeviceChangeDetection(): void;
+    stopDeviceChangeDetection(): void;
+    applyVideoConstraints(constraints: MediaTrackConstraints): Promise<void>;
+    getVideoSettings(): MediaTrackSettings | null;
+    getAudioSettings(): MediaTrackSettings | null;
+
+    isInCall(): boolean;
+    getCurrentRoom(): string | null;
+}
+
+/** 푸시 디바이스 응답 (내 디바이스 목록). deviceToken 은 보안상 미포함. */
+export interface PushDeviceInfo {
+    deviceId: string;
+    deviceType: string;
+    enabled: boolean;
+    /** ISO-8601 문자열. */
+    createdAt: string;
+}
+
+/**
+ * 브라우저 푸시 권한 상태.
+ *
+ * <ul>
+ *   <li>{@code 'granted'} — 이미 허용. enable 호출 시 권한창 안 뜨고 토큰 발급 진행.</li>
+ *   <li>{@code 'default'} — 아직 묻지 않음. enable 호출 시 권한창 표시.</li>
+ *   <li>{@code 'denied'} — 거부됨. enable 호출 시 즉시 PERMISSION_DENIED 로 실패.</li>
+ *   <li>{@code 'unsupported'} — Notification / Service Worker 미지원 환경 (Safari iOS 등).</li>
+ * </ul>
+ */
+export type PushPermissionState = 'granted' | 'denied' | 'default' | 'unsupported';
+
+/**
+ * 푸시 활성화 실패 사유 분류.
+ *
+ * <p>{@code 'NO_TOKEN'} 은 SDK 측 사전 가드 (JWT 미설정), 나머지는 PushManager 단에서 발생.</p>
+ */
+export type PushErrorReason =
+    | 'UNSUPPORTED_BROWSER'
+    | 'FIREBASE_NOT_INSTALLED'
+    | 'SW_REGISTER_FAILED'
+    | 'PERMISSION_DENIED'
+    | 'TOKEN_FAILED'
+    | 'SERVER_REGISTER_FAILED'
+    | 'NO_TOKEN'
+    | 'UNKNOWN';
+
+/** {@code 'pushFailed'} 이벤트 페이로드. */
+export interface PushFailedPayload {
+    reason: PushErrorReason;
+    error: Error;
+}
+
+/**
+ * {@code enablePushNotifications()} 의 반환 결과.
+ *
+ * <p>throw 하지 않고 항상 이 객체를 Promise 로 반환한다 — 호출자가 {@code .ok} 로 분기.</p>
+ */
+export type EnablePushResult =
+    | { ok: true; alreadyEnabled?: boolean }
+    | { ok: false; reason: PushErrorReason; error: Error };
+
+/**
+ * 푸시 활성화 과정에서 발생한 분류된 에러.
+ *
+ * <p>{@code error.code} 로 사유 분기 가능. 호출자는 {@code error.message} 문자열 매칭 대신
+ * {@code error.code} 를 사용해야 안정적이다.</p>
+ */
+export class PushError extends Error {
+    readonly name: 'PushError';
+    readonly code: PushErrorReason;
+    readonly cause?: unknown;
+    constructor(code: PushErrorReason, message: string, cause?: unknown);
+}
+
+/**
+ * {@link PushErrorReason} 의 런타임 값 enum.
+ *
+ * <p>JS 사용자가 문자열 리터럴 대신 상수로 분기할 때 사용:
+ * {@code if (result.reason === PushErrorCode.PERMISSION_DENIED) ...}</p>
+ *
+ * <p>{@code 'NO_TOKEN'}, {@code 'UNKNOWN'} 은 PushManager 외부에서 부여되는 코드라
+ * 이 enum 에 포함되지 않는다 — {@link PushErrorReason} 타입에만 존재.</p>
+ */
+export const PushErrorCode: {
+    readonly UNSUPPORTED_BROWSER: 'UNSUPPORTED_BROWSER';
+    readonly FIREBASE_NOT_INSTALLED: 'FIREBASE_NOT_INSTALLED';
+    readonly SW_REGISTER_FAILED: 'SW_REGISTER_FAILED';
+    readonly PERMISSION_DENIED: 'PERMISSION_DENIED';
+    readonly TOKEN_FAILED: 'TOKEN_FAILED';
+    readonly SERVER_REGISTER_FAILED: 'SERVER_REGISTER_FAILED';
+};
+
+export class PushManager {
+    consumePendingRoom(): Promise<string | null>;
+    reset(): void;
+    getToken(): string | null;
+    isEnabled(): boolean;
+    /** 내 디바이스 목록 조회 (UI 관리용). */
+    getMyDevices(): Promise<PushDeviceInfo[]>;
+    /** 특정 디바이스의 푸시 수신 여부 토글. */
+    setDeviceEnabled(deviceId: string, enabled: boolean): Promise<void>;
+    /** 현재 디바이스의 푸시 수신 여부 토글. */
+    setCurrentDeviceEnabled(enabled: boolean): Promise<void>;
+    static consumePendingRoom(projectId?: string): Promise<string | null>;
+    /**
+     * 현재 브라우저의 푸시 권한 상태. 인스턴스 없이도 호출 가능.
+     */
+    static getPermissionState(): PushPermissionState;
+}
+
+// ============================================================================
+// Main client
+// ============================================================================
+
+export default class TalkFlowClient implements SdkEventEmitter<TalkFlowClientEvents> {
+    constructor(options: TalkFlowClientOptions);
+
+    /**
+     * 채팅 서브클라이언트.
+     * <p><b>JWT 토큰이 설정된 이후에만 non-null</b>. 런타임에서 생성자 또는 {@code setToken()} /
+     * {@code connect(jwt)} 호출 전까지 {@code null}. 접근 전에 반드시 null 체크 또는
+     * {@code connect()} / {@code setToken()} 완료 후 사용.</p>
+     */
+    readonly chat: ChatClient | null;
+
+    /**
+     * WebRTC 서브클라이언트.
+     * <p><b>JWT 토큰이 설정된 이후에만 non-null</b>. 동작 조건은 {@link #chat} 과 동일.</p>
+     */
+    readonly webrtc: WebRTCClient | null;
+
+    /**
+     * Push 서브클라이언트.
+     * <p><b>{@link #enablePushNotifications} 호출 후에만 non-null</b>.
+     * 기본 상태는 {@code null}. 런타임 속성 이름은 {@code pushManager} — TypeScript 에도 동일 이름.</p>
+     */
+    readonly pushManager: PushManager | null;
+
+    /** JWT 에서 추출된 userId. 토큰이 없거나 파싱 실패 시 null. */
+    readonly userId: string | null;
+
+    // EventEmitter
+    on<K extends keyof TalkFlowClientEvents>(event: K, listener: (payload: TalkFlowClientEvents[K]) => void): () => void;
+    once<K extends keyof TalkFlowClientEvents>(event: K, listener: (payload: TalkFlowClientEvents[K]) => void): () => void;
+    off<K extends keyof TalkFlowClientEvents>(event: K, listener: (payload: TalkFlowClientEvents[K]) => void): void;
+    emit<K extends keyof TalkFlowClientEvents>(event: K, ...payload: TalkFlowClientEvents[K] extends void ? [] : [TalkFlowClientEvents[K]]): void;
+    removeAllListeners(event?: keyof TalkFlowClientEvents): void;
+    listenerCount(event: keyof TalkFlowClientEvents): number;
+
+    // Connection lifecycle
+    connect(jwt?: string, options?: ConnectOptions): Promise<void>;
+    disconnect(): Promise<void>;
+    logout(): Promise<void>;
+    setToken(token: string): Promise<void>;
+    updateToken(newToken: string): Promise<void>;
+    isConnected(): boolean;
+    getState(): ConnectionStateValue;
+    hasToken(): boolean;
+
+    // 다국어 (Multilingual)
+    /** 내 기본 선호 언어 설정 (전 방 공통) — BCP-47 / 'OFF'(원문) / null·''(미설정). 방별은 setMyRoomLanguage. */
+    setPreferredLanguage(language: string | null): Promise<unknown>;
+    /** 브라우저 locale 감지 — navigator.language 를 BCP-47 소문자로. 비브라우저/미가용 시 null. */
+    static detectBrowserLanguage(): string | null;
+    /** 표시 헬퍼 — message.translations[myLang] ?? message.content. */
+    static displayText(message: ChatMessage, myLang?: string): string | null;
+
+    // Push
+    /**
+     * 웹 푸시 알림 활성화 — Firebase 초기화, 권한 요청, 토큰 발급, 서버 등록까지 일괄 수행.
+     *
+     * <p>throw 하지 않으며, 실패는 결과 객체로 반환된다. fire-and-forget (await 미사용) 으로 호출해도
+     * unhandled rejection 이 발생하지 않는다. 호출 패턴 가이드는 README "푸시 알림" 섹션 참고.</p>
+     */
+    enablePushNotifications(options?: EnablePushOptions): Promise<EnablePushResult>;
+    /**
+     * 호출 전에 사용 — 브라우저 권한 상태에 따라 UI 분기.
+     * pushManager 인스턴스 없이도 호출 가능.
+     */
+    getPushPermissionState(): PushPermissionState;
+    /** SDK 내부 푸시 활성화 상태. 페이지 로드 직후엔 항상 false. 권한 상태는 {@link #getPushPermissionState}. */
+    isPushEnabled(): boolean;
+    /** 현재 발급된 FCM 토큰. enable 호출 후에만 non-null. */
+    getPushToken(): string | null;
+    /** 푸시 상태 초기화 — 로그아웃 또는 사용자 전환 시 호출. logout() 내부에서 자동 호출됨. */
+    resetPush(): void;
+    consumePendingRoom(): Promise<string | null>;
+    /** 현재 디바이스의 푸시 수신 여부 토글. enable 선행 안 됐으면 undefined 반환. */
+    setCurrentDeviceEnabled(enabled: boolean): Promise<void> | undefined;
+    /** 특정 디바이스 토글 (관리 UI 용). enable 선행 안 됐으면 undefined 반환. */
+    setDeviceEnabled(deviceId: string, enabled: boolean): Promise<void> | undefined;
+    /** 내 푸시 디바이스 목록 조회. enable 선행 안 됐으면 undefined 반환. */
+    getMyDevices(): Promise<PushDeviceInfo[]> | undefined;
+
+    // Chat delegations
+    getRooms(params?: CursorPageParams): Promise<CursorPageResponse<ChatRoomResponse>>;
+    getRoom(roomId: string): Promise<ChatRoomResponse>;
+    getRoomInfo(roomId: string): Promise<ChatRoomResponse>;
+    /** 내 방 언어 설정 (다국어) — 'ko'/'en' 등 BCP-47 / 'OFF'(원문) / null·''(해제). 갱신된 방 반환. */
+    setMyRoomLanguage(roomId: string, language: string | null): Promise<ChatRoomResponse>;
+    createOneToOneRoom(friendId: string): Promise<ChatRoomResponse>;
+    createGroupRoom(data: CreateGroupRoomData): Promise<ChatRoomResponse>;
+    /**
+     * 호출자 프로젝트에서 사용 가능한 어시스턴트 페르소나 리스트.
+     * GLOBAL + PROJECT + OVERRIDE (OVERRIDE 가 GLOBAL 가림).
+     */
+    getAssistants(): Promise<AssistantPersonaResponse[]>;
+    /** 현재 키로 생성 가능한 roomAiType 조회 (discovery). */
+    getRoomAiMeta(): Promise<RoomAiMetaResponse>;
+    /** 어시스턴트 메시지 평점 등록 (1~5점). 어시 메시지({@code senderType === 'ASSISTANT'})에만 의미. */
+    rateAssistantMessage(roomId: string, messageId: string, rating: number, comment?: string): Promise<void>;
+    /** 어시스턴트로 대화 요약 (버튼 진입점, 동기). */
+    summarizeWithAssistant(roomId: string, options: SummarizeToolRequest): Promise<AssistantToolResult>;
+    /** 어시스턴트로 특정 메시지 번역 (버튼 진입점, 동기). */
+    translateWithAssistant(roomId: string, options: TranslateToolRequest): Promise<AssistantToolResult>;
+    /** 방 PM 프롬프트 레이어 조회 — PM_BACKSTAGE 방 전용, 참여자 전체. 미등록 시 404. */
+    getRoomPmPrompt(roomId: string): Promise<PmPromptLayerResponse>;
+    /** 방 PM 프롬프트 레이어 등록/수정 (upsert, 새 버전 자동 기록) — 방 주인(OWNER) 전용. content 1~2,000자. */
+    upsertRoomPmPrompt(roomId: string, content: string): Promise<PmPromptLayerResponse>;
+    /** 방 PM 프롬프트 레이어 합성 복귀 — 방 주인(OWNER) 전용. */
+    activateRoomPmPrompt(roomId: string): Promise<PmPromptLayerResponse>;
+    /** 방 PM 프롬프트 레이어 합성 제외 (soft delete — 본문/이력 보존) — 방 주인(OWNER) 전용. */
+    deactivateRoomPmPrompt(roomId: string): Promise<PmPromptLayerResponse>;
+    /** 방 PM 프롬프트 레이어 버전 이력 — 참여자 전체. */
+    getRoomPmPromptVersions(roomId: string): Promise<PmPromptLayerVersionResponse[]>;
+    /** 방 PM 프롬프트 레이어 버전 활성화 (active 포인터 이동 — 새 버전 미기록) — 방 주인(OWNER) 전용. */
+    activateRoomPmPromptVersion(roomId: string, version: number): Promise<PmPromptLayerResponse>;
+    /** PM 프롬프트 합성 미리보기 (전역+회사+방) — 참여자 전체. */
+    previewRoomPmPrompt(roomId: string): Promise<PmPromptPreviewResponse>;
+    joinGroupRoom(roomId: string, password?: string): Promise<ChatRoomResponse>;
+    leaveRoom(roomId: string): Promise<void>;
+    updateGroupRoom(roomId: string, data: UpdateGroupRoomData): Promise<ChatRoomResponse>;
+    inviteToGroupRoom(roomId: string, userIds: string[]): Promise<ChatRoomResponse>;
+    inviteToGroupRoom(roomId: string, data: InviteToRoomData): Promise<ChatRoomResponse>;
+
+    /** 단순 추방 — 재입장 가능. 방 관리자(OWNER/ADMIN) 만. */
+    kickMember(roomId: string, userId: string): Promise<void>;
+    /** 추방 + 영구 차단. 방 관리자(OWNER/ADMIN) 만. */
+    banMember(roomId: string, userId: string): Promise<void>;
+    /** 영구 차단 해제. 방 관리자(OWNER/ADMIN) 만. */
+    unbanMember(roomId: string, userId: string): Promise<void>;
+    /** 차단 사용자 목록 조회. 방장(ADMIN) 만. */
+    getBannedMembers(roomId: string): Promise<BannedMemberInfo[]>;
+
+    getAvailableGroupRooms(params?: CursorPageParams): Promise<CursorPageResponse<ChatRoomResponse>>;
+    getAllGroupRooms(params?: CursorPageParams): Promise<CursorPageResponse<ChatRoomResponse>>;
+
+    enterRoom(roomId: string): Promise<ChatRoomResponse>;
+
+    /**
+     * 메시지 목록 (커서 페이징) — 반환은 envelope 째({@code result.data.content}).
+     * <p>타임스탬프(sentAt/editedAt/replyTo.sentAt)는 SDK 가 epoch millis(number)로 정규화한다 —
+     * WebSocket 이벤트와 동일 형 (REST 원시 응답은 ISO 문자열).</p>
+     */
+    getMessages(roomId: string, params?: CursorPageParams): Promise<ApiEnvelope<CursorPageResponse<ChatMessage>>>;
+    fetchLinkPreview(url: string): Promise<FetchLinkPreviewResponse | null>;
+    sendMessage(roomId: string, data: SendMessageData): Promise<SendMessageResult>;
+    /** Optimistic UI 버전 — 응답 전 base/예측 messageIds 동기 반환. */
+    sendMessageOptimistic(roomId: string, data: SendMessageData): OptimisticSendMessageHandle;
+    sendTextMessage(roomId: string, message: string): Promise<SendMessageResult>;
+    sendTextMessageOptimistic(roomId: string, message: string): OptimisticSendMessageHandle;
+    sendReply(roomId: string, message: string, replyToMessageId: string): Promise<SendMessageResult>;
+    sendReplyOptimistic(roomId: string, message: string, replyToMessageId: string): OptimisticSendMessageHandle;
+
+    uploadFile(roomId: string, file: File, options?: FileUploadOptions): Promise<FileMetaData>;
+    sendFileMessage(roomId: string, files: File | File[], options?: SendFileMessageOptions): Promise<SendMessageResult>;
+    /**
+     * 파일 메시지 Optimistic UI 버전 — 업로드 시작 전에 messageIds 를 동기 반환.
+     * 파일 검증 실패는 promise 가 만들어지기 전 동기 throw.
+     */
+    sendFileMessageOptimistic(roomId: string, files: File | File[], options?: SendFileMessageOptions): OptimisticSendMessageHandle;
+
+    editMessage(roomId: string, messageId: string, message: string): Promise<void>;
+    deleteMessage(roomId: string, messageId: string, deleteType?: DeleteType): Promise<void>;
+    /** 메시지 읽음 처리 — sync. 연결 상태 or send 결과에 따라 boolean 반환. */
+    markAsRead(roomId: string, messageId: string): boolean;
+    pinMessage(roomId: string, messageId: string): Promise<void>;
+    unpinMessage(roomId: string): Promise<void>;
+
+    toggleReaction(roomId: string, messageId: string, emoji: string): Promise<void>;
+
+    /** STOMP 3 개 destination 구독 — 내부 connectionManager.subscribe 가 async. */
+    subscribeRoom(roomId: string): Promise<void>;
+    unsubscribeRoom(roomId: string): void;
+    unsubscribeAllRooms(): void;
+    setActiveRoom(roomId: string): void;
+    clearActiveRoom(): void;
+    getActiveRoom(): string | null;
+    /** 방 리스트 전역 구독 — 내부 connectionManager.subscribe 가 async. */
+    subscribeRoomList(): Promise<void>;
+    unsubscribeRoomList(): void;
+    isRoomListSubscribed(): boolean;
+    getSubscribedRooms(): string[];
+    isSubscribed(roomId: string): boolean;
+
+    startTyping(roomId: string): void;
+    stopTyping(roomId: string): void;
+
+    // WebRTC delegations
+    initializeIceServers(): Promise<RTCIceServer[]>;
+    getTurnCredentials(): Promise<{ iceServers: RTCIceServer[] }>;
+
+    createCallRoom(data: unknown): Promise<unknown>;
+    getCallRoom(roomId: string): Promise<unknown>;
+    joinCallRoomApi(roomId: string): Promise<unknown>;
+    leaveCallRoomApi(roomId: string): Promise<unknown>;
+
+    /** 수신 call 구독 활성화 — 내부 WebSocket subscribe 가 async. */
+    enableIncomingCalls(): Promise<void>;
+    disableIncomingCalls(): void;
+    isIncomingCallsEnabled(): boolean;
+
+    startCall(options: { targetUserId?: string; roomId?: string; mediaConstraints?: MediaStreamConstraints }): Promise<void>;
+    callUser(targetUserId: string, mediaConstraints?: MediaStreamConstraints): Promise<void>;
+    acceptCall(callerId: string, mediaConstraints?: MediaStreamConstraints): Promise<void>;
+    rejectCall(callerId: string): void;
+    cancelCall(): void;
+    endCall(): void;
+
+    toggleVideo(): boolean;
+    toggleAudio(): boolean;
+    setVideoEnabled(enabled: boolean): void;
+    setAudioEnabled(enabled: boolean): void;
+    startScreenShare(): Promise<MediaStream>;
+    stopScreenShare(): void;
+    getLocalStream(): MediaStream | null;
+
+    getDevices(): Promise<{ videoInputs: MediaDeviceInfo[]; audioInputs: MediaDeviceInfo[]; audioOutputs: MediaDeviceInfo[] }>;
+    switchDevice(deviceId: string, kind: 'video' | 'audio' | 'audiooutput'): Promise<void>;
+    startDeviceChangeDetection(): void;
+    stopDeviceChangeDetection(): void;
+    applyVideoConstraints(constraints: MediaTrackConstraints): Promise<void>;
+    getVideoSettings(): MediaTrackSettings | null;
+    getAudioSettings(): MediaTrackSettings | null;
+
+    isInCall(): boolean;
+    getCurrentRoom(): string | null;
+
+    // Cleanup
+    destroy(): Promise<void>;
+}
+
+// ============================================================================
+// Utility functions (exported)
+// ============================================================================
+
+export function validateAndParseJWT(
+    token: string,
+    options?: { bufferSeconds?: number; validateExpiry?: boolean }
+): { userId: string; payload: Record<string, unknown> };
+export function extractUserIdFromJWT(token: string): string | null;
+export function isJWTExpired(token: string): boolean;
+export function getJWTRemainingTime(token: string): number;
+export function decodeJWTPayload(token: string): Record<string, unknown> | null;
+
+// ============================================================================
+// EventEmitter / Logger (utility classes)
+// ============================================================================
+
+export class EventEmitter<EventMap = Record<string, unknown>> implements SdkEventEmitter<EventMap> {
+    on<K extends keyof EventMap>(event: K, listener: (payload: EventMap[K]) => void): () => void;
+    once<K extends keyof EventMap>(event: K, listener: (payload: EventMap[K]) => void): () => void;
+    off<K extends keyof EventMap>(event: K, listener: (payload: EventMap[K]) => void): void;
+    emit<K extends keyof EventMap>(event: K, ...payload: EventMap[K] extends void ? [] : [EventMap[K]]): void;
+    removeAllListeners(event?: keyof EventMap): void;
+    listenerCount(event: keyof EventMap): number;
+    eventNames(): Array<keyof EventMap>;
+}
+
+export class Logger {
+    constructor(level: LogLevelValue, tag: string);
+    debug(...args: unknown[]): void;
+    info(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+    error(...args: unknown[]): void;
+}
+
+export class ConnectionManager {}
+export class MediaStreamManager {}
+export class PeerConnectionManager {}