connectbase-client 5.12.1 → 5.12.3

package/dist/index.d.mts

@@ -276,6 +276,19 @@ declare class HttpClient {
      * 반복하지 않고 한 번에 포기하는 쪽이 안전하다.
      */
     private directDisabled;
+    /**
+     * 서버가 `X-CB-Realtime-Direct-Base` 로 알려준 socket-server 저지연 원본(`wss://...`).
+     * HTTP direct(`directBaseUrl`)와 별도 값·별도 킬 스위치 — core-server 응답에서만 학습되고
+     * (WS 업그레이드 응답 헤더는 브라우저가 못 읽는다), `RealtimeAPI.doConnect()` 가 매 연결
+     * 시도마다 lazy 하게 조회한다. platform-issue 019fe448.
+     */
+    private directRealtimeBaseUrl;
+    /**
+     * realtime WS 연결이 direct 원본에서 네트워크 레벨로 실패하면 세운다 — `directDisabled`
+     * 와 같은 철학("한 번 실패하면 이 세션에서는 포기하고 원래 호스트로")이지만, 실패 감지가
+     * WS 상태 머신(RealtimeAPI) 쪽에서 일어나므로 별도 플래그로 둔다.
+     */
+    private directRealtimeDisabled;
     /**
      * 클라이언트 생성 시 명시된 요청 타임아웃(ms). 미지정이면 `undefined`.
      *
@@ -377,6 +390,18 @@ declare class HttpClient {
      * Base URL 반환
      */
     getBaseUrl(): string;
+    /**
+     * socket-server 의 direct(저지연) WS 원본. 아직 학습 전이거나(REST 요청을 한 번도 안
+     * 보냈거나 서버가 광고를 안 함) 네트워크 레벨로 실패해 이 세션에서 포기했으면 `null` —
+     * 호출자(`RealtimeAPI`)는 이 경우 원래 소켓 URL로 폴백해야 한다.
+     */
+    getDirectRealtimeBaseUrl(): string | null;
+    /**
+     * direct WS 원본이 네트워크 레벨로 실패했을 때 `RealtimeAPI` 가 호출한다. 이후 연결
+     * 시도는 이 세션 동안 전부 원래 소켓 URL로 간다 — direct 는 최적화일 뿐 필수가 아니므로
+     * 재시도를 반복하지 않는다(`directDisabled`/HTTP direct 와 같은 철학).
+     */
+    disableDirectRealtime(): void;
     /**
      * 이 클라이언트에 설정된 앱 ID 반환 (미설정 시 undefined).
      *
@@ -7154,39 +7179,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

@@ -276,6 +276,19 @@ declare class HttpClient {
      * 반복하지 않고 한 번에 포기하는 쪽이 안전하다.
      */
     private directDisabled;
+    /**
+     * 서버가 `X-CB-Realtime-Direct-Base` 로 알려준 socket-server 저지연 원본(`wss://...`).
+     * HTTP direct(`directBaseUrl`)와 별도 값·별도 킬 스위치 — core-server 응답에서만 학습되고
+     * (WS 업그레이드 응답 헤더는 브라우저가 못 읽는다), `RealtimeAPI.doConnect()` 가 매 연결
+     * 시도마다 lazy 하게 조회한다. platform-issue 019fe448.
+     */
+    private directRealtimeBaseUrl;
+    /**
+     * realtime WS 연결이 direct 원본에서 네트워크 레벨로 실패하면 세운다 — `directDisabled`
+     * 와 같은 철학("한 번 실패하면 이 세션에서는 포기하고 원래 호스트로")이지만, 실패 감지가
+     * WS 상태 머신(RealtimeAPI) 쪽에서 일어나므로 별도 플래그로 둔다.
+     */
+    private directRealtimeDisabled;
     /**
      * 클라이언트 생성 시 명시된 요청 타임아웃(ms). 미지정이면 `undefined`.
      *
@@ -377,6 +390,18 @@ declare class HttpClient {
      * Base URL 반환
      */
     getBaseUrl(): string;
+    /**
+     * socket-server 의 direct(저지연) WS 원본. 아직 학습 전이거나(REST 요청을 한 번도 안
+     * 보냈거나 서버가 광고를 안 함) 네트워크 레벨로 실패해 이 세션에서 포기했으면 `null` —
+     * 호출자(`RealtimeAPI`)는 이 경우 원래 소켓 URL로 폴백해야 한다.
+     */
+    getDirectRealtimeBaseUrl(): string | null;
+    /**
+     * direct WS 원본이 네트워크 레벨로 실패했을 때 `RealtimeAPI` 가 호출한다. 이후 연결
+     * 시도는 이 세션 동안 전부 원래 소켓 URL로 간다 — direct 는 최적화일 뿐 필수가 아니므로
+     * 재시도를 반복하지 않는다(`directDisabled`/HTTP direct 와 같은 철학).
+     */
+    disableDirectRealtime(): void;
     /**
      * 이 클라이언트에 설정된 앱 ID 반환 (미설정 시 undefined).
      *
@@ -7154,39 +7179,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;
@@ -8135,7 +8141,9 @@ var RealtimeAPI = class {
       this.state = "connecting";
       this.notifyStateChange();
       this.log("Connecting...");
-      const wsUrl = this.socketUrl.replace(/^http/, "ws");
+      const directWsBase = this.http.getDirectRealtimeBaseUrl();
+      const usingDirect = !!directWsBase;
+      const wsUrl = (directWsBase ?? this.socketUrl).replace(/^http/, "ws");
       let url;
       if (this.options.accessToken) {
         url = `${wsUrl}/v1/realtime/auth?access_token=${encodeURIComponent(this.options.accessToken)}&client_id=${this.clientId}`;
@@ -8165,6 +8173,7 @@ var RealtimeAPI = class {
             this.ws.close();
             this.ws = null;
           }
+          if (usingDirect) this.http.disableDirectRealtime();
           this.state = "disconnected";
           this.notifyStateChange();
           reject(
@@ -8203,6 +8212,7 @@ var RealtimeAPI = class {
           if (!settled && this.state === "connecting") {
             settled = true;
             clearTimeout(timeoutId);
+            if (usingDirect) this.http.disableDirectRealtime();
             reject(
               new Error(
                 `Connection closed: ${event.reason || "unknown reason"}`
@@ -8220,12 +8230,14 @@ var RealtimeAPI = class {
           if (!settled && this.state === "connecting") {
             settled = true;
             clearTimeout(timeoutId);
+            if (usingDirect) this.http.disableDirectRealtime();
             reject(new Error("Failed to connect"));
           }
         };
       } catch (e) {
         settled = true;
         clearTimeout(timeoutId);
+        if (usingDirect) this.http.disableDirectRealtime();
         reject(e);
       }
     });
@@ -11544,6 +11556,19 @@ var HttpClient = class {
      * 반복하지 않고 한 번에 포기하는 쪽이 안전하다.
      */
     this.directDisabled = false;
+    /**
+     * 서버가 `X-CB-Realtime-Direct-Base` 로 알려준 socket-server 저지연 원본(`wss://...`).
+     * HTTP direct(`directBaseUrl`)와 별도 값·별도 킬 스위치 — core-server 응답에서만 학습되고
+     * (WS 업그레이드 응답 헤더는 브라우저가 못 읽는다), `RealtimeAPI.doConnect()` 가 매 연결
+     * 시도마다 lazy 하게 조회한다. platform-issue 019fe448.
+     */
+    this.directRealtimeBaseUrl = null;
+    /**
+     * realtime WS 연결이 direct 원본에서 네트워크 레벨로 실패하면 세운다 — `directDisabled`
+     * 와 같은 철학("한 번 실패하면 이 세션에서는 포기하고 원래 호스트로")이지만, 실패 감지가
+     * WS 상태 머신(RealtimeAPI) 쪽에서 일어나므로 별도 플래그로 둔다.
+     */
+    this.directRealtimeDisabled = false;
     this.config = { ...config };
     this.storageKey = this.buildStorageKey();
     this.warnIfUnsafePersistence();
@@ -11789,6 +11814,22 @@ var HttpClient = class {
   getBaseUrl() {
     return this.config.baseUrl;
   }
+  /**
+   * socket-server 의 direct(저지연) WS 원본. 아직 학습 전이거나(REST 요청을 한 번도 안
+   * 보냈거나 서버가 광고를 안 함) 네트워크 레벨로 실패해 이 세션에서 포기했으면 `null` —
+   * 호출자(`RealtimeAPI`)는 이 경우 원래 소켓 URL로 폴백해야 한다.
+   */
+  getDirectRealtimeBaseUrl() {
+    return this.directRealtimeDisabled ? null : this.directRealtimeBaseUrl;
+  }
+  /**
+   * direct WS 원본이 네트워크 레벨로 실패했을 때 `RealtimeAPI` 가 호출한다. 이후 연결
+   * 시도는 이 세션 동안 전부 원래 소켓 URL로 간다 — direct 는 최적화일 뿐 필수가 아니므로
+   * 재시도를 반복하지 않는다(`directDisabled`/HTTP direct 와 같은 철학).
+   */
+  disableDirectRealtime() {
+    this.directRealtimeDisabled = true;
+  }
   /**
    * 이 클라이언트에 설정된 앱 ID 반환 (미설정 시 undefined).
    *
@@ -12172,17 +12213,37 @@ var HttpClient = class {
    * 일은 없어야 한다.
    */
   learnDirectOrigin(response) {
-    if (this.directDisabled || this.directBaseUrl) return;
-    const advertised = response.headers?.get("X-CB-Direct-Base");
-    if (!advertised) return;
+    if (!response.headers) return;
+    const tail = (h) => h.split(".").slice(-2).join(".");
+    let base;
     try {
-      const next = new URL(advertised);
-      const base = new URL(this.config.baseUrl);
-      if (next.protocol !== "https:") return;
-      const tail = (h) => h.split(".").slice(-2).join(".");
-      if (tail(next.hostname) !== tail(base.hostname)) return;
-      this.directBaseUrl = next.origin;
+      base = new URL(this.config.baseUrl);
     } catch {
+      return;
+    }
+    if (!this.directDisabled && !this.directBaseUrl) {
+      const advertised = response.headers.get("X-CB-Direct-Base");
+      if (advertised) {
+        try {
+          const next = new URL(advertised);
+          if (next.protocol === "https:" && tail(next.hostname) === tail(base.hostname)) {
+            this.directBaseUrl = next.origin;
+          }
+        } catch {
+        }
+      }
+    }
+    if (!this.directRealtimeDisabled && !this.directRealtimeBaseUrl) {
+      const advertisedRealtime = response.headers.get("X-CB-Realtime-Direct-Base");
+      if (advertisedRealtime) {
+        try {
+          const next = new URL(advertisedRealtime);
+          if (next.protocol === "wss:" && tail(next.hostname) === tail(base.hostname)) {
+            this.directRealtimeBaseUrl = next.origin;
+          }
+        } catch {
+        }
+      }
     }
   }
   /**

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;
@@ -8086,7 +8092,9 @@ var RealtimeAPI = class {
       this.state = "connecting";
       this.notifyStateChange();
       this.log("Connecting...");
-      const wsUrl = this.socketUrl.replace(/^http/, "ws");
+      const directWsBase = this.http.getDirectRealtimeBaseUrl();
+      const usingDirect = !!directWsBase;
+      const wsUrl = (directWsBase ?? this.socketUrl).replace(/^http/, "ws");
       let url;
       if (this.options.accessToken) {
         url = `${wsUrl}/v1/realtime/auth?access_token=${encodeURIComponent(this.options.accessToken)}&client_id=${this.clientId}`;
@@ -8116,6 +8124,7 @@ var RealtimeAPI = class {
             this.ws.close();
             this.ws = null;
           }
+          if (usingDirect) this.http.disableDirectRealtime();
           this.state = "disconnected";
           this.notifyStateChange();
           reject(
@@ -8154,6 +8163,7 @@ var RealtimeAPI = class {
           if (!settled && this.state === "connecting") {
             settled = true;
             clearTimeout(timeoutId);
+            if (usingDirect) this.http.disableDirectRealtime();
             reject(
               new Error(
                 `Connection closed: ${event.reason || "unknown reason"}`
@@ -8171,12 +8181,14 @@ var RealtimeAPI = class {
           if (!settled && this.state === "connecting") {
             settled = true;
             clearTimeout(timeoutId);
+            if (usingDirect) this.http.disableDirectRealtime();
             reject(new Error("Failed to connect"));
           }
         };
       } catch (e) {
         settled = true;
         clearTimeout(timeoutId);
+        if (usingDirect) this.http.disableDirectRealtime();
         reject(e);
       }
     });
@@ -11495,6 +11507,19 @@ var HttpClient = class {
      * 반복하지 않고 한 번에 포기하는 쪽이 안전하다.
      */
     this.directDisabled = false;
+    /**
+     * 서버가 `X-CB-Realtime-Direct-Base` 로 알려준 socket-server 저지연 원본(`wss://...`).
+     * HTTP direct(`directBaseUrl`)와 별도 값·별도 킬 스위치 — core-server 응답에서만 학습되고
+     * (WS 업그레이드 응답 헤더는 브라우저가 못 읽는다), `RealtimeAPI.doConnect()` 가 매 연결
+     * 시도마다 lazy 하게 조회한다. platform-issue 019fe448.
+     */
+    this.directRealtimeBaseUrl = null;
+    /**
+     * realtime WS 연결이 direct 원본에서 네트워크 레벨로 실패하면 세운다 — `directDisabled`
+     * 와 같은 철학("한 번 실패하면 이 세션에서는 포기하고 원래 호스트로")이지만, 실패 감지가
+     * WS 상태 머신(RealtimeAPI) 쪽에서 일어나므로 별도 플래그로 둔다.
+     */
+    this.directRealtimeDisabled = false;
     this.config = { ...config };
     this.storageKey = this.buildStorageKey();
     this.warnIfUnsafePersistence();
@@ -11740,6 +11765,22 @@ var HttpClient = class {
   getBaseUrl() {
     return this.config.baseUrl;
   }
+  /**
+   * socket-server 의 direct(저지연) WS 원본. 아직 학습 전이거나(REST 요청을 한 번도 안
+   * 보냈거나 서버가 광고를 안 함) 네트워크 레벨로 실패해 이 세션에서 포기했으면 `null` —
+   * 호출자(`RealtimeAPI`)는 이 경우 원래 소켓 URL로 폴백해야 한다.
+   */
+  getDirectRealtimeBaseUrl() {
+    return this.directRealtimeDisabled ? null : this.directRealtimeBaseUrl;
+  }
+  /**
+   * direct WS 원본이 네트워크 레벨로 실패했을 때 `RealtimeAPI` 가 호출한다. 이후 연결
+   * 시도는 이 세션 동안 전부 원래 소켓 URL로 간다 — direct 는 최적화일 뿐 필수가 아니므로
+   * 재시도를 반복하지 않는다(`directDisabled`/HTTP direct 와 같은 철학).
+   */
+  disableDirectRealtime() {
+    this.directRealtimeDisabled = true;
+  }
   /**
    * 이 클라이언트에 설정된 앱 ID 반환 (미설정 시 undefined).
    *
@@ -12123,17 +12164,37 @@ var HttpClient = class {
    * 일은 없어야 한다.
    */
   learnDirectOrigin(response) {
-    if (this.directDisabled || this.directBaseUrl) return;
-    const advertised = response.headers?.get("X-CB-Direct-Base");
-    if (!advertised) return;
+    if (!response.headers) return;
+    const tail = (h) => h.split(".").slice(-2).join(".");
+    let base;
     try {
-      const next = new URL(advertised);
-      const base = new URL(this.config.baseUrl);
-      if (next.protocol !== "https:") return;
-      const tail = (h) => h.split(".").slice(-2).join(".");
-      if (tail(next.hostname) !== tail(base.hostname)) return;
-      this.directBaseUrl = next.origin;
+      base = new URL(this.config.baseUrl);
     } catch {
+      return;
+    }
+    if (!this.directDisabled && !this.directBaseUrl) {
+      const advertised = response.headers.get("X-CB-Direct-Base");
+      if (advertised) {
+        try {
+          const next = new URL(advertised);
+          if (next.protocol === "https:" && tail(next.hostname) === tail(base.hostname)) {
+            this.directBaseUrl = next.origin;
+          }
+        } catch {
+        }
+      }
+    }
+    if (!this.directRealtimeDisabled && !this.directRealtimeBaseUrl) {
+      const advertisedRealtime = response.headers.get("X-CB-Realtime-Direct-Base");
+      if (advertisedRealtime) {
+        try {
+          const next = new URL(advertisedRealtime);
+          if (next.protocol === "wss:" && tail(next.hostname) === tail(base.hostname)) {
+            this.directRealtimeBaseUrl = next.origin;
+          }
+        } catch {
+        }
+      }
     }
   }
   /**

package/package.json

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