connectbase-client 3.18.0 → 3.19.0

package/dist/index.d.mts

@@ -6952,24 +6952,33 @@ interface CreateDocumentRequest {
      * 비어있으면 서버가 매직 바이트로 자동 추정 — 정확도를 위해 명시 권장.
      */
     mime_type?: string;
+    /**
+     * 클라이언트가 지정하는 멱등(upsert) 키. 같은 지식 베이스 안에서 유일하다.
+     * 같은 `external_id` 로 다시 `addDocument` 하면 새 문서를 만들지 않고 기존 문서를
+     * 교체(update)한다 — `listDocuments` 로 기존 문서를 찾아 지울 필요 없이
+     * idempotent 한 동기화가 가능하다. 문서 id 도 그대로 유지된다.
+     */
+    external_id?: string;
     metadata?: Record<string, unknown>;
 }
 /**
- * 문서 수정 요청.
+ * 문서 update/upsert 요청. 보낸 필드만 교체된다 (생략한 필드는 변경 없음).
  *
  * `content` / `file_content` / `metadata` 중 하나라도 보내면 서버가 전체 재색인을 수행한다
  * (기존 청크 삭제 → 재청킹 → 재색인). RAG 특성상 콘텐츠가 바뀌면 청크 경계가 바뀌어
  * 부분 수정이 불가능하며, 재색인 시 색인 토큰이 다시 과금된다.
- * `name` 만 보내면 재색인 없이 라벨만 변경된다. 모든 필드는 옵셔널.
+ * `name` / `external_id` 만 보내면 재색인 없이 라벨·멱등 키만 변경된다.
+ * 문서 id 는 항상 유지되므로 검색 결과의 `document_id` 참조가 깨지지 않는다.
  */
 interface UpdateDocumentRequest {
     name?: string;
     content?: string;
-    /** base64 인코딩 바이너리 파일 재업로드 (PDF/DOCX/text). source_type 무관하게 추출. */
+    /** base64 인코딩 파일 (파일 재업로드, PDF/DOCX/text). content 보다 우선하며 source_type 무관하게 추출. */
     file_content?: string;
     /** file_content 의 MIME. 비어있으면 서버 자동 추정. */
     mime_type?: string;
     metadata?: Record<string, unknown>;
+    external_id?: string;
 }
 interface DocumentResponse {
     id: string;
@@ -6977,6 +6986,7 @@ interface DocumentResponse {
     source_type: string;
     mime_type?: string;
     source_url?: string;
+    external_id?: string;
     file_size: number;
     chunk_count: number;
     status: 'pending' | 'processing' | 'ready' | 'failed';
@@ -7035,6 +7045,14 @@ interface KnowledgeSearchResponse {
     query: string;
     results: KnowledgeSearchResult[];
     total: number;
+    /**
+     * 이 응답이 agentic 다중검색으로 생성됐는지 여부. `agentic: true` 를 보냈더라도
+     * AI provider 미설정·LLM 오류로 단일 키워드 검색에 폴백되면 `false` — 옵션이
+     * placebo 가 되지 않도록 실제 수행 여부를 신호한다.
+     */
+    agentic?: boolean;
+    /** 수행된 agentic 검색 라운드 수 (1~2). 0 또는 미존재는 폴백을 의미. */
+    agentic_rounds?: number;
 }
 
 /**
@@ -7113,9 +7131,60 @@ declare class KnowledgeAPI {
      *     source_type: 'url',
      *     source_url: 'https://example.com/help.html'
      * })
+     *
+     * // external_id 로 idempotent 동기화 (빌드 스크립트 등)
+     * // 같은 external_id 로 다시 호출하면 기존 문서를 교체한다 (문서 id 유지).
+     * await cb.knowledge.addDocument('kb-id', {
+     *     name: '블로그: 제목',
+     *     source_type: 'text',
+     *     content: '...',
+     *     external_id: 'blog/my-post-slug',
+     * })
      * ```
      */
     addDocument(kbID: string, data: CreateDocumentRequest): Promise<DocumentResponse>;
+    /**
+     * 문서 수정 (update/upsert)
+     *
+     * 기존 문서의 내용·이름·메타데이터를 교체합니다. **문서 id 는 그대로 유지**되므로
+     * 검색 결과의 `document_id` 를 외부에서 참조(인용·캐시)해도 편집 후 깨지지 않습니다.
+     * 보낸 필드만 교체되며, 내용/이름/메타데이터가 실제로 바뀌면 자동으로 재청킹·재색인됩니다.
+     *
+     * @param kbID - 지식 베이스 ID
+     * @param docID - 문서 ID
+     * @param data - 변경할 필드 (생략한 필드는 변경 없음)
+     * @returns 수정된 문서 정보
+     *
+     * @example
+     * ```typescript
+     * // 내용만 교체 — document_id 는 그대로
+     * const doc = await cb.knowledge.updateDocument('kb-id', 'doc-id', {
+     *     content: '갱신된 환불 정책...',
+     * })
+     *
+     * // 이름 + 메타데이터 교체
+     * await cb.knowledge.updateDocument('kb-id', 'doc-id', {
+     *     name: 'FAQ (2026)',
+     *     metadata: { tag: 'faq', updated: '2026-05' },
+     * })
+     * ```
+     */
+    updateDocument(kbID: string, docID: string, data: UpdateDocumentRequest): Promise<DocumentResponse>;
+    /**
+     * 파일로 문서 수정 (PDF / DOCX / text 파일 재업로드).
+     *
+     * [`addDocumentFromFile`](#addDocumentFromFile) 의 update 버전. 문서 id 는 유지됩니다.
+     *
+     * @param kbID - Knowledge Base ID
+     * @param docID - 문서 ID
+     * @param file - 새 파일. `File` (DOM) / `Blob` / `{ data, mimeType, name }` (Node) 모두 가능
+     * @param options - name / metadata 오버라이드
+     * @returns 수정된 문서 정보
+     */
+    updateDocumentFromFile(kbID: string, docID: string, file: KnowledgeFileInput, options?: {
+        name?: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<DocumentResponse>;
     /**
      * 파일을 KB 에 추가 (PDF / DOCX / text 파일).
      *
@@ -7160,31 +7229,6 @@ declare class KnowledgeAPI {
         name?: string;
         metadata?: Record<string, unknown>;
     }): Promise<DocumentResponse>;
-    /**
-     * 문서 수정 (재색인)
-     *
-     * `content` / `file_content` / `metadata` 중 하나라도 포함하면 전체 재색인이 일어나며
-     * 색인 토큰이 다시 과금됩니다. `name` 만 보내면 재색인 없이 라벨만 변경됩니다.
-     * 재색인 시 서버는 status='pending' 으로 즉시 응답하고 색인은 백그라운드로 진행됩니다
-     * (addDocument 와 동일) — get/listDocuments 로 'ready' 전환을 확인하세요.
-     *
-     * @param kbID - 지식 베이스 ID
-     * @param docID - 문서 ID
-     * @param data - 수정 요청 (모든 필드 옵셔널)
-     * @returns 수정된 문서 정보
-     *
-     * @example
-     * ```typescript
-     * // 내용 갱신 (전체 재색인 발생)
-     * await cb.knowledge.updateDocument('kb-id', 'doc-id', {
-     *     content: '환불은 구매 후 14일 이내에 가능합니다...'
-     * })
-     *
-     * // 이름만 변경 (재색인 없음)
-     * await cb.knowledge.updateDocument('kb-id', 'doc-id', { name: '환불 정책 v2' })
-     * ```
-     */
-    updateDocument(kbID: string, docID: string, data: UpdateDocumentRequest): Promise<DocumentResponse>;
     /**
      * 문서 목록 조회
      *
@@ -7285,6 +7329,11 @@ interface AISource {
 }
 interface AIChatResponse {
     content: string;
+    /**
+     * 추론 모델(Qwen3 reasoning, OpenAI o-series, DeepSeek-R1 등)의 사고 과정.
+     * 최종 답변(`content`)과 분리되어 제공됩니다. 추론 모델이 아니면 비어 있습니다.
+     */
+    reasoning?: string;
     finishReason?: string;
     usage?: {
         promptTokens: number;
@@ -7299,6 +7348,11 @@ interface AIChatResponse {
 interface AIStreamChunk {
     type?: 'sources' | 'token' | 'searching' | 'tool_start' | 'tool_end' | 'heartbeat';
     content: string;
+    /**
+     * 추론 모델의 사고 과정 델타. 추론 구간의 청크는 `content`가 비어 있고
+     * `reasoning`만 채워져 전달됩니다.
+     */
+    reasoning?: string;
     finishReason?: string;
     done: boolean;
     toolCalls?: AIToolCall[];
@@ -7352,6 +7406,7 @@ declare class AIAPI {
      *     knowledgeBaseId: 'kb-id',
      * }, {
      *     onSources: (sources) => console.log('참조:', sources),
+     *     onReasoning: (reasoning) => process.stdout.write(reasoning),
      *     onToken: (content) => process.stdout.write(content),
      *     onDone: () => console.log('\\n완료'),
      *     onError: (error) => console.error('에러:', error)
@@ -7360,6 +7415,11 @@ declare class AIAPI {
      */
     chatStream(request: AIChatRequest, callbacks: {
         onSources?: (sources: AISource[]) => void;
+        /**
+         * 추론 모델의 사고 과정 델타. 추론 모델(Qwen3 reasoning, o-series 등)을
+         * 사용할 때만 호출되며, 최종 답변은 `onToken`으로 별도 전달됩니다.
+         */
+        onReasoning?: (reasoning: string) => void;
         onToken?: (content: string) => void;
         onToolEvent?: (event: AIToolEvent) => void;
         onDone?: () => void;

package/dist/index.d.ts

@@ -6952,24 +6952,33 @@ interface CreateDocumentRequest {
      * 비어있으면 서버가 매직 바이트로 자동 추정 — 정확도를 위해 명시 권장.
      */
     mime_type?: string;
+    /**
+     * 클라이언트가 지정하는 멱등(upsert) 키. 같은 지식 베이스 안에서 유일하다.
+     * 같은 `external_id` 로 다시 `addDocument` 하면 새 문서를 만들지 않고 기존 문서를
+     * 교체(update)한다 — `listDocuments` 로 기존 문서를 찾아 지울 필요 없이
+     * idempotent 한 동기화가 가능하다. 문서 id 도 그대로 유지된다.
+     */
+    external_id?: string;
     metadata?: Record<string, unknown>;
 }
 /**
- * 문서 수정 요청.
+ * 문서 update/upsert 요청. 보낸 필드만 교체된다 (생략한 필드는 변경 없음).
  *
  * `content` / `file_content` / `metadata` 중 하나라도 보내면 서버가 전체 재색인을 수행한다
  * (기존 청크 삭제 → 재청킹 → 재색인). RAG 특성상 콘텐츠가 바뀌면 청크 경계가 바뀌어
  * 부분 수정이 불가능하며, 재색인 시 색인 토큰이 다시 과금된다.
- * `name` 만 보내면 재색인 없이 라벨만 변경된다. 모든 필드는 옵셔널.
+ * `name` / `external_id` 만 보내면 재색인 없이 라벨·멱등 키만 변경된다.
+ * 문서 id 는 항상 유지되므로 검색 결과의 `document_id` 참조가 깨지지 않는다.
  */
 interface UpdateDocumentRequest {
     name?: string;
     content?: string;
-    /** base64 인코딩 바이너리 파일 재업로드 (PDF/DOCX/text). source_type 무관하게 추출. */
+    /** base64 인코딩 파일 (파일 재업로드, PDF/DOCX/text). content 보다 우선하며 source_type 무관하게 추출. */
     file_content?: string;
     /** file_content 의 MIME. 비어있으면 서버 자동 추정. */
     mime_type?: string;
     metadata?: Record<string, unknown>;
+    external_id?: string;
 }
 interface DocumentResponse {
     id: string;
@@ -6977,6 +6986,7 @@ interface DocumentResponse {
     source_type: string;
     mime_type?: string;
     source_url?: string;
+    external_id?: string;
     file_size: number;
     chunk_count: number;
     status: 'pending' | 'processing' | 'ready' | 'failed';
@@ -7035,6 +7045,14 @@ interface KnowledgeSearchResponse {
     query: string;
     results: KnowledgeSearchResult[];
     total: number;
+    /**
+     * 이 응답이 agentic 다중검색으로 생성됐는지 여부. `agentic: true` 를 보냈더라도
+     * AI provider 미설정·LLM 오류로 단일 키워드 검색에 폴백되면 `false` — 옵션이
+     * placebo 가 되지 않도록 실제 수행 여부를 신호한다.
+     */
+    agentic?: boolean;
+    /** 수행된 agentic 검색 라운드 수 (1~2). 0 또는 미존재는 폴백을 의미. */
+    agentic_rounds?: number;
 }
 
 /**
@@ -7113,9 +7131,60 @@ declare class KnowledgeAPI {
      *     source_type: 'url',
      *     source_url: 'https://example.com/help.html'
      * })
+     *
+     * // external_id 로 idempotent 동기화 (빌드 스크립트 등)
+     * // 같은 external_id 로 다시 호출하면 기존 문서를 교체한다 (문서 id 유지).
+     * await cb.knowledge.addDocument('kb-id', {
+     *     name: '블로그: 제목',
+     *     source_type: 'text',
+     *     content: '...',
+     *     external_id: 'blog/my-post-slug',
+     * })
      * ```
      */
     addDocument(kbID: string, data: CreateDocumentRequest): Promise<DocumentResponse>;
+    /**
+     * 문서 수정 (update/upsert)
+     *
+     * 기존 문서의 내용·이름·메타데이터를 교체합니다. **문서 id 는 그대로 유지**되므로
+     * 검색 결과의 `document_id` 를 외부에서 참조(인용·캐시)해도 편집 후 깨지지 않습니다.
+     * 보낸 필드만 교체되며, 내용/이름/메타데이터가 실제로 바뀌면 자동으로 재청킹·재색인됩니다.
+     *
+     * @param kbID - 지식 베이스 ID
+     * @param docID - 문서 ID
+     * @param data - 변경할 필드 (생략한 필드는 변경 없음)
+     * @returns 수정된 문서 정보
+     *
+     * @example
+     * ```typescript
+     * // 내용만 교체 — document_id 는 그대로
+     * const doc = await cb.knowledge.updateDocument('kb-id', 'doc-id', {
+     *     content: '갱신된 환불 정책...',
+     * })
+     *
+     * // 이름 + 메타데이터 교체
+     * await cb.knowledge.updateDocument('kb-id', 'doc-id', {
+     *     name: 'FAQ (2026)',
+     *     metadata: { tag: 'faq', updated: '2026-05' },
+     * })
+     * ```
+     */
+    updateDocument(kbID: string, docID: string, data: UpdateDocumentRequest): Promise<DocumentResponse>;
+    /**
+     * 파일로 문서 수정 (PDF / DOCX / text 파일 재업로드).
+     *
+     * [`addDocumentFromFile`](#addDocumentFromFile) 의 update 버전. 문서 id 는 유지됩니다.
+     *
+     * @param kbID - Knowledge Base ID
+     * @param docID - 문서 ID
+     * @param file - 새 파일. `File` (DOM) / `Blob` / `{ data, mimeType, name }` (Node) 모두 가능
+     * @param options - name / metadata 오버라이드
+     * @returns 수정된 문서 정보
+     */
+    updateDocumentFromFile(kbID: string, docID: string, file: KnowledgeFileInput, options?: {
+        name?: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<DocumentResponse>;
     /**
      * 파일을 KB 에 추가 (PDF / DOCX / text 파일).
      *
@@ -7160,31 +7229,6 @@ declare class KnowledgeAPI {
         name?: string;
         metadata?: Record<string, unknown>;
     }): Promise<DocumentResponse>;
-    /**
-     * 문서 수정 (재색인)
-     *
-     * `content` / `file_content` / `metadata` 중 하나라도 포함하면 전체 재색인이 일어나며
-     * 색인 토큰이 다시 과금됩니다. `name` 만 보내면 재색인 없이 라벨만 변경됩니다.
-     * 재색인 시 서버는 status='pending' 으로 즉시 응답하고 색인은 백그라운드로 진행됩니다
-     * (addDocument 와 동일) — get/listDocuments 로 'ready' 전환을 확인하세요.
-     *
-     * @param kbID - 지식 베이스 ID
-     * @param docID - 문서 ID
-     * @param data - 수정 요청 (모든 필드 옵셔널)
-     * @returns 수정된 문서 정보
-     *
-     * @example
-     * ```typescript
-     * // 내용 갱신 (전체 재색인 발생)
-     * await cb.knowledge.updateDocument('kb-id', 'doc-id', {
-     *     content: '환불은 구매 후 14일 이내에 가능합니다...'
-     * })
-     *
-     * // 이름만 변경 (재색인 없음)
-     * await cb.knowledge.updateDocument('kb-id', 'doc-id', { name: '환불 정책 v2' })
-     * ```
-     */
-    updateDocument(kbID: string, docID: string, data: UpdateDocumentRequest): Promise<DocumentResponse>;
     /**
      * 문서 목록 조회
      *
@@ -7285,6 +7329,11 @@ interface AISource {
 }
 interface AIChatResponse {
     content: string;
+    /**
+     * 추론 모델(Qwen3 reasoning, OpenAI o-series, DeepSeek-R1 등)의 사고 과정.
+     * 최종 답변(`content`)과 분리되어 제공됩니다. 추론 모델이 아니면 비어 있습니다.
+     */
+    reasoning?: string;
     finishReason?: string;
     usage?: {
         promptTokens: number;
@@ -7299,6 +7348,11 @@ interface AIChatResponse {
 interface AIStreamChunk {
     type?: 'sources' | 'token' | 'searching' | 'tool_start' | 'tool_end' | 'heartbeat';
     content: string;
+    /**
+     * 추론 모델의 사고 과정 델타. 추론 구간의 청크는 `content`가 비어 있고
+     * `reasoning`만 채워져 전달됩니다.
+     */
+    reasoning?: string;
     finishReason?: string;
     done: boolean;
     toolCalls?: AIToolCall[];
@@ -7352,6 +7406,7 @@ declare class AIAPI {
      *     knowledgeBaseId: 'kb-id',
      * }, {
      *     onSources: (sources) => console.log('참조:', sources),
+     *     onReasoning: (reasoning) => process.stdout.write(reasoning),
      *     onToken: (content) => process.stdout.write(content),
      *     onDone: () => console.log('\\n완료'),
      *     onError: (error) => console.error('에러:', error)
@@ -7360,6 +7415,11 @@ declare class AIAPI {
      */
     chatStream(request: AIChatRequest, callbacks: {
         onSources?: (sources: AISource[]) => void;
+        /**
+         * 추론 모델의 사고 과정 델타. 추론 모델(Qwen3 reasoning, o-series 등)을
+         * 사용할 때만 호출되며, 최종 답변은 `onToken`으로 별도 전달됩니다.
+         */
+        onReasoning?: (reasoning: string) => void;
         onToken?: (content: string) => void;
         onToolEvent?: (event: AIToolEvent) => void;
         onDone?: () => void;

package/dist/index.js

@@ -8050,6 +8050,15 @@ var KnowledgeAPI = class {
    *     source_type: 'url',
    *     source_url: 'https://example.com/help.html'
    * })
+   *
+   * // external_id 로 idempotent 동기화 (빌드 스크립트 등)
+   * // 같은 external_id 로 다시 호출하면 기존 문서를 교체한다 (문서 id 유지).
+   * await cb.knowledge.addDocument('kb-id', {
+   *     name: '블로그: 제목',
+   *     source_type: 'text',
+   *     content: '...',
+   *     external_id: 'blog/my-post-slug',
+   * })
    * ```
    */
   async addDocument(kbID, data) {
@@ -8058,6 +8067,58 @@ var KnowledgeAPI = class {
       data
     );
   }
+  /**
+   * 문서 수정 (update/upsert)
+   *
+   * 기존 문서의 내용·이름·메타데이터를 교체합니다. **문서 id 는 그대로 유지**되므로
+   * 검색 결과의 `document_id` 를 외부에서 참조(인용·캐시)해도 편집 후 깨지지 않습니다.
+   * 보낸 필드만 교체되며, 내용/이름/메타데이터가 실제로 바뀌면 자동으로 재청킹·재색인됩니다.
+   *
+   * @param kbID - 지식 베이스 ID
+   * @param docID - 문서 ID
+   * @param data - 변경할 필드 (생략한 필드는 변경 없음)
+   * @returns 수정된 문서 정보
+   *
+   * @example
+   * ```typescript
+   * // 내용만 교체 — document_id 는 그대로
+   * const doc = await cb.knowledge.updateDocument('kb-id', 'doc-id', {
+   *     content: '갱신된 환불 정책...',
+   * })
+   *
+   * // 이름 + 메타데이터 교체
+   * await cb.knowledge.updateDocument('kb-id', 'doc-id', {
+   *     name: 'FAQ (2026)',
+   *     metadata: { tag: 'faq', updated: '2026-05' },
+   * })
+   * ```
+   */
+  async updateDocument(kbID, docID, data) {
+    return this.http.put(
+      `/v1/public/knowledge-bases/${kbID}/documents/${docID}`,
+      data
+    );
+  }
+  /**
+   * 파일로 문서 수정 (PDF / DOCX / text 파일 재업로드).
+   *
+   * [`addDocumentFromFile`](#addDocumentFromFile) 의 update 버전. 문서 id 는 유지됩니다.
+   *
+   * @param kbID - Knowledge Base ID
+   * @param docID - 문서 ID
+   * @param file - 새 파일. `File` (DOM) / `Blob` / `{ data, mimeType, name }` (Node) 모두 가능
+   * @param options - name / metadata 오버라이드
+   * @returns 수정된 문서 정보
+   */
+  async updateDocumentFromFile(kbID, docID, file, options) {
+    const { data, mimeType } = await readFileInput(file);
+    return this.updateDocument(kbID, docID, {
+      name: options?.name,
+      file_content: data,
+      mime_type: mimeType,
+      metadata: options?.metadata
+    });
+  }
   /**
    * 파일을 KB 에 추가 (PDF / DOCX / text 파일).
    *
@@ -8109,36 +8170,6 @@ var KnowledgeAPI = class {
       metadata: options?.metadata
     });
   }
-  /**
-   * 문서 수정 (재색인)
-   *
-   * `content` / `file_content` / `metadata` 중 하나라도 포함하면 전체 재색인이 일어나며
-   * 색인 토큰이 다시 과금됩니다. `name` 만 보내면 재색인 없이 라벨만 변경됩니다.
-   * 재색인 시 서버는 status='pending' 으로 즉시 응답하고 색인은 백그라운드로 진행됩니다
-   * (addDocument 와 동일) — get/listDocuments 로 'ready' 전환을 확인하세요.
-   *
-   * @param kbID - 지식 베이스 ID
-   * @param docID - 문서 ID
-   * @param data - 수정 요청 (모든 필드 옵셔널)
-   * @returns 수정된 문서 정보
-   *
-   * @example
-   * ```typescript
-   * // 내용 갱신 (전체 재색인 발생)
-   * await cb.knowledge.updateDocument('kb-id', 'doc-id', {
-   *     content: '환불은 구매 후 14일 이내에 가능합니다...'
-   * })
-   *
-   * // 이름만 변경 (재색인 없음)
-   * await cb.knowledge.updateDocument('kb-id', 'doc-id', { name: '환불 정책 v2' })
-   * ```
-   */
-  async updateDocument(kbID, docID, data) {
-    return this.http.put(
-      `/v1/public/knowledge-bases/${kbID}/documents/${docID}`,
-      data
-    );
-  }
   /**
    * 문서 목록 조회
    *
@@ -8232,6 +8263,7 @@ var AIAPI = class {
    *     knowledgeBaseId: 'kb-id',
    * }, {
    *     onSources: (sources) => console.log('참조:', sources),
+   *     onReasoning: (reasoning) => process.stdout.write(reasoning),
    *     onToken: (content) => process.stdout.write(content),
    *     onDone: () => console.log('\\n완료'),
    *     onError: (error) => console.error('에러:', error)
@@ -8293,6 +8325,7 @@ var AIAPI = class {
           if (event.type === "heartbeat" || event.type === "searching") {
             continue;
           }
+          if (event.reasoning) callbacks.onReasoning?.(event.reasoning);
           if (event.content) callbacks.onToken?.(event.content);
           if (event.done) {
             callbacks.onDone?.();

package/dist/index.mjs

@@ -8007,6 +8007,15 @@ var KnowledgeAPI = class {
    *     source_type: 'url',
    *     source_url: 'https://example.com/help.html'
    * })
+   *
+   * // external_id 로 idempotent 동기화 (빌드 스크립트 등)
+   * // 같은 external_id 로 다시 호출하면 기존 문서를 교체한다 (문서 id 유지).
+   * await cb.knowledge.addDocument('kb-id', {
+   *     name: '블로그: 제목',
+   *     source_type: 'text',
+   *     content: '...',
+   *     external_id: 'blog/my-post-slug',
+   * })
    * ```
    */
   async addDocument(kbID, data) {
@@ -8015,6 +8024,58 @@ var KnowledgeAPI = class {
       data
     );
   }
+  /**
+   * 문서 수정 (update/upsert)
+   *
+   * 기존 문서의 내용·이름·메타데이터를 교체합니다. **문서 id 는 그대로 유지**되므로
+   * 검색 결과의 `document_id` 를 외부에서 참조(인용·캐시)해도 편집 후 깨지지 않습니다.
+   * 보낸 필드만 교체되며, 내용/이름/메타데이터가 실제로 바뀌면 자동으로 재청킹·재색인됩니다.
+   *
+   * @param kbID - 지식 베이스 ID
+   * @param docID - 문서 ID
+   * @param data - 변경할 필드 (생략한 필드는 변경 없음)
+   * @returns 수정된 문서 정보
+   *
+   * @example
+   * ```typescript
+   * // 내용만 교체 — document_id 는 그대로
+   * const doc = await cb.knowledge.updateDocument('kb-id', 'doc-id', {
+   *     content: '갱신된 환불 정책...',
+   * })
+   *
+   * // 이름 + 메타데이터 교체
+   * await cb.knowledge.updateDocument('kb-id', 'doc-id', {
+   *     name: 'FAQ (2026)',
+   *     metadata: { tag: 'faq', updated: '2026-05' },
+   * })
+   * ```
+   */
+  async updateDocument(kbID, docID, data) {
+    return this.http.put(
+      `/v1/public/knowledge-bases/${kbID}/documents/${docID}`,
+      data
+    );
+  }
+  /**
+   * 파일로 문서 수정 (PDF / DOCX / text 파일 재업로드).
+   *
+   * [`addDocumentFromFile`](#addDocumentFromFile) 의 update 버전. 문서 id 는 유지됩니다.
+   *
+   * @param kbID - Knowledge Base ID
+   * @param docID - 문서 ID
+   * @param file - 새 파일. `File` (DOM) / `Blob` / `{ data, mimeType, name }` (Node) 모두 가능
+   * @param options - name / metadata 오버라이드
+   * @returns 수정된 문서 정보
+   */
+  async updateDocumentFromFile(kbID, docID, file, options) {
+    const { data, mimeType } = await readFileInput(file);
+    return this.updateDocument(kbID, docID, {
+      name: options?.name,
+      file_content: data,
+      mime_type: mimeType,
+      metadata: options?.metadata
+    });
+  }
   /**
    * 파일을 KB 에 추가 (PDF / DOCX / text 파일).
    *
@@ -8066,36 +8127,6 @@ var KnowledgeAPI = class {
       metadata: options?.metadata
     });
   }
-  /**
-   * 문서 수정 (재색인)
-   *
-   * `content` / `file_content` / `metadata` 중 하나라도 포함하면 전체 재색인이 일어나며
-   * 색인 토큰이 다시 과금됩니다. `name` 만 보내면 재색인 없이 라벨만 변경됩니다.
-   * 재색인 시 서버는 status='pending' 으로 즉시 응답하고 색인은 백그라운드로 진행됩니다
-   * (addDocument 와 동일) — get/listDocuments 로 'ready' 전환을 확인하세요.
-   *
-   * @param kbID - 지식 베이스 ID
-   * @param docID - 문서 ID
-   * @param data - 수정 요청 (모든 필드 옵셔널)
-   * @returns 수정된 문서 정보
-   *
-   * @example
-   * ```typescript
-   * // 내용 갱신 (전체 재색인 발생)
-   * await cb.knowledge.updateDocument('kb-id', 'doc-id', {
-   *     content: '환불은 구매 후 14일 이내에 가능합니다...'
-   * })
-   *
-   * // 이름만 변경 (재색인 없음)
-   * await cb.knowledge.updateDocument('kb-id', 'doc-id', { name: '환불 정책 v2' })
-   * ```
-   */
-  async updateDocument(kbID, docID, data) {
-    return this.http.put(
-      `/v1/public/knowledge-bases/${kbID}/documents/${docID}`,
-      data
-    );
-  }
   /**
    * 문서 목록 조회
    *
@@ -8189,6 +8220,7 @@ var AIAPI = class {
    *     knowledgeBaseId: 'kb-id',
    * }, {
    *     onSources: (sources) => console.log('참조:', sources),
+   *     onReasoning: (reasoning) => process.stdout.write(reasoning),
    *     onToken: (content) => process.stdout.write(content),
    *     onDone: () => console.log('\\n완료'),
    *     onError: (error) => console.error('에러:', error)
@@ -8250,6 +8282,7 @@ var AIAPI = class {
           if (event.type === "heartbeat" || event.type === "searching") {
             continue;
           }
+          if (event.reasoning) callbacks.onReasoning?.(event.reasoning);
           if (event.content) callbacks.onToken?.(event.content);
           if (event.done) {
             callbacks.onDone?.();

package/package.json

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