connectbase-client 3.49.0 → 3.50.0

package/dist/index.mjs

@@ -2251,18 +2251,27 @@ var StorageAPI = class {
    * Presigned URL 로 직접 업로드. 호출 전에 URL 스킴(https)을 검증해
    * 서버 응답을 그대로 신뢰하는 SSRF/오용 경로를 차단.
    * 타임아웃과 외부 signal 을 모두 지원한다.
+   *
+   * `onProgress` 가 주어지고 `XMLHttpRequest` 를 쓸 수 있는(브라우저) 환경이면
+   * XHR 의 `upload.onprogress` 로 바이트 단위 진행률을 보고한다. 그 외에는
+   * fetch 로 업로드하고 시작(0%)/완료(100%)만 통지한다(Node/Edge 호환).
    */
   async uploadToPresigned(rawUrl, file, options) {
     const parsed = validateExternalUrl(rawUrl, {
       allowLocalhost: isLocalhostOrigin(),
       context: "storage.presigned-url"
     });
+    const url = parsed.toString();
+    if (options?.onProgress && typeof XMLHttpRequest !== "undefined") {
+      return this.putViaXhr(url, file, options.onProgress, options);
+    }
     const { signal, cleanup } = createTimeoutController({
       timeout: options?.timeout,
       signal: options?.signal
     });
     try {
-      const response = await fetch(parsed.toString(), {
+      options?.onProgress?.({ loaded: 0, total: file.size, percentage: 0 });
+      const response = await fetch(url, {
         method: "PUT",
         body: file,
         headers: {
@@ -2277,10 +2286,79 @@ var StorageAPI = class {
           "PRESIGNED_UPLOAD_FAILED"
         );
       }
+      options?.onProgress?.({ loaded: file.size, total: file.size, percentage: 100 });
     } finally {
       cleanup();
     }
   }
+  /**
+   * XMLHttpRequest 기반 PUT 업로드. `upload.onprogress` 로 바이트 진행률을
+   * 보고하며, 외부 signal(취소)과 타임아웃을 모두 지원한다. URL 은 호출 전에
+   * 이미 검증된 값을 받는다(uploadToPresigned 에서 스킴 검증 수행).
+   */
+  putViaXhr(url, file, onProgress, options) {
+    return new Promise((resolve, reject) => {
+      const external = options?.signal;
+      if (external?.aborted) {
+        reject(external.reason ?? new DOMException("Aborted", "AbortError"));
+        return;
+      }
+      const xhr = new XMLHttpRequest();
+      xhr.open("PUT", url, true);
+      xhr.setRequestHeader("Content-Type", file.type || "application/octet-stream");
+      const timeout = options?.timeout ?? DEFAULT_REQUEST_TIMEOUT_MS;
+      if (timeout > 0 && Number.isFinite(timeout)) {
+        xhr.timeout = timeout;
+      }
+      let abortListener = null;
+      const cleanup = () => {
+        if (external && abortListener) {
+          external.removeEventListener("abort", abortListener);
+        }
+      };
+      if (external) {
+        abortListener = () => xhr.abort();
+        external.addEventListener("abort", abortListener, { once: true });
+      }
+      xhr.upload.onprogress = (event) => {
+        if (!event.lengthComputable) return;
+        const total = event.total || file.size;
+        onProgress({
+          loaded: event.loaded,
+          total,
+          percentage: total > 0 ? Math.round(event.loaded / total * 100) : 0
+        });
+      };
+      xhr.onload = () => {
+        cleanup();
+        if (xhr.status >= 200 && xhr.status < 300) {
+          onProgress({ loaded: file.size, total: file.size, percentage: 100 });
+          resolve();
+        } else {
+          reject(
+            new ApiError(
+              xhr.status,
+              `Upload failed: ${xhr.statusText || "unknown error"}`,
+              "PRESIGNED_UPLOAD_FAILED"
+            )
+          );
+        }
+      };
+      xhr.onerror = () => {
+        cleanup();
+        reject(new ApiError(0, "Upload failed: network error", "PRESIGNED_UPLOAD_FAILED"));
+      };
+      xhr.ontimeout = () => {
+        cleanup();
+        reject(new DOMException(`Request timed out after ${timeout}ms`, "TimeoutError"));
+      };
+      xhr.onabort = () => {
+        cleanup();
+        reject(external?.reason ?? new DOMException("Aborted", "AbortError"));
+      };
+      xhr.send(file);
+    });
+  }
   /**
    * 파일 목록 조회
    *
@@ -2310,14 +2388,28 @@ var StorageAPI = class {
    *
    * 서버를 거치지 않고 Object Storage에 직접 업로드합니다.
    *
+   * 3번째 인자는 부모 폴더 ID(문자열) 또는 옵션 객체를 받습니다. 옵션으로
+   * `onProgress` 콜백을 넘기면 업로드 진행률(%)을 실시간으로 받을 수 있습니다
+   * (브라우저 환경). 기존 `uploadFile(id, file, 'folder-id')` 호출과 하위 호환됩니다.
+   *
    * @example
    * ```ts
    * const fileInput = document.querySelector('input[type="file"]')
    * const result = await cb.storage.uploadFile('storage-id', fileInput.files[0])
    * console.log(result.url) // 업로드된 파일 URL
+   *
+   * // 특정 폴더에 업로드 (기존 방식 그대로)
+   * await cb.storage.uploadFile('storage-id', file, 'folder-id')
+   *
+   * // 진행률 표시 + 특정 폴더
+   * await cb.storage.uploadFile('storage-id', file, {
+   *   parentId: 'folder-id',
+   *   onProgress: (p) => console.log(`${p.percentage}%`), // { loaded, total, percentage }
+   * })
    * ```
    */
-  async uploadFile(storageId, file, parentId) {
+  async uploadFile(storageId, file, parentIdOrOptions) {
+    const options = typeof parentIdOrOptions === "string" ? { parentId: parentIdOrOptions } : parentIdOrOptions ?? {};
     const prefix = this.getPublicPrefix();
     const presignedResponse = await this.http.post(
       `${prefix}/storages/files/${storageId}/presigned-url`,
@@ -2325,10 +2417,14 @@ var StorageAPI = class {
         file_name: file.name,
         file_size: file.size,
         mime_type: file.type || "application/octet-stream",
-        parent_id: parentId
+        parent_id: options.parentId
       }
     );
-    await this.uploadToPresigned(presignedResponse.upload_url, file);
+    await this.uploadToPresigned(presignedResponse.upload_url, file, {
+      onProgress: options.onProgress,
+      signal: options.signal,
+      timeout: options.timeout
+    });
     const completeResponse = await this.http.post(
       `${prefix}/storages/files/${storageId}/complete-upload`,
       { file_id: presignedResponse.file_id }
@@ -2347,11 +2443,14 @@ var StorageAPI = class {
   }
   /**
    * 여러 파일 업로드
+   *
+   * `onProgress` 를 옵션으로 넘기면 **파일별로** 진행률 콜백이 호출됩니다
+   * (각 파일마다 0→100%). 전체 진행률이 필요하면 완료된 파일 수를 직접 집계하세요.
    */
-  async uploadFiles(storageId, files, parentId) {
+  async uploadFiles(storageId, files, parentIdOrOptions) {
     const results = [];
     for (const file of files) {
-      const result = await this.uploadFile(storageId, file, parentId);
+      const result = await this.uploadFile(storageId, file, parentIdOrOptions);
       results.push(result);
     }
     return results;
@@ -2450,7 +2549,11 @@ var StorageAPI = class {
         overwrite
       }
     );
-    await this.uploadToPresigned(presignedResponse.upload_url, file);
+    await this.uploadToPresigned(presignedResponse.upload_url, file, {
+      onProgress: options?.onProgress,
+      signal: options?.signal,
+      timeout: options?.timeout
+    });
     const completeResponse = await this.http.post(
       `${prefix}/storages/files/${storageId}/complete-upload`,
       { file_id: presignedResponse.file_id }

package/package.json

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