connectbase-client 3.31.0 → 3.33.0

package/dist/index.d.mts

@@ -2951,6 +2951,21 @@ interface RealtimeConnectOptions {
     timeout?: number;
     /** 디버그 로깅 활성화 (기본: false) */
     debug?: boolean;
+    /**
+     * WebSocket 핸드셰이크가 실패할 때의 fallback transport (기본: `'sse'`).
+     *
+     * 일부 네트워크(특정 가정용 ISP/기업 프록시/미들박스)는 HTTPS 는 통과시키면서
+     * WebSocket upgrade 만 차단한다. 이 경우 `'sse'` 이면 `connect()` 가 reject 하지 않고
+     * **degraded(SSE) 모드로 resolve** 하며, 이후 `stream()` 호출은 자동으로 HTTP SSE
+     * (`/v1/public/ai/chat/stream`) 로 흘러 AI 스트리밍이 계속 동작한다 (앱 코드 변경 불필요).
+     *
+     * SSE 는 단방향(server→client)이므로 fallback 모드에서는 AI `stream()` 만 지원되고
+     * presence/typing/subscribe/sendMessage 같은 양방향 기능은 명시적 에러를 던진다.
+     * 현재 활성 transport 는 `cb.realtime.transport` 로 확인할 수 있다.
+     *
+     * `'none'` 이면 기존처럼 WS 실패 시 `connect()` 가 reject 한다.
+     */
+    fallback?: 'sse' | 'none';
 }
 /** 이벤트 핸들러 타입 */
 type MessageHandler<T = unknown> = (message: RealtimeMessage<T>) => void;
