@vibexnpm/talkx 6.1.0 → 7.1.0

package/package.json

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

package/src/TalkFlowClient.js

@@ -287,7 +287,16 @@ class TalkFlowClient extends EventEmitter {
     /**
      * 내 정보 조회.
      *
-     * @returns {Promise<Object>} `{userId, email, name, phone, profileUrl, companyRole, orgNodeId, orgName, ...}`
+     * `metadata` 를 볼 수 있는 **유일한** 곳이다. 고치는 문은 {@link #updateMyProfile} 하나뿐이고
+     * 그쪽은 **전체 교체**라, 부분 수정하려면 여기서 먼저 읽어 병합한 뒤 통째로 보내야 한다:
+     *
+     * ```js
+     * const me = await client.getMyProfile();
+     * await client.updateMyProfile({ metadata: { ...me.metadata, statusMessage: '회의 중' } });
+     * ```
+     *
+     * @returns {Promise<Object>} `{userId, email, name, phone, profileUrl, companyRole,
+     *   orgNodeId, orgName, preferredLanguage, metadata, mustChangePassword, ...}`
      */
     async getMyProfile() {
         this._checkToken();
@@ -304,10 +313,24 @@ class TalkFlowClient extends EventEmitter {
      * <p>이메일·조직·역할은 바꿀 수 없다 — 이메일은 로그인 키, 조직은 파트너가 정하고,
      * 역할은 본인이 승급할 수 없어야 한다.</p>
      *
-     * @param {Object} profile
-     * @param {string} [profile.name]
-     * @param {string} [profile.phone]
-     * @param {string} [profile.profileUrl]
+     * <p><b>내 정보를 고치는 유일한 메서드다.</b> {@code updateMyInfo} 와
+     * {@code PUT /api/v1/users/update} 는 v7.0.0 에서 걷어냈다 — 같은 칸(이름·프로필 이미지)을
+     * 고치는 문이 둘이라 한 화면에서 순서 없이 두 번 부르면 나중 호출이 앞을 덮었고, 어느 쪽도
+     * 혼자서는 부족했다(그쪽엔 {@code phone} 이, 이쪽엔 나머지 셋이 없었다).</p>
+     *
+     * <p>서버는 갱신된 프로필이 담긴 <b>새 JWT</b> 를 함께 준다. 채택하지 않으면 옛 토큰의
+     * name/profileUrl 클레임이 최대 7일(토큰 TTL) 동안 계속 나간다. 같은 사용자의 토큰 교체라
+     * {@code setToken} 은 재연결을 일으키지 않는다 — STOMP connectHeaders 만 갱신된다.</p>
+     *
+     * @param {Object} profile — 넘기지 않은 필드는 «변경 안 함»
+     * @param {string} [profile.name] - 이름 (max 100자)
+     * @param {string} [profile.phone] - 전화번호 (max 30자)
+     * @param {string} [profile.profileUrl] - 프로필 이미지 URL (max 500자)
+     * @param {Object} [profile.metadata] - 메타데이터 (**전체 교체** — 부분 수정하려면
+     *   {@link #getMyProfile} 로 현재 값을 읽어 병합한 뒤 통째로 보내라. 서버는 병합하지 않는다)
+     * @param {string|null} [profile.preferredLanguage] - 기본 선호 언어 (BCP-47 / 'OFF'(원문) / null)
+     * @param {string} [profile.timeZone] - IANA zone id. 어시가 대화 시각을 이 기준으로 렌더한다.
+     *   `Intl.DateTimeFormat().resolvedOptions().timeZone` 값을 그대로 보내면 된다.
      * @returns {Promise<Object>} 갱신된 내 정보 (accessToken 포함)
      */
     async updateMyProfile(profile) {
@@ -342,48 +365,13 @@ class TalkFlowClient extends EventEmitter {
         return this.apiClient.put('/api/v1/me/password', { currentPassword, newPassword });
     }
 
-    /**
-     * 사용자 정보 수정.
-     *
-     * 서버는 갱신된 프로필이 담긴 **새 JWT** 를 응답에 함께 실어 준다(`/auth` 와 같은 계약).
-     * 이걸 채택하지 않으면 옛 토큰의 name/profileUrl 클레임이 계속 나가, 서버가 그 클레임을 읽는
-     * 경로에서 낡은 값이 최대 7일(토큰 TTL) 동안 보인다.
-     *
-     * 같은 사용자의 토큰 교체라 `setToken` 은 재연결을 일으키지 않는다 — userId 가 바뀔 때만
-     * 재초기화하고, 여기서는 STOMP connectHeaders 만 갱신된다.
-     *
-     * @param {Object} userData
-     * @param {string} [userData.nickname] - 닉네임 (max 100자)
-     * @param {string} [userData.profileImageUrl] - 프로필 이미지 URL (max 500자)
-     * @param {Object} [userData.metadata] - 메타데이터 (전체 교체)
-     * @param {string|null} [userData.preferredLanguage] - 기본 선호 언어 (BCP-47 / 'OFF'(원문) / null). 다국어.
-     * @returns {Promise<Object>}
-     */
-    async updateMyInfo(userData) {
-        this._checkToken();
-        const response = await this.apiClient.put('/api/v1/users/update', userData);
-
-        if (response?.data?.accessToken) {
-            // 토큰 교체 실패로 수정 자체를 실패시키지 않는다 — 서버 반영은 이미 끝났고,
-            // 옛 토큰도 유효(낡았을 뿐)하므로 여기서 throw 하면 호출자가 이미 적용된 수정을
-            // 다시 시도하게 된다. authenticate() 는 토큰이 없으면 아무것도 못 하므로 계약이 다르다.
-            try {
-                await this.setToken(response.data.accessToken);
-            } catch (error) {
-                this.logger.warn('Profile updated but token refresh failed; keeping the old token', error);
-            }
-        }
-
-        return response;
-    }
-
     /**
      * 내 기본 선호 언어 설정 (전 방 공통, 다국어). 명시 변경 — 방별 오버라이드는 {@link #setMyRoomLanguage}.
      * @param {string|null} language - BCP-47 코드(예 'ko','en') / 'OFF'(원문) / null·''(미설정)
      * @returns {Promise<Object>}
      */
     async setPreferredLanguage(language) {
-        return this.updateMyInfo({ preferredLanguage: language });
+        return this.updateMyProfile({ preferredLanguage: language });
     }
 
     /**
@@ -396,8 +384,9 @@ class TalkFlowClient extends EventEmitter {
      * 발생한다. 서버 {@code LanguageCode} 도 동일 규칙으로 축약하므로 어느 쪽으로 들어와도 같은 값이 된다.</p>
      *
      * <p>예전에는 {@code registerUser} 가 이 값을 자동으로 실어 보냈는데 그 경로가 사라졌다.
-     * 지금은 호출자가 직접 감지해 {@code PUT /api/v1/users/update} 의 {@code preferredLanguage}
-     * 로 넣어야 한다 — 넣지 않으면 사용자 기본 언어가 미설정으로 남아 자동 번역이 서버 기본값을 쓴다.</p>
+     * 지금은 호출자가 직접 감지해 {@link #setPreferredLanguage} (또는 {@link #updateMyProfile} 의
+     * {@code preferredLanguage}) 로 넣어야 한다 — 넣지 않으면 사용자 기본 언어가 미설정으로 남아
+     * 자동 번역이 서버 기본값을 쓴다.</p>
      * @returns {string|null}
      */
     static detectBrowserLanguage() {
@@ -474,8 +463,13 @@ class TalkFlowClient extends EventEmitter {
     /**
      * 사용자 목록 조회
      *
-     * <p>응답 행에 {@code phone}/{@code orgNodeId}/{@code orgName} 이 포함된다 — 부서명은
-     * 저장값이 아니라 조회 시점에 조직 마스터에서 해소한 값이다.</p>
+     * <p>응답 행에 {@code email}/{@code phone}/{@code orgNodeId}/{@code orgName} 이 포함된다 —
+     * 부서명은 저장값이 아니라 조회 시점에 조직 마스터에서 해소한 값이다.</p>
+     *
+     * <p>{@code email} 은 <b>연락용</b>이다. 로그인 키인 {@code loginEmail} 은 어떤 목록에도
+     * 실리지 않는다 — 둘은 다른 값이고, 퇴사 시 {@code loginEmail} 만 비워진다.</p>
+     *
+     * <p>퇴사·차단된 회원은 목록·검색 어디에도 나오지 않는다.</p>
      *
      * @param {Object} [params]
      * @param {number} [params.size=50] - 페이지 크기 (1-100)

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/index.d.ts

@@ -1038,6 +1038,15 @@ export interface MyProfile {
     orgNodeId?: string | null;
     orgName?: string | null;
     preferredLanguage?: string | null;
+    /**
+     * 확장 메타데이터 — 내 값을 볼 수 있는 **유일한** 곳이다.
+     *
+     * 고치는 문은 `updateMyProfile({ metadata })` 하나뿐이고 **전체 교체**다 —
+     * 서버는 병합하지 않는다. 부분 수정하려면 이 값을 먼저 읽어 병합한 뒤 통째로 보내라.
+     */
+    metadata?: Record<string, unknown> | null;
+    /** IANA zone id — 어시가 대화 시각을 이 기준으로 렌더한다. 읽을 수 없으면 설정 화면이 현재 값을 못 보여준다. */
+    timeZone?: string | null;
     projectId: string;
     joinedAt?: string | null;
     /**
@@ -1255,6 +1264,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.
  *
@@ -1272,6 +1293,7 @@ export interface TypingEvent {
  *
  * 현재는 PM_BACKSTAGE(방당 단일 PM) 만 phase 를 발행 — 멘션/버튼/14인 경로는 본 이벤트 없이 typing 만.
  */
+
 export interface AssistantProgressEvent {
     /** 채팅방 ID. */
     roomId: string;
@@ -1285,7 +1307,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). */
@@ -1351,7 +1375,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;
@@ -1363,7 +1388,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;
@@ -2358,7 +2384,17 @@ export default class TalkFlowClient implements SdkEventEmitter<TalkFlowClientEve
     getMyProfile(): Promise<MyProfile>;
 
     /** 내 정보 수정 — 응답의 새 토큰을 자동 채택한다(name/profileUrl 이 토큰 claim). */
-    updateMyProfile(profile: { name?: string; phone?: string; profileUrl?: string }): Promise<MyProfile>;
+    updateMyProfile(profile: {
+        name?: string;
+        phone?: string;
+        profileUrl?: string;
+        /** **전체 교체** — 부분 수정은 `getMyProfile()` 로 읽어 병합한 뒤 통째로 보낸다. */
+        metadata?: Record<string, unknown> | null;
+        /** BCP-47 코드 / 'OFF'(원문) / null */
+        preferredLanguage?: string | null;
+        /** IANA zone id — `Intl.DateTimeFormat().resolvedOptions().timeZone` */
+        timeZone?: string;
+    }): Promise<MyProfile>;
 
     /** 비밀번호 변경 — 현재 비밀번호 재확인. 토큰은 그대로 유효해 재로그인이 필요 없다. */
     changeMyPassword(params: { currentPassword: string; newPassword: string }): Promise<unknown>;