@vibexnpm/talkx 8.9.0 → 8.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@vibexnpm/talkx",
-    "version": "8.9.0",
+    "version": "8.11.0",
     "type": "module",
     "description": "TalkFlow SDK - Chat & WebRTC unified client",
     "main": "dist/talkflow-sdk.umd.js",

package/src/chat/ChatClient.js

@@ -1429,6 +1429,26 @@ class ChatClient extends EventEmitter {
         return this.apiClient.get('/api/v1/rooms/groups/all', { size, lastId, lastSortValue });
     }
 
+    /**
+     * 파일함 — 내가 지금 참여 중인 방들에 올라온 파일(미디어 포함) 목록, 최신순 커서 페이지.
+     *
+     * <p>한 줄이 파일 하나다(메시지 하나에 파일이 여러 개면 여러 줄). 보이는 범위는 채팅 화면과 같다 — 참여 중인 방만,
+     * 재입장 이전·보관 기간 밖·삭제된 메시지의 파일은 오지 않는다. PM 이 만든 파일도 온다.</p>
+     *
+     * <p>다른 목록 조회({@link ChatClient#getMessages})처럼 서버 응답 래퍼째 돌려준다 — 페이지는 {@code result.data}.</p>
+     *
+     * @param {Object} [params]
+     * @param {string} [params.roomId] - 방 하나로 거르기. 생략하면 참여 중인 방 전부. 참여하지 않은 방이면 403
+     * @param {number} [params.size=50] - 페이지 크기 (1-100, 파일 수)
+     * @param {string} [params.lastId] - 직전 응답의 lastId 를 그대로 — 불투명 값이라 만들어 쓰지 않는다
+     * @param {number} [params.lastSortValue] - 직전 응답의 lastSortValue 를 그대로
+     * @returns {Promise<Object>}
+     */
+    async getFiles(params = {}) {
+        const { roomId, size = 50, lastId, lastSortValue } = params;
+        return this.apiClient.get('/api/v1/files', { roomId, size, lastId, lastSortValue });
+    }
+
     /**
      * 메시지 목록 조회
      * @param {string} roomId - 채팅방 ID
@@ -3068,6 +3088,16 @@ class ChatClient extends EventEmitter {
                     unreadVersion: event.unreadVersion
                 });
                 break;
+            case RoomListEventType.AI_UNAVAILABLE:
+                // PM 을 직접 불렀는데 회사 AI 가 막혀 답하지 않았다 — 부른 사람에게만 온다. 잠깐 알리고 사라지게(토스트).
+                // 리스트·미독은 건드리지 않는다. 막힌 상태를 계속 보여 줄 띠는 getMyProfile().aiBlocked 로 그린다.
+                this.emit('aiUnavailable', {
+                    roomId: event.roomId,
+                    messageId: event.messageId,
+                    aiBlocked: event.aiBlocked,
+                    timestamp: event.timestamp
+                });
+                break;
             default:
                 this.logger.warn('Unknown room list event type:', event.eventType);
         }

package/src/constants.js

@@ -355,7 +355,14 @@ export const RoomListEventType = {
      * unreadVersion 으로 순서 역전(읽음 0 이 신규 메시지보다 먼저 도착)을 방어한다.
      * SDK 는 이를 roomListUnreadUpdated 이벤트로 emit 한다.
      */
