connectbase-client 3.32.0 → 3.34.0

package/dist/index.mjs

@@ -2913,13 +2913,25 @@ var RealtimeAPI = class {
     this.state = "disconnected";
     this._connectionId = null;
     this._appId = null;
+    /**
+     * 현재 활성 transport.
+     * - `'ws'`: WebSocket 정상 연결
+     * - `'sse'`: WS 핸드셰이크 실패로 HTTP SSE fallback 모드 (AI `stream()` 만 지원)
+     * - `null`: 미연결
+     */
+    this.activeTransport = null;
+    /** SSE fallback 모드 활성 여부. true 면 백그라운드 WS 재연결 머신을 정지한다. */
+    this.sseFallbackActive = false;
+    /** SSE fallback 스트림의 AbortController (sessionId → controller) — stop()/disconnect() 에서 중단용 */
+    this.sseSessions = /* @__PURE__ */ new Map();
     this.options = {
       maxRetries: 5,
       retryInterval: 1e3,
       userId: "",
       accessToken: "",
       timeout: 3e4,
-      debug: false
+      debug: false,
+      fallback: "sse"
     };
     this.retryCount = 0;
     this.pendingRequests = /* @__PURE__ */ new Map();
@@ -2948,6 +2960,13 @@ var RealtimeAPI = class {
   get appId() {
     return this._appId;
   }
+  /**
+   * 현재 활성 transport (`'ws'` | `'sse'` | `null`).
+   * `'sse'` 이면 WS 가 차단되어 fallback 모드로 동작 중이며 AI `stream()` 만 가능하다.
+   */
+  get transport() {
+    return this.activeTransport;
+  }
   /**
    * WebSocket 연결
    * @param options 연결 옵션
@@ -2968,10 +2987,36 @@ var RealtimeAPI = class {
     this.connectPromise = this.doConnect();
     try {
       await this.connectPromise;
+    } catch (e) {
+      const hasAuth = !!(this.options.accessToken || this.http.getPublicKey());
+      if (this.options.fallback !== "none" && hasAuth) {
+        this.activateSseFallback(e);
+      } else {
+        throw e;
+      }
     } finally {
       this.connectPromise = null;
     }
   }
+  /**
+   * SSE fallback 모드로 전환한다. WS 는 사용 불가하지만 state 는 'connected' 로 두어
+   * (degraded) AI stream() 이 SSE 로 동작하게 한다. 백그라운드 WS 재연결 머신은 정지한다.
+   */
+  activateSseFallback(cause) {
+    if (this.ws) {
+      try {
+        this.ws.close();
+      } catch {
+      }
+      this.ws = null;
+    }
+    this.sseFallbackActive = true;
+    this.activeTransport = "sse";
+    this.state = "connected";
+    this.retryCount = 0;
+    this.log(`WS unavailable (${cause instanceof Error ? cause.message : String(cause)}); using SSE fallback transport for AI streaming`);
+    this.notifyStateChange();
+  }
   /**
    * 연결 해제
    */
@@ -2994,6 +3039,15 @@ var RealtimeAPI = class {
       }
     });
     this.streamSessions.clear();
+    this.sseSessions.forEach((controller) => {
+      try {
+        controller.abort();
+      } catch {
+      }
+    });
+    this.sseSessions.clear();
+    this.sseFallbackActive = false;
+    this.activeTransport = null;
     this.presenceHandlers = [];
     this.presenceSubscriptions.clear();
     this.typingHandlers.clear();
