@vibexnpm/talkx 8.6.0 → 8.9.0

package/package.json

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

package/src/TalkFlowClient.js

@@ -39,6 +39,7 @@ class TalkFlowClient extends EventEmitter {
      * // 1단계: 로그인 — 클라이언트 생성 «전» 에 부른다. ck/projectId/JWT 를 한 번에 받는다.
      * //   const { clientKey, projectId, accessToken } = await TalkFlowClient.loginUser({
      * //       serverUrl, email, password });
+     * //   (회사 계정이 둘 이상이면 먼저 workspaceSelectionRequired 결과 → projectId 를 실어 다시 부른다)
      *
      * // 2단계: 받은 값으로 SDK 초기화
      * const client = new TalkFlowClient({
@@ -210,6 +211,15 @@ class TalkFlowClient extends EventEmitter {
         return this.connectionManager ? this.connectionManager.isConnected() : false;
     }
 
+    /**
+     * 회사 구독 대기 중인가 — 서버가 웹소켓을 NOT_SUBSCRIBED 로 거부해 연결을 멈췄다(결제 전·해지 회사).
+     * 결제가 확인되면(`GET /api/v1/company/billing` 의 `subscription === 'ACTIVE'`) 같은 토큰으로 {@link #connect} 를 다시 부른다.
+     * @returns {boolean}
+     */
+    isSubscriptionRequired() {
+        return this.connectionManager ? this.connectionManager.isSubscriptionRequired() : false;
+    }
+
     _enableRefreshSession() {
         if (this.authSession) return;
         this.options.sessionMode = 'refresh';
@@ -310,21 +320,28 @@ class TalkFlowClient extends EventEmitter {
      * <p>Server Key 도 고객사 BFF 도 필요 없다. 응답의
      * {@code clientKey}/{@code projectId}/{@code accessToken} 이 그대로 SDK 초기화 입력이다.</p>
      *
-     * <p><b>회사 선택 단계가 없다</b>: 로그인 키가 전역 유일이라 이메일 하나로 회원과 회사가
-     * 함께 정해진다. 퇴사하면 그 키가 풀려 다른 회사에서 같은 이메일을 다시 쓸 수 있다.</p>
+     * <p><b>회사 선택</b>: 같은 이메일이 여러 회사에 계정을 가질 수 있다(다른 회사의 게스트 등). 비밀번호가 맞는 계정이
+     * 둘 이상이면 토큰 없이 {@code {workspaceSelectionRequired: true, workspaces: [{projectId, companyName, companyRole}]}}
+     * 를 돌려준다 — 저장된 세션은 그대로다. 고른 {@code projectId} 를 실어 같은 이메일·비밀번호로 다시 부른다.
+     * 계정이 하나면 지금처럼 바로 로그인된다.</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}`
+     * @param {string} [options.projectId] - 회사 선택 응답에서 고른 회사
+     * @returns {Promise<Object>} `{accessToken, tokenType, expiresIn, projectId, clientKey, user}` 또는 회사 선택 결과
      *
      * @example
-     * const login = await TalkFlowClient.loginUser({
+     * let login = await TalkFlowClient.loginUser({
      *     serverUrl: 'https://chat.apiorbit.net',
      *     email: 'dan@example.com',
      *     password: '********'
      * });
+     * if (login.workspaceSelectionRequired) {
+     *     const picked = await showWorkspacePicker(login.workspaces);   // 화면에서 고른 회사
+     *     login = await TalkFlowClient.loginUser({ serverUrl, email, password, projectId: picked.projectId });
+     * }
      *
      * const client = new TalkFlowClient({
      *     apiKey: login.clientKey,
@@ -333,13 +350,13 @@ class TalkFlowClient extends EventEmitter {
      * });
      * await client.connect();
      */
-    static async loginUser({ serverUrl, email, password }) {
+    static async loginUser({ serverUrl, email, password, projectId }) {
         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 가 없다(서버에서 필터 제외).
-        return AuthSession.forServer(serverUrl).login({ email, password });
+        return AuthSession.forServer(serverUrl).login({ email, password, projectId });
     }
 
     /**
@@ -348,16 +365,19 @@ class TalkFlowClient extends EventEmitter {
      * <p>이미 클라이언트가 있는 상태의 재로그인·계정 전환용이다. 최초 진입은 클라이언트 생성 전에
      * 부르는 정적 {@link TalkFlowClient.loginUser} 를 쓴다 — 그쪽이 {@code clientKey} 까지 준다.</p>
      *
+     * <p>회사 선택 응답이면 토큰을 설정하지 않고 그 결과를 돌려준다 — 정적 {@link TalkFlowClient.loginUser} 와 같다.</p>
+     *
      * @param {Object} credentials
      * @param {string} credentials.email
      * @param {string} credentials.password
-     * @returns {Promise<Object>} 로그인 응답
+     * @param {string} [credentials.projectId] - 회사 선택 응답에서 고른 회사
+     * @returns {Promise<Object>} 로그인 응답 또는 회사 선택 결과
      */
-    async loginUser({ email, password }) {
+    async loginUser({ email, password, projectId }) {
         if (!email || !password) throw new Error('email and password are required');
         this._enableRefreshSession();
         await this._authReady;
-        return this.authSession.login({ email, password });
+        return this.authSession.login({ email, password, projectId });
     }
 
     /**

package/src/auth/AuthSession.js

@@ -4,6 +4,21 @@ const sessions = new Map();
 const TERMINAL_CODES = new Set(['REFRESH_INVALID', 'REFRESH_REUSED', 'SESSION_REVOKED', 'ACCOUNT_BLOCKED', 'LOGIN_FAILED']);
 export const isTerminalAuthError = error => TERMINAL_CODES.has(error?.response?.code || error?.code);
 
+/**
+ * 로그인 회사 선택 결과 — 토큰이 없다. 목록이 비었거나 회사 id 가 없는 응답은 계약 위반이라 인증 불가로 끊는다(빈 선택 화면을 띄우지 않게).
+ */
+function workspaceSelection(data) {
+    const workspaces = Array.isArray(data.workspaces) ? data.workspaces : [];
+    if (workspaces.length === 0 || workspaces.some(workspace => !workspace?.projectId)) {
+        const error = new Error('Invalid authentication response'); error.code = 'AUTH_UNAVAILABLE'; throw error;
+    }
+    return {
+        workspaceSelectionRequired: true,
+        workspaces: workspaces.map(({ projectId, companyName, companyRole }) =>
+            ({ projectId, companyName: companyName ?? null, companyRole }))
+    };
+}
+
 export function tokenClaims(token) {
     try {
         const value = token.replace(/^Bearer\s+/i, '').split('.')[1].replace(/-/g, '+').replace(/_/g, '/');
@@ -240,13 +255,23 @@ export default class AuthSession extends EventEmitter {
         } finally { clearTimeout(timeout); }
     }
 
-    async login({ email, password }) {
+    /**
+     * 같은 이메일로 여러 회사 계정이 있고 비밀번호가 둘 이상 맞으면 서버는 토큰 없이 회사 목록만 준다. 그 응답은
+     * {@link workspaceSelection} 결과로 돌려준다. 저장소·인증 상태·이전 세션은 건드리지 않는다 — 서버도 이 단계에서는
+     * 이전 세션을 끊지 않는다. 호출자는 고른 {@code projectId} 를 실어 같은 자격으로 다시 부른다(서버가 비밀번호를 다시 검증).
+     */
+    async login({ email, password, projectId }) {
         const generation = ++this.generation;
         return this._locked(async () => {
             const previous = this._readMarker();
             this._writeMarker(previous);
             if (previous.pendingRefreshToken) await this._request('/v1/auth/signout', { refreshToken: previous.pendingRefreshToken, deviceId: previous.deviceId });
-            const data = await this._request('/api/v1/auth/login', { email, password, previousRefreshToken: previous.refreshToken });
+            const data = await this._request('/api/v1/auth/login',
+                { email, password, previousRefreshToken: previous.refreshToken, ...(projectId ? { projectId } : {}) });
+            if (data?.workspaceSelectionRequired === true) {
+                if (generation !== this.generation) throw this._cancelled();
+                return workspaceSelection(data);
+            }
             if (!data?.refreshToken) {
                 const error = new Error('Server does not support the refresh session contract');
                 error.code = 'AUTH_PROTOCOL_UNSUPPORTED';

package/src/chat/ChatClient.js

@@ -147,6 +147,7 @@ class ChatClient extends EventEmitter {
             PLANNING: '기획 중…',
             DOCUMENT_ANALYSIS: '문서 분석 중…',
             VIDEO_ANALYSIS: '영상 분석 중…',
+            WEB_READING: '페이지 읽는 중…',
             WRITING: '작성 중…'
         };
         // PHASE 의 expiresAt 누락/이상 시 fallback TTL (ms) — 서버 ttl(최소 30s) 보다 약간 길게.
@@ -2511,8 +2512,8 @@ class ChatClient extends EventEmitter {
      * @param {string} roomId - 채팅방 ID
      * @returns {Promise<void>}
      *
-     * @fires memberJoined - { roomId, members: [{ userId, nickname, profileUrl }], participantCount, timestamp }
-     * @fires memberLeft   - { roomId, members: [{ userId, nickname, profileUrl }], participantCount, timestamp }
+     * @fires memberJoined - { roomId, members: [{ userId, nickname, profileUrl, companyRole? }], participantCount, timestamp }
+     * @fires memberLeft   - { roomId, members: [{ userId, nickname, profileUrl, companyRole? }], participantCount, timestamp }
      */
     async subscribeRoom(roomId) {
         if (this.subscribedRooms.has(roomId)) {

package/src/constants.js

@@ -22,6 +22,8 @@ export const ErrorTypes = {
     CONNECTION_FAILED: 'CONNECTION_FAILED',
     CONNECTION_LOST: 'CONNECTION_LOST',
     CONNECTION_TIMEOUT: 'CONNECTION_TIMEOUT',
+    // 회사 구독 없음 — 서버가 NOT_SUBSCRIBED 로 거부했다(결제 전·해지). 재연결하지 않고 connect() 를 기다린다.
+    SUBSCRIPTION_REQUIRED: 'SUBSCRIPTION_REQUIRED',
 
     // Authentication errors
     JWT_INVALID: 'JWT_INVALID',

package/src/core/ConnectionManager.js

@@ -10,6 +10,11 @@ import { ConnectionState, ErrorTypes, WebSocketPaths, DefaultConfig, LogLevel }
 import { Client as StompClient, ReconnectionTimeMode, StompSocketState } from '@stomp/stompjs';
 import SockJS from 'sockjs-client';
 
+/** 서버 구독 관문의 거부 코드(STOMP ERROR 본문 code · HTTP 402) — 결제 전·해지 회사. */
+const SUBSCRIPTION_REQUIRED_CODE = 'NOT_SUBSCRIBED';
+/** 서버가 구독 상태를 잠시 확인하지 못했다(503) — 대기가 아니라 일시 실패다. */
+const SUBSCRIPTION_CHECK_UNAVAILABLE_CODE = 'SUBSCRIPTION_CHECK_UNAVAILABLE';
+
 // STOMP Client 가져오기 (CDN 사용 시 전역 객체 우선)
 const getStompClient = () => {
     // noinspection JSUnresolvedReference
@@ -82,6 +87,9 @@ class ConnectionManager extends EventEmitter {
         this._recoveryTimer = null;
         this._terminalAuthError = false;
         this._recoveryEligible = false;
+        // 회사 구독 대기 — 서버가 CONNECT·SUBSCRIBE·SEND 를 NOT_SUBSCRIBED 로 거부했다(결제 전·해지 회사).
+        // 인증 거부와 다르다: 토큰은 그대로 유효하고, 결제가 끝나면 앱이 같은 토큰으로 connect() 를 다시 부른다.
+        this._subscriptionRequired = false;
 
         this._installLifecycleListeners();
     }
@@ -153,7 +161,7 @@ class ConnectionManager extends EventEmitter {
      * @private
      */
     _onResume(reason) {
-        if (!this.resumeOnVisibility || this._intentionalDisconnect || this._terminalAuthError) {
+        if (!this.resumeOnVisibility || this._intentionalDisconnect || this._terminalAuthError || this._subscriptionRequired) {
             return;
         }
 
@@ -248,7 +256,10 @@ class ConnectionManager extends EventEmitter {
             this.stompClient = null;
         }
 
-        if (this._intentionalDisconnect || this._terminalAuthError) return;
+        // 구독 대기면 다시 붙지 않는다 — refresh 세션의 토큰 갱신(AuthSession 'access-token-renewed')·저빈도 복구·탭 복귀가 모두
+        // 이리로 오고, 정리를 기다리는 동안 옛 클라이언트가 NOT_SUBSCRIBED 로 대기에 들어간 경우도 여기서 걸린다. 대기는 앱이 connect() 를
+        // 다시 불러야 풀린다.
+        if (this._intentionalDisconnect || this._terminalAuthError || this._subscriptionRequired) return;
 
         // connect() 가 CONNECTED/CONNECTING 이면 조기 반환하므로 상태를 먼저 내려둔다.
         this._setState(ConnectionState.DISCONNECTED);
@@ -407,6 +418,8 @@ class ConnectionManager extends EventEmitter {
         }
         this._cancelReconnectRecovery();
         this._terminalAuthError = false;
+        // 구독 대기는 앱이 connect() 를 다시 불러야 풀린다(결제 확인 뒤). 아직 구독이 없으면 서버가 다시 거부해 대기로 돌아온다.
+        this._subscriptionRequired = false;
         this._setState(ConnectionState.CONNECTING);
         this.reconnectAttempts = 0;
         this._intentionalDisconnect = false;
@@ -476,10 +489,20 @@ class ConnectionManager extends EventEmitter {
      * @private
      */
     _onStompError(frame) {
+        let code = null;
+        let serverMessage = null;
         try {
             const payload = JSON.parse(frame.body || frame.headers?.message || '{}');
-            this._authRejected = ['ACCESS_UNAUTHORIZED', 'SESSION_REVOKED', 'TOKEN_INVALID'].includes(payload.code);
+            code = payload.code ?? null;
+            serverMessage = typeof payload.message === 'string' ? payload.message : null;
+            this._authRejected = ['ACCESS_UNAUTHORIZED', 'SESSION_REVOKED', 'TOKEN_INVALID'].includes(code);
         } catch { /* Non-authentication STOMP errors keep the normal reconnect policy. */ }
+        // 회사 구독 없음 — 재연결해도 같은 거부다. 인증 거부로 기록하지 않고 «구독 대기» 로 멈춘다.
+        // 구독 확인 일시 실패(SUBSCRIPTION_CHECK_UNAVAILABLE)는 아래 기본 경로 — 평소처럼 다시 붙는다.
+        if (code === SUBSCRIPTION_REQUIRED_CODE) {
+            this._stopForSubscription(serverMessage);
+            return;
+        }
         this.logger.error('STOMP error:', frame);
         this._setState(ConnectionState.ERROR);
 
@@ -490,7 +513,9 @@ class ConnectionManager extends EventEmitter {
         };
 
         if (this._authRejected) this._recordAuthRejection();
-        const terminal = !this._canRecoverConnection();
+        // 구독 확인 일시 실패는 첫 연결이라도 대기 중인 connect() 를 끝내지 않는다 — STOMP 가 곧 다시 붙는다. 여기서 reject 하면
+        // 앱은 실패로 알고 방 목록 구독 등 후속 초기화를 건너뛰는데 연결은 붙어 «반쪽 연결» 이 된다.
+        const terminal = code !== SUBSCRIPTION_CHECK_UNAVAILABLE_CODE && !this._canRecoverConnection();
         if (terminal) this._drainPendingSubscriptions(`STOMP error: ${error.message}`);
 
         this.emit('error', error);
@@ -512,7 +537,7 @@ class ConnectionManager extends EventEmitter {
 
         // forceReconnect 의 의도적 teardown 이면 재연결 시도로 집계하지 않는다 —
         // 카운터가 오염되면 복귀 직후 다시 max 를 소진해버린다.
-        if (this._tearingDown || this._intentionalDisconnect || this._terminalAuthError) {
+        if (this._tearingDown || this._intentionalDisconnect || this._terminalAuthError || this._subscriptionRequired) {
             this.logger.debug('WebSocket closed during intentional teardown — not counting as reconnect');
             return;
         }
@@ -618,7 +643,43 @@ class ConnectionManager extends EventEmitter {
 
     _canRecoverConnection() {
         return this._recoveryEligible && !this._intentionalDisconnect && !this._terminalAuthError
-            && this.reconnectRecoveryDelay > 0;
+            && !this._subscriptionRequired && this.reconnectRecoveryDelay > 0;
+    }
+
+    /** 회사 구독 대기 중인가 — 서버가 NOT_SUBSCRIBED 로 거부해 연결을 멈췄다. 앱이 connect() 를 다시 부르면 풀린다. */
+    isSubscriptionRequired() {
+        return this._subscriptionRequired;
+    }
+
+    /**
+     * «구독 대기» 로 멈춘다 (서버 구독 관문 설계 v3 §7).
+     *
+     * <p>인증 정지({@link #_stopForAuthError})와 같은 방식으로 STOMP 재연결 루프·저빈도 복구·탭 복귀 재연결을 끄되, 토큰은
+     * 거부된 토큰으로 기록하지 않는다 — 토큰 갱신·로그인은 그대로 둔다. 대기 중인 connect()·구독은 reject 하고, 한 번 들어올 때
+     * {@code subscriptionRequired} 를 알린다(일반 {@code error} 는 내지 않는다 — 연결 오류 안내가 결제 안내를 가리지 않게).
+     * 연결 중에 해지되면 다음 SUBSCRIBE·SEND 의 ERROR 로 같은 경로에 온다.</p>
+     *
+     * @private
+     */
+    _stopForSubscription(serverMessage) {
+        const entering = !this._subscriptionRequired;
+        this._subscriptionRequired = true;
+        this._cancelReconnectRecovery();
+        this._setState(ConnectionState.ERROR);
+        // 본문의 안내 문구 — message 헤더는 오류 JSON 전체가 이스케이프된 채 오므로 쓰지 않는다.
+        const message = serverMessage || 'Company subscription required';
+        const error = Object.assign(new Error('Company subscription required'),
+            { code: SUBSCRIPTION_REQUIRED_CODE, type: ErrorTypes.SUBSCRIPTION_REQUIRED });
+        this._connectReject?.(error);
+        this._connectResolve = this._connectReject = null;
+        this._drainPendingSubscriptions('Company subscription required');
+        const client = this.stompClient;
+        Promise.resolve(client?.deactivate()).catch(failure => this.logger.warn('Subscription teardown failed:', failure));
+        this.logger.warn('Company subscription required — connection stopped until connect() is called again');
+        if (entering) {
+            // 정지 전이를 마친 뒤 알린다 — 처리기가 곧바로 connect() 를 불러도 정리 중인 연결과 섞이지 않는다.
+            Promise.resolve().then(() => this.emit('subscriptionRequired', { code: SUBSCRIPTION_REQUIRED_CODE, message }));
+        }
     }
 
     /** 기존에 연결됐던 클라이언트만 긴 장애 후 탭 이벤트 없이 다시 시도한다. */
@@ -795,6 +856,7 @@ class ConnectionManager extends EventEmitter {
         // 명시적 해제 — 포그라운드 복귀가 이걸 되살리면 안 된다.
         this._intentionalDisconnect = true;
         this._recoveryEligible = false;
+        this._subscriptionRequired = false;
         this._authRejected = false;
         this._rejectedToken = null;
         this._cancelReconnectRecovery();

package/src/index.js

@@ -14,6 +14,7 @@
  * import TalkFlowClient from '@talkflow/sdk';
  *
  * // 1단계: 로그인. 클라이언트 생성 «전» 에 부른다 — ck/projectId/JWT 를 한 번에 받는다.
+ * //        회사 계정이 둘 이상이면 먼저 { workspaceSelectionRequired, workspaces } 가 온다 → projectId 를 실어 다시 부른다.
  * const { clientKey, projectId, accessToken } = await TalkFlowClient.loginUser({
  *   serverUrl: 'https://chat.apiorbit.net',
  *   email: 'me@example.com',

package/src/talkflow/eventForwarding.js

@@ -7,6 +7,8 @@ const CONNECTION_EVENT_MAP = [
     // 재연결 '성공' + 포그라운드 복귀 감지 (RECONNECT_SYNC_DESIGN §6.1/§6.4)
     ['reconnected', 'reconnected'],
     ['resumed', 'resumed'],
+    // 회사 구독 대기(서버 구독 관문) — 연결 오류와 따로 알린다. 결제 뒤 connect() 를 다시 부르면 풀린다.
+    ['subscriptionRequired', 'subscriptionRequired'],
     ['error', 'connectionError']
 ];
 

package/types/__typetests__/authSession.types.ts

@@ -1,4 +1,4 @@
-import TalkFlowClient, { AuthState, LoginResult } from '../index';
+import TalkFlowClient, { AuthState, LoginResult, WorkspaceSelection, CompanyRole, ParticipantResponse, RoomListMemberInfo } from '../index';
 const client = new TalkFlowClient({ serverUrl: 'https://api.example.com', sessionMode: 'refresh' });
 const restored: Promise<LoginResult | null> = client.restoreSession();
 const state: AuthState = client.getAuthState();
@@ -6,3 +6,25 @@ const signedIn: boolean = client.isLoggedIn();
 const access: Promise<string> = client.getAccessToken({ forceRefresh: true, rejectedToken: 'old' });
 client.on('authStateChanged', ({ state }) => { const typed: AuthState = state; void typed; });
 void [restored, state, signedIn, access];
+
+// 회사 선택 — 결과를 workspaceSelectionRequired 로 가른 뒤에만 토큰 칸을 쓴다.
+async function loginWithSelection(): Promise<LoginResult> {
+    const first = await TalkFlowClient.loginUser({ serverUrl: 'https://api.example.com', email: 'a@b.c', password: 'pw' });
+    if (first.workspaceSelectionRequired) {
+        const picked: WorkspaceSelection['workspaces'][number] = first.workspaces[0];
+        const role: CompanyRole = picked.companyRole;
+        void role;
+        const second = await client.loginUser({ email: 'a@b.c', password: 'pw', projectId: picked.projectId });
+        if (second.workspaceSelectionRequired) throw new Error('unexpected');
+        return second;
+    }
+    const key: string = first.clientKey;
+    void key;
+    return first;
+}
+// @ts-expect-error 가르기 전에는 clientKey 가 없을 수 있다
+TalkFlowClient.loginUser({ serverUrl: 'x', email: 'a', password: 'b' }).then(result => result.clientKey.length);
+const guestRole: CompanyRole = 'GUEST';
+const participantRole: ParticipantResponse['companyRole'] = 'GUEST';
+const memberRole: RoomListMemberInfo['companyRole'] = undefined;
+void [loginWithSelection, guestRole, participantRole, memberRole];

package/types/__typetests__/webReading.types.ts

@@ -0,0 +1,18 @@
+/**
+ * 웹페이지 읽기 진행 단계(8.9.0) — `WEB_READING` 이 phase 유니온에 있다는 것을 tsc 로 고정한다.
+ *
+ * <p>phase 를 직접 분기하는 화면이 이 값을 쓸 수 있어야 한다. 기본 라벨은 «페이지 읽는 중…» 이다.</p>
+ */
+import type { AssistantProgressEvent, AssistantRoomProgressEvent, AssistantProgressStreamSnapshot } from '../index';
+
+export function isWebReading(event: AssistantProgressEvent): boolean {
+    return event.active && event.phase === 'WEB_READING';
+}
+
+export function roomIsWebReading(event: AssistantRoomProgressEvent): boolean {
+    return event.phase === 'WEB_READING';
+}
+
+export function snapshotIsWebReading(snapshot: AssistantProgressStreamSnapshot): boolean {
+    return snapshot.phase === 'WEB_READING';
+}

package/types/index.d.ts

@@ -26,6 +26,8 @@ export const ErrorTypes: {
     readonly CONNECTION_FAILED: 'CONNECTION_FAILED';
     readonly CONNECTION_LOST: 'CONNECTION_LOST';
     readonly CONNECTION_TIMEOUT: 'CONNECTION_TIMEOUT';
+    /** 회사 구독 없음(결제 전·해지) — 웹소켓이 멈췄다. 결제 확인 뒤 `connect()` 를 다시 부른다. */
+    readonly SUBSCRIPTION_REQUIRED: 'SUBSCRIPTION_REQUIRED';
     readonly JWT_INVALID: 'JWT_INVALID';
     readonly JWT_EXPIRED: 'JWT_EXPIRED';
     readonly JWT_PARSE_FAILED: 'JWT_PARSE_FAILED';
@@ -1044,14 +1046,20 @@ export interface DecisionResponse {
     optionId: string;
 }
 
+/**
+ * 회사 역할. `GUEST` 는 회사 밖에서 초대받아 그 회사 계정을 가진 사람이다 — 초대받은 방에서 채팅만 하고 PM·AI 버튼·조직도·
+ * 방 만들기·초대 등은 서버가 막는다(403 `GUEST_FORBIDDEN`). 화면 노출 판단용이며 인가 근거는 아니다.
+ */
+export type CompanyRole = 'PARTNER' | 'MEMBER' | 'GUEST';
+
 /** 로그인한 회원. `userId` 는 메시지 발신자 식별과 같은 값이다. */
 export interface LoginMember {
     userId: string;
     email?: string | null;
     nickname?: string | null;
     profileUrl?: string | null;
-    /** 회사 역할 — 클라이언트가 파트너 화면 노출을 결정한다. 인가 근거는 아니다(서버가 재확인). */
-    companyRole: 'PARTNER' | 'MEMBER';
+    /** 회사 역할 — 클라이언트가 파트너·게스트 화면 노출을 결정한다. 인가 근거는 아니다(서버가 재확인). */
+    companyRole: CompanyRole;
     preferredLanguage?: string | null;
     /**
      * 초기 비밀번호를 아직 안 바꿨는가 — `true` 면 **비밀번호 변경 화면으로 보내라**.
@@ -1063,11 +1071,11 @@ export interface LoginMember {
 }
 
 /**
- * `TalkFlowClient.loginUser` 응답.
- *
- * 회사 선택 단계가 없다 — 로그인 키가 전역 유일이라 이메일 하나로 회원과 회사가 함께 정해진다.
+ * `TalkFlowClient.loginUser` 의 로그인 성공 응답. 회사 선택이 필요하면 대신 {@link WorkspaceSelection} 이 온다 —
+ * `workspaceSelectionRequired` 로 가른다.
  */
 export interface LoginResult {
+    workspaceSelectionRequired?: false;
     /** SDK가 저장·회전하는 갱신 자격. 직접 API를 쓰는 경우에만 응답에서 사용한다. */
     refreshToken?: string;
     /** 서버 현재 시각 및 refresh 만료 시각, Unix epoch 밀리초. */
@@ -1083,6 +1091,23 @@ export interface LoginResult {
     user: LoginMember;
 }
 
+/** 로그인 회사 선택지 하나. */
+export interface Workspace {
+    projectId: string;
+    companyName: string | null;
+    /** 그 회사에서의 역할 — 선택 화면에 «게스트» 표시를 붙이는 데 쓴다. */
+    companyRole: CompanyRole;
+}
+
+/**
+ * 로그인 회사 선택 결과 — 같은 이메일의 여러 회사 계정에서 비밀번호가 둘 이상 맞았다. **토큰이 없고 저장된 세션은 그대로다.**
+ * 고른 `projectId` 를 실어 같은 이메일·비밀번호로 `loginUser` 를 다시 부른다.
+ */
+export interface WorkspaceSelection {
+    workspaceSelectionRequired: true;
+    workspaces: Workspace[];
+}
+
 /** 회사 조직도의 회원 — 초대 UI 에 필요한 것만. */
 export interface DirectoryMember {
     userId: string;
@@ -1124,7 +1149,7 @@ export interface MyProfile {
     phone?: string | null;
     profileUrl?: string | null;
     /** 회사 역할 — 방 역할(ParticipantResponse.role)과 다른 축이다. */
-    companyRole: 'PARTNER' | 'MEMBER';
+    companyRole: CompanyRole;
     orgNodeId?: string | null;
     orgName?: string | null;
     preferredLanguage?: string | null;
@@ -1170,6 +1195,10 @@ export interface ParticipantResponse {
     role: 'OWNER' | 'ADMIN' | 'MEMBER' | 'ASSISTANT';
     /** 참가 시각(epoch millis). */
     joinedAt: number;
+    /**
+     * 회사 역할 — 게스트 배지(`GUEST`)용. 방 역할({@link role})과 다른 축이다. PM(ASSISTANT)·정보를 못 찾은 참여자는 없다.
+     */
+    companyRole?: CompanyRole;
 }
 
 /** 채팅방 last message preview. */
@@ -1280,6 +1309,8 @@ export interface RoomListMemberInfo {
     userId: string;
     nickname?: string | null;
     profileUrl?: string | null;
+    /** 회사 역할 — 방금 들어온 게스트에도 다시 읽지 않고 배지를 그린다. PM·역할을 모르는 경로는 없다. */
+    companyRole?: CompanyRole;
 }
 
 export interface RoomListUpdateEvent {
@@ -1478,7 +1509,7 @@ export interface AssistantProgressEvent {
     /** 진행 주체 페르소나 ID. */
     personaId: string | null;
     /** 진행 단계 — `active:true` 일 때. 종료 시 null. */
-    phase: 'THINKING' | 'SEARCHING' | 'PLANNING' | 'DOCUMENT_ANALYSIS' | 'VIDEO_ANALYSIS' | 'WRITING' | null;
+    phase: 'THINKING' | 'SEARCHING' | 'PLANNING' | 'DOCUMENT_ANALYSIS' | 'VIDEO_ANALYSIS' | 'WEB_READING' | 'WRITING' | null;
     /** DOCUMENT_ANALYSIS의 실측 진행률. 같은 phase heartbeat 사이와 재입장 후에도 보존된다. */
     progress?: DocumentAnalysisProgress | null;
     /** phase 의 기본 표시 라벨(예: "생각 중…"). SDK 매핑 — 커스텀하려면 `phase` 사용. 종료 시 null. */
@@ -1549,7 +1580,7 @@ export interface AssistantRoomProgressEvent {
     /** 표시 기준이 된 stream (가장 최근 갱신). 없으면 null. */
     streamId: string | null;
     personaId: string | null;
-    phase: 'THINKING' | 'SEARCHING' | 'PLANNING' | 'DOCUMENT_ANALYSIS' | 'VIDEO_ANALYSIS' | 'WRITING' | null;
+    phase: 'THINKING' | 'SEARCHING' | 'PLANNING' | 'DOCUMENT_ANALYSIS' | 'VIDEO_ANALYSIS' | 'WEB_READING' | 'WRITING' | null;
     progress?: DocumentAnalysisProgress | null;
     label: string | null;
     /** 표시 기준 stream 의 누적 본문. `textAvailable:false` 거나 진행 중이 아니면 null. */
@@ -1562,7 +1593,7 @@ export interface AssistantRoomProgressEvent {
 export interface AssistantProgressStreamSnapshot {
     streamId: string;
     personaId: string | null;
-    phase: 'THINKING' | 'SEARCHING' | 'PLANNING' | 'DOCUMENT_ANALYSIS' | 'VIDEO_ANALYSIS' | 'WRITING' | null;
+    phase: 'THINKING' | 'SEARCHING' | 'PLANNING' | 'DOCUMENT_ANALYSIS' | 'VIDEO_ANALYSIS' | 'WEB_READING' | 'WRITING' | null;
     progress?: DocumentAnalysisProgress | null;
     label: string | null;
     text: string | null;
@@ -1934,7 +1965,7 @@ export interface ChatMessageReceivedPayload {
 
 export interface MemberChangePayload {
     roomId: string;
-    members: Array<{ userId: string; nickname?: string; profileUrl?: string | null }>;
+    members: Array<{ userId: string; nickname?: string; profileUrl?: string | null; companyRole?: CompanyRole }>;
     participantCount: number;
     timestamp?: number;
 }
@@ -1968,7 +1999,7 @@ export interface RetentionCleanupPayload {
 /**
  * TalkFlowClient 이벤트 맵 — 런타임 {@code TalkFlowClient.js} 의 {@code this.emit(...)} 호출 기반.
  *
- * <p><b>Connection 관련</b>: stateChange, connected, disconnected, reconnecting, reconnected, resumed, connectionError, tokenSet, loggedOut</p>
+ * <p><b>Connection 관련</b>: stateChange, connected, disconnected, reconnecting, reconnected, resumed, subscriptionRequired, connectionError, tokenSet, loggedOut</p>
  * <p><b>Chat 관련 (ChatClient 이벤트를 이 이름으로 re-emit)</b>: chatMessage, newChatMessage, messageUpdated, messageDeleted, reactionChanged, linkPreviewAttached, messageRead, typing, assistantProgress, memberJoined, memberLeft, roomSubscribed, roomUnsubscribed, roomListSubscribed, roomListUnsubscribed, roomListUpdate, roomListMessage, roomListCreated, roomListJoined, roomListLeft, roomListSelfLeft, roomListRoomUpdated, retentionCleanup</p>
  * <p><b>Push 관련</b>: pushEnabled, pushFailed, pushNotification</p>
  * <p><b>WebRTC 관련</b>: localStreamStarted, localStreamStopped, remoteTrack, screenShareStarted, screenShareEnded, deviceChange, mediaStateChanged, callStarted, callEnded, callRequested, callAccepted, callRejected, callCancelled, callInvitation, callBusy, incomingCall, incomingCallWhileBusy, userJoined, userLeft, participantLeft, participantMediaState, peerConnected, peerDisconnected, peerClosed, webrtcError</p>
@@ -1993,6 +2024,15 @@ export interface TalkFlowClientEvents {
      * 발행된다(두 이벤트가 겹치지 않아 재동기화가 중복 실행되지 않는다).</p>
      */
     resumed: { reason: 'visibilitychange' | 'pageshow' | 'online' };
+    /**
+     * 회사 구독 없음 — 서버가 웹소켓 연결·구독·전송을 `NOT_SUBSCRIBED` 로 거부했다(결제 전·해지 회사). SDK 는 재연결하지 않고
+     * 토큰도 거부된 것으로 기록하지 않는다(로그인·토큰 갱신은 그대로). 대기에 들어갈 때 한 번 발행되며 `connectionError` 는 내지 않는다.
+     *
+     * <p>앱: 파트너면 결제 화면, 그 밖은 «회사 구독이 필요합니다. 관리자에게 문의하세요.» 안내. 결제가 확인되면
+     * (`subscription === 'ACTIVE'`) 같은 토큰으로 `connect()` 를 다시 부른다. 구독 확인 일시 실패(`SUBSCRIPTION_CHECK_UNAVAILABLE`)는
+     * 이 이벤트가 아니다 — 평소처럼 재연결한다.</p>
+     */
+    subscriptionRequired: { code: 'NOT_SUBSCRIBED'; message: string };
     connectionError: unknown;
     tokenSet: { userId: string };
     loggedOut: void;
@@ -2602,16 +2642,18 @@ export default class TalkFlowClient implements SdkEventEmitter<TalkFlowClientEve
     /**
      * 회원 로그인 — 클라이언트 생성 **전에** 호출한다. Server Key 도 고객사 BFF 도 필요 없다.
      * 응답의 `clientKey`/`projectId`/`accessToken` 이 그대로 SDK 초기화 입력이다.
-     * 회사 선택 단계가 없다 — 로그인 키가 전역 유일이다.
+     * 같은 이메일로 비밀번호가 맞는 회사 계정이 둘 이상이면 {@link WorkspaceSelection} 이 온다 — 고른 `projectId` 로 다시 부른다.
      */
     static loginUser(options: {
         serverUrl: string;
         email: string;
         password: string;
-    }): Promise<LoginResult>;
+        /** 회사 선택 응답에서 고른 회사. */
+        projectId?: string;
+    }): Promise<LoginResult | WorkspaceSelection>;
 
-    /** 회원 로그인 (인스턴스) — 재로그인·계정 전환용. 성공 시 토큰을 자동 설정한다. */
-    loginUser(credentials: { email: string; password: string }): Promise<LoginResult>;
+    /** 회원 로그인 (인스턴스) — 재로그인·계정 전환용. 성공 시 토큰을 자동 설정한다. 회사 선택 결과면 토큰을 설정하지 않는다. */
+    loginUser(credentials: { email: string; password: string; projectId?: string }): Promise<LoginResult | WorkspaceSelection>;
 
     /** localStorage의 refresh로 복구. 세션이 없으면 null, 네트워크/서버 장애는 reject. */
     static restoreSession(options: { serverUrl: string }): Promise<LoginResult | null>;
@@ -2648,6 +2690,8 @@ export default class TalkFlowClient implements SdkEventEmitter<TalkFlowClientEve
     /**
      * 연결 완료까지 기다립니다. 이전 연결의 자동 복구가 이어지는 동안 재시도 한도 소진으로 reject하지 않습니다.
      * 복구 연결 시 resolve하며, 명시적 disconnect·인증 종료·최초 연결 실패 시 reject합니다.
+     * 회사 구독이 없으면(서버 `NOT_SUBSCRIBED`) `code: 'NOT_SUBSCRIBED'`·`type: 'SUBSCRIPTION_REQUIRED'` 로 reject 하고
+     * 재연결하지 않습니다 — {@link TalkFlowClientEvents.subscriptionRequired} 참고.
      */
     connect(jwt?: string, options?: ConnectOptions): Promise<void>;
     disconnect(): Promise<void>;
@@ -2655,6 +2699,11 @@ export default class TalkFlowClient implements SdkEventEmitter<TalkFlowClientEve
     setToken(token: string): Promise<void>;
     updateToken(newToken: string): Promise<void>;
     isConnected(): boolean;
+    /**
+     * 회사 구독 대기 중인가 — 서버가 웹소켓을 `NOT_SUBSCRIBED` 로 거부해 연결을 멈췄다(결제 전·해지 회사).
+     * 결제가 확인되면(`GET /api/v1/company/billing` 의 `subscription === 'ACTIVE'`) 같은 토큰으로 `connect()` 를 다시 부른다.
+     */
+    isSubscriptionRequired(): boolean;
     getState(): ConnectionStateValue;
     hasToken(): boolean;