connectbase-client 3.17.0 → 3.17.1

package/CHANGELOG.md

@@ -3,6 +3,24 @@
 본 SDK 의 모든 주요 변경사항을 [Keep a Changelog](https://keepachangelog.com/ko/1.1.0/) 형식으로 기록합니다.
 버전은 [Semantic Versioning](https://semver.org/lang/ko/) 을 따릅니다.
 
+## [3.17.1] - 2026-05-19
+
+### Docs — README 에 Knowledge Base (RAG) 섹션 신설
+
+기존 README 의 API Reference 가 game / auth / database / storage / realtime / endpoint /
+push / webrtc / payments / support 만 다루고 knowledge 섹션이 통째로 누락된 상태였음.
+npm 페이지에서 SDK 사용자가 RAG 기능 존재를 인지하지 못하는 누락 보강.
+
+추가:
+- API Reference 에 "Knowledge Base (RAG)" 섹션 — `addDocument` (text/url) /
+  `addDocumentFromFile` (PDF/DOCX/text, 50MB) / `listDocuments` / `deleteDocument` /
+  `search` (BM25 + Agentic) / `searchGet` 예제
+- 파일 업로드 제약 (지원/미지원 MIME, 50MB, OCR 미지원) 박스
+- 사용자별 격리 (AppMember JWT 기반 metadata.user_id 자동 태깅) 안내
+- Features 리스트에 "Knowledge Base (RAG)" 한 줄 추가
+
+코드 변경 없음 — docs only. 코드 표면은 3.17.0 과 동일.
+
 ## [3.17.0] - 2026-05-18
 
 ### Added — `cb.knowledge.addDocumentFromFile` (PDF / DOCX / text 파일 업로드)
@@ -103,6 +121,19 @@ OAuth 리다이렉트 콜백 페이지(`?access_token=&refresh_token=` legacy, `
 회귀 가드: `test/auto-restore-session-callback-skip.test.ts` — 6 케이스
 (일반 / legacy 토큰-in-URL / code-only / error / 단독 access_token / autoRestoreSession=false).
 
+## [3.16.1] - 2026-05-16
+
+### Added — `SCRIPT_SETUP_OVERRUN` GameErrorCode literal
+
+game-server 의 hook ctx 2-phase split (setup vs hook deadline 분리, backend
+commit `ffe5108a` + `2132af4f`) 에 맞춰 `GameErrorCode` literal union 에
+`'SCRIPT_SETUP_OVERRUN'` 을 추가했다. 사용자 hook 본문이 아닌 SDK 가 매 호출
+주입하는 setup 단계 (스크립트 로드 + state 직렬화) 가 budget 을 초과한 경우
+구분 가능하도록 한 4채널 동등 작업의 JS/TS 측. Unity / Godot / Unreal 도 동일
+시점에 동일 코드를 노출.
+
+backward-compat: 신규 literal 추가만 — 기존 사용 패턴 호환.
+
 ## [3.16.0] - 2026-05-14
 
 ### Added — cross-app OAuth 로 Provider 함수 호출 / Database Realtime 구독

package/README.md

@@ -91,6 +91,7 @@ try {
 - **WebRTC**: Real-time audio/video communication
 - **Payments**: Subscription and one-time payment support
 - **AI Streaming**: Real-time AI text generation via WebSocket (Gemini)
+- **Knowledge Base (RAG)**: Document indexing + BM25 search with nori 한국어 형태소. PDF / DOCX / text file upload via `addDocumentFromFile`
 - **Endpoint**: Call your own GPU models on your own PC through one `cb_pk_*` key — ConnectBase forwards the payload as-is (dumb pipe)
 - **Support**: End-user feedback/issue reporting — users send issues to app operators, AI auto-classifies summary/urgency/category
 - **CLI**: Command-line tool for deploying web storage and tunneling local services
@@ -778,6 +779,71 @@ const { pages } = await cb.storage.listPageMetas('web-storage-id')
 await cb.storage.deletePageMeta('web-storage-id', '/products/123')
 ```
 
+### Knowledge Base (RAG)
+
+문서를 등록하고 BM25 풀텍스트 검색으로 관련 청크를 찾는 RAG 인프라. 한국어는 nori 형태소 분석기 적용. AI 채팅에 컨텍스트로 연결하려면 `cb.ai.chatStream({ knowledgeBaseId })` 를 사용한다.
+
+```typescript
+// 텍스트 문서 추가 (즉시 처리)
+const doc = await cb.knowledge.addDocument('kb-id', {
+    name: '환불 정책',
+    source_type: 'text',
+    content: '환불은 구매 후 7일 이내 신청 가능합니다...',
+    metadata: { category: 'policy' }
+})
+// doc.status: 'pending' → 백그라운드 처리 후 'ready'
+
+// URL 에서 가져오기
+await cb.knowledge.addDocument('kb-id', {
+    name: '도움말',
+    source_type: 'url',
+    source_url: 'https://example.com/help.html',
+})
+
+// PDF / DOCX / text 파일 업로드 (3.17.0+)
+// 브라우저: <input type="file"> 결과를 그대로 전달
+const file = (document.querySelector('input[type=file]') as HTMLInputElement).files![0]
+await cb.knowledge.addDocumentFromFile('kb-id', file, {
+    metadata: { tag: 'manual' },
+})
+
+// Node.js: fs.readFileSync 로 읽은 Buffer
+import { readFileSync } from 'node:fs'
+await cb.knowledge.addDocumentFromFile('kb-id', {
+    data: readFileSync('./report.pdf'),
+    mimeType: 'application/pdf',
+    name: 'report.pdf',
+})
+
+// 문서 목록 / 삭제
+const { documents } = await cb.knowledge.listDocuments('kb-id')
+await cb.knowledge.deleteDocument('kb-id', 'doc-id')
+
+// 키워드 검색 (BM25)
+const results = await cb.knowledge.search('kb-id', {
+    query: '환불 정책이 어떻게 되나요?',
+    top_k: 5,
+})
+results.results.forEach(r => console.log(`[${r.score.toFixed(2)}] ${r.document_name}: ${r.content.slice(0, 80)}...`))
+
+// Agentic Search — AI 가 다중 쿼리 자동 생성 (앱에 AI 프로바이더 설정 필요)
+await cb.knowledge.search('kb-id', { query: '회원 등급별 혜택 비교', agentic: true })
+
+// GET 방식 (간단한 사용)
+await cb.knowledge.searchGet('kb-id', '환불', 3)
+```
+
+**파일 업로드 제약 (`addDocumentFromFile`)**
+
+- 지원 MIME: `application/pdf` (텍스트 PDF), DOCX, `text/*` (plain/markdown/csv/html), `application/json`
+- 미지원: 스캔 이미지 PDF / OCR / HWP / XLSX → `unsupported mime type for text extraction` 에러
+- 크기 상한: **50MB** (원본 바이너리 기준)
+- 추출 결과 빈 텍스트일 경우 `extracted text is empty` 에러 (스캔 PDF 등)
+
+**사용자별 격리 (다중 사용자 RAG)**
+
+`Authorization: Bearer <appmember-jwt>` 를 함께 보내면 서버가 자동으로 본인 metadata.user_id 로 결과를 제한하고, addDocument 시에도 자동 태깅. `search` 의 `where` 에 `'$auth.member_id'` 토큰 사용 시 서버가 인증된 AppMember ID 로 치환한다.
+
 ### Realtime
 
 ```typescript

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "connectbase-client",
-  "version": "3.17.0",
+  "version": "3.17.1",
   "description": "Connect Base JavaScript/TypeScript SDK for browser and Node.js",
   "repository": {
     "type": "git",