-    ROOM_UNREAD_UPDATED: 'ROOM_UNREAD_UPDATED'
+    ROOM_UNREAD_UPDATED: 'ROOM_UNREAD_UPDATED',
+    /**
+     * PM 을 직접(@PM) 불렀는데 회사 AI 가 막혀(크레딧·결제) 답하지 않았다 → 부른 사람에게만 온다. 방에는 아무것도 남지 않는다.
+     * 잠깐 알리고 사라지게(토스트) 쓴다. 리스트·미독은 건드리지 않는다. 사유는 aiBlocked(REST 402 와 같은 코드).
+     * 막힌 상태를 계속 보여 줄 띠는 getMyProfile() 의 aiBlocked 로 그린다.
+     * SDK 는 이를 aiUnavailable 이벤트로 emit 한다.
+     */
+    AI_UNAVAILABLE: 'AI_UNAVAILABLE'
 };
 
 /**

package/src/talkflow/delegates.js

@@ -20,6 +20,8 @@ const CHAT_DELEGATE_METHODS = [
     'getAllGroupRooms',
     'enterRoom',
     'getMessages',
+    // 파일함 — 참여 중인 방들의 파일 목록(방 하나로 거르기 가능).
+    'getFiles',
     'fetchLinkPreview',
     'sendMessage',
     'sendMessageOptimistic',

package/src/talkflow/eventForwarding.js

@@ -53,6 +53,8 @@ const CHAT_EVENT_MAP = [
     ['roomListDeleted', 'roomListDeleted'],
     ['roomListRoomUpdated', 'roomListRoomUpdated'],
     ['roomListUnreadUpdated', 'roomListUnreadUpdated'],
+    // @PM 을 불렀는데 회사 AI 가 막힘 — 부른 사람에게만 오는 방 목록 채널 알림(AI_UNAVAILABLE).
+    ['aiUnavailable', 'aiUnavailable'],
     // Gmail 메일함 — mailChanged 는 받은 그대로. 새 메일 알림(newMail)은 아래에서 푸시와 합쳐 따로 낸다.
     ['mailSubscribed', 'mailSubscribed'],
     ['mailUnsubscribed', 'mailUnsubscribed'],

package/types/__typetests__/aiUnavailable.types.ts

@@ -0,0 +1,48 @@
+/**
+ * «AI 사용 불가» 알림·회사 AI 막힘 띠(8.10.0) — FE 가 타입 단언 없이 쓰는지 tsc 로 고정한다.
+ *
+ * <p>jest 는 `.d.ts` 를 보지 않는다. 최상위 client 와 chat 양쪽에서 `aiUnavailable` 를 구독할 수 있는지, 사유가 유니온인지,
+ * `getMyProfile()` 의 `aiBlocked` 에 구독 없음(`NOT_SUBSCRIBED`)이 들어갈 수 없는지(서버가 `/me` 에는 싣지 않는다)를 본다.</p>
+ *
+ * <p>실행: {@code npm run typecheck}</p>
+ */
+import TalkFlowClient, { RoomListEventType } from '../index';
+import type { AiBlockedReason, AiUnavailableEvent, ChatClient, MyProfile, RoomListUpdateEvent } from '../index';
+
+declare const talkflow: TalkFlowClient;
+/** {@code talkflow.chat} 은 연결 전 null 이라 선언이 nullable 이다 — 연결된 chat 을 직접 받는 모양으로 본다. */
+declare const chat: ChatClient;
+
+function toast(_reason: AiBlockedReason, _roomId: string): void {}
+
+// 전용 이벤트 — 최상위·chat 양쪽
+talkflow.on('aiUnavailable', (e: AiUnavailableEvent) => toast(e.aiBlocked, e.roomId));
+chat.on('aiUnavailable', (e) => {
+    const reason: AiBlockedReason = e.aiBlocked;
+    const messageId: string | undefined = e.messageId;
+    toast(reason, e.roomId);
+    return messageId;
+});
+
+// 통합 이벤트로 받던 코드도 단언 없이 좁혀진다
+talkflow.on('roomListUpdate', (e: RoomListUpdateEvent) => {
+    if (e.eventType === RoomListEventType.AI_UNAVAILABLE && e.aiBlocked) {
+        toast(e.aiBlocked, e.roomId);
+    }
+});
+
+// 사유 유니온 — 서버 REST 402 코드와 같다
+const reasons: AiBlockedReason[] = ['CREDIT_EXHAUSTED', 'CREDIT_INSUFFICIENT', 'BILLING_SUSPENDED', 'NOT_SUBSCRIBED'];
+// @ts-expect-error — 모르는 사유는 막힌다
+const unknownReason: AiBlockedReason = 'SUSPENDED';
+
+// 채팅방 상단 띠 — /me 의 aiBlocked
+async function banner(): Promise<string | null> {
+    const me: MyProfile = await talkflow.getMyProfile();
+    return me.aiBlocked ?? null;
+}
+const profileReason: NonNullable<MyProfile['aiBlocked']> = 'CREDIT_EXHAUSTED';
+// @ts-expect-error — /me 에는 구독 없음이 오지 않는다(그 회사는 구독 필요 화면이 맡는다)
+const notOnProfile: NonNullable<MyProfile['aiBlocked']> = 'NOT_SUBSCRIBED';
+
+export { reasons, unknownReason, banner, profileReason, notOnProfile };

