connectbase-client 3.39.2 → 3.42.0

package/CHANGELOG.md

@@ -3,6 +3,47 @@
 본 SDK 의 모든 주요 변경사항을 [Keep a Changelog](https://keepachangelog.com/ko/1.1.0/) 형식으로 기록합니다.
 버전은 [Semantic Versioning](https://semver.org/lang/ko/) 을 따릅니다.
 
+## [3.42.0] - 2026-07-02
+
+### Added — 웹 배포 대용량 바이너리 Object Storage 직접 업로드 (플랫폼 이슈 019f221b)
+
+3.41.0 의 fail-fast 를 이어, 한도를 넘는 **바이너리**를 배포할 수 있게 했다. 파일당 6 MiB(TiDB
+단일 엔트리 한도)를 넘는 바이너리(3D 모델·큰 동영상/폰트 등)를 배포하지 못하던 문제 해결.
+
+- **대용량 바이너리 직접 업로드**: 한도를 넘는 바이너리는 presigned URL 로 **Object Storage 의 서빙
+  경로에 직접** 업로드하고, 배포 요청에는 `pre_uploaded` 메타데이터만 전송한다. web-proxy 가 서빙하는
+  바로 그 경로에 안착하므로 동일 origin·참조 재작성/CORS 불필요. (대응 core-server 필요. 미지원 서버면
+  3.41.0 과 동일하게 fail-fast.)
+- **fail-fast 유지**: 오프로드 불가한 파일(대용량 **텍스트**, 또는 서버 미지원)은 업로드 전에 즉시 중단.
+- **3D 에셋 확장자 추가**: `.glb`/`.bin`(바이너리), `.gltf`(JSON)을 허용 확장자에 추가 +
+  정확한 MIME(`model/gltf-binary` 등). 이제 3D 모델을 확장자 위장 없이 번들에 그대로 둘 수 있다.
+
+## [3.41.0] - 2026-07-02
+
+### Added — 웹 배포 파일당 크기 한도 사전 검증 (fail-fast)
+
+`connectbase deploy` 가 파일을 수집한 직후, 서버로 업로드하기 **전에** 각 파일이 웹 스토리지
+파일당 크기 한도를 넘는지 검사한다(플랫폼 이슈 019f221b). 기존에는 전량 수집·업로드를 마친
+뒤에야 서버에서 원시 DB 오류(`Error 8025 (HY000): entry too large`)로 실패해 원인 파악이 어려웠다.
+
+- 초과 파일이 있으면 어떤 파일이 얼마나 큰지(바이너리는 원본→base64 크기까지) 나열하고 즉시 종료한다.
+- 검사 기준: 파일 내용은 DB(TiDB Text 컬럼)에 저장되며 단일 엔트리 한도 6 MiB 를 넘을 수 없다.
+  바이너리는 base64(약 1.33x)로 저장되므로 원본 기준 실질 상한 약 4.5 MB. 텍스트는 UTF-8 바이트로 정확히 계산.
+
+## [3.40.0] - 2026-06-28
+
+### Added — KB 하이브리드(시맨틱) 검색 지원
+
+지식베이스 검색에 BM25 키워드 + 벡터 의미 검색을 RRF(Reciprocal Rank Fusion)로 융합하는
+하이브리드 검색을 추가했다. 콘솔 > **AI** 에서 임베딩을 켠 앱(gemini / openai BYOK)에서
+동작하며, 오타·동의어·의역에 강하다.
+
+- **\`KnowledgeSearchRequest.hybrid?: boolean\`** — \`cb.knowledge.search()\` 에 hybrid 옵션 추가.
+  미설정(기본)이면 임베딩을 켠 앱에서 자동 적용, \`false\` 면 키워드 전용 검색을 강제.
+- **\`AIChatRequest.hybrid?: boolean\`** — \`cb.ai.chat()\` / \`cb.ai.chatStream()\` 의 RAG 검색에도
+  동일 옵션 적용. 미설정이면 임베딩을 켠 앱에서 자동 적용된다.
+- 임베딩 미설정 앱에서는 무시되며 기존 BM25 검색으로 동작한다(하위호환, 회귀 없음).
+
 ## [3.39.2] - 2026-06-26
 
 ### Performance — 터널 프록시 응답 지연 제거 (TCP_NODELAY / keep-alive)

package/dist/cli.js

@@ -32,6 +32,9 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var cli_exports = {};
 __export(cli_exports, {
   computeDeployDiff: () => computeDeployDiff,
+  guessMimeType: () => guessMimeType,
+  isAllowedDeployExt: () => isAllowedDeployExt,
+  isBinaryDeployExt: () => isBinaryDeployExt,
   makeRequest: () => makeRequest,
   normalizeRelativePath: () => normalizeRelativePath,
   parseArgs: () => parseArgs,
@@ -191,7 +194,11 @@ var ALLOWED_EXTENSIONS = /* @__PURE__ */ new Set([
   ".xml",
   ".webmanifest",
   ".map",
-  ".wasm"
+  ".wasm",
+  // 3D 에셋: .glb/.bin 은 바이너리, .gltf 는 JSON(텍스트)
+  ".glb",
+  ".gltf",
+  ".bin"
 ]);
 var BINARY_EXTENSIONS = /* @__PURE__ */ new Set([
   ".png",
@@ -213,8 +220,46 @@ var BINARY_EXTENSIONS = /* @__PURE__ */ new Set([
   ".webm",
   ".pdf",
   ".zip",
-  ".wasm"
+  ".wasm",
+  ".glb",
+  ".bin"
 ]);
+var MIME_BY_EXT = {
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".webp": "image/webp",
+  ".avif": "image/avif",
+  ".ico": "image/x-icon",
+  ".svg": "image/svg+xml",
+  ".woff": "font/woff",
+  ".woff2": "font/woff2",
+  ".ttf": "font/ttf",
+  ".otf": "font/otf",
+  ".eot": "application/vnd.ms-fontobject",
+  ".mp3": "audio/mpeg",
+  ".wav": "audio/wav",
+  ".ogg": "audio/ogg",
+  ".mp4": "video/mp4",
+  ".webm": "video/webm",
+  ".pdf": "application/pdf",
+  ".zip": "application/zip",
+  ".wasm": "application/wasm",
+  ".glb": "model/gltf-binary",
+  ".gltf": "model/gltf+json",
+  ".bin": "application/octet-stream"
+};
+function guessMimeType(filePath) {
+  return MIME_BY_EXT[path2.extname(filePath).toLowerCase()] || "application/octet-stream";
+}
+function isAllowedDeployExt(filePath) {
+  return ALLOWED_EXTENSIONS.has(path2.extname(filePath).toLowerCase());
+}
+function isBinaryDeployExt(filePath) {
+  return BINARY_EXTENSIONS.has(path2.extname(filePath).toLowerCase());
+}
+var WEB_FILE_MAX_STORED_BYTES = 6 * 1024 * 1024 - 64 * 1024;
 function sha256Hex(value) {
   return crypto.createHash("sha256").update(value, "utf8").digest("hex");
 }
@@ -281,6 +326,146 @@ function collectFiles(dir, baseDir = dir) {
   }
   return files;
 }
+function formatSize(bytes) {
+  if (bytes >= 1024 * 1024) return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
+  return `${(bytes / 1024).toFixed(1)} KB`;
+}
+function validateFileSizes(files) {
+  const oversized = files.map((f) => {
+    const storedBytes = Buffer.byteLength(f.content, "utf8");
+    const originalBytes = f.isBinary ? Math.round(f.content.length * 3 / 4) : storedBytes;
+    return { path: f.path, isBinary: f.isBinary, storedBytes, originalBytes };
+  }).filter((f) => f.storedBytes > WEB_FILE_MAX_STORED_BYTES);
+  if (oversized.length === 0) return;
+  error(`\uC6F9 \uC2A4\uD1A0\uB9AC\uC9C0 \uD30C\uC77C\uB2F9 \uD06C\uAE30 \uD55C\uB3C4(\uC57D ${formatSize(WEB_FILE_MAX_STORED_BYTES)})\uB97C \uCD08\uACFC\uD55C \uD30C\uC77C\uC774 \uC788\uC5B4 \uBC30\uD3EC\uD560 \uC218 \uC5C6\uC2B5\uB2C8\uB2E4:`);
+  for (const f of oversized) {
+    const detail = f.isBinary ? `${formatSize(f.originalBytes)} \u2192 base64 ${formatSize(f.storedBytes)}` : formatSize(f.storedBytes);
+    error(`  \u2022 ${f.path} (${detail})`);
+  }
+  log("");
+  warn("\uC815\uC801 \uD638\uC2A4\uD305 \uD30C\uC77C\uC740 DB \uB2E8\uC77C \uC5D4\uD2B8\uB9AC(6 MiB)\uC5D0 \uC800\uC7A5\uB418\uBA70, \uBC14\uC774\uB108\uB9AC\uB294 base64(\uC57D 1.33x)\uB85C");
+  warn("\uBD80\uD480\uC5B4 \uC6D0\uBCF8 \uAE30\uC900 \uC57D 4.5 MB \uAC00 \uC2E4\uC9C8 \uC0C1\uD55C\uC785\uB2C8\uB2E4.");
+  warn(`\uB300\uC6A9\uB7C9 \uC5D0\uC14B(3D \uBAA8\uB378\xB7\uB3D9\uC601\uC0C1\xB7\uD070 \uD3F0\uD2B8 \uB4F1)\uC740 \uD30C\uC77C \uC2A4\uD1A0\uB9AC\uC9C0(${colors.cyan}cb.storage${colors.reset}, presigned URL)\uC5D0`);
+  warn("\uC62C\uB9AC\uACE0 URL \uB85C \uCC38\uC870\uD558\uC138\uC694. \uD30C\uC77C \uC2A4\uD1A0\uB9AC\uC9C0\uB294 \uD30C\uC77C\uB2F9 \uACE0\uC815 \uC0C1\uD55C\uC774 \uC5C6\uC2B5\uB2C8\uB2E4.");
+  process.exit(1);
+}
+async function requestDeployPresign(baseStorageUrl, headers, files, timeoutMs) {
+  const body = JSON.stringify({ files });
+  const res = await makeRequest(`${baseStorageUrl}/deploy/presign`, "POST", headers, body, { timeoutMs });
+  if (res.status === 404) return null;
+  if (res.status < 200 || res.status >= 300) {
+    const data = res.data;
+    const msg = typeof data === "object" && data !== null ? data.message || data.error || JSON.stringify(data) : `HTTP ${res.status}`;
+    throw new Error(`presign \uC694\uCCAD \uC2E4\uD328: ${msg}`);
+  }
+  const parsed = res.data;
+  return parsed?.urls ?? [];
+}
+function putToPresignedUrl(uploadUrl, body, contentType, timeoutMs) {
+  return new Promise((resolve2, reject) => {
+    let parsed;
+    try {
+      parsed = new URL(uploadUrl);
+    } catch {
+      reject(new Error("\uC798\uBABB\uB41C \uC5C5\uB85C\uB4DC URL"));
+      return;
+    }
+    if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
+      reject(new Error(`\uC9C0\uC6D0\uD558\uC9C0 \uC54A\uB294 \uC5C5\uB85C\uB4DC URL \uC2A4\uD0B4: ${parsed.protocol}`));
+      return;
+    }
+    const lib = parsed.protocol === "https:" ? https : http;
+    const options = {
+      hostname: parsed.hostname,
+      port: parsed.port || (parsed.protocol === "https:" ? 443 : 80),
+      path: parsed.pathname + parsed.search,
+      method: "PUT",
+      family: 4,
+      autoSelectFamily: false,
+      headers: {
+        "Content-Type": contentType || "application/octet-stream",
+        "Content-Length": body.length
+      }
+    };
+    const req = lib.request(options, (res) => {
+      const chunks = [];
+      res.on("data", (chunk) => chunks.push(chunk));
+      res.on("end", () => {
+        const status = res.statusCode || 0;
+        if (status >= 200 && status < 300) {
+          resolve2();
+          return;
+        }
+        reject(
+          new Error(
+            `Object Storage \uC5C5\uB85C\uB4DC \uC2E4\uD328 (HTTP ${status}): ${Buffer.concat(chunks).toString("utf8").slice(0, 200)}`
+          )
+        );
+      });
+    });
+    req.on("socket", (socket) => {
+      socket.setKeepAlive(true, 3e4);
+    });
+    req.setTimeout(timeoutMs, () => {
+      req.destroy(new Error(`\uC5C5\uB85C\uB4DC \uC2DC\uAC04 \uCD08\uACFC (${Math.round(timeoutMs / 1e3)}\uCD08)`));
+    });
+    req.on("error", reject);
+    req.end(body);
+  });
+}
+async function offloadLargeBinaries(baseStorageUrl, headers, diff, _envLabel, timeoutMs) {
+  const oversized = diff.upsert.filter((f) => Buffer.byteLength(f.content, "utf8") > WEB_FILE_MAX_STORED_BYTES);
+  if (oversized.length === 0) return;
+  const largeText = oversized.filter((f) => !f.is_binary);
+  const largeBinaries = oversized.filter((f) => f.is_binary);
+  if (largeText.length > 0) {
+    error(`\uC6F9 \uC2A4\uD1A0\uB9AC\uC9C0 \uD30C\uC77C\uB2F9 \uD06C\uAE30 \uD55C\uB3C4(\uC57D ${formatSize(WEB_FILE_MAX_STORED_BYTES)})\uB97C \uCD08\uACFC\uD55C \uD14D\uC2A4\uD2B8 \uD30C\uC77C\uC774 \uC788\uC5B4 \uBC30\uD3EC\uD560 \uC218 \uC5C6\uC2B5\uB2C8\uB2E4:`);
+    for (const f of largeText) error(`  \u2022 ${f.path} (${formatSize(Buffer.byteLength(f.content, "utf8"))})`);
+    log("");
+    warn("\uD070 JS/CSS \uB294 \uCF54\uB4DC \uC2A4\uD50C\uB9AC\uD305\uC73C\uB85C \uBD84\uD560\uD558\uC138\uC694. (\uBC14\uC774\uB108\uB9AC\uC640 \uB2EC\uB9AC \uD14D\uC2A4\uD2B8\uB294 \uC624\uBE0C\uC81D\uD2B8 \uC2A4\uD1A0\uB9AC\uC9C0\uB85C \uC624\uD504\uB85C\uB4DC\uD560 \uC218 \uC5C6\uC2B5\uB2C8\uB2E4.)");
+    process.exit(1);
+  }
+  if (largeBinaries.length === 0) return;
+  const presignFiles = largeBinaries.map((f) => ({
+    path: f.path,
+    size: Buffer.from(f.content, "base64").length,
+    mime_type: guessMimeType(f.path)
+  }));
+  let presigned;
+  try {
+    presigned = await requestDeployPresign(baseStorageUrl, headers, presignFiles, timeoutMs);
+  } catch (err) {
+    error(`\uB300\uC6A9\uB7C9 \uD30C\uC77C \uC5C5\uB85C\uB4DC \uC900\uBE44 \uC2E4\uD328: ${err instanceof Error ? err.message : err}`);
+    process.exit(1);
+  }
+  if (presigned === null) {
+    error(`\uC11C\uBC84\uAC00 \uB300\uC6A9\uB7C9 \uD30C\uC77C \uC9C1\uC811 \uC5C5\uB85C\uB4DC\uB97C \uC9C0\uC6D0\uD558\uC9C0 \uC54A\uC544 \uB2E4\uC74C \uD30C\uC77C\uC744 \uBC30\uD3EC\uD560 \uC218 \uC5C6\uC2B5\uB2C8\uB2E4(\uC57D ${formatSize(WEB_FILE_MAX_STORED_BYTES)} \uCD08\uACFC):`);
+    for (const f of largeBinaries) error(`  \u2022 ${f.path} (${formatSize(Buffer.from(f.content, "base64").length)})`);
+    log("");
+    warn(`\uB300\uC6A9\uB7C9 \uC5D0\uC14B\uC740 \uD30C\uC77C \uC2A4\uD1A0\uB9AC\uC9C0(${colors.cyan}cb.storage${colors.reset})\uC5D0 \uC62C\uB9AC\uACE0 URL \uB85C \uCC38\uC870\uD558\uAC70\uB098, \uC11C\uBC84 \uC5C5\uB370\uC774\uD2B8 \uD6C4 \uB2E4\uC2DC \uC2DC\uB3C4\uD558\uC138\uC694.`);
+    process.exit(1);
+  }
+  const urlByPath = new Map(presigned.map((p) => [p.path, p.upload_url]));
+  info(`\uB300\uC6A9\uB7C9 \uBC14\uC774\uB108\uB9AC ${largeBinaries.length}\uAC1C\uB97C Object Storage \uB85C \uC9C1\uC811 \uC5C5\uB85C\uB4DC\uD569\uB2C8\uB2E4...`);
+  for (const f of largeBinaries) {
+    const uploadUrl = urlByPath.get(f.path);
+    if (!uploadUrl) {
+      error(`presign \uC751\uB2F5\uC5D0 \uC5C5\uB85C\uB4DC URL \uC774 \uC5C6\uC2B5\uB2C8\uB2E4: ${f.path}`);
+      process.exit(1);
+    }
+    const bytes = Buffer.from(f.content, "base64");
+    try {
+      await putToPresignedUrl(uploadUrl, bytes, guessMimeType(f.path), timeoutMs);
+    } catch (err) {
+      error(`\uC5C5\uB85C\uB4DC \uC2E4\uD328 (${f.path}): ${err instanceof Error ? err.message : err}`);
+      process.exit(1);
+    }
+    success(`\uC9C1\uC811 \uC5C5\uB85C\uB4DC: ${f.path} (${formatSize(bytes.length)})`);
+    f.pre_uploaded = true;
+    f.size = bytes.length;
+    f.content = "";
+  }
+}
 var DEFAULT_REQUEST_TIMEOUT_MS = 6e4;
 async function makeRequest(url, method, headers, body, reqOpts = {}) {
   return new Promise((resolve2, reject) => {
@@ -387,12 +572,14 @@ async function deploy(directory, config, isDev = false, deployOpts = {}) {
   const timeoutMs = computeDeployTimeout(totalSize, deployOpts.timeoutMs);
   log(`${colors.dim}\uD0C0\uC784\uC544\uC6C3: ${Math.round(timeoutMs / 1e3)}\uCD08${colors.reset}`);
   if (isDev) {
+    validateFileSizes(files);
     await fullDeploy(baseStorageUrl, headers, files, envLabel, "deploy/dev", timeoutMs);
     return;
   }
   try {
     const manifest = await tryFetchManifest(baseStorageUrl, headers);
     if (!manifest) {
+      validateFileSizes(files);
       await fullDeploy(baseStorageUrl, headers, files, envLabel, "deploy", timeoutMs);
       return;
     }
@@ -404,6 +591,7 @@ ${colors.cyan}URL: https://${config.storageId}.web.connectbase.world${colors.res
 `);
       return;
     }
