@vibexnpm/talkx 8.12.0 → 8.13.0

package/package.json

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

package/src/chat/ChatClient.js

@@ -1451,6 +1451,43 @@ class ChatClient extends EventEmitter {
         return this.apiClient.get('/api/v1/files', { roomId, type, size, lastId, lastSortValue });
     }
 
+    /**
+     * PM 보고서 목록 — 내가 지금 참여 중인 방들에 PM 이 올린 작업 결과(지금은 자료조사)를 최신순 커서 페이지로.
+     *
+     * <p>한 줄이 결과 하나다 — 제목(위임 요지)·미리보기(결과 앞 200자)·방·시킨 사람·PM·올라온 시각. 본문은
+     * {@link ChatClient#getPmReport} 로 연다. 보이는 범위는 파일함과 같다 — 참여 중인 방만, 재입장 이전·보관 기간 밖·
+     * 나만 삭제한 결과는 오지 않는다. 실패 안내·단순 답변은 보고서가 아니다.</p>
+     *
+     * <p>{@link ChatClient#getFiles} 처럼 서버 응답 래퍼째 돌려준다 — 페이지는 {@code result.data}. 끝은 {@code hasNext}
+     * 로만 판단한다 — 드물게 짧거나 빈 페이지가 {@code hasNext: true} 와 함께 온다(게시 뒤 결과가 지워진 줄은 빠진다).</p>
+     *
+     * @param {Object} [params]
+     * @param {'RESEARCH'} [params.kind] - 보고서 종류 — 지금은 {@code RESEARCH}(자료조사) 하나, 생략하면 자료조사.
+     *        그 밖의 값이면 400. 종류·방을 바꾸면 커서 없이 처음부터 부른다
+     * @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 getPmReports(params = {}) {
+        const { kind, roomId, size = 50, lastId, lastSortValue } = params;
+        return this.apiClient.get('/api/v1/pm-reports', { kind, roomId, size, lastId, lastSortValue });
+    }
+
+    /**
+     * PM 보고서 상세 — 목록 한 줄과 같은 칸 + 본문({@code content}, 마크다운 · 출처 절 포함).
+     *
+     * <p>채팅에서 결과에 붙었던 안내도 같은 문구로 붙는다 — 대화 변경 고지(본문 위)·이미지 분석 범위 안내(본문 끝).
+     * 없거나 볼 수 없으면(나만 삭제·방에서 나감 등) 404 하나로 답한다. 반환은 래퍼째({@code result.data}).</p>
+     *
+     * @param {string} reportId - 목록 한 줄의 {@code id}
+     * @returns {Promise<Object>}
+     */
+    async getPmReport(reportId) {
+        return this.apiClient.get(`/api/v1/pm-reports/${encodeURIComponent(reportId)}`);
+    }
+
     /**
      * 메시지 목록 조회
      * @param {string} roomId - 채팅방 ID

package/src/talkflow/delegates.js

@@ -22,6 +22,9 @@ const CHAT_DELEGATE_METHODS = [
     'getMessages',
     // 파일함 — 참여 중인 방들의 파일 목록(방 하나로 거르기 가능).
     'getFiles',
+    // PM 보고서 — 참여 중인 방들에 PM 이 올린 작업 결과(지금은 자료조사) 목록·상세.
+    'getPmReports',
+    'getPmReport',
     'fetchLinkPreview',
     'sendMessage',
     'sendMessageOptimistic',

package/types/__typetests__/pmReports.types.ts

@@ -0,0 +1,55 @@
+/**
+ * PM 보고서 타입 — docs/chat.md «PM 보고서» 예제가 <b>실제로 컴파일되는지</b>.
+ *
+ * <p>jest 는 `.d.ts` 를 보지 않는다. 문서가 약속한 모양(반환은 envelope 째 · 커서 두 칸은 직전 응답 그대로 · 이름·제목은
+ * 비어 있을 수 있음 · 종류는 지금 RESEARCH 하나 · 상세는 목록 한 줄 + 본문)이 선언과 맞는지 여기서 tsc 로 고정한다.</p>
+ *
+ * <p>실행: {@code npm run typecheck}</p>
+ */
+import TalkFlowClient from '../index';
+import type { PmReport, PmReportDetail, PmReportListParams } from '../index';
+
+declare const talkflow: TalkFlowClient;
+declare const roomId: string;
+
+// 1) 처음부터 끝까지 — 다음 페이지는 응답의 커서 두 칸을 그대로 넘긴다.
+async function loadAll(filterRoomId?: string): Promise<PmReport[]> {
+    const rows: PmReport[] = [];
+    let params: PmReportListParams = { roomId: filterRoomId, size: 50 };
+    for (;;) {
+        const result = await talkflow.getPmReports(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) 한 줄 그리기 → 열기 — 상세는 같은 칸 + 본문.
+async function open(row: PmReport): Promise<string> {
+    const title: string = row.title ?? row.preview;
+    const who: string = row.requesterName ?? '알 수 없음';
+    const pm: string = row.pmName ?? 'PM';
+    const room: string = row.roomName ?? '';
+    const publishedAt: number = row.publishedAt;
+    const changed: boolean = row.contextChanged;
+    void [who, pm, room, publishedAt, changed];
+    const detail: PmReportDetail = (await talkflow.getPmReport(row.id)).data;
+    const length: number = detail.contentLength;
+    void length;
+    return `${title}\n\n${detail.content}`;
+}
+
+// 3) 종류는 지금 RESEARCH 하나 — 다른 이름은 컴파일에서 막힌다.
+async function wrongKind(): Promise<void> {
+    // @ts-expect-error — 기획은 아직 보고서 종류로 열지 않았다.
+    await talkflow.getPmReports({ kind: 'PLANNING' });
+    await talkflow.getPmReports({ kind: 'RESEARCH', roomId });
+}
+
+void [loadAll, open, wrongKind];

package/types/index.d.ts

@@ -1339,6 +1339,66 @@ export interface ChatFile {
     file: FileMetaData;
 }
 
+/** PM 보고서 종류 — 지금은 자료조사({@code RESEARCH}) 하나. {@link PmReport.kind} 와 {@link PmReportListParams.kind} 가 같은 값. */
+export type PmReportKind = 'RESEARCH';
+
+/** {@link ChatClient.getPmReports} 파라미터 — 보고서 한 페이지. */
+export interface PmReportListParams {
+    /** 보고서 종류 — 생략하면 {@code RESEARCH}. 종류·방을 바꾸면 커서 없이 처음부터 부른다. */
+    kind?: PmReportKind;
+    /** 방 하나로 거르기. 생략하면 내가 지금 참여 중인 방 전부. 참여하지 않은 방이면 403. */
+    roomId?: string;
+    /** 페이지 크기. 기본 50, max 100. */
+    size?: number;
+    /** 직전 응답의 {@code lastId} 그대로. */
+    lastId?: string;
+    /** 직전 응답의 {@code lastSortValue} 그대로(epoch millis). */
+    lastSortValue?: number | string;
+}
+
+/**
+ * PM 보고서 목록 한 줄 — 방에 PM 이 올린 작업 결과 하나.
+ *
+ * <p>보이는 범위는 파일함과 같다 — 참여 중인 방만, 재입장 이전·보관 기간 밖·나만 삭제한 결과는 오지 않는다.</p>
+ */
+export interface PmReport {
+    /** 보고서 id — 상세({@link ChatClient.getPmReport})에 넘기는 값. 목록 key 로 쓴다. */
+    id: string;
+    /** 결과 메시지 — {@link ChatMessage.messageId} 와 같은 값. 채팅에서 그 메시지로 이동할 때 쓴다. */
+    messageId: string;
+    kind: PmReportKind;
+    /** 제목 — PM 이 작업을 맡긴 요지(120자). 비어 있으면 null. */
+    title: string | null;
+    /** 결과 앞 200자 — 마크다운 원문 그대로. */
+    preview: string;
+    /** 채팅에서 «작업 중 참고한 대화 일부가 수정/삭제되어…» 고지가 붙은 결과인가 — 상세 본문 위에 같은 문구가 붙는다. */
+    contextChanged: boolean;
+    roomId: string;
+    /** 방 이름 — 1:1 은 상대 이름. 찾지 못하면 null. */
+    roomName: string | null;
+    roomType: ChatRoomTypeValue | null;
+    /** 작업을 시킨 사람. */
+    requesterId: string | null;
+    /** 그 사람 닉네임 — 찾지 못하면(탈퇴 등) null. */
+    requesterName: string | null;
+    requesterProfileUrl: string | null;
+    /** 결과를 올린 PM 페르소나 이름 — 찾지 못하면 null. */
+    pmName: string | null;
+    /** 결과가 방에 올라온 시각(epoch millis). */
+    publishedAt: number;
+}
+
+/** PM 보고서 상세 — 목록 한 줄({@link PmReport})과 같은 칸 + 본문. */
+export interface PmReportDetail extends PmReport {
+    /**
+     * 본문(마크다운) — 결과 전문(출처 절 포함). 채팅에서 결과에 붙었던 안내도 같은 문구로 붙는다: 대화 변경 고지(본문 위,
+     * {@code contextChanged} 일 때)·이미지 분석 범위 안내(본문 끝).
+     */
+    content: string;
+    /** 본문 글자 수(코드포인트). */
+    contentLength: number;
+}
+
 // ============================================================================
 // Event payloads
 // ============================================================================
@@ -2455,6 +2515,17 @@ export class ChatClient implements SdkEventEmitter<ChatClientEvents> {
      * 다음 페이지는 응답의 {@code lastId}·{@code lastSortValue} 를 그대로 넘긴다.
      */
     getFiles(params?: ChatFileListParams): Promise<ApiEnvelope<CursorPageResponse<ChatFile>>>;
+
+    /**
+     * PM 보고서 목록 — 내가 지금 참여 중인 방들에 PM 이 올린 작업 결과(지금은 자료조사), 최신순 커서 페이징. 반환은
+     * envelope 째({@code result.data.content}). 보이는 범위는 파일함과 같다. 다음 페이지는 응답의 {@code lastId}·
+     * {@code lastSortValue} 를 그대로 넘긴다. 끝은 {@code hasNext} 로만 판단한다 — 드물게 짧거나 빈 페이지가
+     * {@code hasNext: true} 와 함께 온다.
+     */
+    getPmReports(params?: PmReportListParams): Promise<ApiEnvelope<CursorPageResponse<PmReport>>>;
+
+    /** PM 보고서 상세 — 목록 한 줄 + 본문({@code content}). 없거나 볼 수 없으면 404. 반환은 envelope 째. */
+    getPmReport(reportId: string): Promise<ApiEnvelope<PmReportDetail>>;
     fetchLinkPreview(url: string): Promise<FetchLinkPreviewResponse | null>;
     sendMessage(roomId: string, data: SendMessageData): Promise<SendMessageResult>;
     /** Optimistic UI 버전 — 응답 전 base/예측 messageIds 동기 반환. */
@@ -2948,6 +3019,17 @@ export default class TalkFlowClient implements SdkEventEmitter<TalkFlowClientEve
      * 다음 페이지는 응답의 {@code lastId}·{@code lastSortValue} 를 그대로 넘긴다.
      */
     getFiles(params?: ChatFileListParams): Promise<ApiEnvelope<CursorPageResponse<ChatFile>>>;
+
+    /**
+     * PM 보고서 목록 — 내가 지금 참여 중인 방들에 PM 이 올린 작업 결과(지금은 자료조사), 최신순 커서 페이징. 반환은
+     * envelope 째({@code result.data.content}). 보이는 범위는 파일함과 같다. 다음 페이지는 응답의 {@code lastId}·
+     * {@code lastSortValue} 를 그대로 넘긴다. 끝은 {@code hasNext} 로만 판단한다 — 드물게 짧거나 빈 페이지가
+     * {@code hasNext: true} 와 함께 온다.
+     */
+    getPmReports(params?: PmReportListParams): Promise<ApiEnvelope<CursorPageResponse<PmReport>>>;
+
+    /** PM 보고서 상세 — 목록 한 줄 + 본문({@code content}). 없거나 볼 수 없으면 404. 반환은 envelope 째. */
+    getPmReport(reportId: string): Promise<ApiEnvelope<PmReportDetail>>;
     fetchLinkPreview(url: string): Promise<FetchLinkPreviewResponse | null>;
     sendMessage(roomId: string, data: SendMessageData): Promise<SendMessageResult>;
     /** Optimistic UI 버전 — 응답 전 base/예측 messageIds 동기 반환. */