@vibexnpm/talkx 7.0.0 → 7.2.0

package/package.json

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

package/src/chat/ChatClient.js

@@ -142,6 +142,7 @@ class ChatClient extends EventEmitter {
             THINKING: '생각 중…',
             SEARCHING: '검색 중…',
             PLANNING: '기획 중…',
+            DOCUMENT_ANALYSIS: '문서 분석 중…',
             WRITING: '작성 중…'
         };
         // PHASE 의 expiresAt 누락/이상 시 fallback TTL (ms) — 서버 ttl(최소 30s) 보다 약간 길게.
@@ -3078,12 +3079,19 @@ class ChatClient extends EventEmitter {
                 return;
             }
             const phase = event.phase || null;
+            const samePhase = Boolean(prevSlot && prevSlot.phase === phase);
+            // 같은 phase의 일반 heartbeat에는 progress가 없다. 그 틱이 직전 실측 숫자를 지우지 않게
+            // 보존하고, phase가 바뀔 때만 이전 작업의 숫자를 폐기한다.
+            const progress = event.progress
+                ? this._normalizeAssistantProgress(event.progress)
+                : (samePhase && prevSlot ? prevSlot.progress : null);
             // 같은 stream 의 PHASE 재발행(B-3 synthesis heartbeat 등)이면 누적 상태를 보존한다.
             // ⚠️ 새 stream 의 커서는 <b>-1</b> 로 연다. DeltaCoalescer 의 첫 청크가 seq=0 이라 0 으로 열면
             // 첫 글자가 "중복"으로 버려진다 (설계 §5.5.0).
             const prev = prevSlot;
             const slot = this._setAssistantSlot(roomId, streamId, event, {
                 phase,
+                progress,
                 phaseUpdatedAt: createdAt !== null ? createdAt : (prev ? prev.phaseUpdatedAt : 0),
                 text: prev ? (prev.text || '') : '',
                 lastSeq: prev ? this._seqOf(prev.lastSeq) : -1,
@@ -3132,7 +3140,9 @@ class ChatClient extends EventEmitter {
                 lastSeq = seq;
             }
 
-            const slot = this._setAssistantSlot(roomId, streamId, event, { phase, text, lastSeq, textAvailable });
+            const slot = this._setAssistantSlot(roomId, streamId, event, {
+                phase, progress: prev ? (prev.progress || null) : null, text, lastSeq, textAvailable
+            });
             this._emitAssistantStream(roomId, streamId, slot, {
                 active: true,
                 text: slot.textAvailable ? slot.text : null,            // 누적 전체(버블 렌더용)
@@ -3153,6 +3163,7 @@ class ChatClient extends EventEmitter {
                 active: false,
                 personaId: event.personaId || (slot && slot.personaId) || null,
                 phase: null,
+                progress: null,
                 label: null,
                 status: event.status || null,
                 messageId: event.messageId || null
@@ -3242,7 +3253,7 @@ class ChatClient extends EventEmitter {
                 // 유예 구간에 걸린 종료분. 진행 표시를 켜지 않고 최종 메시지로 바로 확정시킨다.
                 this._tombstoneAssistantStream(roomId, streamId);
                 this._emitAssistantStream(roomId, streamId, null, {
-                    active: false, phase: null, label: null, personaId: s.personaId || null,
+                    active: false, phase: null, progress: null, label: null, personaId: s.personaId || null,
                     status: s.doneStatus || null, messageId: s.messageId || null, resumed: true
                 });
                 return;
@@ -3253,6 +3264,7 @@ class ChatClient extends EventEmitter {
                 personaId: s.personaId, expiresAt: undefined
             }, {
                 phase: s.phase || null,
+                progress: this._normalizeAssistantProgress(s.progress),
                 phaseUpdatedAt: typeof s.phaseUpdatedAt === 'number' ? s.phaseUpdatedAt : 0,
                 text: textAvailable ? (s.text || '') : '',
                 lastSeq: this._seqOf(s.lastSeq),
@@ -3452,6 +3464,7 @@ class ChatClient extends EventEmitter {
         const slot = {
             personaId: event.personaId || (prev && prev.personaId) || null,
             phase: fields.phase,
+            progress: fields.progress || null,
             // 마지막으로 <b>적용된</b> PHASE 의 발행 시각 — pending PHASE 역행 판정 커서(§6.2).
             phaseUpdatedAt: fields.phaseUpdatedAt !== undefined
                 ? fields.phaseUpdatedAt
@@ -3476,7 +3489,7 @@ class ChatClient extends EventEmitter {
         this._deleteAssistantSlot(roomId, streamId);
         this.logger.debug(`Assistant progress auto-cleared (timeout): room=${roomId}, stream=${streamId}`);
         this._emitAssistantStream(roomId, streamId, slot, {
-            active: false, phase: null, label: null, reason: 'timeout'
+            active: false, phase: null, progress: null, label: null, reason: 'timeout'
         });
     }
 
@@ -3491,12 +3504,14 @@ class ChatClient extends EventEmitter {
      */
     _emitAssistantStream(roomId, streamId, slot, overrides) {
         const phase = 'phase' in overrides ? overrides.phase : (slot ? slot.phase : null);
+        const progress = 'progress' in overrides ? overrides.progress : (slot ? slot.progress : null);
         this.emit('assistantProgress', {
             roomId,
             streamId,
             personaId: slot ? slot.personaId : null,
             phase,
-            label: phase ? (this._assistantPhaseLabels[phase] || null) : null,
+            progress,
+            label: this._assistantPhaseLabel(phase, progress),
             textAvailable: slot ? slot.textAvailable : true,
             lastSeq: slot ? slot.lastSeq : -1,
             ...overrides
@@ -3528,6 +3543,7 @@ class ChatClient extends EventEmitter {
             return {
                 roomId, active: false, streamCount: 0,
                 streamId: null, personaId: null, phase: null, label: null, text: null, textAvailable: true,
+                progress: null,
                 streams: []
             };
         }
@@ -3539,7 +3555,8 @@ class ChatClient extends EventEmitter {
             streamId,
             personaId: slot.personaId,
             phase: slot.phase,
-            label: slot.phase ? (this._assistantPhaseLabels[slot.phase] || null) : null,
+            progress: slot.progress || null,
+            label: this._assistantPhaseLabel(slot.phase, slot.progress),
             text: slot.textAvailable ? (slot.text || null) : null,
             textAvailable: slot.textAvailable,
             // stream 단위 UI(권장 (B))가 마운트 즉시 버블을 복원할 수 있도록 전부 싣는다.
@@ -3550,7 +3567,8 @@ class ChatClient extends EventEmitter {
                     streamId: id,
                     personaId: s.personaId,
                     phase: s.phase,
-                    label: s.phase ? (this._assistantPhaseLabels[s.phase] || null) : null,
+                    progress: s.progress || null,
+                    label: this._assistantPhaseLabel(s.phase, s.progress),
                     text: s.textAvailable ? (s.text || null) : null,
                     textAvailable: s.textAvailable,
                     resumed: s.resumed === true
@@ -3558,6 +3576,32 @@ class ChatClient extends EventEmitter {
         };
     }
 
+    /** @private */
+    _normalizeAssistantProgress(progress) {
+        if (!progress || !['ANALYZING', 'SUMMARIZING'].includes(progress.stage)) return null;
+        if (progress.stage === 'SUMMARIZING') {
+            return { stage: 'SUMMARIZING', current: null, total: null, unit: null };
+        }
+        const current = Number.isInteger(progress.current) ? progress.current : null;
+        const total = Number.isInteger(progress.total) ? progress.total : null;
+        const unit = ['DOCUMENT', 'PAGE', 'TEXT_CHUNK'].includes(progress.unit) ? progress.unit : null;
+        if (current === null || total === null || !unit || current < 0 || total < 1 || current > total) {
+            return null;
+        }
+        return { stage: 'ANALYZING', current, total, unit };
+    }
+
+    /** @private */
+    _assistantPhaseLabel(phase, progress) {
+        if (!phase) return null;
+        if (phase !== 'DOCUMENT_ANALYSIS') return this._assistantPhaseLabels[phase] || null;
+        if (progress && progress.stage === 'SUMMARIZING') return '분석 결과 종합 중…';
+        if (!progress || progress.stage !== 'ANALYZING') return this._assistantPhaseLabels[phase];
+        const suffix = progress.unit === 'PAGE' ? '페이지'
+            : progress.unit === 'TEXT_CHUNK' ? '구간' : '개';
+        return `문서 분석 중… (${progress.current}/${progress.total}${suffix})`;
+    }
+
     /**
      * 방의 <b>현재</b> AI 진행 상태를 즉시 반환 (네트워크 호출 없음).
      *

package/types/__typetests__/scheduleCard.types.ts

@@ -0,0 +1,51 @@
+/**
+ * 일정 제안 카드 타입 — 소비자 코드가 <b>실제로 컴파일되는지</b>.
+ *
+ * <p>jest 는 `.d.ts` 를 보지 않는다. 카드 렌더러가 쓰는 모양(모르는 kind 폴백 · REJECTED 에서만 읽는 사유 코드 ·
+ * 항상 있는 공개 범위 고지)이 선언과 맞는지 여기서 tsc 로 고정한다.</p>
+ *
+ * <p>실행: {@code npm run typecheck}</p>
+ */
+import type { ChatMessage, ScheduleCard } from '../index';
+
+declare const message: ChatMessage;
+
+// 1) 메시지에는 없을 수 있다 — 일반 메시지는 필드가 부재.
+const maybeCard: ScheduleCard | null | undefined = message.scheduleCard;
+
+// 2) 공개 범위 고지는 항상 문자열이다 — 카드를 그리면 반드시 표시한다.
+function notice(card: ScheduleCard): string {
+    return card.visibilityNotice;
+}
+
+// 3) kind 는 열린 문자열이다 — 알려진 값 분기 + default 텍스트 폴백이 성립해야 한다.
+function headline(card: ScheduleCard, fallbackContent: string | null): string {
+    switch (card.kind) {
+        case 'PROPOSED': return '일정을 등록할까요?';
+        case 'CREATED': return '일정을 등록했습니다';
+        case 'REJECTED': return rejectedText(card.failureCode);
+        case 'UNKNOWN': return '등록됐는지 확인하지 못했습니다. 캘린더에서 확인해 주세요';
+        case 'CANCELLED': return '일정 제안을 취소했습니다';
+        case 'EXPIRED': return '만료되었습니다. 다시 요청해 주세요';
+        default: return fallbackContent ?? '';   // 모르는 kind — content 로 폴백
+    }
+}
+
+// 4) 사유 코드는 선택 필드다 — 없거나 모르는 코드는 일반 거절 문구.
+function rejectedText(code: string | undefined): string {
+    const known: Record<string, string> = {
+        PARTICIPANT_LIMIT_EXCEEDED: '참여자가 너무 많아(최대 100명) 등록하지 못했습니다',
+    };
+    return (code !== undefined && known[code] !== undefined ? known[code] : '일정을 등록하지 못했습니다')
+        + '. 다시 요청해 주세요';
+}
+
+// 5) 선택 필드는 null 일 수 있다 — 그대로 비교·병합할 수 있어야 한다.
+function names(card: ScheduleCard): string {
+    return (card.participantNames ?? []).join(', ') + (card.title ?? '') + (card.whenText ?? '') + (card.location ?? '');
+}
+
+// 6) 알 수 없는 kind 문자열도 받아들인다(구버전 호환).
+const future: ScheduleCard = { proposalId: 'p-1', kind: 'SOMETHING_NEW', visibilityNotice: '이 방 구성원에게 공개되는 일정입니다' };
+
+export { maybeCard, notice, headline, names, future };

package/types/index.d.ts

@@ -772,6 +772,58 @@ export interface ChatMessage {
      * 마스킹이 호출자마다 다르게 계산되기 때문이다.</p>
      */
     voteCard?: VoteCard | null;
+    /**
+     * 일정 제안 카드 — PM 이 대화에서 일정을 «제안» 했거나 그 결과를 알리는 메시지의 payload.
+     *
+     * <p><b>모르면 그냥 텍스트로 그려라 — 그게 정상 동작이다.</b> {@code content} 에 같은 내용과 공개 범위 고지가
+     * 사람이 읽는 형태로 들어 있다. 반대로 카드를 그린다면 {@code content} 를 다시 그리지 마라.</p>
+     *
+     * <p>결과(등록됨·거절·확인 불가·취소·만료)는 원래 카드를 고치지 않고 {@code kind} 가 다른 <b>새 메시지</b>로 온다.
+     * 지금 승인할 수 있는지는 카드가 아니라 {@code GET /api/v1/calendar/proposals/{proposalId}} 의
+     * {@code approvable} 이 말한다(SDK 메서드 없음 — 다른 캘린더 API 처럼 REST 로 직접 부른다).</p>
+     */
+    scheduleCard?: ScheduleCard | null;
+}
+
+/**
+ * 일정 제안 카드 payload — 제안 하나에 «승인할까요?» 카드 한 장, 결과 카드는 최대 한 장이다.
+ *
+ * <p>값은 발행 시점 <b>스냅샷</b>이다. 결과는 원래 카드를 고치지 않고 {@code kind} 가 다른 새 메시지로 온다.</p>
+ */
+export interface ScheduleCard {
+    /** 조회·승인·취소의 키. */
+    proposalId: string;
+    /**
+     * {@code 'PROPOSED'}(승인 대기) | {@code 'CREATED'} | {@code 'REJECTED'} | {@code 'UNKNOWN'} |
+     * {@code 'CANCELLED'} | {@code 'EXPIRED'}.
+     *
+     * <p>🔴 {@code 'PROPOSED'} 는 «등록됨» 이 아니다. 🔴 {@code 'UNKNOWN'} 은 «실패» 가 아니라 «등록됐는지 모른다» 다 —
+     * 재시도·다시 요청 버튼을 두지 않는다(만들어졌을 수 있어 다시 만들면 일정이 둘 된다).</p>
+     *
+     * <p>🔴 <b>모르는 값이 올 수 있다</b> — switch 의 default 는 텍스트({@code content}) 폴백으로 둔다.</p>
+     */
+    kind: 'PROPOSED' | 'CREATED' | 'REJECTED' | 'UNKNOWN' | 'CANCELLED' | 'EXPIRED' | (string & {});
+    /** 제목 스냅샷. 비어 있을 수 있다. */
+    title?: string | null;
+    /** 사람이 읽는 시각 — 서버가 <b>제안 당시 해석 타임존</b>으로 만든 문자열(끝에 존 ID). 다시 계산하지 않는다. */
+    whenText?: string | null;
+    /** 장소 스냅샷. 비어 있을 수 있다. */
+    location?: string | null;
+    /** 초대 대상 표시 이름. 비어 있어도 공개 범위는 방 전체다({@link ScheduleCard.visibilityNotice}). */
+    participantNames?: string[] | null;
+    /**
+     * 🔴 공개 범위 고지 — <b>참가자 수와 관계없이 항상</b> 온다. 카드를 그린다면 반드시 표시한다.
+     * 초대한 사람이 없어도 이 방 구성원 전원에게 보이는 일정이다.
+     */
+    visibilityNotice: string;
+    /**
+     * 거절 사유 <b>코드</b> — 🔴 {@code kind === 'REJECTED'} 일 때만 오고, 그때도 없을 수 있다.
+     *
+     * <p>문구 변환은 화면이 한다. 코드가 없거나 모르는 코드면 <b>일반 거절 문구</b>
+     * («일정을 등록하지 못했습니다») 를 보여주고 «다시 요청해 주세요» 를 붙인다. 상류 원문 메시지는 오지 않는다.
+     * 수동 입력 폼의 오류 안내(필드별 표시 등)를 쓰지 않는다 — 제안에는 고칠 폼이 없다.</p>
+     */
+    failureCode?: string;
 }
 
 /**
@@ -1264,6 +1316,18 @@ export interface TypingEvent {
     senderType: 'USER' | 'ASSISTANT';
 }
 
+/** 문서 분석의 재입장 복원 가능한 실측 진행률. */
+export interface DocumentAnalysisProgress {
+    /** ANALYZING=페이지/텍스트 구간 처리, SUMMARIZING=확보한 근거 종합. */
+    stage: 'ANALYZING' | 'SUMMARIZING';
+    /** ANALYZING일 때 처리 완료 수. */
+    current: number | null;
+    /** ANALYZING일 때 전체 수. */
+    total: number | null;
+    /** 진행 단위. SUMMARIZING일 때 null. */
+    unit: 'DOCUMENT' | 'PAGE' | 'TEXT_CHUNK' | null;
+}
+
 /**
  * AI 진행 표시 이벤트 — `/topic/chat/{roomId}/assistant-stream` 의 PHASE/DONE.
  *
@@ -1281,6 +1345,7 @@ export interface TypingEvent {
  *
  * 현재는 PM_BACKSTAGE(방당 단일 PM) 만 phase 를 발행 — 멘션/버튼/14인 경로는 본 이벤트 없이 typing 만.
  */
+
 export interface AssistantProgressEvent {
     /** 채팅방 ID. */
     roomId: string;
@@ -1294,7 +1359,9 @@ export interface AssistantProgressEvent {
     /** 진행 주체 페르소나 ID. */
     personaId: string | null;
     /** 진행 단계 — `active:true` 일 때. 종료 시 null. */
-    phase: 'THINKING' | 'SEARCHING' | 'PLANNING' | 'WRITING' | null;
+    phase: 'THINKING' | 'SEARCHING' | 'PLANNING' | 'DOCUMENT_ANALYSIS' | 'WRITING' | null;
+    /** DOCUMENT_ANALYSIS의 실측 진행률. 같은 phase heartbeat 사이와 재입장 후에도 보존된다. */
+    progress?: DocumentAnalysisProgress | null;
     /** phase 의 기본 표시 라벨(예: "생각 중…"). SDK 매핑 — 커스텀하려면 `phase` 사용. 종료 시 null. */
     label: string | null;
     /** true=진행중(PHASE/DELTA) / false=종료(DONE·TTL). */
@@ -1360,7 +1427,8 @@ export interface AssistantRoomProgressEvent {
     /** 표시 기준이 된 stream (가장 최근 갱신). 없으면 null. */
     streamId: string | null;
     personaId: string | null;
-    phase: 'THINKING' | 'SEARCHING' | 'PLANNING' | 'WRITING' | null;
+    phase: 'THINKING' | 'SEARCHING' | 'PLANNING' | 'DOCUMENT_ANALYSIS' | 'WRITING' | null;
+    progress?: DocumentAnalysisProgress | null;
     label: string | null;
     /** 표시 기준 stream 의 누적 본문. `textAvailable:false` 거나 진행 중이 아니면 null. */
     text?: string | null;
@@ -1372,7 +1440,8 @@ export interface AssistantRoomProgressEvent {
 export interface AssistantProgressStreamSnapshot {
     streamId: string;
     personaId: string | null;
-    phase: 'THINKING' | 'SEARCHING' | 'PLANNING' | 'WRITING' | null;
+    phase: 'THINKING' | 'SEARCHING' | 'PLANNING' | 'DOCUMENT_ANALYSIS' | 'WRITING' | null;
+    progress?: DocumentAnalysisProgress | null;
     label: string | null;
     text: string | null;
     textAvailable: boolean;