+    await offloadLargeBinaries(baseStorageUrl, headers, diff, envLabel, timeoutMs);
     info(`\uBCC0\uACBD: ${colors.green}+${diff.upsert.length}${colors.reset} / ${colors.red}-${diff.delete.length}${colors.reset} (\uC804\uCCB4 ${files.length}\uAC1C \uC911)`);
     const uploadSize = diff.upsert.reduce((s, f) => s + f.content.length, 0);
     info(`\uC5C5\uB85C\uB4DC \uD06C\uAE30: ${(uploadSize / 1024).toFixed(1)} KB`);
@@ -2628,6 +2816,9 @@ main().catch((err) => {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   computeDeployDiff,
+  guessMimeType,
+  isAllowedDeployExt,
+  isBinaryDeployExt,
   makeRequest,
   normalizeRelativePath,
   parseArgs,

package/dist/index.d.mts

@@ -2402,14 +2402,15 @@ declare class StorageAPI {
      * 파일 목록 조회
      *
      * @param storageId - 파일 스토리지 ID
-     * @param parentId - 부모 폴더 ID (미지정 시 루트 폴더)
+     * @param parentId - 부모 폴더 ID. 지정 시 해당 폴더의 **직계 자식만** 반환한다.
+     *   미지정 시 스토리지 **전체 파일 트리**를 flat 배열로 반환한다.
      *
      * @example
      * ```ts
-     * // 루트 폴더의 파일 목록
+     * // 스토리지 전체 파일 목록 (flat 트리)
      * const files = await cb.storage.getFiles('storage-id')
      *
-     * // 특정 폴더의 하위 파일 목록
+     * // 특정 폴더의 직계 자식만 (대용량 버킷에서 전체 트리 전송 회피)
      * const subFiles = await cb.storage.getFiles('storage-id', 'folder-id')
      * ```
      */
@@ -7370,6 +7371,12 @@ interface KnowledgeSearchRequest {
     top_k?: number;
     /** Agentic Search 활성화 — AI 가 쿼리를 자동 생성하여 다중 검색 수행 */
     agentic?: boolean;
+    /**
+     * Hybrid 검색 — BM25 키워드 + 벡터 시맨틱 검색을 RRF 로 융합.
+     * 미설정(기본): 콘솔 > AI 에서 embedding 을 켠 앱은 자동 적용.
+     * `false`: 키워드 전용 검색 강제. embedding 미설정 앱에서는 무시(BM25 only).
+     */
+    hybrid?: boolean;
     /**
      * metadata 기반 필터 (옵셔널). 키 형식 `metadata.<path>` 또는 raw key.
      * 값에 `AUTH_MEMBER_ID_TOKEN` 사용 시 서버가 인증된 AppMember ID 로 치환.
@@ -7655,6 +7662,11 @@ interface AIChatRequest {
     knowledgeBaseId?: string;
     topK?: number;
     agentic?: boolean;
+    /**
+     * KB 검색 hybrid(BM25 + 벡터 시맨틱, RRF 융합) 제어. 미설정(기본)이면 콘솔 > AI 에서
+     * embedding 을 켠 앱은 자동 적용, `false` 면 키워드 전용 검색 강제.
+     */
+    hybrid?: boolean;
     toolGroupId?: string;
     /**
      * 0 보다 크면, 서버측 도구 그룹 실행(`toolGroupId` 사용 시)에서 각 도구 결과를 모델에

package/dist/index.d.ts

@@ -2402,14 +2402,15 @@ declare class StorageAPI {
      * 파일 목록 조회
      *
      * @param storageId - 파일 스토리지 ID
-     * @param parentId - 부모 폴더 ID (미지정 시 루트 폴더)
+     * @param parentId - 부모 폴더 ID. 지정 시 해당 폴더의 **직계 자식만** 반환한다.
+     *   미지정 시 스토리지 **전체 파일 트리**를 flat 배열로 반환한다.
      *
      * @example
      * ```ts
-     * // 루트 폴더의 파일 목록
+     * // 스토리지 전체 파일 목록 (flat 트리)
      * const files = await cb.storage.getFiles('storage-id')
      *
-     * // 특정 폴더의 하위 파일 목록
+     * // 특정 폴더의 직계 자식만 (대용량 버킷에서 전체 트리 전송 회피)
      * const subFiles = await cb.storage.getFiles('storage-id', 'folder-id')
      * ```
      */
@@ -7370,6 +7371,12 @@ interface KnowledgeSearchRequest {
     top_k?: number;
     /** Agentic Search 활성화 — AI 가 쿼리를 자동 생성하여 다중 검색 수행 */
     agentic?: boolean;
+    /**
+     * Hybrid 검색 — BM25 키워드 + 벡터 시맨틱 검색을 RRF 로 융합.
+     * 미설정(기본): 콘솔 > AI 에서 embedding 을 켠 앱은 자동 적용.
+     * `false`: 키워드 전용 검색 강제. embedding 미설정 앱에서는 무시(BM25 only).
+     */
+    hybrid?: boolean;
     /**
      * metadata 기반 필터 (옵셔널). 키 형식 `metadata.<path>` 또는 raw key.
      * 값에 `AUTH_MEMBER_ID_TOKEN` 사용 시 서버가 인증된 AppMember ID 로 치환.
@@ -7655,6 +7662,11 @@ interface AIChatRequest {
     knowledgeBaseId?: string;
     topK?: number;
     agentic?: boolean;
+    /**
+     * KB 검색 hybrid(BM25 + 벡터 시맨틱, RRF 융합) 제어. 미설정(기본)이면 콘솔 > AI 에서
+     * embedding 을 켠 앱은 자동 적용, `false` 면 키워드 전용 검색 강제.
+     */
+    hybrid?: boolean;
     toolGroupId?: string;
     /**
      * 0 보다 크면, 서버측 도구 그룹 실행(`toolGroupId` 사용 시)에서 각 도구 결과를 모델에

package/dist/index.js

@@ -2279,14 +2279,15 @@ var StorageAPI = class {
    * 파일 목록 조회
    *
    * @param storageId - 파일 스토리지 ID
-   * @param parentId - 부모 폴더 ID (미지정 시 루트 폴더)
+   * @param parentId - 부모 폴더 ID. 지정 시 해당 폴더의 **직계 자식만** 반환한다.
+   *   미지정 시 스토리지 **전체 파일 트리**를 flat 배열로 반환한다.
    *
    * @example
    * ```ts
-   * // 루트 폴더의 파일 목록
+   * // 스토리지 전체 파일 목록 (flat 트리)
    * const files = await cb.storage.getFiles('storage-id')
    *
-   * // 특정 폴더의 하위 파일 목록
+   * // 특정 폴더의 직계 자식만 (대용량 버킷에서 전체 트리 전송 회피)
    * const subFiles = await cb.storage.getFiles('storage-id', 'folder-id')
    * ```
    */

package/dist/index.mjs

@@ -2234,14 +2234,15 @@ var StorageAPI = class {
    * 파일 목록 조회
    *
    * @param storageId - 파일 스토리지 ID
-   * @param parentId - 부모 폴더 ID (미지정 시 루트 폴더)
+   * @param parentId - 부모 폴더 ID. 지정 시 해당 폴더의 **직계 자식만** 반환한다.
+   *   미지정 시 스토리지 **전체 파일 트리**를 flat 배열로 반환한다.
    *
    * @example
    * ```ts
-   * // 루트 폴더의 파일 목록
+   * // 스토리지 전체 파일 목록 (flat 트리)
    * const files = await cb.storage.getFiles('storage-id')
    *
-   * // 특정 폴더의 하위 파일 목록
+   * // 특정 폴더의 직계 자식만 (대용량 버킷에서 전체 트리 전송 회피)
    * const subFiles = await cb.storage.getFiles('storage-id', 'folder-id')
    * ```
    */

package/package.json

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