connectbase-client 1.8.1 → 1.9.1

package/dist/index.js

@@ -53,12 +53,50 @@ var AuthError = class extends Error {
   }
 };
 
+// src/core/abort.ts
+var DEFAULT_REQUEST_TIMEOUT_MS = 3e4;
+function createTimeoutController(options = {}) {
+  const controller = new AbortController();
+  const timeout = options.timeout ?? DEFAULT_REQUEST_TIMEOUT_MS;
+  const external = options.signal;
+  let timeoutId = null;
+  let externalListener = null;
+  if (external) {
+    if (external.aborted) {
+      controller.abort(external.reason);
+    } else {
+      externalListener = () => controller.abort(external.reason);
+      external.addEventListener("abort", externalListener, { once: true });
+    }
+  }
+  if (timeout > 0 && Number.isFinite(timeout)) {
+    timeoutId = setTimeout(() => {
+      controller.abort(
+        new DOMException(`Request timed out after ${timeout}ms`, "TimeoutError")
+      );
+    }, timeout);
+  }
+  return {
+    signal: controller.signal,
+    cleanup: () => {
+      if (timeoutId !== null) clearTimeout(timeoutId);
+      if (external && externalListener) {
+        external.removeEventListener("abort", externalListener);
+      }
+    }
+  };
+}
+
 // src/core/http.ts
 var TOKEN_STORAGE_KEY = "cb_auth_tokens";
 var HttpClient = class {
   constructor(config) {
     this.isRefreshing = false;
     this.refreshPromise = null;
+    // 연속 refresh 실패 시 지수 백오프 — 같은 세션이 스피너 UI 로 묶였을 때
+    // 밀리초 단위로 서버에 재시도 요청이 쏟아지는 것을 차단.
+    this.refreshFailureCount = 0;
+    this.refreshLockedUntil = 0;
     this.config = { ...config };
     this.storageKey = this.buildStorageKey();
     this.warnIfUnsafePersistence();
@@ -200,22 +238,34 @@ var HttpClient = class {
     if (this.isRefreshing) {
       return this.refreshPromise;
     }
+    const now = Date.now();
+    if (now < this.refreshLockedUntil) {
+      const error = new AuthError("Token refresh locked due to repeated failures. Please login again.");
+      this.emitError(error);
+      this.config.onAuthError?.(error);
+      throw error;
+    }
     this.isRefreshing = true;
     if (!this.config.refreshToken) {
       this.isRefreshing = false;
       this.config.onTokenExpired?.();
       const error = new AuthError("Refresh token is missing. Please login again.");
+      this.emitError(error);
       this.config.onAuthError?.(error);
       throw error;
     }
     this.refreshPromise = (async () => {
+      const { signal, cleanup } = createTimeoutController({
+        timeout: this.config.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS
+      });
       try {
         const response = await fetch(`${this.config.baseUrl}/v1/auth/re-issue`, {
           method: "POST",
           headers: {
             "Content-Type": "application/json",
             "Authorization": `Bearer ${this.config.refreshToken}`
-          }
+          },
+          signal
         });
         if (!response.ok) {
           throw new Error("Token refresh failed");
@@ -226,20 +276,36 @@ var HttpClient = class {
           accessToken: data.access_token,
           refreshToken: data.refresh_token
         });
+        this.refreshFailureCount = 0;
+        this.refreshLockedUntil = 0;
         return data.access_token;
       } catch {
+        this.refreshFailureCount++;
+        const backoffMs = Math.min(
+          500 * 2 ** Math.max(0, this.refreshFailureCount - 1),
+          3e4
+        );
+        this.refreshLockedUntil = Date.now() + backoffMs;
         this.clearTokens();
         this.config.onTokenExpired?.();
         const error = new AuthError("Token refresh failed. Please login again.");
+        this.emitError(error);
         this.config.onAuthError?.(error);
         throw error;
       } finally {
+        cleanup();
         this.isRefreshing = false;
         this.refreshPromise = null;
       }
     })();
     return this.refreshPromise;
   }
+  emitError(error) {
+    try {
+      this.config.onError?.(error);
+    } catch {
+    }
+  }
   isTokenExpired(token) {
     try {
       const payload = JSON.parse(atob(token.split(".")[1]));
@@ -278,72 +344,119 @@ var HttpClient = class {
       const errorData = await response.json().catch(() => ({
         message: response.statusText
       }));
+      const retryAfterHeader = response.status === 429 ? response.headers.get("Retry-After") : null;
+      let retryAfterSeconds;
+      if (retryAfterHeader) {
+        const asInt = Number.parseInt(retryAfterHeader, 10);
+        if (Number.isFinite(asInt) && asInt >= 0) {
+          retryAfterSeconds = asInt;
+        } else {
+          const dateMs = Date.parse(retryAfterHeader);
+          if (Number.isFinite(dateMs)) {
+            retryAfterSeconds = Math.max(
+              0,
+              Math.round((dateMs - Date.now()) / 1e3)
+            );
+          }
+        }
+      }
       const rawError = errorData.error;
       if (rawError && typeof rawError === "object" && "message" in rawError) {
-        throw new ApiError(
+        const details = {
+          ...rawError.details && typeof rawError.details === "object" ? rawError.details : {}
+        };
+        if (retryAfterSeconds !== void 0) {
+          details.retry_after_seconds = retryAfterSeconds;
+        }
+        const err2 = new ApiError(
           response.status,
           rawError.message || "Unknown error",
           rawError.code,
-          rawError.details
+          Object.keys(details).length > 0 ? details : rawError.details
         );
+        this.emitError(err2);
+        throw err2;
       }
       const message = typeof rawError === "string" ? rawError : errorData.message || "Unknown error";
-      throw new ApiError(response.status, message);
+      const legacyDetails = retryAfterSeconds !== void 0 ? { retry_after_seconds: retryAfterSeconds } : void 0;
+      const err = new ApiError(response.status, message, void 0, legacyDetails);
+      this.emitError(err);
+      throw err;
     }
     if (response.status === 204 || response.headers.get("content-length") === "0") {
       return {};
     }
     return response.json();
   }
+  /**
+   * AbortController 를 관리하며 fetch 호출을 실행. 타임아웃/외부 signal 병합.
+   */
+  async doFetch(url, init, config) {
+    const { signal, cleanup } = createTimeoutController({
+      timeout: config?.timeout ?? this.config.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS,
+      signal: config?.signal
+    });
+    try {
+      const response = await fetch(`${this.config.baseUrl}${url}`, {
+        ...init,
+        signal
+      });
+      return await this.handleResponse(response);
+    } finally {
+      cleanup();
+    }
+  }
   async get(url, config) {
     const headers = await this.prepareHeaders(config);
-    const response = await fetch(`${this.config.baseUrl}${url}`, {
-      method: "GET",
-      headers
-    });
-    return this.handleResponse(response);
+    return this.doFetch(url, { method: "GET", headers }, config);
   }
   async post(url, data, config) {
     const headers = await this.prepareHeaders(config);
     if (data instanceof FormData) {
       headers.delete("Content-Type");
     }
-    const response = await fetch(`${this.config.baseUrl}${url}`, {
-      method: "POST",
-      headers,
-      body: data instanceof FormData ? data : JSON.stringify(data)
-    });
-    return this.handleResponse(response);
+    return this.doFetch(
+      url,
+      {
+        method: "POST",
+        headers,
+        body: data instanceof FormData ? data : JSON.stringify(data)
+      },
+      config
+    );
   }
   async put(url, data, config) {
     const headers = await this.prepareHeaders(config);
-    const response = await fetch(`${this.config.baseUrl}${url}`, {
-      method: "PUT",
-      headers,
-      body: JSON.stringify(data)
-    });
-    return this.handleResponse(response);
+    return this.doFetch(
+      url,
+      {
+        method: "PUT",
+        headers,
+        body: JSON.stringify(data)
+      },
+      config
+    );
   }
   async patch(url, data, config) {
     const headers = await this.prepareHeaders(config);
-    const response = await fetch(`${this.config.baseUrl}${url}`, {
-      method: "PATCH",
-      headers,
-      body: JSON.stringify(data)
-    });
-    return this.handleResponse(response);
+    return this.doFetch(
+      url,
+      {
+        method: "PATCH",
+        headers,
+        body: JSON.stringify(data)
+      },
+      config
+    );
   }
   async delete(url, config) {
     const headers = await this.prepareHeaders(config);
-    const response = await fetch(`${this.config.baseUrl}${url}`, {
-      method: "DELETE",
-      headers
-    });
-    return this.handleResponse(response);
+    return this.doFetch(url, { method: "DELETE", headers }, config);
   }
   /**
    * Raw fetch 요청 (SSE 스트리밍 등에 사용)
-   * 인증 헤더가 자동으로 추가됩니다.
+   * 인증 헤더가 자동으로 추가됩니다. timeout 은 호출자가 직접 signal 로 관리해야 합니다
+   * (스트리밍 특성상 전역 timeout 을 강제하지 않음).
    */
   async fetchRaw(url, init) {
     const headers = await this.prepareHeaders();
@@ -359,6 +472,57 @@ var HttpClient = class {
   }
 };
 
+// src/core/validate.ts
+function checkType(value, type) {
+  switch (type) {
+    case "string":
+      return typeof value === "string";
+    case "number":
+      return typeof value === "number" && Number.isFinite(value);
+    case "boolean":
+      return typeof value === "boolean";
+    case "array":
+      return Array.isArray(value);
+    case "object":
+      return typeof value === "object" && value !== null && !Array.isArray(value);
+    case "string-or-number":
+      return typeof value === "string" || typeof value === "number" && Number.isFinite(value);
+  }
+}
+function assertShape(value, shape, endpoint) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new ApiError(
+      502,
+      `[${endpoint}] expected object, got ${typeof value}`,
+      "SCHEMA_MISMATCH"
+    );
+  }
+  const obj = value;
+  for (const [key, spec] of Object.entries(shape)) {
+    const present = key in obj;
+    if (!present) {
+      if (spec.optional) continue;
+      throw new ApiError(
+        502,
+        `[${endpoint}] missing required field "${key}"`,
+        "SCHEMA_MISMATCH"
+      );
+    }
+    const fieldValue = obj[key];
+    if (spec.optional && (fieldValue === null || fieldValue === void 0)) {
+      continue;
+    }
+    if (!checkType(fieldValue, spec.type)) {
+      throw new ApiError(
+        502,
+        `[${endpoint}] field "${key}" expected ${spec.type}, got ${typeof fieldValue}`,
+        "SCHEMA_MISMATCH"
+      );
+    }
+  }
+  return value;
+}
+
 // src/api/auth.ts
 var GUEST_MEMBER_TOKEN_KEY_PREFIX = "cb_guest_";
 function credentialToStorageKeyHash(credential) {
@@ -465,6 +629,15 @@ var AuthAPI = class {
       data,
       { skipAuth: true }
     );
+    assertShape(
+      response,
+      {
+        access_token: { type: "string" },
+        refresh_token: { type: "string" },
+        member_id: { type: "string-or-number" }
+      },
+      "auth.signInMember"
+    );
     this.http.setTokens(response.access_token, response.refresh_token);
     this.notifyVisitorTracker(response.member_id);
     return response;
@@ -504,7 +677,17 @@ var AuthAPI = class {
    * ```
    */
   async getMe() {
-    return this.http.get("/v1/public/app-members/me");
+    const response = await this.http.get(
+      "/v1/public/app-members/me"
+    );
+    assertShape(
+      response,
+      {
+        member_id: { type: "string-or-number" }
+      },
+      "auth.getMe"
+    );
+    return response;
   }
   /**
    * 현재 로그인한 멤버의 custom_data 수정
@@ -1791,6 +1974,72 @@ var DatabaseAPI = class {
   }
 };
 
+// src/core/url-validation.ts
+var LOCAL_HOSTS = /* @__PURE__ */ new Set(["localhost", "127.0.0.1", "::1"]);
+var MAX_URL_LENGTH = 2048;
+function validateExternalUrl(rawUrl, options = {}) {
+  const context = options.context ?? "external URL";
+  if (typeof rawUrl !== "string" || rawUrl.length === 0) {
+    throw new ApiError(
+      400,
+      `${context}: empty URL`,
+      "INVALID_PRESIGNED_URL"
+    );
+  }
+  if (rawUrl.length > MAX_URL_LENGTH) {
+    throw new ApiError(
+      400,
+      `${context}: URL exceeds ${MAX_URL_LENGTH} chars`,
+      "INVALID_PRESIGNED_URL"
+    );
+  }
+  let parsed;
+  try {
+    parsed = new URL(rawUrl);
+  } catch {
+    throw new ApiError(
+      400,
+      `${context}: cannot parse URL`,
+      "INVALID_PRESIGNED_URL"
+    );
+  }
+  const allowHttp = options.allowLocalhost && LOCAL_HOSTS.has(parsed.hostname);
+  if (parsed.protocol !== "https:" && !(allowHttp && parsed.protocol === "http:")) {
+    throw new ApiError(
+      400,
+      `${context}: scheme must be https (got ${parsed.protocol})`,
+      "INVALID_PRESIGNED_URL"
+    );
+  }
+  if (!options.allowLocalhost && LOCAL_HOSTS.has(parsed.hostname)) {
+    throw new ApiError(
+      400,
+      `${context}: localhost is not allowed in production`,
+      "INVALID_PRESIGNED_URL"
+    );
+  }
+  if (options.allowedHosts && options.allowedHosts.length > 0) {
+    const host = parsed.hostname;
+    const allowed = options.allowedHosts.some((h) => {
+      if (h === host) return true;
+      return host.endsWith(`.${h}`);
+    });
+    if (!allowed) {
+      throw new ApiError(
+        400,
+        `${context}: host ${host} is not in allowlist`,
+        "INVALID_PRESIGNED_URL"
+      );
+    }
+  }
+  return parsed;
+}
+function isLocalhostOrigin() {
+  if (typeof window === "undefined") return false;
+  const hostname = window.location.hostname;
+  return LOCAL_HOSTS.has(hostname);
+}
+
 // src/api/storage.ts
 var StorageAPI = class {
   constructor(http) {
@@ -1802,6 +2051,40 @@ var StorageAPI = class {
   getPublicPrefix() {
     return this.http.hasPublicKey() ? "/v1/public" : "/v1";
   }
+  /**
+   * Presigned URL 로 직접 업로드. 호출 전에 URL 스킴(https)을 검증해
+   * 서버 응답을 그대로 신뢰하는 SSRF/오용 경로를 차단.
+   * 타임아웃과 외부 signal 을 모두 지원한다.
+   */
+  async uploadToPresigned(rawUrl, file, options) {
+    const parsed = validateExternalUrl(rawUrl, {
+      allowLocalhost: isLocalhostOrigin(),
+      context: "storage.presigned-url"
+    });
+    const { signal, cleanup } = createTimeoutController({
+      timeout: options?.timeout,
+      signal: options?.signal
+    });
+    try {
+      const response = await fetch(parsed.toString(), {
+        method: "PUT",
+        body: file,
+        headers: {
+          "Content-Type": file.type || "application/octet-stream"
+        },
+        signal
+      });
+      if (!response.ok) {
+        throw new ApiError(
+          response.status,
+          `Upload failed: ${response.statusText}`,
+          "PRESIGNED_UPLOAD_FAILED"
+        );
+      }
+    } finally {
+      cleanup();
+    }
+  }
   /**
    * 파일 목록 조회
    *
@@ -1848,16 +2131,7 @@ var StorageAPI = class {
         parent_id: parentId
       }
     );
-    const uploadResponse = await fetch(presignedResponse.upload_url, {
-      method: "PUT",
-      body: file,
-      headers: {
-        "Content-Type": file.type || "application/octet-stream"
-      }
-    });
-    if (!uploadResponse.ok) {
-      throw new Error(`Upload failed: ${uploadResponse.statusText}`);
-    }
+    await this.uploadToPresigned(presignedResponse.upload_url, file);
     const completeResponse = await this.http.post(
       `${prefix}/storages/files/${storageId}/complete-upload`,
       { file_id: presignedResponse.file_id }
@@ -1979,16 +2253,7 @@ var StorageAPI = class {
         overwrite
       }
     );
-    const uploadResponse = await fetch(presignedResponse.upload_url, {
-      method: "PUT",
-      body: file,
-      headers: {
-        "Content-Type": file.type || "application/octet-stream"
-      }
-    });
-    if (!uploadResponse.ok) {
-      throw new Error(`Upload failed: ${uploadResponse.statusText}`);
-    }
+    await this.uploadToPresigned(presignedResponse.upload_url, file);
     const completeResponse = await this.http.post(
       `${prefix}/storages/files/${storageId}/complete-upload`,
       { file_id: presignedResponse.file_id }
@@ -2256,7 +2521,11 @@ var FunctionsAPI = class {
   async call(functionId, payload) {
     const response = await this.invoke(functionId, payload);
     if (!response.success) {
-      throw new Error(response.error || "Function execution failed");
+      throw new ApiError(
+        500,
+        response.error || "Function execution failed",
+        "FUNCTION_EXECUTION_FAILED"
+      );
     }
     return response.result;
   }
@@ -2977,7 +3246,7 @@ var RealtimeAPI = class {
                 }
               });
             } catch (e) {
-              console.error("[Realtime] Failed to parse message:", line, e);
+              this.logError("Failed to parse message", { line, error: e });
             }
           }
         };
@@ -2994,7 +3263,7 @@ var RealtimeAPI = class {
         };
         this.ws.onerror = (error) => {
           this.log("WebSocket error occurred");
-          console.error("[Realtime] WebSocket error:", error);
+          this.logError("WebSocket error", error);
           this.notifyError(new Error("WebSocket connection error"));
           if (!settled && this.state === "connecting") {
             settled = true;
@@ -3014,6 +3283,16 @@ var RealtimeAPI = class {
       console.log(`[Realtime] ${message}`);
     }
   }
+  /**
+   * 에러 로그. `options.debug` 가 true 일 때만 console 에 출력.
+   * 운영 환경에서는 소비자 애플리케이션의 `ConnectBase({ onError })` 또는
+   * `cb.errorTracker` 로 전달하는 것을 권장하므로 SDK 자체 console 출력은 opt-in.
+   */
+  logError(message, error) {
+    if (this.options.debug) {
+      console.error(`[Realtime] ${message}`, error);
+    }
+  }
   handleServerMessage(msg, connectResolve) {
     switch (msg.event) {
       case "connected": {
@@ -3224,7 +3503,7 @@ var RealtimeAPI = class {
             previousTypingHandlers
           );
         } catch (e) {
-          console.error("[Realtime] Reconnect failed:", e);
+          this.logError("Reconnect failed", e);
         }
       }, delay);
     } else {
@@ -3256,7 +3535,7 @@ var RealtimeAPI = class {
         this.subscriptions.set(category, { info, handlers });
         this.log(`Restored subscription: ${category}`);
       } catch (e) {
-        console.error(`[Realtime] Failed to restore subscription for ${category}:`, e);
+        this.logError(`Failed to restore subscription for ${category}`, e);
         this.notifyError(new Error(`Failed to restore subscription: ${category}`));
       }
     }
@@ -3273,7 +3552,7 @@ var RealtimeAPI = class {
         this.presenceSubscriptions.set(userId, handlers);
         this.log(`Restored presence subscription: ${userId}`);
       } catch (e) {
-        console.error(`[Realtime] Failed to restore presence subscription for ${userId}:`, e);
+        this.logError(`Failed to restore presence subscription for ${userId}`, e);
       }
     }
     for (const [roomId, handlers] of previousTypingHandlers) {
@@ -3289,7 +3568,7 @@ var RealtimeAPI = class {
         this.typingHandlers.set(roomId, handlers);
         this.log(`Restored typing subscription: ${roomId}`);
       } catch (e) {
-        console.error(`[Realtime] Failed to restore typing subscription for ${roomId}:`, e);
+        this.logError(`Failed to restore typing subscription for ${roomId}`, e);
       }
     }
   }
@@ -4400,7 +4679,19 @@ var PaymentAPI = class {
    */
   async createCheckoutSession(data) {
     const prefix = this.getPublicPrefix();
-    return this.http.post(`${prefix}/payments/checkout-session`, data);
+    const response = await this.http.post(
+      `${prefix}/payments/checkout-session`,
+      data
+    );
+    assertShape(
+      response,
+      {
+        session_id: { type: "string" },
+        session_url: { type: "string" }
+      },
+      "payment.createCheckoutSession"
+    );
+    return response;
   }
   /**
    * 결제 승인
@@ -4614,7 +4905,19 @@ var SubscriptionAPI = class {
    */
   async create(data) {
     const prefix = this.getPublicPrefix();
-    return this.http.post(`${prefix}/subscriptions`, data);
+    const response = await this.http.post(
+      `${prefix}/subscriptions`,
+      data
+    );
+    assertShape(
+      response,
+      {
+        id: { type: "string-or-number" },
+        status: { type: "string" }
+      },
+      "subscription.create"
+    );
+    return response;
   }
   /**
    * 구독 목록 조회
@@ -4823,7 +5126,18 @@ var PushAPI = class {
    */
   async registerDevice(request) {
     const prefix = this.getPublicPrefix();
-    return this.http.post(`${prefix}/push/devices`, request);
+    const response = await this.http.post(
+      `${prefix}/push/devices`,
+      request
+    );
+    assertShape(
+      response,
+      {
+        device_token: { type: "string" }
+      },
+      "push.registerDevice"
+    );
+    return response;
   }
   /**
    * 디바이스 등록 해제
@@ -5189,21 +5503,39 @@ var VideoAPI = class {
     if (body && !(body instanceof FormData)) {
       headers["Content-Type"] = "application/json";
     }
-    const response = await fetch(`${this.videoBaseUrl}${path}`, {
-      method,
-      headers,
-      body: body instanceof FormData ? body : body ? JSON.stringify(body) : void 0
+    const { signal, cleanup } = createTimeoutController({
+      timeout: DEFAULT_REQUEST_TIMEOUT_MS
     });
-    if (!response.ok) {
-      const errorData = await response.json().catch(() => ({
-        message: response.statusText
-      }));
-      throw new ApiError(response.status, errorData.message || "Unknown error");
-    }
-    if (response.status === 204 || response.headers.get("content-length") === "0") {
-      return {};
+    try {
+      const response = await fetch(`${this.videoBaseUrl}${path}`, {
+        method,
+        headers,
+        body: body instanceof FormData ? body : body ? JSON.stringify(body) : void 0,
+        signal
+      });
+      if (!response.ok) {
+        const errorData = await response.json().catch(() => ({
+          message: response.statusText
+        }));
+        const rawError = errorData.error;
+        if (rawError && typeof rawError === "object" && "message" in rawError) {
+          throw new ApiError(
+            response.status,
+            rawError.message || "Unknown error",
+            rawError.code,
+            rawError.details
+          );
+        }
+        const message = typeof rawError === "string" ? rawError : errorData.message || "Unknown error";
+        throw new ApiError(response.status, message);
+      }
+      if (response.status === 204 || response.headers.get("content-length") === "0") {
+        return {};
+      }
+      return await response.json();
+    } finally {
+      cleanup();
     }
-    return response.json();
   }
   // ========== Video Operations ==========
   /**
@@ -5295,7 +5627,29 @@ var VideoAPI = class {
     throw new VideoProcessingError("Timeout waiting for video to be ready");
   }
   /**
-   * List videos
+   * 영상 목록 조회.
+   *
+   * 필터링/페이지네이션 옵션을 조합해 조건에 맞는 영상들을 반환한다.
+   * API Key(publicKey) 또는 JWT 인증이 모두 지원되며, publicKey 로는 공개 영상만 노출된다.
+   *
+   * @param options - 필터/페이지네이션 옵션
+   * @param options.status - `uploading` | `processing` | `ready` | `failed`
+   * @param options.visibility - `public` | `unlisted` | `private` | `members`
+   * @param options.search - 제목 부분 일치 검색
+   * @param options.channel_id - 특정 채널로 한정
+   * @param options.page - 1 부터 시작
+   * @param options.limit - 기본 20, 최대 100
+   * @returns `videos` 배열과 `total` 카운트를 포함하는 응답
+   *
+   * @example
+   * ```ts
+   * // 내 채널의 최근 공개 영상 10개
+   * const { videos, total } = await cb.video.list({
+   *   channel_id: 'ch_abc',
+   *   visibility: 'public',
+   *   limit: 10,
+   * })
+   * ```
    */
   async list(options) {
     const prefix = this.getPublicPrefix();
@@ -5331,7 +5685,20 @@ var VideoAPI = class {
     await this.videoFetch("DELETE", `${prefix}/videos/${videoId}`);
   }
   /**
-   * Get streaming URL for a video
+   * 영상 스트리밍 URL 획득 (HLS manifest 권장).
+   *
+   * 반환된 URL 은 `hls.js` 또는 Safari 네이티브 HLS 플레이어에 그대로 전달 가능하다.
+   * 서명된 URL 이므로 만료 시간이 존재하며, 갱신이 필요한 경우 다시 호출한다.
+   *
+   * @param videoId - 대상 영상 ID
+   * @param quality - `auto` (기본) | `1080p` | `720p` | `480p` | `360p` 등 트랜스코딩된 품질 레벨
+   * @returns HLS manifest URL 과 만료 정보
+   *
+   * @example
+   * ```ts
+   * const { url, expires_at } = await cb.video.getStreamUrl(videoId, '720p')
+   * videoElement.src = url
+   * ```
    */
   async getStreamUrl(videoId, quality) {
     const prefix = this.getPublicPrefix();
@@ -6186,7 +6553,11 @@ var GameAPI = class {
       headers: this.getHeaders()
     });
     if (!response.ok) {
-      throw new Error(`Failed to list rooms: ${response.statusText}`);
+      throw new ApiError(
+        response.status,
+        `Failed to list rooms: ${response.statusText}`,
+        "GAME_LIST_ROOMS_FAILED"
+      );
     }
     const data = await response.json();
     return data.rooms;
@@ -6200,7 +6571,11 @@ var GameAPI = class {
       headers: this.getHeaders()
     });
     if (!response.ok) {
-      throw new Error(`Failed to get room: ${response.statusText}`);
+      throw new ApiError(
+        response.status,
+        `Failed to get room: ${response.statusText}`,
+        "GAME_GET_ROOM_FAILED"
+      );
     }
     return response.json();
   }
@@ -7666,7 +8041,17 @@ var QueueAPI = class {
     if (options?.visibility_timeout) params.set("visibility_timeout", String(options.visibility_timeout));
     if (options?.auto_ack !== void 0) params.set("auto_ack", String(options.auto_ack));
     const query = params.toString();
-    return this.http.get(`/v1/public/queues/${queueID}/messages${query ? `?${query}` : ""}`);
+    const response = await this.http.get(
+      `/v1/public/queues/${queueID}/messages${query ? `?${query}` : ""}`
+    );
+    assertShape(
+      response,
+      {
+        messages: { type: "array" }
+      },
+      "queue.consume"
+    );
+    return response;
   }
   /**
    * 메시지 처리 완료 확인 (Ack)
@@ -8037,11 +8422,33 @@ var AnalyticsAPI = class {
     sendHeartbeat();
     this.log("Heartbeat enabled (30s interval)");
   }
-  /** 큐에 있는 이벤트 즉시 전송 */
+  /**
+   * 큐에 있는 이벤트 즉시 전송.
+   *
+   * 기본적으로 이벤트는 배치(10개) 또는 주기(5초)로 flush 되지만, 페이지 이탈 직전이나
+   * 결정적 이벤트(결제 완료 등)는 수동으로 `flush()` 를 호출해 전송 지연을 줄일 수 있다.
+   *
+   * @returns 서버 응답 완료 시까지 대기하는 Promise
+   *
+   * @example
+   * ```ts
+   * // 결제 완료 직후 이탈에 대비해 즉시 flush
+   * await cb.analytics.track('purchase_completed', { order_id: '123' })
+   * await cb.analytics.flush()
+   * window.location.href = '/thank-you'
+   * ```
+   */
   async flush() {
     await this.flushQueue();
   }
-  /** 세션 매니저 접근 (고급) */
+  /**
+   * 세션 매니저 접근 (고급 사용자용).
+   *
+   * 외부에서 세션 ID 를 읽어 자체 로깅에 합치거나 강제 세션 종료/재시작이 필요한 경우
+   * 사용. 일반적으로는 AnalyticsAPI 가 내부적으로 세션을 관리하므로 호출할 필요가 없다.
+   *
+   * @returns 내부 SessionManager 인스턴스
+   */
   getSession() {
     return this.session;
   }
@@ -8958,6 +9365,8 @@ var ConnectBase = class {
       publicKey: config.publicKey,
       secretKey: config.secretKey,
       persistence: config.persistence,
+      requestTimeoutMs: config.requestTimeoutMs,
+      onError: config.onError,
       onTokenRefresh: config.onTokenRefresh,
       onAuthError: config.onAuthError,
       onTokenExpired: config.onTokenExpired