@@ -3171,10 +3186,26 @@ declare class RealtimeAPI {
     private clientId;
     private userId?;
     private _appId;
+    /**
+     * 현재 활성 transport.
+     * - `'ws'`: WebSocket 정상 연결
+     * - `'sse'`: WS 핸드셰이크 실패로 HTTP SSE fallback 모드 (AI `stream()` 만 지원)
+     * - `null`: 미연결
+     */
+    private activeTransport;
+    /** SSE fallback 모드 활성 여부. true 면 백그라운드 WS 재연결 머신을 정지한다. */
+    private sseFallbackActive;
+    /** SSE fallback 스트림의 AbortController (sessionId → controller) — stop()/disconnect() 에서 중단용 */
+    private sseSessions;
     /** 현재 연결 ID */
     get connectionId(): string | null;
     /** 현재 연결된 앱 ID */
     get appId(): string | null;
+    /**
+     * 현재 활성 transport (`'ws'` | `'sse'` | `null`).
+     * `'sse'` 이면 WS 가 차단되어 fallback 모드로 동작 중이며 AI `stream()` 만 가능하다.
+     */
+    get transport(): 'ws' | 'sse' | null;
     private options;
     private retryCount;
     private pendingRequests;
@@ -3195,6 +3226,11 @@ declare class RealtimeAPI {
      * - userId: 사용자 식별자 (표시용)
      */
     connect(options?: RealtimeConnectOptions): Promise<void>;
+    /**
+     * SSE fallback 모드로 전환한다. WS 는 사용 불가하지만 state 는 'connected' 로 두어
+     * (degraded) AI stream() 이 SSE 로 동작하게 한다. 백그라운드 WS 재연결 머신은 정지한다.
+     */
+    private activateSseFallback;
     /**
      * 연결 해제
      */
@@ -3251,6 +3287,17 @@ declare class RealtimeAPI {
      * ```
      */
     stream(messages: StreamMessage[], handlers: StreamHandlers, options?: StreamOptions): Promise<StreamSession>;
+    /** WebSocket 으로 AI 스트리밍 (기본 경로) */
+    private streamViaWS;
+    /**
+     * HTTP SSE (`/v1/public/ai/chat/stream`) 로 AI 스트리밍 — WS 가 차단된 네트워크용 fallback.
+     *
+     * SSE 는 단방향이라 WS 의 `StreamDoneData` 토큰 카운트(total/prompt)를 받지 못하므로
+     * `totalTokens`/`promptTokens` 는 0 으로 채워진다(`fullText`/`duration` 은 정확). `mcpGroup`
+     * (MCP 도구) 은 SSE fallback 에서 미지원 — 지정 시 무시되고 도구 없이 스트리밍한다.
+     */
+    private streamViaSSE;
+    private runSseStream;
     /**
      * 스트리밍 중지
      */
@@ -3438,6 +3485,11 @@ declare class RealtimeAPI {
      * 재연결 성공 후 호출됩니다.
      */
     private restoreSubscriptions;
+    /**
+     * 양방향(WS 전용) 기능을 SSE fallback 모드에서 호출하면 명확한 에러를 던진다.
+     * SSE 는 단방향이라 presence/typing/subscribe/sendMessage 를 지원하지 못한다.
+     */
+    private assertBidirectional;
     private sendRequest;
     private sendRaw;
     private notifyStateChange;
@@ -7543,6 +7595,21 @@ interface AIChatRequest {
     topK?: number;
     agentic?: boolean;
     toolGroupId?: string;
+    /**
+     * 0 보다 크면, 서버측 도구 그룹 실행(`toolGroupId` 사용 시)에서 각 도구 결과를 모델에
+     * **재투입하기 전** N 자(rune 기준)로 잘라낸다(말미에 잘림 표시). SSE `onToolEvent` 의
+     * `tool_end.result` 로 표시되는 값은 원문을 유지한다.
+     *
+     * 거대한 도구 결과(예: 복잡한 페이지의 `browser_snapshot`)가 누적 컨텍스트를 부풀려
+     * 매 턴 prefill 을 무겁게 만들 때, 표시는 원문으로 두고 모델 재투입분만 압축해
+     * 지연을 줄이는 용도. 미지정/0 이면 자르지 않는다.
+     */
+    toolResultMaxChars?: number;
+    /**
+     * 요청에 포함한 MCP 도구(`tools`)를 호출할 외부 MCP 서버의 Public Key (cb_pk_* 형식).
+     * MCP 도구를 직접 넘기지 않으면 불필요하다.
+     */
+    mcpPublicKey?: string;
 }
 /**
  * `chatStream` 콜백.

package/dist/index.d.ts

@@ -2951,6 +2951,21 @@ interface RealtimeConnectOptions {
     timeout?: number;
     /** 디버그 로깅 활성화 (기본: false) */
     debug?: boolean;
+    /**
+     * WebSocket 핸드셰이크가 실패할 때의 fallback transport (기본: `'sse'`).
+     *
+     * 일부 네트워크(특정 가정용 ISP/기업 프록시/미들박스)는 HTTPS 는 통과시키면서
+     * WebSocket upgrade 만 차단한다. 이 경우 `'sse'` 이면 `connect()` 가 reject 하지 않고
+     * **degraded(SSE) 모드로 resolve** 하며, 이후 `stream()` 호출은 자동으로 HTTP SSE
+     * (`/v1/public/ai/chat/stream`) 로 흘러 AI 스트리밍이 계속 동작한다 (앱 코드 변경 불필요).
+     *
+     * SSE 는 단방향(server→client)이므로 fallback 모드에서는 AI `stream()` 만 지원되고
+     * presence/typing/subscribe/sendMessage 같은 양방향 기능은 명시적 에러를 던진다.
+     * 현재 활성 transport 는 `cb.realtime.transport` 로 확인할 수 있다.
+     *
+     * `'none'` 이면 기존처럼 WS 실패 시 `connect()` 가 reject 한다.
+     */
+    fallback?: 'sse' | 'none';
 }
 /** 이벤트 핸들러 타입 */
 type MessageHandler<T = unknown> = (message: RealtimeMessage<T>) => void;
@@ -3171,10 +3186,26 @@ declare class RealtimeAPI {
     private clientId;
     private userId?;
     private _appId;
+    /**
+     * 현재 활성 transport.
+     * - `'ws'`: WebSocket 정상 연결
+     * - `'sse'`: WS 핸드셰이크 실패로 HTTP SSE fallback 모드 (AI `stream()` 만 지원)
+     * - `null`: 미연결
+     */
+    private activeTransport;
+    /** SSE fallback 모드 활성 여부. true 면 백그라운드 WS 재연결 머신을 정지한다. */
+    private sseFallbackActive;
+    /** SSE fallback 스트림의 AbortController (sessionId → controller) — stop()/disconnect() 에서 중단용 */
+    private sseSessions;
     /** 현재 연결 ID */
     get connectionId(): string | null;
     /** 현재 연결된 앱 ID */
     get appId(): string | null;
+    /**
+     * 현재 활성 transport (`'ws'` | `'sse'` | `null`).
+     * `'sse'` 이면 WS 가 차단되어 fallback 모드로 동작 중이며 AI `stream()` 만 가능하다.
+     */
+    get transport(): 'ws' | 'sse' | null;
     private options;
     private retryCount;
     private pendingRequests;
@@ -3195,6 +3226,11 @@ declare class RealtimeAPI {
      * - userId: 사용자 식별자 (표시용)
      */
     connect(options?: RealtimeConnectOptions): Promise<void>;
+    /**
+     * SSE fallback 모드로 전환한다. WS 는 사용 불가하지만 state 는 'connected' 로 두어
+     * (degraded) AI stream() 이 SSE 로 동작하게 한다. 백그라운드 WS 재연결 머신은 정지한다.
+     */
+    private activateSseFallback;
     /**
      * 연결 해제
      */
@@ -3251,6 +3287,17 @@ declare class RealtimeAPI {
      * ```
      */
     stream(messages: StreamMessage[], handlers: StreamHandlers, options?: StreamOptions): Promise<StreamSession>;
+    /** WebSocket 으로 AI 스트리밍 (기본 경로) */
+    private streamViaWS;
+    /**
+     * HTTP SSE (`/v1/public/ai/chat/stream`) 로 AI 스트리밍 — WS 가 차단된 네트워크용 fallback.
+     *
+     * SSE 는 단방향이라 WS 의 `StreamDoneData` 토큰 카운트(total/prompt)를 받지 못하므로
+     * `totalTokens`/`promptTokens` 는 0 으로 채워진다(`fullText`/`duration` 은 정확). `mcpGroup`
+     * (MCP 도구) 은 SSE fallback 에서 미지원 — 지정 시 무시되고 도구 없이 스트리밍한다.
+     */
+    private streamViaSSE;
+    private runSseStream;
     /**
      * 스트리밍 중지
      */
@@ -3438,6 +3485,11 @@ declare class RealtimeAPI {
      * 재연결 성공 후 호출됩니다.
      */
     private restoreSubscriptions;
+    /**
+     * 양방향(WS 전용) 기능을 SSE fallback 모드에서 호출하면 명확한 에러를 던진다.
+     * SSE 는 단방향이라 presence/typing/subscribe/sendMessage 를 지원하지 못한다.
+     */
+    private assertBidirectional;
     private sendRequest;
     private sendRaw;
     private notifyStateChange;
@@ -7543,6 +7595,21 @@ interface AIChatRequest {
     topK?: number;
     agentic?: boolean;
     toolGroupId?: string;
+    /**
+     * 0 보다 크면, 서버측 도구 그룹 실행(`toolGroupId` 사용 시)에서 각 도구 결과를 모델에
+     * **재투입하기 전** N 자(rune 기준)로 잘라낸다(말미에 잘림 표시). SSE `onToolEvent` 의
+     * `tool_end.result` 로 표시되는 값은 원문을 유지한다.
+     *
+     * 거대한 도구 결과(예: 복잡한 페이지의 `browser_snapshot`)가 누적 컨텍스트를 부풀려
+     * 매 턴 prefill 을 무겁게 만들 때, 표시는 원문으로 두고 모델 재투입분만 압축해
+     * 지연을 줄이는 용도. 미지정/0 이면 자르지 않는다.
+     */
+    toolResultMaxChars?: number;
+    /**
+     * 요청에 포함한 MCP 도구(`tools`)를 호출할 외부 MCP 서버의 Public Key (cb_pk_* 형식).
+     * MCP 도구를 직접 넘기지 않으면 불필요하다.
+     */
+    mcpPublicKey?: string;
 }
 /**
  * `chatStream` 콜백.

package/dist/index.js

@@ -153,6 +153,10 @@ function sanitizePathForBreadcrumb(rawUrl) {
 }
 
 // src/core/http.ts
+function fetchCredentialsForPath(url) {
+  const path = url.split("?")[0];
+  return path.startsWith("/v1/public/") ? "omit" : "include";
+}
 var TOKEN_STORAGE_KEY = "cb_auth_tokens";
 function decodeJwtPayload(token) {
   try {
@@ -679,7 +683,7 @@ var HttpClient = class {
     try {
       const response = await fetch(`${this.config.baseUrl}${url}`, {
         ...init,
-        credentials: "include",
+        credentials: fetchCredentialsForPath(url),
         signal
       });
       return { response, ok: response.ok, status: response.status };
@@ -748,7 +752,7 @@ var HttpClient = class {
     }
     return fetch(`${this.config.baseUrl}${url}`, {
       ...init,
-      credentials: "include",
+      credentials: fetchCredentialsForPath(url),
       headers: mergedHeaders
     });
   }
@@ -2955,13 +2959,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();
@@ -2990,6 +3006,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 연결 옵션
@@ -3010,10 +3033,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();
+  }
   /**
    * 연결 해제
    */
@@ -3036,6 +3085,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();
@@ -3049,6 +3107,7 @@ var RealtimeAPI = class {
    * 카테고리 구독
    */
   async subscribe(category, options = {}) {
+    this.assertBidirectional("subscribe");
     if (this.state !== "connected") {
       throw new Error("Not connected. Call connect() first.");
     }
@@ -3109,6 +3168,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");
     }
@@ -3126,6 +3186,7 @@ var RealtimeAPI = class {
    * 히스토리 조회
    */
   async getHistory(category, limit) {
+    this.assertBidirectional("getHistory");
     if (this.state !== "connected") {
       throw new Error("Not connected");
     }
@@ -3181,9 +3242,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, {
@@ -3218,11 +3292,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();
@@ -3281,6 +3474,7 @@ var RealtimeAPI = class {
    * ```
    */
   async setPresence(status, options = {}) {
+    this.assertBidirectional("setPresence");
     if (this.state !== "connected") {
       throw new Error("Not connected");
     }
@@ -3308,6 +3502,7 @@ var RealtimeAPI = class {
    * ```
    */
   async setPresenceOnDisconnect(status, metadata) {
+    this.assertBidirectional("setPresenceOnDisconnect");
     if (this.state !== "connected") {
       throw new Error("Not connected");
     }
@@ -3331,6 +3526,7 @@ var RealtimeAPI = class {
    * ```
    */
   async getPresence(userId) {
+    this.assertBidirectional("getPresence");
     if (this.state !== "connected") {
       throw new Error("Not connected");
     }
@@ -3361,6 +3557,7 @@ var RealtimeAPI = class {
    * ```
    */
   async getPresenceMany(userIds) {
+    this.assertBidirectional("getPresenceMany");
     if (this.state !== "connected") {
       throw new Error("Not connected");
     }
@@ -3400,6 +3597,7 @@ var RealtimeAPI = class {
    * ```
    */
   async subscribePresence(userId, handler) {
+    this.assertBidirectional("subscribePresence");
     if (this.state !== "connected") {
       throw new Error("Not connected");
     }
@@ -3469,6 +3667,7 @@ var RealtimeAPI = class {
    * ```
    */
   async startTyping(roomId) {
+    this.assertBidirectional("startTyping");
     if (this.state !== "connected") {
       throw new Error("Not connected");
     }
@@ -3493,6 +3692,7 @@ var RealtimeAPI = class {
    * ```
    */
   async stopTyping(roomId) {
+    this.assertBidirectional("stopTyping");
     if (this.state !== "connected") {
       throw new Error("Not connected");
     }
@@ -3522,6 +3722,7 @@ var RealtimeAPI = class {
    * ```
    */
   async onTypingChange(roomId, handler) {
+    this.assertBidirectional("onTypingChange");
     if (this.state !== "connected") {
       throw new Error("Not connected");
     }
@@ -3569,6 +3770,7 @@ var RealtimeAPI = class {
    * ```
    */
   async markRead(category, messageIds) {
+    this.assertBidirectional("markRead");
     if (this.state !== "connected") {
       throw new Error("Not connected");
     }
@@ -3717,6 +3919,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();
@@ -3879,6 +4083,10 @@ var RealtimeAPI = class {
     }
   }
   handleDisconnect() {
+    if (this.sseFallbackActive) {
+      this.ws = null;
+      return;
+    }
     this.ws = null;
     this._connectionId = null;
     this.streamSessions.forEach((session) => {
@@ -3911,6 +4119,7 @@ var RealtimeAPI = class {
         3e4
       );
       setTimeout(async () => {
+        if (this.sseFallbackActive) return;
         try {
           await this.doConnect();
           this.log("Reconnected successfully, restoring subscriptions...");
@@ -3921,12 +4130,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."));
+      }
     }
   }
   /**
@@ -3989,6 +4205,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) {