@vibexnpm/talkx 8.10.0 → 8.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@vibexnpm/talkx",
-    "version": "8.10.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

package/src/talkflow/delegates.js

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

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

@@ -631,6 +631,8 @@ export interface FileMetaData {
      */
     fileId?: string;
     fileUrl: string;
+    /** MIME 타입(예: {@code 'image/png'}) — 서버가 업로드·메시지·파일함 응답에 싣는 값. */
+    fileType?: string;
     fileName?: string;
     fileSize?: number;
     contentType?: string;
@@ -1288,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
 // ============================================================================
@@ -2397,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 동기 반환. */
@@ -2883,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 동기 반환. */