connectbase-client 5.12.0 → 5.12.2

package/dist/index.d.mts

@@ -7154,39 +7154,6 @@ interface ReadReceiptInfo {
 /** 읽음 확인 핸들러 */
 type ReadReceiptHandler = (receipt: ReadReceiptInfo) => void;
 
-/**
- * Realtime API
- * WebSocket 기반 실시간 통신 API
- *
- * @example
- * ```typescript
- * // 연결
- * await client.realtime.connect()
- *
- * // 카테고리 구독
- * const chat = await client.realtime.subscribe('chat-room-1')
- *
- * // 메시지 수신
- * chat.onMessage((msg) => {
- *     console.log('Received:', msg.data)
- * })
- *
- * // 메시지 전송
- * await chat.send({ text: 'Hello!' })
- *
- * // 히스토리 조회 (persist=true인 카테고리만)
- * if (chat.info.persist) {
- *     const history = await chat.getHistory(50)
- *     console.log('History:', history.messages)
- * }
- *
- * // 구독 해제
- * await chat.unsubscribe()
- *
- * // 연결 해제
- * client.realtime.disconnect()
- * ```
- */
 declare class RealtimeAPI {
     private http;
     private socketUrl;

package/dist/index.d.ts

@@ -7154,39 +7154,6 @@ interface ReadReceiptInfo {
 /** 읽음 확인 핸들러 */
 type ReadReceiptHandler = (receipt: ReadReceiptInfo) => void;
 
-/**
- * Realtime API
- * WebSocket 기반 실시간 통신 API
- *
- * @example
- * ```typescript
- * // 연결
- * await client.realtime.connect()
- *
- * // 카테고리 구독
- * const chat = await client.realtime.subscribe('chat-room-1')
- *
- * // 메시지 수신
- * chat.onMessage((msg) => {
- *     console.log('Received:', msg.data)
- * })
- *
- * // 메시지 전송
- * await chat.send({ text: 'Hello!' })
- *
- * // 히스토리 조회 (persist=true인 카테고리만)
- * if (chat.info.persist) {
- *     const history = await chat.getHistory(50)
- *     console.log('History:', history.messages)
- * }
- *
- * // 구독 해제
- * await chat.unsubscribe()
- *
- * // 연결 해제
- * client.realtime.disconnect()
- * ```
- */
 declare class RealtimeAPI {
     private http;
     private socketUrl;

package/dist/index.js

@@ -7209,6 +7209,7 @@ var QueueAPI = class {
 };
 
 // src/api/realtime.ts
+var UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 var RealtimeAPI = class {
   constructor(http, socketUrl) {
     this.ws = null;
@@ -7286,6 +7287,11 @@ var RealtimeAPI = class {
     if (options.userId) {
       this.userId = options.userId;
     }
+    if (this.userId && !this.options.accessToken && UUID_RE.test(this.userId)) {
+      throw new Error(
+        `Invalid userId: "${this.userId}" looks like a UUID, which is reserved for authenticated members. Pass that member's accessToken (JWT) instead of userId+publicKey, or use a non-UUID identifier for anonymous/guest connections.`
+      );
+    }
     this.connectPromise = this.doConnect();
     try {
       await this.connectPromise;
@@ -7305,6 +7311,7 @@ var RealtimeAPI = class {
    * (degraded) AI stream() 이 SSE 로 동작하게 한다. 백그라운드 WS 재연결 머신은 정지한다.
    */
   activateSseFallback(cause) {
+    if (this.sseFallbackActive) return;
     if (this.ws) {
       try {
         this.ws.close();
@@ -7312,14 +7319,20 @@ var RealtimeAPI = class {
       }
       this.ws = null;
     }
+    const causeMsg = cause instanceof Error ? cause.message : String(cause);
     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`
+      `WS unavailable (${causeMsg}); using SSE fallback transport for AI streaming`
     );
     this.notifyStateChange();
+    this.notifyError(
+      new Error(
+        `Realtime WebSocket unavailable, downgraded to SSE fallback transport (cb.realtime.transport === 'sse'). Only realtime.stream() works in this mode \u2014 subscribe/send/setPresence/typing calls will throw. Cause: ${causeMsg}`
+      )
+    );
   }
   /**
    * 연결 해제
@@ -11658,7 +11671,7 @@ var HttpClient = class {
     if (this.persistence !== "none") return;
     if (!this.config.refreshToken) return;
     try {
-      await this.refreshAccessToken();
+      await this.refreshAccessToken({ silent: true });
     } catch {
     }
   }
@@ -11791,7 +11804,8 @@ var HttpClient = class {
   getAppId() {
     return this.config.appId;
   }
-  async refreshAccessToken() {
+  async refreshAccessToken(options) {
+    const silent = options?.silent ?? false;
     if (this.isRefreshing) {
       return this.refreshPromise;
     }
@@ -11905,27 +11919,35 @@ var HttpClient = class {
         );
         this.refreshLockedUntil = Date.now() + backoffMs;
         if (failureKind === "permanent") {
-          this.clearTokens();
-          this.config.onTokenExpired?.();
+          if (!silent) {
+            this.clearTokens();
+            this.config.onTokenExpired?.();
+          }
           const error2 = new AuthError(`${baseMsg}. Please login again.`);
-          this.emitError(error2);
-          this.config.onAuthError?.(error2);
+          if (!silent) {
+            this.emitError(error2);
+            this.config.onAuthError?.(error2);
+          }
           throw error2;
         }
         if (failureKind === "client_bug") {
           const error2 = new AuthError(
             `${baseMsg}. Client request invalid; tokens preserved.`
           );
-          this.emitError(error2);
-          this.config.onAuthError?.(error2);
+          if (!silent) {
+            this.emitError(error2);
+            this.config.onAuthError?.(error2);
+          }
           throw error2;
         }
         const error = new AuthError(
           `${baseMsg}. Transient failure; tokens preserved, will retry after backoff.`
         );
-        this.emitError(error);
-        this.config.onTransientRefreshFailure?.(error);
-        this.config.onAuthError?.(error);
+        if (!silent) {
+          this.emitError(error);
+          this.config.onTransientRefreshFailure?.(error);
+          this.config.onAuthError?.(error);
+        }
         throw error;
       } finally {
         cleanup();

package/dist/index.mjs

@@ -7160,6 +7160,7 @@ var QueueAPI = class {
 };
 
 // src/api/realtime.ts
+var UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 var RealtimeAPI = class {
   constructor(http, socketUrl) {
     this.ws = null;
@@ -7237,6 +7238,11 @@ var RealtimeAPI = class {
     if (options.userId) {
       this.userId = options.userId;
     }
+    if (this.userId && !this.options.accessToken && UUID_RE.test(this.userId)) {
+      throw new Error(
+        `Invalid userId: "${this.userId}" looks like a UUID, which is reserved for authenticated members. Pass that member's accessToken (JWT) instead of userId+publicKey, or use a non-UUID identifier for anonymous/guest connections.`
+      );
+    }
     this.connectPromise = this.doConnect();
     try {
       await this.connectPromise;
@@ -7256,6 +7262,7 @@ var RealtimeAPI = class {
    * (degraded) AI stream() 이 SSE 로 동작하게 한다. 백그라운드 WS 재연결 머신은 정지한다.
    */
   activateSseFallback(cause) {
+    if (this.sseFallbackActive) return;
     if (this.ws) {
       try {
         this.ws.close();
@@ -7263,14 +7270,20 @@ var RealtimeAPI = class {
       }
       this.ws = null;
     }
+    const causeMsg = cause instanceof Error ? cause.message : String(cause);
     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`
+      `WS unavailable (${causeMsg}); using SSE fallback transport for AI streaming`
     );
     this.notifyStateChange();
+    this.notifyError(
+      new Error(
+        `Realtime WebSocket unavailable, downgraded to SSE fallback transport (cb.realtime.transport === 'sse'). Only realtime.stream() works in this mode \u2014 subscribe/send/setPresence/typing calls will throw. Cause: ${causeMsg}`
+      )
+    );
   }
   /**
    * 연결 해제
@@ -11609,7 +11622,7 @@ var HttpClient = class {
     if (this.persistence !== "none") return;
     if (!this.config.refreshToken) return;
     try {
-      await this.refreshAccessToken();
+      await this.refreshAccessToken({ silent: true });
     } catch {
     }
   }
@@ -11742,7 +11755,8 @@ var HttpClient = class {
   getAppId() {
     return this.config.appId;
   }
-  async refreshAccessToken() {
+  async refreshAccessToken(options) {
+    const silent = options?.silent ?? false;
     if (this.isRefreshing) {
       return this.refreshPromise;
     }
@@ -11856,27 +11870,35 @@ var HttpClient = class {
         );
         this.refreshLockedUntil = Date.now() + backoffMs;
         if (failureKind === "permanent") {
-          this.clearTokens();
-          this.config.onTokenExpired?.();
+          if (!silent) {
+            this.clearTokens();
+            this.config.onTokenExpired?.();
+          }
           const error2 = new AuthError(`${baseMsg}. Please login again.`);
-          this.emitError(error2);
-          this.config.onAuthError?.(error2);
+          if (!silent) {
+            this.emitError(error2);
+            this.config.onAuthError?.(error2);
+          }
           throw error2;
         }
         if (failureKind === "client_bug") {
           const error2 = new AuthError(
             `${baseMsg}. Client request invalid; tokens preserved.`
           );
-          this.emitError(error2);
-          this.config.onAuthError?.(error2);
+          if (!silent) {
+            this.emitError(error2);
+            this.config.onAuthError?.(error2);
+          }
           throw error2;
         }
         const error = new AuthError(
           `${baseMsg}. Transient failure; tokens preserved, will retry after backoff.`
         );
-        this.emitError(error);
-        this.config.onTransientRefreshFailure?.(error);
-        this.config.onAuthError?.(error);
+        if (!silent) {
+          this.emitError(error);
+          this.config.onTransientRefreshFailure?.(error);
+          this.config.onAuthError?.(error);
+        }
         throw error;
       } finally {
         cleanup();

package/package.json

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