connectbase-client 5.6.2 → 5.6.3

package/dist/index.mjs

@@ -234,6 +234,29 @@ var GameError = class extends Error {
 };
 
 // src/api/ai.ts
+function aiErrorToApiError(err) {
+  const statusByCode = {
+    provider_timeout: 504,
+    gateway_timeout: 504,
+    bad_gateway: 502,
+    service_unavailable: 503,
+    rate_limit_exceeded: 429,
+    quota_exceeded: 429,
+    invalid_request: 400,
+    config_error: 400,
+    unauthorized: 401
+  };
+  const details = {};
+  if (err.provider) details.provider = err.provider;
+  if (err.model) details.model = err.model;
+  if (err.retryAfter !== void 0) details.retry_after_seconds = err.retryAfter;
+  return new ApiError(
+    err.status ?? statusByCode[err.code] ?? 500,
+    err.message,
+    err.detailCode || err.code,
+    Object.keys(details).length > 0 ? details : void 0
+  );
+}
 var AI_CHAT_DEFAULT_TIMEOUT_MS = 9e4;
 var AI_CHAT_MAX_TIMEOUT_MS = 3e5;
 var AI_CHAT_CLIENT_GRACE_MS = 1e4;
@@ -247,19 +270,101 @@ var AIAPI = class {
    *
    * @param options `options.timeout` 으로 이 1회 생성의 시간 예산(ms)을 정한다 — 자세한
    *   의미와 상한은 {@link AIChatOptions.timeout} 참고. 미지정이면 90초.
+   *
+   * ### 전송 방식 (5.6.3+)
+   *
+   * 겉보기 API 는 그대로지만 **내부적으로는 스트리밍 전송을 쓰고 결과를 합쳐서 돌려준다.**
+   *
+   * 왜: 응답이 다 만들어질 때까지 한 바이트도 흐르지 않는 요청은, 중간의 어떤 계층이든
+   * "첫 바이트까지 N초" 제한을 두면 그 자리에서 끊긴다 — CDN(100초), 리버스 프록시,
+   * 로드밸런서, 모바일 캐리어 NAT 가 전부 그런 제한을 갖는다. 서버 타임아웃을 아무리
+   * 늘려도 이 성질은 남으므로, 상한을 올리는 게 아니라 **바이트가 계속 흐르게** 하는 것이
+   * 유일한 근본 해결이다(긴 생성에 스트리밍을 쓰는 것은 LLM API 의 표준 관행이다).
+   *
+   * 호출자가 볼 수 있는 차이는 없다 — `content`/`reasoning`/`toolCalls`/`sources`/
+   * `finishReason`/`usage` 모두 동일하게 채워지고, 에러도 같은 `code` 로 던져진다.
+   * 토큰을 실시간으로 보여줘야 하면 {@link AIAPI.chatStream} 을 쓴다.
    */
   async chat(request, options) {
     const budgetMs = Math.min(
       options?.timeout ?? this.http.requestTimeoutMs ?? AI_CHAT_DEFAULT_TIMEOUT_MS,
       AI_CHAT_MAX_TIMEOUT_MS
     );
-    return this.http.post(
-      "/v1/public/ai/chat",
-      // timeoutSeconds 는 서버가 쓰는 생성 예산. 마지막에 펼쳐 호출자가 임의로 넣은
-      // 값이 이 계산을 덮어쓰지 못하게 한다.
-      { ...request, timeoutSeconds: Math.ceil(budgetMs / 1e3) },
-      { timeout: budgetMs + AI_CHAT_CLIENT_GRACE_MS, signal: options?.signal }
-    );
+    const controller = new AbortController();
+    let budgetExpired = false;
+    const timer = setTimeout(() => {
+      budgetExpired = true;
+      controller.abort();
+    }, budgetMs + AI_CHAT_CLIENT_GRACE_MS);
+    const external = options?.signal;
+    const forwardAbort = () => controller.abort();
+    if (external) {
+      if (external.aborted) controller.abort();
+      else external.addEventListener("abort", forwardAbort, { once: true });
+    }
+    const aggregated = { content: "", provider: "", model: "" };
+    let failure;
+    let aborted = false;
+    let reasoning = "";
+    try {
+      await this.runStream(
+        // timeoutSeconds 는 서버가 쓰는 생성 예산. 마지막에 펼쳐 호출자가 임의로 넣은
+        // 값이 이 계산을 덮어쓰지 못하게 한다.
+        { ...request, timeoutSeconds: Math.ceil(budgetMs / 1e3) },
+        {
+          onToken: (token) => {
+            aggregated.content += token;
+          },
+          onReasoning: (delta) => {
+            reasoning += delta;
+          },
+          onSources: (sources) => {
+            aggregated.sources = sources;
+          },
+          // 에러는 콜백으로 오므로 붙잡아 두었다가 아래에서 throw 한다 — 콜백 안에서
+          // 던지면 스트림 정리(reader cancel)를 건너뛴다.
+          onError: (error) => {
+            failure = error;
+          },
+          onAbort: () => {
+            aborted = true;
+          }
+        },
+        { signal: controller.signal },
+        {
+          // HTTP 레벨 실패는 비스트리밍 시절과 **완전히 같은 ApiError** 로 던진다.
+          onHttpError: async (response) => {
+            throw await this.http.buildApiError(response);
+          },
+          // 스트림 종료 청크에만 실리는 값들 — 토큰 콜백으로는 표현되지 않는다.
+          onFinalChunk: (chunk) => {
+            if (chunk.finishReason)
+              aggregated.finishReason = chunk.finishReason;
+            if (chunk.toolCalls?.length) aggregated.toolCalls = chunk.toolCalls;
+            if (chunk.usage) aggregated.usage = chunk.usage;
+            if (chunk.provider) aggregated.provider = chunk.provider;
+            if (chunk.model) aggregated.model = chunk.model;
+          }
+        }
+      );
+    } finally {
+      clearTimeout(timer);
+      external?.removeEventListener("abort", forwardAbort);
+    }
+    if (failure) throw aiErrorToApiError(failure);
+    if (aborted) {
+      if (budgetExpired) {
+        throw new ApiError(
+          504,
+          `AI \uC751\uB2F5\uC774 ${Math.round(budgetMs / 1e3)}\uCD08 \uC608\uC0B0 \uC548\uC5D0 \uB05D\uB098\uC9C0 \uC54A\uC558\uC2B5\uB2C8\uB2E4`,
+          "provider_timeout"
+        );
+      }
+      throw new DOMException("The operation was aborted.", "AbortError");
+    }
+    if (failure) throw failure;
+    if (reasoning) aggregated.reasoning = reasoning;
+    return aggregated;
   }
   /**
    * AI 채팅 스트리밍 (SSE)
@@ -299,6 +404,17 @@ var AIAPI = class {
    * ```
    */
   async chatStream(request, callbacks, options) {
+    return this.runStream(request, callbacks, options);
+  }
+  /**
+   * SSE 소비 본체. `chatStream`(공개)과 `chat`(집계)이 공유한다.
+   *
+   * `hooks.onFinalChunk` 은 종료 청크처럼 **토큰 콜백으로는 표현되지 않는 값**
+   * (usage / finishReason / toolCalls)을 집는 내부 훅이다. 공개 옵션으로 열지 않는 이유:
+   * 스트리밍 사용자는 그 값들을 콜백으로 이미 받거나 필요로 하지 않는데, 공개하면
+   * "언제 몇 번 불리는가" 가 계약이 되어 와이어 포맷을 못 바꾸게 된다.
+   */
+  async runStream(request, callbacks, options, hooks) {
     const signal = options?.signal;
     const isAbort = (err) => signal?.aborted === true || err instanceof DOMException && err.name === "AbortError" || typeof err === "object" && err !== null && err.name === "AbortError";
     let reader;
@@ -313,6 +429,7 @@ var AIAPI = class {
         signal
       });
       if (!response.ok) {
+        if (hooks?.onHttpError) await hooks.onHttpError(response);
         const errorData = await response.json().catch(() => ({ error: "stream_failed" }));
         callbacks.onError?.(
           toAIError(errorData, {
@@ -377,9 +494,11 @@ var AIAPI = class {
             if (event.type === "heartbeat") {
               continue;
             }
+            if (event.usage) hooks?.onFinalChunk?.(event);
             if (event.reasoning) callbacks.onReasoning?.(event.reasoning);
             if (event.content) callbacks.onToken?.(event.content);
             if (event.done) {
+              if (!event.usage) hooks?.onFinalChunk?.(event);
               callbacks.onDone?.();
               return;
             }
@@ -11603,70 +11722,81 @@ var HttpClient = class {
     }
     return headers;
   }
-  async handleResponse(response) {
-    if (!response.ok) {
-      let errorData = {};
-      let bodyIsJson = true;
-      try {
-        errorData = await response.json();
-      } catch {
-        bodyIsJson = false;
-      }
-      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)
-            );
-          }
+  /**
+   * 실패 응답(`!response.ok`)을 ApiError 로 변환한다. 던지지도, emitError 하지도 않는다.
+   *
+   * handleResponse 와 **같은 파싱을 두 곳이 필요로 해서** 뽑아냈다 — `ai.chat` 이 스트리밍
+   * 전송으로 옮겨가면서 SSE 응답의 HTTP 레벨 실패도 기존 비스트리밍과 **완전히 같은
+   * ApiError** 로 보여야 하기 때문이다. 파싱을 복제하면 그 순간부터 두 경로의 에러 모양이
+   * 갈린다 (실제로 코드 유실 사고가 있었다 — platform-issue 019fa21c).
+   */
+  async buildApiError(response) {
+    let errorData = {};
+    let bodyIsJson = true;
+    try {
+      errorData = await response.json();
+    } catch {
+      bodyIsJson = false;
+    }
+    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) {
-        const structured = rawError;
-        const details = {
-          ...structured.details && typeof structured.details === "object" ? structured.details : {}
-        };
-        if (retryAfterSeconds !== void 0) {
-          details.retry_after_seconds = retryAfterSeconds;
-        }
-        const err2 = new ApiError(
-          response.status,
-          typeof structured.message === "string" && structured.message !== "" ? structured.message : "Unknown error",
-          typeof structured.code === "string" ? structured.code : void 0,
-          Object.keys(details).length > 0 ? details : void 0
-        );
-        this.emitError(err2);
-        throw err2;
-      }
-      const flatMessage = typeof errorData.message === "string" && errorData.message !== "" ? errorData.message : void 0;
-      const explicitCode = typeof errorData.code === "string" && errorData.code !== "" ? errorData.code : void 0;
-      const errorIsCode = typeof rawError === "string" && /^[a-z][a-z0-9_]*$/.test(rawError);
-      const message = flatMessage ?? (typeof rawError === "string" && rawError !== "" ? rawError : void 0) ?? (bodyIsJson ? void 0 : gatewayMessageFromStatus(response.status)) ?? (response.statusText !== "" ? response.statusText : "Unknown error");
-      const code = explicitCode ?? (errorIsCode ? rawError : void 0) ?? gatewayCodeFromStatus(response.status);
-      const legacyDetails = {};
+    }
+    const rawError = errorData.error;
+    if (rawError && typeof rawError === "object" && "message" in rawError) {
+      const structured = rawError;
+      const details = {
+        ...structured.details && typeof structured.details === "object" ? structured.details : {}
+      };
       if (retryAfterSeconds !== void 0) {
-        legacyDetails.retry_after_seconds = retryAfterSeconds;
+        details.retry_after_seconds = retryAfterSeconds;
       }
-      if (typeof errorData.provider === "string") {
-        legacyDetails.provider = errorData.provider;
-      }
-      if (typeof errorData.model === "string") {
-        legacyDetails.model = errorData.model;
-      }
-      const err = new ApiError(
+      const err2 = new ApiError(
         response.status,
-        message,
-        code,
-        Object.keys(legacyDetails).length > 0 ? legacyDetails : void 0
+        typeof structured.message === "string" && structured.message !== "" ? structured.message : "Unknown error",
+        typeof structured.code === "string" ? structured.code : void 0,
+        Object.keys(details).length > 0 ? details : void 0
       );
+      return err2;
+    }
+    const flatMessage = typeof errorData.message === "string" && errorData.message !== "" ? errorData.message : void 0;
+    const explicitCode = typeof errorData.code === "string" && errorData.code !== "" ? errorData.code : void 0;
+    const errorIsCode = typeof rawError === "string" && /^[a-z][a-z0-9_]*$/.test(rawError);
+    const message = flatMessage ?? (typeof rawError === "string" && rawError !== "" ? rawError : void 0) ?? (bodyIsJson ? void 0 : gatewayMessageFromStatus(response.status)) ?? (response.statusText !== "" ? response.statusText : "Unknown error");
+    const code = explicitCode ?? (errorIsCode ? rawError : void 0) ?? gatewayCodeFromStatus(response.status);
+    const legacyDetails = {};
+    if (retryAfterSeconds !== void 0) {
+      legacyDetails.retry_after_seconds = retryAfterSeconds;
+    }
+    if (typeof errorData.provider === "string") {
+      legacyDetails.provider = errorData.provider;
+    }
+    if (typeof errorData.model === "string") {
+      legacyDetails.model = errorData.model;
+    }
+    const err = new ApiError(
+      response.status,
+      message,
+      code,
+      Object.keys(legacyDetails).length > 0 ? legacyDetails : void 0
+    );
+    return err;
+  }
+  async handleResponse(response) {
+    if (!response.ok) {
+      const err = await this.buildApiError(response);
       this.emitError(err);
       throw err;
     }

package/package.json

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