@@ -3007,6 +3061,7 @@ var RealtimeAPI = class {
    * 카테고리 구독
    */
   async subscribe(category, options = {}) {
+    this.assertBidirectional("subscribe");
     if (this.state !== "connected") {
       throw new Error("Not connected. Call connect() first.");
     }
@@ -3067,6 +3122,7 @@ var RealtimeAPI = class {
    * @param options 전송 옵션 (includeSelf: 발신자도 메시지 수신 여부, 기본값 true)
    */
   async sendMessage(category, data, options = {}) {
+    this.assertBidirectional("sendMessage");
     if (this.state !== "connected") {
       throw new Error("Not connected");
     }
@@ -3084,6 +3140,7 @@ var RealtimeAPI = class {
    * 히스토리 조회
    */
   async getHistory(category, limit) {
+    this.assertBidirectional("getHistory");
     if (this.state !== "connected") {
       throw new Error("Not connected");
     }
@@ -3139,9 +3196,22 @@ var RealtimeAPI = class {
    * ```
    */
   async stream(messages, handlers, options = {}) {
-    if (this.state !== "connected") {
-      throw new Error("Not connected. Call connect() first.");
+    const canWs = this.state === "connected" && this.activeTransport === "ws" && this.ws?.readyState === WebSocket.OPEN;
+    if (canWs) {
+      try {
+        return this.streamViaWS(messages, handlers, options);
+      } catch (e) {
+        if (this.options.fallback === "none") throw e;
+        this.log(`WS stream send failed (${e instanceof Error ? e.message : String(e)}); falling back to SSE`);
+      }
+    }
+    if (this.options.fallback !== "none") {
+      return this.streamViaSSE(messages, handlers, options);
     }
+    throw new Error("Not connected. Call connect() first.");
+  }
+  /** WebSocket 으로 AI 스트리밍 (기본 경로) */
+  streamViaWS(messages, handlers, options) {
     const requestId = this.generateRequestId();
     const sessionId = options.sessionId || this.generateRequestId();
     this.streamSessions.set(sessionId, {
@@ -3176,11 +3246,130 @@ var RealtimeAPI = class {
       }
     };
   }
+  /**
+   * HTTP SSE (`/v1/public/ai/chat/stream`) 로 AI 스트리밍 — WS 가 차단된 네트워크용 fallback.
+   *
+   * SSE 는 단방향이라 WS 의 `StreamDoneData` 토큰 카운트(total/prompt)를 받지 못하므로
+   * `totalTokens`/`promptTokens` 는 0 으로 채워진다(`fullText`/`duration` 은 정확). `mcpGroup`
+   * (MCP 도구) 은 SSE fallback 에서 미지원 — 지정 시 무시되고 도구 없이 스트리밍한다.
+   */
+  streamViaSSE(messages, handlers, options) {
+    const sessionId = options.sessionId || this.generateRequestId();
+    const controller = new AbortController();
+    this.sseSessions.set(sessionId, controller);
+    if (options.mcpGroup) {
+      this.log("mcpGroup is not supported in SSE fallback mode; streaming without MCP tools");
+    }
+    this.log(`Streaming via SSE fallback (session ${sessionId})`);
+    void this.runSseStream(sessionId, messages, handlers, options, controller.signal);
+    return {
+      sessionId,
+      stop: async () => {
+        await this.stopStream(sessionId);
+      }
+    };
+  }
+  async runSseStream(sessionId, messages, handlers, options, signal) {
+    const startedAt = Date.now();
+    let tokenIndex = 0;
+    let fullText = "";
+    let reader;
+    const wireMessages = options.system ? [{ role: "system", content: options.system }, ...messages] : messages;
+    const body = {
+      messages: wireMessages,
+      provider: options.provider,
+      model: options.model,
+      temperature: options.temperature,
+      maxTokens: options.maxTokens
+    };
+    try {
+      const response = await this.http.fetchRaw("/v1/public/ai/chat/stream", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+        signal
+      });
+      if (!response.ok) {
+        const errData = await response.json().catch(() => ({ error: "Stream request failed" }));
+        handlers.onError?.(new Error(errData.error || errData.message || "Stream request failed"));
+        return;
+      }
+      reader = response.body?.getReader();
+      if (!reader) {
+        handlers.onError?.(new Error("ReadableStream not supported"));
+        return;
+      }
+      const decoder = new TextDecoder();
+      let buffer = "";
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        buffer += decoder.decode(value, { stream: true });
+        const lines = buffer.split("\n");
+        buffer = lines.pop() || "";
+        for (const line of lines) {
+          if (!line.startsWith("data: ")) continue;
+          const data = line.slice(6).trim();
+          if (data === "[DONE]") {
+            handlers.onDone?.({ sessionId, fullText, totalTokens: 0, promptTokens: 0, duration: Date.now() - startedAt });
+            return;
+          }
+          try {
+            const ev = JSON.parse(data);
+            if (ev.error) {
+              handlers.onError?.(new Error(ev.message || ev.error || "stream error"));
+              return;
+            }
+            if (ev.type === "tool_start") {
+              handlers.onToolCall?.(ev.name || "", ev.arguments || {}, tokenIndex);
+              continue;
+            }
+            if (ev.type === "tool_end") {
+              handlers.onToolResult?.(ev.name || "", ev.success !== false, ev.durationMs || 0, tokenIndex);
+              continue;
+            }
+            if (ev.type === "sources" || ev.type === "searching" || ev.type === "heartbeat") {
+              continue;
+            }
+            if (ev.content) {
+              fullText += ev.content;
+              handlers.onToken?.(ev.content, tokenIndex++);
+            }
+            if (ev.done) {
+              handlers.onDone?.({ sessionId, fullText, totalTokens: 0, promptTokens: 0, duration: Date.now() - startedAt });
+              return;
+            }
+          } catch {
+          }
+        }
+      }
+    } catch (err) {
+      const aborted = signal.aborted || err instanceof DOMException && err.name === "AbortError" || typeof err === "object" && err !== null && err.name === "AbortError";
+      if (!aborted) {
+        handlers.onError?.(err instanceof Error ? err : new Error(String(err)));
+      }
+    } finally {
+      this.sseSessions.delete(sessionId);
+      if (reader) {
+        try {
+          await reader.cancel();
+        } catch {
+        }
+      }
+    }
+  }
   /**
    * 스트리밍 중지
    */
   async stopStream(sessionId) {
-    if (this.state !== "connected") {
+    const sse = this.sseSessions.get(sessionId);
+    if (sse) {
+      sse.abort();
+      this.sseSessions.delete(sessionId);
+      return;
+    }
+    if (this.state !== "connected" || !this.ws || this.ws.readyState !== WebSocket.OPEN) {
+      this.streamSessions.delete(sessionId);
       return;
     }
     const requestId = this.generateRequestId();
@@ -3239,6 +3428,7 @@ var RealtimeAPI = class {
    * ```
    */
   async setPresence(status, options = {}) {
+    this.assertBidirectional("setPresence");
     if (this.state !== "connected") {
       throw new Error("Not connected");
     }
@@ -3266,6 +3456,7 @@ var RealtimeAPI = class {
    * ```
    */
   async setPresenceOnDisconnect(status, metadata) {
+    this.assertBidirectional("setPresenceOnDisconnect");
     if (this.state !== "connected") {
       throw new Error("Not connected");
     }
@@ -3289,6 +3480,7 @@ var RealtimeAPI = class {
    * ```
    */
   async getPresence(userId) {
+    this.assertBidirectional("getPresence");
     if (this.state !== "connected") {
       throw new Error("Not connected");
     }
@@ -3319,6 +3511,7 @@ var RealtimeAPI = class {
    * ```
    */
   async getPresenceMany(userIds) {
+    this.assertBidirectional("getPresenceMany");
     if (this.state !== "connected") {
       throw new Error("Not connected");
     }
@@ -3358,6 +3551,7 @@ var RealtimeAPI = class {
    * ```
    */
   async subscribePresence(userId, handler) {
+    this.assertBidirectional("subscribePresence");
     if (this.state !== "connected") {
       throw new Error("Not connected");
     }
@@ -3427,6 +3621,7 @@ var RealtimeAPI = class {
    * ```
    */
   async startTyping(roomId) {
+    this.assertBidirectional("startTyping");
     if (this.state !== "connected") {
       throw new Error("Not connected");
     }
@@ -3451,6 +3646,7 @@ var RealtimeAPI = class {
    * ```
    */
   async stopTyping(roomId) {
+    this.assertBidirectional("stopTyping");
     if (this.state !== "connected") {
       throw new Error("Not connected");
     }
@@ -3480,6 +3676,7 @@ var RealtimeAPI = class {
    * ```
    */
   async onTypingChange(roomId, handler) {
+    this.assertBidirectional("onTypingChange");
     if (this.state !== "connected") {
       throw new Error("Not connected");
     }
@@ -3527,6 +3724,7 @@ var RealtimeAPI = class {
    * ```
    */
   async markRead(category, messageIds) {
+    this.assertBidirectional("markRead");
     if (this.state !== "connected") {
       throw new Error("Not connected");
     }
@@ -3675,6 +3873,8 @@ var RealtimeAPI = class {
         this._connectionId = data.connection_id;
         this._appId = data.app_id;
         this.state = "connected";
+        this.activeTransport = "ws";
+        this.sseFallbackActive = false;
         this.retryCount = 0;
         this.notifyStateChange();
         if (connectResolve) connectResolve();
@@ -3837,6 +4037,10 @@ var RealtimeAPI = class {
     }
   }
   handleDisconnect() {
+    if (this.sseFallbackActive) {
+      this.ws = null;
+      return;
+    }
     this.ws = null;
     this._connectionId = null;
     this.streamSessions.forEach((session) => {
@@ -3869,6 +4073,7 @@ var RealtimeAPI = class {
         3e4
       );
       setTimeout(async () => {
+        if (this.sseFallbackActive) return;
         try {
           await this.doConnect();
           this.log("Reconnected successfully, restoring subscriptions...");
@@ -3879,12 +4084,19 @@ var RealtimeAPI = class {
           );
         } catch (e) {
           this.logError("Reconnect failed", e);
+          if (this.retryCount >= this.options.maxRetries && this.options.fallback !== "none" && !this.sseFallbackActive) {
+            this.activateSseFallback(e);
+          }
         }
       }, delay);
     } else {
-      this.state = "disconnected";
-      this.notifyStateChange();
-      this.notifyError(new Error("Connection lost. Max retries exceeded."));
+      if (this.options.fallback !== "none") {
+        this.activateSseFallback(new Error("Connection lost. Max WS retries exceeded."));
+      } else {
+        this.state = "disconnected";
+        this.notifyStateChange();
+        this.notifyError(new Error("Connection lost. Max retries exceeded."));
+      }
     }
   }
   /**
@@ -3947,6 +4159,17 @@ var RealtimeAPI = class {
       }
     }
   }
+  /**
+   * 양방향(WS 전용) 기능을 SSE fallback 모드에서 호출하면 명확한 에러를 던진다.
+   * SSE 는 단방향이라 presence/typing/subscribe/sendMessage 를 지원하지 못한다.
+   */
+  assertBidirectional(feature) {
+    if (this.activeTransport === "sse") {
+      throw new Error(
+        `realtime.${feature}() requires a WebSocket connection, which is blocked on this network. Only AI streaming (realtime.stream) works in SSE fallback mode (cb.realtime.transport === 'sse').`
+      );
+    }
+  }
   sendRequest(message) {
     return new Promise((resolve, reject) => {
       if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {

package/package.json

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