package/types/__typetests__/files.types.ts

@@ -0,0 +1,53 @@
+/**
+ * 파일함 타입 — docs/chat.md «파일함» 예제가 <b>실제로 컴파일되는지</b>.
+ *
+ * <p>jest 는 `.d.ts` 를 보지 않는다. 문서가 약속한 모양(반환은 envelope 째 · 한 줄 = 파일 하나 · 커서 두 칸은 직전 응답
+ * 그대로 · 이름·방 이름은 비어 있을 수 있음 · 종류는 다섯 값)이 선언과 맞는지 여기서 tsc 로 고정한다.</p>
+ *
+ * <p>실행: {@code npm run typecheck}</p>
+ */
+import TalkFlowClient from '../index';
+import type { ChatFile, ChatFileListParams } from '../index';
+
+declare const talkflow: TalkFlowClient;
+declare const roomId: string;
+
+// 1) 처음부터 끝까지 — 다음 페이지는 응답의 커서 두 칸을 그대로 넘긴다.
+async function loadAll(filterRoomId?: string): Promise<ChatFile[]> {
+    const rows: ChatFile[] = [];
+    let params: ChatFileListParams = { roomId: filterRoomId, size: 50 };
+    for (;;) {
+        const result = await talkflow.getFiles(params);
+        rows.push(...result.data.content);
+        if (!result.data.hasNext) {
+            return rows;
+        }
+        params = {
+            ...params,
+            lastId: result.data.lastId ?? undefined,
+            lastSortValue: result.data.lastSortValue ?? undefined,
+        };
+    }
+}
+
+// 2) 한 줄 그리기 — 누가·언제·어느 방·파일명·다운로드 링크·종류.
+function describe(row: ChatFile): string {
+    const who: string = row.uploaderName ?? '알 수 없음';
+    const madeByPm: boolean = row.uploaderType === 'ASSISTANT';
+    const room: string = row.roomName ?? '';
+    const uploadedAt: number = row.uploadedAt;
+    const kind: 'IMAGE' | 'VIDEO' | 'AUDIO' | 'DOCUMENT' | 'FILE' = row.category;
+    const link: string = row.file.fileUrl;
+    const mime: string | undefined = row.file.fileType;
+    void [madeByPm, uploadedAt, kind, mime];
+    return `${who} · ${room} · ${row.file.fileName ?? link}`;
+}
+
+// 3) 방 목록 필터는 파일함에 없다 — 방 하나는 roomId 로 고른다.
+async function wrongFilter(): Promise<void> {
+    // @ts-expect-error — type 은 방 목록(getRooms) 파라미터다.
+    await talkflow.getFiles({ type: 'GROUP' });
+    await talkflow.getFiles({ roomId });
+}
+
+void [loadAll, describe, wrongFilter];

package/types/index.d.ts

@@ -534,6 +534,7 @@ export const RoomListEventType: {
     readonly ROOM_DELETED: 'ROOM_DELETED';
     readonly MESSAGE_RETENTION_CLEANUP: 'MESSAGE_RETENTION_CLEANUP';
     readonly ROOM_UNREAD_UPDATED: 'ROOM_UNREAD_UPDATED';
+    readonly AI_UNAVAILABLE: 'AI_UNAVAILABLE';
 };
 export type RoomListEventTypeValue = typeof RoomListEventType[keyof typeof RoomListEventType];
 
