@vibexnpm/talkx 2.3.1

package/README.md

@@ -0,0 +1,327 @@
+# TalkFlow SDK
+
+채팅 + WebRTC + 웹 푸시 통합 JavaScript SDK.
+
+```bash
+npm install @vibexnpm/talkflow
+```
+
+---
+
+## 빠른 시작
+
+```javascript
+import TalkFlowClient from '@vibexnpm/talkflow';
+
+// 1. SDK 초기화 (Client Key 사용)
+const client = new TalkFlowClient({
+    apiKey: 'ck-your-client-key',     // 브라우저 노출 안전
+    projectId: 'your-project-id'
+});
+
+// 2. 고객사 backend 에서 JWT 발급받아 연결
+const jwtToken = await fetchJwtFromYourBackend();
+await client.connect(jwtToken);
+
+// 3. 채팅 사용
+const detail = await client.enterRoom('room-id');
+await client.sendTextMessage('room-id', '안녕하세요!');
+
+// 4. 푸시 알림 — 사용자 버튼 클릭 안에서 활성화 권장
+pushButton.addEventListener('click', async () => {
+    const result = await client.enablePushNotifications();
+    if (!result.ok && result.reason === 'PERMISSION_DENIED') {
+        showSettingsGuide();
+    }
+});
+```
+
+> 처음 사용한다면 [docs/getting-started.md](docs/getting-started.md) 부터 읽어주세요. 설치 → 인증 → 첫 연결까지 안내합니다.
+
+---
+
+## 권장 초기 설정 순서
+
+고객사에서 가장 많이 헷갈리는 부분은 **JWT 발급**, **서버 연결**, **푸시 권한 요청**의 순서입니다. 초기 연동은 아래 순서를 권장합니다:
+
+1. 고객사 backend 가 TalkFlow JWT 를 발급합니다.
+2. 브라우저에서 `TalkFlowClient` 를 생성합니다.
+3. `await client.connect(jwtToken)` 으로 연결합니다.
+4. 연결이 끝난 뒤, **사용자 버튼 클릭**으로 `client.enablePushNotifications()` 를 호출합니다.
+
+### 푸시 권한 팝업 주의사항
+
+- `Notification.requestPermission()` 은 브라우저 정책상 **사용자 제스처 (클릭 / 탭)** 안에서 호출하는 것이 가장 안전합니다.
+- Chrome 계열에서는 비동기 연결 작업이 끝난 뒤 자동으로 권한 요청을 띄우면, 팝업이 바로 안 뜨거나 새로고침 후에만 뜨는 것처럼 보일 수 있습니다.
+- 그래서 초기 온보딩에서는 `connect(jwt, { enablePush: true })` 보다, **연결 완료 후 버튼 클릭으로 `enablePushNotifications()` 호출**을 권장합니다.
+
+```javascript
+// ✅ 권장
+await client.connect(jwtToken);
+enablePushButton.onclick = () => client.enablePushNotifications();
+
+// ⚠️ 초기 온보딩에서는 비권장
+await client.connect(jwtToken, { enablePush: true });
+```
+
+---
+
+## 문서
+
+| 문서 | 내용 |
+|---|---|
+| [getting-started.md](docs/getting-started.md) | **처음 사용한다면 여기부터.** 설치, API Key, 빠른 시작, 프로덕션 인증 플로우 |
+| [connection.md](docs/connection.md) | 연결 관리, 설정 옵션, 재연결 정책, JWT 토큰 lifecycle, 환경 설정, 상태 확인 |
+| [chat.md](docs/chat.md) | 채팅방 관리, 메시지 전송, 파일 업로드, 답글, 리액션, 핀, 타이핑, 채팅방 리스트 실시간 갱신, **AI 어시스턴트 페르소나 (멘션 응답)** |
+| [push.md](docs/push.md) | **웹 푸시 알림.** 권한 lifecycle, 활성화 패턴 (자동 vs 사용자 액션), 디바이스 토글, 알림 클릭 라우팅 |
+| [webrtc.md](docs/webrtc.md) | 1:1 / 그룹 통화, 미디어 제어, 디바이스 관리, TURN 서버 |
+| [events.md](docs/events.md) | 모든 이벤트 레퍼런스. 채팅 이벤트 처리 패턴 (`eventType` 분기 vs 상태 필드 렌더) |
+| [errors.md](docs/errors.md) | 에러 분류 (`PushErrorReason`, `ErrorTypes`), HTTP 상태 코드, 입력 제약 |
+
+---
+
+## API 사용 패턴
+
+TalkFlow SDK 는 **단일 `client` 인스턴스**로 모든 기능에 접근합니다. 메서드와 이벤트 모두 `client.xxx()` / `client.on(...)` 형태로 통일되어 있습니다.
+
+```javascript
+// ✅ 권장 — 모든 메서드는 client 에 직접 호출
+const detail = await client.enterRoom(roomId);
+await client.sendMessage(roomId, request);
+const inCall = client.isInCall();
+
+// ✅ 권장 — 모든 이벤트는 client 에 직접 구독
+client.on('chatMessage', handler);
+client.on('messageRead', handler);
+client.on('callStarted', handler);
+client.on('pushNotification', handler);
+client.on('pushFailed', handler);
+```
+
+내부적으로 채팅 (ChatClient), WebRTC (WebRTCClient), 푸시 (PushManager) 서브 모듈로 구성되어 있지만 외부에서는 `client` 만 사용하면 됩니다.
+
+---
+
+## AI 어시스턴트
+
+채팅방에 AI 어시스턴트를 추가하면 사용자 메시지에 자동으로 답변합니다.
+
+```javascript
+// 1) 사용 가능한 어시스턴트 리스트 조회 → UI 에 표시
+const assistants = await client.getAssistants();
+// 각 항목: { id, displayName, mentionKey, role }
+
+// 2) 사용자가 UI 에서 선택한 어시스턴트 id 들을 방 생성에 전달
+const room = await client.createGroupRoom({
+  roomName: '신제품 기획방',
+  invitedUserIds: ['user-1', 'user-2'],
+  invitedAssistantPersonaIds: [/* 사용자가 선택한 id 배열 */],
+  assistantMode: 'GENERAL', // GENERAL | PEOPLE_ONLY | CALL_ONLY
+  roomAiType: 'PERSONA_MULTI' // 선택 — 생략 시 자동 파생. 'NONE' 이면 AI 없는 사람 전용 방 (docs/chat.md)
+});
+
+// 3) 채팅창에서 사용 — @멘션 또는 일반 메시지
+//    - @법률자문관 처럼 직접 멘션하면 해당 어시스턴트가 답변
+//    - 멘션 없이 일반 메시지를 보내면 메시지 내용에 가장 적합한 어시스턴트가 자동으로 답변 (없으면 침묵)
+await client.sendTextMessage(room.data.id, '@법률자문관 계약서 검토 부탁');
+await client.sendTextMessage(room.data.id, '신제품 출시 일정 어떻게 잡을지 의견 부탁드립니다');
+
+// 방장 설정 변경: 사람만 / 호출 시만 모드
+await client.updateGroupRoom(room.data.id, { assistantMode: 'CALL_ONLY' });
+
+// 4) 어시스턴트 응답은 일반 chatMessage 이벤트로 수신 (senderType 으로 구분)
+client.on('chatMessage', ({ message }) => {
+  if (message.senderType === 'ASSISTANT') {
+    renderAssistantMessage(message);
+  } else {
+    renderUserMessage(message);
+  }
+});
+
+// 5) "AI 응답 준비 중" 표시 (SDK v2.2.x+) — 어시 응답이 5~13초 걸리므로 사용자가 무반응으로 느끼지 않도록
+//    typing 이벤트에 senderType 필드가 추가됨. 'ASSISTANT' 분기로 별도 UI 표시 권장.
+client.on('typing', e => {
+  if (e.senderType === 'ASSISTANT') {
+    if (e.typing) showAssistantThinking(e.roomId);    // 예: 메시지 영역에 "AI 응답 중..." 표시
+    else hideAssistantThinking(e.roomId);
+  } else {
+    // 기존 사용자 typing UI (입력 영역 등)
+    if (e.typing) showUserTyping(e.userName);
+    else hideUserTyping(e.userName);
+  }
+});
+```
+
+**어시 typing 동작**:
+- **서버가 `chat.assistant.typing.enabled=true` 인 경우에만** `typing=true` 1회 발행 (멘션 매칭 또는 자동 라우팅 결정 시점). 어시 메시지가 도착하면 SDK 가 즉시 `typing=false` 자동 emit
+- 어시 응답 없이 30초 경과 시 SDK 가 자동으로 `typing=false` emit — UI 가 영구 "응답 중" 상태에 갇히지 않음
+- 30초 timeout 조정: `client.chat._assistantTypingTimeoutMs = 45000`
+
+**운영 활성화**: 본 기능은 서버측 feature flag (`chat.assistant.typing.enabled`) 에 의해 제어. default `false` (운영 안전 — 구버전 SDK 영구 표시 리스크 회피). dev/stg = `true`, prod 는 SDK v2.2.x+ 모든 고객사 롤아웃 확인 후 서버 운영자가 명시적 활성화.
+
+**호환성**: 기존 `chat.on('typing', ...)` handler 가 `senderType` 무시해도 동작은 함. 다만 어시 typing 이 `userName="AI"` 로 사용자 typing 처럼 표시될 수 있으니 분기 권장.
+
+운영 중 어시스턴트 추가 / 제거 (방장 권한):
+
+```javascript
+// 어시스턴트 추가 — 회원 초대와 동일한 방식
+await client.inviteToGroupRoom(roomId, {
+  assistantPersonaIds: [/* 어시스턴트 id 배열 */]
+});
+
+// 어시스턴트 제거 — 회원 kick 과 동일한 방식
+await client.kickMember(roomId, /* 어시스턴트 id */);
+```
+
+### 어시스턴트 도구 — 평점 / 요약 / 번역
+
+자동 응답 외에, UI 버튼으로 어시스턴트 도구를 직접 실행할 수 있습니다.
+
+```javascript
+import { SummarizeFormat } from '@vibexnpm/talkflow';
+
+// 1) 평점 — 어시스턴트 메시지에 1~5점 (어시 메시지에만 노출 권장)
+client.on('chatMessage', ({ message }) => {
+  if (message.senderType === 'ASSISTANT' && !message.deletedStatus) {
+    showRatingButtons(message); // 사용자가 별점 선택 시 ↓
+  }
+});
+await client.rateAssistantMessage(roomId, message.messageId, 5, '정확했어요'); // comment 선택
+
+// 2) 요약 — 최근 대화를 지정 포맷으로 요약 (방에 어시 메시지로 broadcast)
+const summary = await client.summarizeWithAssistant(roomId, {
+  personaId,                          // getAssistants() 의 id
+  format: SummarizeFormat.MINUTES,    // MINUTES|SHORT|TIMELINE|ACTIONS|OPTIONS (기본 SHORT)
+  messageCount: 30                    // 최근 N개 (1~50, 선택)
+});
+if (summary.outcome !== 'EMITTED') console.warn(summary.detail); // SKIPPED/FAILED 사유
+
+// 3) 번역 — 특정 메시지를 목표 언어로 번역
+const translated = await client.translateWithAssistant(roomId, {
+  personaId,
+  sourceMessageId: message.messageId,
+  targetLang: 'en'                    // 선택 (미지정 시 서버 정책)
+});
+// 결과 메시지는 일반 chatMessage 이벤트로도 수신됨 (outcome === 'EMITTED' 시 messageId 존재)
+```
+
+요약/번역은 동기 호출이라 LLM 처리(수 초) 후 반환되며, 생성된 어시스턴트 메시지는 일반 `chatMessage` 이벤트로도 도착합니다.
+
+---
+
+## CDN 사용
+
+```html
+<!-- 최신 버전 -->
+<script src="https://cdn.jsdelivr.net/npm/@vibexnpm/talkflow"></script>
+
+<!-- 버전 지정 (운영 환경 권장) -->
+<script src="https://cdn.jsdelivr.net/npm/@vibexnpm/talkflow@1.0.0"></script>
+
+<script>
+    const client = new TalkFlowSDK.default({
+        apiKey: 'CLIENT_KEY',
+        projectId: 'your-project-id',
+        jwtToken: '<고객사 backend 에서 받은 JWT>'
+    });
+</script>
+```
+
+CDN 사용 시 웹 푸시 활성화는 [docs/push.md](docs/push.md#cdn-사용-시) 참고.
+
+---
+
+## TypeScript 지원
+
+TypeScript 타입 정의는 `types/index.d.ts` 에 포함됩니다. `package.json` 의 `"types"` 필드가 이 파일을 가리키므로 별도 설정 없이 자동 지원됩니다.
+
+```typescript
+import TalkFlowClient, {
+    ConnectionState,
+    ChatMessageType,
+    ChatRoomType,
+    RoomListEventType,
+    LogLevel,
+    PushErrorCode,
+    type TalkFlowClientOptions,
+    type EnablePushResult,
+    type PushPermissionState,
+    type PushFailedPayload,
+    type ChatMessageReceivedPayload,
+    type RoomListUpdateEvent,
+    type PushNotificationPayload,
+} from '@vibexnpm/talkflow';
+
+const client = new TalkFlowClient({
+    apiKey: 'CLIENT_KEY',
+    projectId: 'project-id',
+    jwtToken: jwt,
+    env: 'production',
+    logLevel: LogLevel.WARN,
+});
+
+// 푸시 결과 처리
+const result: EnablePushResult = await client.enablePushNotifications();
+if (!result.ok && result.reason === PushErrorCode.PERMISSION_DENIED) {
+    showSettingsGuide();
+}
+
+// 권한 상태 분기
+const state: PushPermissionState = client.getPushPermissionState();
+```
+
+### 서브클라이언트 프로퍼티는 nullable
+
+`client.chat` / `client.webrtc` / `client.pushManager` 는 **JWT 토큰이 설정되기 전까지 `null`** 입니다.
+
+```typescript
+const client = new TalkFlowClient({ apiKey, projectId });
+// client.chat 은 이 시점에 null
+await client.connect(jwt);
+// 이제 client.chat 은 non-null
+client.chat!.sendTextMessage('room-id', 'hi');
+```
+
+> 단, `client.getPushPermissionState()` 는 pushManager 가 null 이어도 호출 가능합니다 (브라우저 표준 API 만 조회).
+
+### 제공되는 주요 타입
+
+| 카테고리 | 타입/상수 |
+|---|---|
+| 상수 | `ConnectionState`, `ErrorTypes`, `SignalTypes`, `ChatMessageType`, `ChatRoomType`, `SenderType`, `PersonaRole`, `RoomAiType`, `EngagementIntensity`, `RoomListEventType`, `LogLevel`, `Environment`, `WebSocketPaths`, `DefaultConfig`, `Endpoints`, `PushErrorCode` |
+| 도메인 | `ChatMessage`, `ChatRoomResponse`, `ParticipantResponse`, `LastMessageResponse`, `FileMetaData`, `ReactionResponse`, `ReplyToSnapshot`, `CursorPageResponse<T>`, `PushDeviceInfo`, `AssistantPersonaResponse`, `RoomAiMetaResponse` |
+| 옵션 | `TalkFlowClientOptions`, `ConnectOptions`, `EnablePushOptions`, `CursorPageParams`, `CreateGroupRoomData`, `UpdateGroupRoomData`, `SendMessageData`, `SendMessageResult`, `FileUploadOptions`, `SendFileMessageOptions`, `DeleteType` |
+| 이벤트 맵 | `TalkFlowClientEvents`, `ChatClientEvents`, `WebRTCClientEvents` |
+| 이벤트 payload | `ChatMessageReceivedPayload`, `MemberChangePayload`, `MessageReadEventPayload`, `RetentionCleanupPayload`, `RoomListUpdateEvent`, `PushNotificationPayload`, `PushFailedPayload`, `TypingEvent`, `UploadProgressEvent`, `SendFileMessageProgressEvent` |
+| 푸시 (신규) | `PushPermissionState`, `PushErrorReason`, `EnablePushResult`, `PushError` |
+| 클래스 | `TalkFlowClient` (default), `ChatClient`, `WebRTCClient`, `PushManager`, `EventEmitter`, `Logger` |
+
+상세 사용은 [docs/](docs/) 디렉토리의 각 문서 참고.
+
+---
+
+## 브라우저 지원
+
+- Chrome 70+
+- Firefox 65+
+- Safari 13+
+- Edge 79+
+
+> Safari iOS 등 일부 환경은 웹 푸시 (Notification + Service Worker) 를 지원하지 않습니다. `client.getPushPermissionState() === 'unsupported'` 로 사전 분기 가능합니다.
+
+---
+
+## 리소스 정리
+
+```javascript
+await client.destroy();
+// disconnect → 서브 클라이언트 destroy → 모든 리스너 제거
+```
+
+페이지 unmount 시 호출하여 메모리 누수 방지.
+
+---
+
+## 라이선스
+
+MIT