@vibexnpm/talkx 8.2.0 → 8.4.1

package/README.md

@@ -78,6 +78,7 @@ await client.connect(jwtToken, { enablePush: true });
 | [push.md](docs/push.md) | **웹 푸시 알림.** 권한 lifecycle, 활성화 패턴 (자동 vs 사용자 액션), 디바이스 토글, 알림 클릭 라우팅 |
 | [webrtc.md](docs/webrtc.md) | 1:1 / 그룹 통화, 미디어 제어, 디바이스 관리, TURN 서버 |
 | [vote.md](docs/vote.md) | **투표.** 생성(멱등키 필수) · 투표/재투표 · 결과 마스킹 · 이미지 선택지 · 채팅 카드 렌더링 |
+| [video-analysis.md](docs/video-analysis.md) | **영상 분석.** 사용 가능 여부·한도 · 업로드 · 접수(멱등키 필수) · 방 게시 · 상태 조회 · 취소 · 에러 코드 |
 | [events.md](docs/events.md) | 모든 이벤트 레퍼런스. 채팅 이벤트 처리 패턴 (`eventType` 분기 vs 상태 필드 렌더) |
 | [errors.md](docs/errors.md) | 에러 분류 (`PushErrorReason`, `ErrorTypes`), HTTP 상태 코드, 입력 제약 |
 
@@ -209,6 +210,8 @@ renderTranslatedText(translated.translatedText); // 요청자 전용 응답, 방
 
 요약/번역은 동기 호출이라 LLM 처리(수 초) 후 반환됩니다. 요약은 생성된 어시스턴트 메시지가 일반 `chatMessage` 이벤트로도 도착하고, 번역은 요청자 전용 응답으로만 반환됩니다.
 
+영상 분석(`analyzeVideoWithAssistant` · `analyzeVideo`)은 비동기 작업입니다 — 접수하면 `jobId` 가 돌아오고 결과는 조회하거나 방 메시지로 받습니다. [docs/video-analysis.md](docs/video-analysis.md) 를 따릅니다.
+
 ---
 
 ## CDN 사용

package/dist/index.d.ts

@@ -501,6 +501,12 @@ export interface PmPromptPreviewResponse {
     composedPrompt: string;
 }
 
+/** {@code leaveRoom} 옵션 — 방장의 «위임 후 나가기». */
+export interface LeaveRoomOptions {
+    /** 방장을 넘겨받을 사람 userId. 방의 활성 사람 참가자이면서 활성 계정이어야 한다. 일반 참가자는 생략. */
+    newOwnerId?: string;
+}
+
 /**
  * {@link ChatClient.inviteToGroupRoom} 의 신규 형식 입력. 회원 / 어시스턴트 동시 초대 지원.
  * 둘 중 하나 이상 필수.
@@ -522,6 +528,8 @@ export const RoomListEventType: {
     readonly ROOM_UPDATED: 'ROOM_UPDATED';
     readonly ROOM_KICKED: 'ROOM_KICKED';
     readonly ROOM_BANNED: 'ROOM_BANNED';
+    readonly ROOM_OWNER_CHANGED: 'ROOM_OWNER_CHANGED';
+    readonly ROOM_DELETED: 'ROOM_DELETED';
     readonly MESSAGE_RETENTION_CLEANUP: 'MESSAGE_RETENTION_CLEANUP';
     readonly ROOM_UNREAD_UPDATED: 'ROOM_UNREAD_UPDATED';
 };
@@ -1266,10 +1274,24 @@ export interface RoomMeta {
 }
 
 /** 채팅방 리스트 실시간 업데이트 이벤트. */