@@ -630,6 +631,8 @@ export interface FileMetaData {
      */
     fileId?: string;
     fileUrl: string;
+    /** MIME 타입(예: {@code 'image/png'}) — 서버가 업로드·메시지·파일함 응답에 싣는 값. */
+    fileType?: string;
     fileName?: string;
     fileSize?: number;
     contentType?: string;
@@ -1173,6 +1176,14 @@ export interface MyProfile {
     mustChangePassword: boolean;
     accessToken?: string;
     expiresIn?: number;
+    /**
+     * 회사 AI 가 지금 막혔는가 — 채팅방 상단 띠용. 막혔으면 사유, 열려 있으면 키가 없다.
+     *
+     * PM 입구와 같은 판정이라 값이 있는 동안 PM 은 불러도 답하지 않는다. 최대 30초 늦게 바뀔 수 있고, 서버가 상태 변화를 따로
+     * 알려 주지 않으므로 앱 시작·방 입장·탭 복귀·{@link AiUnavailableEvent} 수신 때 다시 읽는다. 게스트에게는 없다.
+     * 구독 없음(`NOT_SUBSCRIBED`)은 여기 오지 않는다 — 그 회사는 구독 필요 화면이 맡는다.
+     */
+    aiBlocked?: Exclude<AiBlockedReason, 'NOT_SUBSCRIBED'>;
 }
 
 /** 채팅방 참가자. */
@@ -1279,6 +1290,47 @@ export interface ApiEnvelope<T> {
     message?: string;
 }
 
+/** {@link ChatClient.getFiles} 파라미터 — 파일함 한 페이지. */
+export interface ChatFileListParams {
+    /** 방 하나로 거르기. 생략하면 내가 지금 참여 중인 방 전부. 참여하지 않은 방이면 403. */
+    roomId?: string;
+    /** 페이지 크기(파일 수). 기본 50, max 100. */
+    size?: number;
+    /** 직전 응답의 {@code lastId} 그대로 — 불투명 값이라 만들어 쓰지 않는다. */
+    lastId?: string;
+    /** 직전 응답의 {@code lastSortValue} 그대로(epoch millis) — {@link CursorPageParams} 와 같은 형. */
+    lastSortValue?: number | string;
+}
+
+/**
+ * 파일함 한 줄 — 파일 하나(메시지 하나에 파일이 여러 개면 여러 줄).
+ *
+ * <p>보이는 범위는 채팅 화면과 같다 — 참여 중인 방만, 재입장 이전·보관 기간 밖·삭제된 메시지의 파일은 오지 않는다.</p>
+ */
+export interface ChatFile {
+    /** 이 줄의 id — 목록 key 로 쓴다. 페이지 커서 {@code lastId} 와 같은 모양. */
+    id: string;
+    roomId: string;
+    /** 방 이름 — 1:1 은 상대 이름. 상대를 찾지 못하면 null. */
+    roomName: string | null;
+    roomType: ChatRoomTypeValue | null;
+    /** 이 파일이 실린 메시지 — {@link ChatMessage.messageId} 와 같은 값. */
+    messageId: string;
+    /** 올린 쪽 id — 사람은 사용자 id, PM 이 만든 파일은 페르소나 id. */
+    uploaderId: string;
+    uploaderType: SenderTypeValue;
+    /** 사람은 닉네임, PM 은 페르소나 이름. 찾지 못하면(탈퇴·삭제) null. */
+    uploaderName: string | null;
+    /** 사람만. PM 은 null. */
+    uploaderProfileUrl: string | null;
+    /** 올린 시각(epoch millis). */
+    uploadedAt: number;
+    /** 종류 — 파일 MIME 기준, 채팅 첨부 분류와 같다. */
+    category: 'IMAGE' | 'VIDEO' | 'AUDIO' | 'DOCUMENT' | 'FILE';
+    /** 파일명({@code fileName})·다운로드 링크({@code fileUrl})·MIME({@code fileType})·크기·썸네일 — 채팅 메시지 첨부와 같은 모양. */
+    file: FileMetaData;
+}
+
 // ============================================================================
 // Event payloads
 // ============================================================================
@@ -1356,9 +1408,36 @@ export interface RoomListUpdateEvent {
      * {@code ROOM_UNREAD_UPDATED} 에 실려, 순서 역전을 {@link RoomUnreadReconciler} 가 판별한다.
      */
     unreadVersion?: number;
+    /** {@code AI_UNAVAILABLE} 전용 — 회사 AI 가 막힌 사유. 다른 eventType 에서는 undefined. 전용 이벤트 {@link AiUnavailableEvent} 로도 받을 수 있다. */
+    aiBlocked?: AiBlockedReason;
     [extra: string]: unknown;
 }
 
+/**
+ * 회사 AI 가 막힌 사유 — AI 버튼(요약·번역 등)이 받는 REST 402 오류 코드와 같다.
+ * <ul>
+ *   <li>{@code CREDIT_EXHAUSTED} — 이번 결제 기간 AI 크레딧을 다 썼다(다음 갱신·충전 때 풀림).</li>
+ *   <li>{@code CREDIT_INSUFFICIENT} — 남은 크레딧을 진행 중인 AI 작업이 잡고 있다(작업이 끝나면 풀림, 드묾).</li>
+ *   <li>{@code BILLING_SUSPENDED} — 결제가 확인되지 않았다.</li>
+ *   <li>{@code NOT_SUBSCRIBED} — 회사 구독이 없다. {@link AiUnavailableEvent} 에만 드물게 오고 {@link MyProfile.aiBlocked} 에는 오지 않는다.</li>
+ * </ul>
+ */
+export type AiBlockedReason = 'CREDIT_EXHAUSTED' | 'CREDIT_INSUFFICIENT' | 'BILLING_SUSPENDED' | 'NOT_SUBSCRIBED';
+
+/**
+ * `aiUnavailable` 이벤트 payload — PM 을 직접(@PM) 불렀는데 회사 AI 가 막혀 답하지 않았다. <b>부른 사람에게만</b> 오고, 방에는
+ * 아무것도 남지 않는다. 잠깐 알리고 사라지게(토스트) 쓴다 — 리스트·미독은 바꾸지 않는다. 막힌 상태를 계속 보여 줄 띠는
+ * {@link MyProfile.aiBlocked} 로 그린다.
+ */
+export interface AiUnavailableEvent {
+    roomId: string;
+    /** 부른 메시지. */
+    messageId?: string;
+    aiBlocked: AiBlockedReason;
+    /** 서버 발행 시각(epoch millis). */
+    timestamp?: number;
+}
+
 /**
  * `roomListUnreadUpdated` 이벤트 payload — 내가 어느 기기에서 읽든 같은 사용자의 다른 세션에 전달된다.
  *
@@ -2000,7 +2079,7 @@ export interface RetentionCleanupPayload {
  * TalkFlowClient 이벤트 맵 — 런타임 {@code TalkFlowClient.js} 의 {@code this.emit(...)} 호출 기반.
  *
  * <p><b>Connection 관련</b>: stateChange, connected, disconnected, reconnecting, reconnected, resumed, subscriptionRequired, connectionError, tokenSet, loggedOut</p>
- * <p><b>Chat 관련 (ChatClient 이벤트를 이 이름으로 re-emit)</b>: chatMessage, newChatMessage, messageUpdated, messageDeleted, reactionChanged, linkPreviewAttached, messageRead, typing, assistantProgress, memberJoined, memberLeft, roomSubscribed, roomUnsubscribed, roomListSubscribed, roomListUnsubscribed, roomListUpdate, roomListMessage, roomListCreated, roomListJoined, roomListLeft, roomListSelfLeft, roomListRoomUpdated, retentionCleanup</p>
+ * <p><b>Chat 관련 (ChatClient 이벤트를 이 이름으로 re-emit)</b>: chatMessage, newChatMessage, messageUpdated, messageDeleted, reactionChanged, linkPreviewAttached, messageRead, typing, assistantProgress, memberJoined, memberLeft, roomSubscribed, roomUnsubscribed, roomListSubscribed, roomListUnsubscribed, roomListUpdate, roomListMessage, roomListCreated, roomListJoined, roomListLeft, roomListSelfLeft, roomListRoomUpdated, aiUnavailable, 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>
  */
@@ -2088,6 +2167,8 @@ export interface TalkFlowClientEvents {
     roomListRoomUpdated: RoomListUpdateEvent;
     /** 내가 어느 기기에서 읽든 방별 미독 절대값(+version)을 통지 — 크로스-디바이스 badge 동기화. */
     roomListUnreadUpdated: RoomUnreadUpdatedEvent;
+    /** @PM 을 불렀는데 회사 AI 가 막혀 PM 이 답하지 않음 (AI_UNAVAILABLE) — 부른 사람에게만 온다. 잠깐 알리고 사라지게. */
+    aiUnavailable: AiUnavailableEvent;
     mailSubscribed: Record<string, unknown>;
     mailUnsubscribed: Record<string, unknown>;
     mailChanged: MailChangedEvent;
@@ -2204,6 +2285,8 @@ export interface ChatClientEvents {
     roomListRoomUpdated: RoomListUpdateEvent;
     /** 내가 어느 기기에서 읽든 방별 미독 절대값(+version)을 통지 — 크로스-디바이스 badge 동기화. */
     roomListUnreadUpdated: RoomUnreadUpdatedEvent;
+    /** @PM 을 불렀는데 회사 AI 가 막혀 PM 이 답하지 않음 (AI_UNAVAILABLE) — 부른 사람에게만 온다. 잠깐 알리고 사라지게. */
+    aiUnavailable: AiUnavailableEvent;
     mailSubscribed: Record<string, unknown>;
     mailUnsubscribed: Record<string, unknown>;
     mailChanged: MailChangedEvent;
@@ -2357,6 +2440,13 @@ export class ChatClient implements SdkEventEmitter<ChatClientEvents> {
      * WebSocket 이벤트와 동일 형 (REST 원시 응답은 ISO 문자열).</p>
      */
     getMessages(roomId: string, params?: CursorPageParams): Promise<ApiEnvelope<CursorPageResponse<ChatMessage>>>;
+
+    /**
+     * 파일함 — 내가 지금 참여 중인 방들에 올라온 파일(미디어 포함), 최신순 커서 페이징. 반환은 envelope 째
+     * ({@code result.data.content}). 한 줄이 파일 하나다. {@code roomId} 를 주면 그 방만(참여하지 않은 방이면 403).
+     * 다음 페이지는 응답의 {@code lastId}·{@code lastSortValue} 를 그대로 넘긴다.
+     */
+    getFiles(params?: ChatFileListParams): Promise<ApiEnvelope<CursorPageResponse<ChatFile>>>;
     fetchLinkPreview(url: string): Promise<FetchLinkPreviewResponse | null>;
     sendMessage(roomId: string, data: SendMessageData): Promise<SendMessageResult>;
     /** Optimistic UI 버전 — 응답 전 base/예측 messageIds 동기 반환. */
@@ -2843,6 +2933,13 @@ export default class TalkFlowClient implements SdkEventEmitter<TalkFlowClientEve
      * WebSocket 이벤트와 동일 형 (REST 원시 응답은 ISO 문자열).</p>
      */
     getMessages(roomId: string, params?: CursorPageParams): Promise<ApiEnvelope<CursorPageResponse<ChatMessage>>>;
+
+    /**
+     * 파일함 — 내가 지금 참여 중인 방들에 올라온 파일(미디어 포함), 최신순 커서 페이징. 반환은 envelope 째
+     * ({@code result.data.content}). 한 줄이 파일 하나다. {@code roomId} 를 주면 그 방만(참여하지 않은 방이면 403).
+     * 다음 페이지는 응답의 {@code lastId}·{@code lastSortValue} 를 그대로 넘긴다.
+     */
+    getFiles(params?: ChatFileListParams): Promise<ApiEnvelope<CursorPageResponse<ChatFile>>>;
     fetchLinkPreview(url: string): Promise<FetchLinkPreviewResponse | null>;
     sendMessage(roomId: string, data: SendMessageData): Promise<SendMessageResult>;
     /** Optimistic UI 버전 — 응답 전 base/예측 messageIds 동기 반환. */