@vibexnpm/talkx 5.3.0 → 5.6.0

package/package.json

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

package/src/TalkFlowClient.js

@@ -237,10 +237,134 @@ class TalkFlowClient extends EventEmitter {
 
     // ==================== 사용자 API ====================
 
+    /**
+     * 회원 로그인 — 이메일/비밀번호로 채팅 접속 일체를 받는다. **클라이언트 생성 전에 호출한다.**
+     *
+     * <p>{@link #registerUser} 와 달리 Server Key 도 고객사 BFF 도 필요 없다. 응답의
+     * {@code clientKey}/{@code projectId}/{@code accessToken} 이 그대로 SDK 초기화 입력이다.</p>
+     *
+     * <p><b>회사 선택 단계가 없다</b>: 로그인 키가 전역 유일이라 이메일 하나로 회원과 회사가
+     * 함께 정해진다. 퇴사하면 그 키가 풀려 다른 회사에서 같은 이메일을 다시 쓸 수 있다.</p>
+     *
+     * @param {Object} options
+     * @param {string} options.serverUrl - 채팅 서버 base URL
+     * @param {string} options.email
+     * @param {string} options.password
+     * @returns {Promise<Object>} `{accessToken, tokenType, expiresIn, projectId, clientKey, user}`
+     *
+     * @example
+     * const login = await TalkFlowClient.loginUser({
+     *     serverUrl: 'https://chat.apiorbit.net',
+     *     email: 'dan@example.com',
+     *     password: '********'
+     * });
+     *
+     * const client = new TalkFlowClient({
+     *     apiKey: login.clientKey,
+     *     projectId: login.projectId,
+     *     jwtToken: login.accessToken
+     * });
+     * await client.connect();
+     */
+    static async loginUser({ serverUrl, email, password }) {
+        if (!serverUrl) throw new Error('serverUrl is required');
+        if (!email) throw new Error('email is required');
+        if (!password) throw new Error('password is required');
+
+        // 로그인은 키를 «받기 위해» 부르는 경로라 X-API-KEY/X-PROJECT-ID 가 없다(서버에서 필터 제외).
+        const client = new ApiClient({ baseUrl: serverUrl, apiKey: '', projectId: '' });
+        const response = await client.post('/api/v1/auth/login', { email, password });
+        return (response && response.data) ? response.data : response;
+    }
+
+    /**
+     * 회원 로그인 (인스턴스) — 성공 시 JWT 를 자동 설정한다.
+     *
+     * <p>이미 클라이언트가 있는 상태의 재로그인·계정 전환용이다. 최초 진입은 클라이언트 생성 전에
+     * 부르는 정적 {@link TalkFlowClient.loginUser} 를 쓴다 — 그쪽이 {@code clientKey} 까지 준다.</p>
+     *
+     * @param {Object} credentials
+     * @param {string} credentials.email
+     * @param {string} credentials.password
+     * @returns {Promise<Object>} 로그인 응답
+     */
+    async loginUser({ email, password }) {
+        const response = await this.apiClient.post('/api/v1/auth/login', { email, password });
+        const data = (response && response.data) ? response.data : response;
+
+        if (data && data.accessToken) {
+            await this.setToken(data.accessToken);
+            this.logger.info('Member logged in, token auto-set');
+        }
+        return data;
+    }
+
+    /**
+     * 내 정보 조회.
+     *
+     * @returns {Promise<Object>} `{userId, email, name, phone, profileUrl, companyRole, orgNodeId, orgName, ...}`
+     */
+    async getMyProfile() {
+        this._checkToken();
+        const response = await this.apiClient.get('/api/v1/me');
+        return (response && response.data) ? response.data : response;
+    }
+
+    /**
+     * 내 정보 수정 — 이름·전화번호·프로필 이미지.
+     *
+     * <p>서버가 <b>새 JWT</b> 를 함께 준다: {@code name}/{@code profileUrl} 이 토큰 claim 이라
+     * 갱신하지 않으면 옛 값이 토큰 만료(7일)까지 계속 나간다. 여기서 자동 채택한다.</p>
+     *
+     * <p>이메일·조직·역할은 바꿀 수 없다 — 이메일은 로그인 키, 조직은 파트너가 정하고,
+     * 역할은 본인이 승급할 수 없어야 한다.</p>
+     *
+     * @param {Object} profile
+     * @param {string} [profile.name]
+     * @param {string} [profile.phone]
+     * @param {string} [profile.profileUrl]
+     * @returns {Promise<Object>} 갱신된 내 정보 (accessToken 포함)
+     */
+    async updateMyProfile(profile) {
+        this._checkToken();
+        const response = await this.apiClient.put('/api/v1/me', profile);
+        const data = (response && response.data) ? response.data : response;
+
+        if (data && data.accessToken) {
+            // 토큰 교체 실패로 수정 자체를 실패시키지 않는다 — 서버 반영은 이미 끝났고 옛 토큰도
+            // 유효(낡았을 뿐)하므로 여기서 throw 하면 호출자가 이미 적용된 수정을 다시 시도한다.
+            try {
+                await this.setToken(data.accessToken);
+            } catch (error) {
+                this.logger.warn('Profile updated but token refresh failed; keeping the old token', error);
+            }
+        }
+        return data;
+    }
+
+    /**
+     * 비밀번호 변경 — 현재 비밀번호를 재확인한다.
+     *
+     * <p>토큰만 탈취해도 비밀번호를 바꿀 수 있으면 계정을 통째로 빼앗긴다. 비밀번호는 바뀌어도
+     * 토큰은 그대로 유효하다 — 재로그인이 필요하지 않다.</p>
+     *
+     * @param {Object} params
+     * @param {string} params.currentPassword
+     * @param {string} params.newPassword - 8자 이상
+     */
+    async changeMyPassword({ currentPassword, newPassword }) {
+        this._checkToken();
+        return this.apiClient.put('/api/v1/me/password', { currentPassword, newPassword });
+    }
+
     /**
      * 사용자 인증 (등록/로그인).
      * 인증 성공 시 반환된 JWT 토큰을 자동으로 설정합니다.
      *
+     * <h3>⚠️ DEPRECATED — {@link TalkFlowClient.loginUser} 로 대체</h3>
+     * <p>고객사 앱이 자기 회원 ID 를 들고 오던 경로다. 서버에서 {@code POST /api/v1/users/auth} 가
+     * 제거될 예정이며 그때 이 메서드도 함께 사라진다. 신규 코드는 {@code loginUser} 를 쓴다.</p>
+     *
      * <h3>⚠️ Server API Key 전용</h3>
      * <p>이 메서드는 JWT 를 발급하는 엔드포인트 ({@code POST /api/v1/users/auth}) 를 호출합니다.
      * <strong>프로덕션 환경에서는 Client API Key 로 이 메서드를 호출하면 서버가 403 을 반환합니다.</strong></p>

package/src/chat/ChatClient.js

@@ -648,23 +648,24 @@ class ChatClient extends EventEmitter {
      * @param {Object} [options]
      * @param {string} [options.format] - 요약 포맷 ({@link SummarizeFormat}). 미지정/알 수 없는 값이면 서버가 {@code SHORT} 적용.
      * @param {string} [options.lang] - 출력 언어(BCP-47 예 {@code 'ko'}/{@code 'en'}, 또는 {@code 'OFF'}=원문). 미지정 시 요청자 언어로 해소.
-     * @returns {Promise<{status: string, format?: string, language?: string}>} {@code status}: {@code 'STARTED'}(워커 시작 —
-     *   {@code summaryUpdate} 대기) | {@code 'ALREADY_RUNNING'}(방에서 <b>다른</b> 요약이 진행 중일 수 있음 — 응답의
-     *   {@code format}/{@code language} 로 내 키인지 확인) | {@code 'NO_CHANGE'}(새 대화 없음 — 알림 발생 안 함).
-     *   {@code format}/{@code language}=이번 요청이 해소한 키(방 단위 경합 식별용).
-     *
-     * @fires summaryUpdate - { roomId, status: 'READY'|'NO_CHANGE'|'FAILED'|'INVALIDATED', format, languages, updatedAt }.
+     * @returns {Promise<{status: string, format?: string, language?: string}>} {@code status}: {@code 'QUEUED'} —
+     *   방 단위 durable work item 에 저장·병합됐다. local worker 포화여도 요청은 버려지지 않으며
+     *   최종 {@code READY|NO_CHANGE|NO_MESSAGES|FAILED} {@code summaryUpdate} 를 기다린다.
+     *   {@code format}/{@code language}=이번 호출이 work item 에 병합한 키.
+     *   ⚠️ 닫힌 목록이 아니다 — 분기에는 default 를 두고, 모르는 값에 스피너를 띄우지 마라.
+     * @throws {Error} HTTP 503 {@code SUMMARY_REFRESH_UNAVAILABLE} — durable 저장 자체가 실패했다.
+     *   간격을 두고 재시도하고 사용자에게는 일시 오류로 알린다.
+     *   {@code err.status}=503, {@code err.response.code}={@code 'SUMMARY_REFRESH_UNAVAILABLE'}.
+     *
+     * @fires summaryUpdate - { roomId, status: 'READY'|'NO_CHANGE'|'NO_MESSAGES'|'FAILED'|'INVALIDATED'|string, format, languages, updatedAt }.
      *   fan-out 으로 여러 언어를 한 번에 생성하므로 {@code languages} 는 배열(§S1). {@code INVALIDATED} 는 refreshSummary 가
      *   아니라 방 원문 삭제/편집으로 발생(요약이 통째로 폐기됨).
      *
      * @example
      * const { status } = await chat.refreshSummary(roomId, { format: SummarizeFormat.MINUTES, lang: 'ko' });
-     * if (status === 'STARTED') showSpinner();          // fan-out 진행 시작 — summaryUpdate 대기
-     * else if (status === 'ALREADY_RUNNING') {
-     *   // 방에서 다른 요약이 도는 중일 수 있다. 완료 이벤트 summaryUpdate 의 languages 에 내 언어가 없으면
-     *   // 그때 다시 refreshSummary 로 내 언어를 요청한다(재요청 금지가 아니라 "내 언어가 없으면 재요청").
-     *   showSpinner();
-     * } else if (status === 'NO_CHANGE') toast('변경 사항이 없습니다');
+     * if (status === 'QUEUED') showQueuedProgress();    // durable 접수 — summaryUpdate 대기
+     * else showUnknownSummaryState(status);             // 미래 서버 값은 추측하지 않는다
+     * // 503(SUMMARY_REFRESH_UNAVAILABLE)은 durable 접수 실패 — try/catch로 받고 간격을 두고 재시도.
      */
     async refreshSummary(roomId, options = {}) {
         const { format, lang } = options;
@@ -678,9 +679,10 @@ class ChatClient extends EventEmitter {
     /**
      * Rolling 누적 요약 조회 — 통합본(rollup) + 구간 부분요약(segments) 페이지. 저장된 요약의 단일 진실 소스.
      *
-     * <p>{@code summaryUpdate}({@code status:'READY'}) 수신 후, 그리고 화면 진입/재접속 시 호출한다 — 알림은
-     * transient(저장 안 됨)라 유실될 수 있으므로 GET 으로 동기화한다. 아직 한 번도 요약된 적 없으면 {@code rollup}
-     * 이 {@code null} 이다. segment 는 {@code afterSeq}/{@code size} 로 페이지네이션한다({@code hasNext}/{@code nextSeq}).</p>
+     * <p>terminal {@code summaryUpdate} 수신 후, 화면 진입/재접속 시, 그리고 {@code QUEUED} 뒤 앱이 정한 완료
+     * timeout에 <b>한 번</b> 호출한다 — 알림은 transient(저장 안 됨)라 유실될 수 있으므로 GET 으로 동기화한다.
+     * 주기적 polling은 하지 않는다. 아직 한 번도 요약된 적 없으면 {@code rollup} 이 {@code null} 이다.
+     * segment 는 {@code afterSeq}/{@code size} 로 페이지네이션한다({@code hasNext}/{@code nextSeq}).</p>
      *
      * <p>같은 방을 여러 포맷×언어로 보관하므로 {@code options.format}/{@code options.lang} 으로 골라 조회한다.
      * {@code lang} 미지정 시 서버가 요청자 언어로 해소하고, 응답 {@code language} 로 <b>어느 언어 기준</b>인지
@@ -694,7 +696,7 @@ class ChatClient extends EventEmitter {
      * @param {string} [options.lang] - 조회할 언어(BCP-47 예 {@code 'ko'}, 또는 {@code 'OFF'}=원문). 미지정 시 요청자 언어로 해소(응답 {@code language}).
      * @param {number} [options.afterSeq] - segment 페이지 커서(exclusive). 미지정 시 처음부터.
      * @param {number} [options.size=50] - segment 페이지 크기(서버 상한 50).
-     * @returns {Promise<RoomSummaryView>} { language, rollup | null, availableFormats, segments, hasNext, nextSeq }
+     * @returns {Promise<RoomSummaryView>} { language, roomStatus, rollup | null, availableFormats, segments, hasNext, nextSeq }
      *
      * @example
      * const view = await chat.getSummary(roomId, { format: 'timeline', lang: 'ko' });
@@ -3392,24 +3394,27 @@ class ChatClient extends EventEmitter {
     /**
      * Rolling 누적 요약 완료 알림(summary 채널) 수신 처리 — status 를 그대로 {@code summaryUpdate} 로 emit.
      *
-     * <p>서버 {@code SummaryStreamEvent}: {@code { status: 'READY'|'NO_CHANGE'|'FAILED'|'INVALIDATED', roomId, format?, languages?, updatedAt? }}.
+     * <p>서버 {@code SummaryStreamEvent}: {@code { status: 'READY'|'NO_CHANGE'|'NO_MESSAGES'|'FAILED'|'INVALIDATED'|string, roomId, format?, languages?, updatedAt? }}.
      * assistant-stream 과 달리 단계/토큰 누적이 없어 상태 관리 없이 그대로 통지한다. transient(저장 안 됨)라 UI 는
      * 이벤트를 신호로만 쓰고 확정 내용은 {@link #getSummary} 로 읽는다. {@code READY}=요약 갱신됨(→ getSummary),
-     * {@code FAILED}=실패(재시도 가능), {@code NO_CHANGE}=변경 없음(대개 refreshSummary 응답에서 동기로 이미 받음),
+     * {@code FAILED}=실패(재시도 가능), {@code NO_CHANGE}=durable 작업이 변경 없이 완료,
+     * {@code NO_MESSAGES}=해당 키에 요약할 대화 없음,
      * {@code INVALIDATED}=방 원문 삭제/편집으로 요약이 통째로 버려짐(→ 요약 화면을 즉시 비우고, 필요 시 refreshSummary 로 재생성).</p>
      *
      * <p><b>키 식별(format+languages)</b>: 한 refresh 가 방 활성 언어들을 fan-out 으로 한 번에 생성하므로(§S1), 완료
-     * 이벤트의 {@code languages} 에 내 언어가 있으면 {@code getSummary({ format, lang })} 로 읽는다. {@code READY}·
-     * {@code FAILED} 모두 언어 목록을 싣는다({@code NO_CHANGE}·{@code INVALIDATED} 는 없음).</p>
+     * 이벤트의 {@code languages} 에 내 언어가 있으면 {@code getSummary({ format, lang })} 로 읽는다.
+     * {@code READY}·{@code NO_CHANGE}·{@code NO_MESSAGES}·{@code FAILED} 모두 언어 목록을 싣는다
+     * ({@code INVALIDATED} 만 없음). 알 수 없는 미래 status도 그대로 전달하므로 소비자는 default 분기와
+     * one-shot {@code getSummary} 재동기화를 둔다.</p>
      * @private
      */
     _handleSummaryEvent(roomId, event) {
         if (!event || !event.status) return;
         this.emit('summaryUpdate', {
             roomId,
-            status: event.status,                 // 'READY' | 'NO_CHANGE' | 'FAILED' | 'INVALIDATED'
-            format: event.format || null,         // READY/FAILED 포함(NO_CHANGE·INVALIDATED 는 null)
-            languages: event.languages || null,   // fan-out 으로 생성/최신화된 언어 목록(READY/FAILED). 그 외 null
+            status: event.status,                 // known status + future server values (pass-through)
+            format: event.format || null,         // READY/NO_CHANGE/NO_MESSAGES/FAILED 포함
+            languages: event.languages || null,   // READY/NO_CHANGE/NO_MESSAGES/FAILED 처리 언어 목록
             updatedAt: event.updatedAt || null
         });
     }

package/src/constants.js

@@ -364,7 +364,7 @@ export const WebSocketPaths = {
     getChatTypingDestination: (roomId) => `/topic/chat/${roomId}/typing`,
     // AI 진행 표시(생각중/검색중/작성중) + 토큰 스트리밍 — typing 과 별개 채널(가산 UX 레이어).
     getChatAssistantStreamDestination: (roomId) => `/topic/chat/${roomId}/assistant-stream`,
-    // Rolling 누적 요약 완료 알림(READY/NO_CHANGE/FAILED) — refreshSummary 의 비동기 완료 통지 채널.
+    // Rolling 누적 요약 종결 알림(READY/NO_CHANGE/NO_MESSAGES/FAILED) — refreshSummary 비동기 완료 채널.
     getChatSummaryDestination: (roomId) => `/topic/chat/${roomId}/summary`,
 
     // Room list (카톡 스타일 리스트 실시간 업데이트)

package/types/__typetests__/singleMessageAttachment.types.ts

@@ -13,6 +13,7 @@ import type {
     ChatMessage,
     ChatMessageTypeValue,
     FileMetaData,
+    RoomSummaryView,
     SendFileInfo
 } from '../index';
 import { ChatMessageType } from '../index';
@@ -65,4 +66,24 @@ function legacyResponseFile(f: FileMetaData): string | undefined {
     return f.fileId;
 }
 
-export { category, viaTopLevel, mixed, gallery, document, render, uploadThenSend, optimistic, legacyResponseFile };
+// 7) 서버 rolling 배포를 견디도록 summary 상태는 열린 문자열 union이어야 한다.
+function renderSummaryStatus(status: NonNullable<RoomSummaryView['roomStatus']>): string {
+    switch (status) {
+        case 'QUEUED': return 'queued';
+        case 'IDLE': return 'idle';
+        case 'RUNNING': return 'running';
+        case 'FAILED': return 'failed';
+        case 'NO_MESSAGES': return 'empty';
+        default: {
+            // @ts-expect-error 열린 union이므로 알려진 값만 처리해도 exhaustive never가 될 수 없다.
+            const futureServerStatus: never = status;
+            void futureServerStatus;
+            return 'unknown';
+        }
+    }
+}
+
+const futureSummaryStatus: NonNullable<RoomSummaryView['roomStatus']> = 'FUTURE_SERVER_STATUS';
+
+export { category, viaTopLevel, mixed, gallery, document, render, uploadThenSend, optimistic, legacyResponseFile,
+    renderSummaryStatus, futureSummaryStatus };

package/types/index.d.ts

@@ -327,16 +327,20 @@ export interface RefreshSummaryOptions {
 export interface RefreshSummaryResult {
     /**
      * <ul>
-     *   <li>{@code 'STARTED'} — 요약 워커 시작됨({@code summaryUpdate} 대기).</li>
-     *   <li>{@code 'ALREADY_RUNNING'} — 방에서 요약이 진행 중(<b>다른</b> 포맷·언어일 수 있음). {@code format}/{@code language}
-     *       로 내 키인지 확인하고, {@code summaryUpdate} 가 내 키가 아니면 그때 다시 요청한다(무조건 재요청 금지 아님).</li>
-     *   <li>{@code 'NO_CHANGE'} — 새 대화 없음(알림 발생 안 함; 직전 실패가 있었다면 자동 복구됨).</li>
+     *   <li>{@code 'QUEUED'} — 방 단위 durable work item 에 저장·병합됐다. pod 실행 슬롯이 포화여도
+     *       요청은 버려지지 않으며, 최종 {@code READY|NO_CHANGE|NO_MESSAGES|FAILED} {@code summaryUpdate} 를 기다린다.</li>
      * </ul>
+     *
+     * <p>durable 저장 자체가 실패하면 성공 결과가 아니라 <b>HTTP 503</b>
+     * ({@code SUMMARY_REFRESH_UNAVAILABLE})으로 오며, {@link ChatClient.refreshSummary} 가 reject 한다.</p>
+     *
+     * <p>⚠️ <b>닫힌 union 이 아니다</b>: 서버가 값을 추가할 수 있으므로 분기에는 반드시 default 를 둔다.
+     * 모르는 값을 {@code QUEUED} 로 가정하지 말고 별도 상태 확인 UI를 표시한다.</p>
      */
-    status: 'STARTED' | 'ALREADY_RUNNING' | 'NO_CHANGE';
-    /** 이번 요청이 해소한 포맷({@link SummarizeFormat} 소문자). 방 단위 경합 식별용. */
+    status: 'QUEUED' | (string & {});
+    /** durable work item 에 병합한 포맷({@link SummarizeFormat} 소문자). */
     format?: string;
-    /** 이번 요청이 해소한 언어(소문자 BCP-47 / {@code 'OFF'}=원문). 방 단위 경합 식별용. */
+    /** durable work item 에 병합한 요청자 언어(소문자 BCP-47 / {@code 'OFF'}=원문). */
     language?: string;
 }
 
@@ -400,11 +404,15 @@ export interface RoomSummaryView {
      */
     language: string;
     /**
-     * 방 전체 요약 프로세스 상태 — {@code 'IDLE'}(대기) | {@code 'RUNNING'}(요약 중) | {@code 'FAILED'}(실패).
-     * <b>방 단위(키별 아님)</b>: 방은 한 번에 한 키만 요약하므로, 지금 다른 포맷·언어를 요약 중이어도 {@code 'RUNNING'} 이다.
-     * 특정 rollup 의 최신 여부는 {@code rollup.stale} 로 판단한다(rollup 자체는 완료된 데이터). 요약 이력이 없으면 null.
+     * 실행 상태 — {@code 'QUEUED'}(durable 대기) | {@code 'IDLE'}(유휴) |
+     * {@code 'RUNNING'}(요약 중) | {@code 'FAILED'}(선택 키 실패) |
+     * {@code 'NO_MESSAGES'}(선택 키에 요약할 대화 없음).
+     * 대기/실행은 방 단위이고 terminal 결과는 조회한 포맷×언어 키 기준이다. 특정 rollup 의 최신 여부는
+     * {@code rollup.stale} 로 판단한다. 요약 이력이 없어도 durable job 상태가 있으면 null이 아닐 수 있다.
+     * 닫힌 union이 아니므로 분기에는 default를 둔다.
      */
-    roomStatus: 'IDLE' | 'RUNNING' | 'FAILED' | null;
+    /** durable execution-plane 상태에서 합성되므로 재접속 뒤에도 복원된다. */
+    roomStatus: 'QUEUED' | 'IDLE' | 'RUNNING' | 'FAILED' | 'NO_MESSAGES' | (string & {}) | null;
     /** 요청/기본 포맷의 통합 요약본. 그 포맷×언어로 아직 요약 안 됐으면 null(availableFormats 로 같은 언어의 다른 포맷 확인). */
     rollup: RoomSummaryRollup | null;
     /** 이 방이 <b>이 언어로</b> 보유한 포맷 목록(short/timeline/… — 탭 렌더용). 타 언어는 포함하지 않는다. */
@@ -424,15 +432,18 @@ export interface RoomSummaryView {
 export interface SummaryUpdateEvent {
     roomId: string;
     /**
-     * {@code 'READY'}(갱신됨 → getSummary) | {@code 'FAILED'}(실패 → 재시도 가능) | {@code 'NO_CHANGE'}(변경 없음) |
+     * {@code 'READY'}(갱신됨 → getSummary) | {@code 'FAILED'}(실패 → 재시도 가능) |
+     * {@code 'NO_CHANGE'}(변경 없이 durable 작업 종결 → getSummary로 최종 동기화) |
+     * {@code 'NO_MESSAGES'}(선택 키에 요약할 대화 없음) |
      * {@code 'INVALIDATED'}(방 원문 삭제/편집으로 요약이 통째로 버려짐 → 화면을 비우고 필요 시 refreshSummary 로 재생성).
+     * 닫힌 union이 아니므로 모르는 값은 추측하지 말고 one-shot getSummary로 재동기화한다.
      */
-    status: 'READY' | 'NO_CHANGE' | 'FAILED' | 'INVALIDATED';
-    /** 완료/실패한 포맷. {@code READY}·{@code FAILED} 포함, {@code NO_CHANGE}·{@code INVALIDATED} 는 null. */
+    status: 'READY' | 'NO_CHANGE' | 'NO_MESSAGES' | 'FAILED' | 'INVALIDATED' | (string & {});
+    /** 완료 포맷. {@code READY}·{@code NO_CHANGE}·{@code NO_MESSAGES}·{@code FAILED} 포함, {@code INVALIDATED} 는 null. */
     format: string | null;
     /**
-     * fan-out 으로 한 번에 생성/최신화된 언어 목록(소문자 BCP-47 / {@code 'OFF'}). {@code READY}·{@code FAILED} 포함,
-     * 그 외 null. 각 사용자는 자기 언어가 이 목록에 있으면 {@code getSummary({ format, lang })} 로 읽는다(§S1).
+     * fan-out 으로 한 번에 처리한 언어 목록(소문자 BCP-47 / {@code 'OFF'}).
+     * {@code READY}·{@code NO_CHANGE}·{@code NO_MESSAGES}·{@code FAILED} 포함, {@code INVALIDATED} 만 null.
      */
     languages: string[] | null;
     /** 갱신 시각(epoch millis). {@code READY} 만 포함, 그 외 null. */
@@ -951,6 +962,48 @@ export interface DecisionResponse {
     optionId: string;
 }
 
+/** 로그인한 회원. `userId` 는 메시지 발신자 식별과 같은 값이다. */
+export interface LoginMember {
+    userId: string;
+    email?: string | null;
+    nickname?: string | null;
+    profileUrl?: string | null;
+    preferredLanguage?: string | null;
+}
+
+/**
+ * `TalkFlowClient.loginUser` 응답.
+ *
+ * 회사 선택 단계가 없다 — 로그인 키가 전역 유일이라 이메일 하나로 회원과 회사가 함께 정해진다.
+ */
+export interface LoginResult {
+    accessToken: string;
+    tokenType: string;
+    expiresIn?: number;
+    projectId: string;
+    /** 회사의 활성 ck- 키. SDK 초기화의 `apiKey` 로 그대로 넣는다. */
+    clientKey: string;
+    user: LoginMember;
+}
+
+/** 내 정보. 수정 응답에는 `accessToken` 이 함께 온다(name/profileUrl 이 토큰 claim). */
+export interface MyProfile {
+    userId: string;
+    email?: string | null;
+    name?: string | null;
+    phone?: string | null;
+    profileUrl?: string | null;
+    /** 회사 역할 — 방 역할(ParticipantResponse.role)과 다른 축이다. */
+    companyRole: 'PARTNER' | 'MEMBER';
+    orgNodeId?: string | null;
+    orgName?: string | null;
+    preferredLanguage?: string | null;
+    projectId: string;
+    joinedAt?: string | null;
+    accessToken?: string;
+    expiresIn?: number;
+}
+
 /** 채팅방 참가자. */
 export interface ParticipantResponse {
     userId: string;
@@ -2240,6 +2293,30 @@ export default class TalkFlowClient implements SdkEventEmitter<TalkFlowClientEve
     removeAllListeners(event?: keyof TalkFlowClientEvents): void;
     listenerCount(event: keyof TalkFlowClientEvents): number;
 
+    // 회원 인증 · 내 정보
+    /**
+     * 회원 로그인 — 클라이언트 생성 **전에** 호출한다. Server Key 도 고객사 BFF 도 필요 없다.
+     * 응답의 `clientKey`/`projectId`/`accessToken` 이 그대로 SDK 초기화 입력이다.
+     * 회사 선택 단계가 없다 — 로그인 키가 전역 유일이다.
+     */
+    static loginUser(options: {
+        serverUrl: string;
+        email: string;
+        password: string;
+    }): Promise<LoginResult>;
+
+    /** 회원 로그인 (인스턴스) — 재로그인·계정 전환용. 성공 시 토큰을 자동 설정한다. */
+    loginUser(credentials: { email: string; password: string }): Promise<LoginResult>;
+
+    /** 내 정보 조회. */
+    getMyProfile(): Promise<MyProfile>;
+
+    /** 내 정보 수정 — 응답의 새 토큰을 자동 채택한다(name/profileUrl 이 토큰 claim). */
+    updateMyProfile(profile: { name?: string; phone?: string; profileUrl?: string }): Promise<MyProfile>;
+
+    /** 비밀번호 변경 — 현재 비밀번호 재확인. 토큰은 그대로 유효해 재로그인이 필요 없다. */
+    changeMyPassword(params: { currentPassword: string; newPassword: string }): Promise<unknown>;
+
     // Connection lifecycle
     connect(jwt?: string, options?: ConnectOptions): Promise<void>;
     disconnect(): Promise<void>;