+/** 방 목록 이벤트의 사용자 정보 — 서버 {@code RoomListEvent.MemberInfo}. */
+export interface RoomListMemberInfo {
+    userId: string;
+    nickname?: string | null;
+    profileUrl?: string | null;
+}
+
 export interface RoomListUpdateEvent {
     eventType: RoomListEventTypeValue;
     roomId: string;
     actorId?: string;
+    /**
+     * 입장·퇴장·추방·차단한 사용자, 또는 {@code ROOM_OWNER_CHANGED} 의 새 방장(1명). 서버 {@code RoomListEvent.MemberInfo}.
+     * {@code ROOM_JOINED}·{@code ROOM_LEFT}·{@code ROOM_KICKED}·{@code ROOM_BANNED}·{@code ROOM_OWNER_CHANGED} 에서만 채워진다.
+     */
+    members?: RoomListMemberInfo[];
+    /** 이벤트 직후 활성 참가자 수 — 입장·퇴장·추방·차단·위임 이벤트에서 채워지고, {@code ROOM_DELETED} 는 0. */
+    activeParticipantCount?: number;
     /** {@code MESSAGE_*} 이벤트의 방 마지막 메시지 시각(epoch millis). 그 외 이벤트에서는 undefined. */
     lastMessageAt?: number | null;
     /** 이벤트 발행 시각(epoch millis). */
@@ -1373,6 +1395,8 @@ export interface DocumentAnalysisProgress {
  *   렌더가 그대로 동작한다.
  *
  * 현재는 PM_BACKSTAGE(방당 단일 PM) 만 phase 를 발행 — 멘션/버튼/14인 경로는 본 이벤트 없이 typing 만.
+ * 예외는 영상 분석 버튼({@code analyzeVideoWithAssistant})으로, 어시스턴트가 붙어 있는 방이면 방 종류와
+ * 무관하게 `VIDEO_ANALYSIS` 를 발행한다(docs/video-analysis.md).
  */
 
 export interface AssistantProgressEvent {
@@ -1388,7 +1412,7 @@ export interface AssistantProgressEvent {
     /** 진행 주체 페르소나 ID. */
     personaId: string | null;
     /** 진행 단계 — `active:true` 일 때. 종료 시 null. */
-    phase: 'THINKING' | 'SEARCHING' | 'PLANNING' | 'DOCUMENT_ANALYSIS' | 'WRITING' | null;
+    phase: 'THINKING' | 'SEARCHING' | 'PLANNING' | 'DOCUMENT_ANALYSIS' | 'VIDEO_ANALYSIS' | 'WRITING' | null;
     /** DOCUMENT_ANALYSIS의 실측 진행률. 같은 phase heartbeat 사이와 재입장 후에도 보존된다. */
     progress?: DocumentAnalysisProgress | null;
     /** phase 의 기본 표시 라벨(예: "생각 중…"). SDK 매핑 — 커스텀하려면 `phase` 사용. 종료 시 null. */
@@ -1416,7 +1440,10 @@ export interface AssistantProgressEvent {
     textAvailable?: boolean;
     /** 종료(DONE) 결과 — DONE 수신 시만. */
     status?: 'SUCCEEDED' | 'FAILED' | 'CANCELLED' | 'TIMEOUT' | null;
-    /** 종료(DONE, SUCCEEDED) 시 영속된 최종 메시지 ID. */
+    /**
+     * 종료(DONE) 시 방에 올라간 메시지 ID. 보통 `SUCCEEDED` 에만 있다.
+     * 영상 분석은 실패 안내 메시지의 ID 가 `FAILED`·`TIMEOUT` 에도 실린다 — 성공 여부는 `status` 로 판정한다.
+     */
     messageId?: string | null;
     /**
      * 종료 사유 — 'timeout'(TTL 만료). DONE 수신 해제엔 없음.
@@ -1456,7 +1483,7 @@ export interface AssistantRoomProgressEvent {
     /** 표시 기준이 된 stream (가장 최근 갱신). 없으면 null. */
     streamId: string | null;
     personaId: string | null;
-    phase: 'THINKING' | 'SEARCHING' | 'PLANNING' | 'DOCUMENT_ANALYSIS' | 'WRITING' | null;
+    phase: 'THINKING' | 'SEARCHING' | 'PLANNING' | 'DOCUMENT_ANALYSIS' | 'VIDEO_ANALYSIS' | 'WRITING' | null;
     progress?: DocumentAnalysisProgress | null;
     label: string | null;
     /** 표시 기준 stream 의 누적 본문. `textAvailable:false` 거나 진행 중이 아니면 null. */
@@ -1469,7 +1496,7 @@ export interface AssistantRoomProgressEvent {
 export interface AssistantProgressStreamSnapshot {
     streamId: string;
     personaId: string | null;
-    phase: 'THINKING' | 'SEARCHING' | 'PLANNING' | 'DOCUMENT_ANALYSIS' | 'WRITING' | null;
+    phase: 'THINKING' | 'SEARCHING' | 'PLANNING' | 'DOCUMENT_ANALYSIS' | 'VIDEO_ANALYSIS' | 'WRITING' | null;
     progress?: DocumentAnalysisProgress | null;
     label: string | null;
     text: string | null;
@@ -1946,6 +1973,10 @@ export interface TalkFlowClientEvents {
     roomListBanned: RoomListUpdateEvent;
     /** 본인이 영구 차단당함. */
     roomListSelfBanned: RoomListUpdateEvent;
+    /** 방장 위임 (ROOM_OWNER_CHANGED) — actorId 는 이전 방장, members[0] 이 새 방장. */
+    roomListOwnerChanged: RoomListUpdateEvent;
+    /** 방장이 방을 삭제 (ROOM_DELETED) — 리스트에서 제거 + 열린 방 화면 닫기. actorId 는 삭제한 방장. */
+    roomListDeleted: RoomListUpdateEvent;
     roomListRoomUpdated: RoomListUpdateEvent;
     /** 내가 어느 기기에서 읽든 방별 미독 절대값(+version)을 통지 — 크로스-디바이스 badge 동기화. */
     roomListUnreadUpdated: RoomUnreadUpdatedEvent;
@@ -2049,6 +2080,10 @@ export interface ChatClientEvents {
     roomListBanned: RoomListUpdateEvent;
     /** 본인이 영구 차단당함. */
     roomListSelfBanned: RoomListUpdateEvent;
+    /** 방장 위임 (ROOM_OWNER_CHANGED) — actorId 는 이전 방장, members[0] 이 새 방장. */
+    roomListOwnerChanged: RoomListUpdateEvent;
+    /** 방장이 방을 삭제 (ROOM_DELETED) — 리스트에서 제거 + 열린 방 화면 닫기. actorId 는 삭제한 방장. */
+    roomListDeleted: RoomListUpdateEvent;
     roomListRoomUpdated: RoomListUpdateEvent;
     /** 내가 어느 기기에서 읽든 방별 미독 절대값(+version)을 통지 — 크로스-디바이스 badge 동기화. */
     roomListUnreadUpdated: RoomUnreadUpdatedEvent;
@@ -2124,6 +2159,12 @@ export class ChatClient implements SdkEventEmitter<ChatClientEvents> {
     summarizeWithAssistant(roomId: string, options: SummarizeToolRequest): Promise<AssistantToolResult>;
     /** 특정 메시지 온디맨드 번역 (버튼 진입점, 동기, 요청자 전용 응답). */
     translateWithAssistant(roomId: string, options: TranslateToolRequest): Promise<OnDemandTranslationResponse>;
+    uploadVideoAsset(file: File, options?: FileUploadOptions): Promise<VideoAsset>;
+    analyzeVideo(analysis: VideoAnalysisRequest, options: VideoAnalysisOptions): Promise<VideoAnalysisJob>;
+    analyzeVideoWithAssistant(roomId: string, request: RoomVideoAnalysisRequest, options: VideoAnalysisOptions): Promise<VideoAnalysisJob>;
+    getVideoAnalysis(jobId: string): Promise<VideoAnalysisJob>;
+    cancelVideoAnalysis(jobId: string): Promise<VideoAnalysisCancellation>;
+    getVideoAnalysisCapabilities(): Promise<VideoAnalysisCapabilities>;
     /** Rolling 누적 요약 갱신 트리거 (비동기). 완료는 {@code summaryUpdate} 이벤트 + {@link getSummary} 로 확인. */
     refreshSummary(roomId: string, options?: RefreshSummaryOptions): Promise<RefreshSummaryResult>;
     /** Rolling 누적 요약 조회 — rollup + segment 페이지. 저장된 요약의 단일 진실 소스. */
@@ -2161,7 +2202,15 @@ export class ChatClient implements SdkEventEmitter<ChatClientEvents> {
     /** PM 프롬프트 합성 미리보기 (전역+회사+방) — 참여자 전체. */
     previewRoomPmPrompt(roomId: string): Promise<PmPromptPreviewResponse>;
     joinGroupRoom(roomId: string, password?: string): Promise<ChatRoomResponse>;
-    leaveRoom(roomId: string): Promise<void>;
+    /**
+     * 방 나가기. 방장은 {@code options.newOwnerId} 로 «위임 후 나가기» — 없으면 409 {@code ROOM_OWNER_CANNOT_LEAVE}.
+     * 방을 없애고 나가려면 {@link deleteRoom}.
+     */
+    leaveRoom(roomId: string, options?: LeaveRoomOptions): Promise<void>;
+    /** 방장 위임 — 방장은 방에 남고 MEMBER 가 된다. 방장(OWNER) 전용. 갱신된 방 상세(역할 반영)를 돌려준다. */
+    transferOwnership(roomId: string, newOwnerId: string): Promise<ChatRoomResponse>;
+    /** 방 삭제(소프트) — 방장(OWNER) 전용. 참가자 전원 퇴장, 이후 enterRoom·getRoomInfo 403·joinGroupRoom 404. 본인 구독 자동 해제. */
+    deleteRoom(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>;
@@ -2567,6 +2616,12 @@ export default class TalkFlowClient implements SdkEventEmitter<TalkFlowClientEve
     summarizeWithAssistant(roomId: string, options: SummarizeToolRequest): Promise<AssistantToolResult>;
     /** 특정 메시지 온디맨드 번역 (버튼 진입점, 동기, 요청자 전용 응답). */
     translateWithAssistant(roomId: string, options: TranslateToolRequest): Promise<OnDemandTranslationResponse>;
+    uploadVideoAsset(file: File, options?: FileUploadOptions): Promise<VideoAsset>;
+    analyzeVideo(analysis: VideoAnalysisRequest, options: VideoAnalysisOptions): Promise<VideoAnalysisJob>;
+    analyzeVideoWithAssistant(roomId: string, request: RoomVideoAnalysisRequest, options: VideoAnalysisOptions): Promise<VideoAnalysisJob>;
+    getVideoAnalysis(jobId: string): Promise<VideoAnalysisJob>;
+    cancelVideoAnalysis(jobId: string): Promise<VideoAnalysisCancellation>;
+    getVideoAnalysisCapabilities(): Promise<VideoAnalysisCapabilities>;
     /** Rolling 누적 요약 갱신 트리거 (비동기). 완료는 {@code summaryUpdate} 이벤트 + {@link getSummary} 로 확인. */
     refreshSummary(roomId: string, options?: RefreshSummaryOptions): Promise<RefreshSummaryResult>;
     /** Rolling 누적 요약 조회 — rollup + segment 페이지. 저장된 요약의 단일 진실 소스. */
@@ -2604,7 +2659,15 @@ export default class TalkFlowClient implements SdkEventEmitter<TalkFlowClientEve
     /** PM 프롬프트 합성 미리보기 (전역+회사+방) — 참여자 전체. */
     previewRoomPmPrompt(roomId: string): Promise<PmPromptPreviewResponse>;
     joinGroupRoom(roomId: string, password?: string): Promise<ChatRoomResponse>;
-    leaveRoom(roomId: string): Promise<void>;
+    /**
+     * 방 나가기. 방장은 {@code options.newOwnerId} 로 «위임 후 나가기» — 없으면 409 {@code ROOM_OWNER_CANNOT_LEAVE}.
+     * 방을 없애고 나가려면 {@link deleteRoom}.
+     */
+    leaveRoom(roomId: string, options?: LeaveRoomOptions): Promise<void>;
+    /** 방장 위임 — 방장은 방에 남고 MEMBER 가 된다. 방장(OWNER) 전용. 갱신된 방 상세(역할 반영)를 돌려준다. */
+    transferOwnership(roomId: string, newOwnerId: string): Promise<ChatRoomResponse>;
+    /** 방 삭제(소프트) — 방장(OWNER) 전용. 참가자 전원 퇴장, 이후 enterRoom·getRoomInfo 403·joinGroupRoom 404. 본인 구독 자동 해제. */
+    deleteRoom(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>;
@@ -2815,3 +2878,35 @@ export class RoomUnreadReconciler {
     /** 전체 초기화. */
     clear(): void;
 }
+
+
+/** Caller retains this key and reuses it after a lost response. */
+export interface VideoAnalysisOptions { idempotencyKey: string; }
+export type VideoAnalysisSource =
+    | { type: 'UPLOADED_ASSET'; assetId: string; startMs?: number; endMs?: number }
+    | { type: 'CHAT_ATTACHMENT'; roomId: string; messageId: string; attachmentId: string; startMs?: number; endMs?: number };
+export interface VideoAnalysisRequest { instruction: string; locale?: string; sources: VideoAnalysisSource[]; }
+export interface RoomVideoAnalysisRequest { personaId: string; triggerMessageId: string; analysis: VideoAnalysisRequest; }
+export interface VideoAsset { assetId: string; fileName: string; mimeType: string; sizeBytes: number; durationMs: number; expiresAt: string; }
+export interface VideoAnalysisResult {
+    answerMarkdown: string;
+    evidence: { sourceId: string; startMs: number | null; endMs: number | null; modality: 'VISUAL' | 'AUDIO' | 'BOTH'; observation: string }[];
+    limitations: string[];
+    /** Requested temporal coverage and sampling; not a guarantee every frame was inspected. */
+    coverage: { sourceId: string; startMs: number; endMs: number; framesPerSecond: number }[];
+    model: string; promptVersion: string;
+    usage: { uncachedInputTokens: number; cachedInputTokens: number; outputTokens: number; thinkingTokens: number };
+}
+export interface VideoAnalysisJob {
+    jobId: string; status: 'QUEUED' | 'RUNNING' | 'SUCCEEDED' | 'FAILED' | 'CANCELLED'; phase: string;
+    errorCode: string | null; detail: string | null;
+    sources: { sourceId: string; assetId: string | null; roomId: string | null; messageId: string | null; attachmentId: string | null; startMs: number | null; endMs: number | null }[];
+    result: VideoAnalysisResult | null; createdAt: string; deadlineAt: string;
+    roomId: string | null; streamId: string | null; resultMessageId: string | null; deliveryPending: boolean;
+}
+export interface VideoAnalysisCapabilities {
+    available: boolean; model: string; standaloneUploadConfigured: boolean; maxSources: number;
+    maxBytesPerSource: number; maxTotalDurationMs: number; framesPerSecond: number; mimeTypes: string[];
+}
+
+export interface VideoAnalysisCancellation { jobId: string; status: VideoAnalysisJob['status']; deliveryPending: boolean; }