connectbase-client 6.4.0 → 6.6.0

package/dist/index.mjs

@@ -232,6 +232,49 @@ var GameError = class extends Error {
     };
   }
 };
+var RealtimeConnectionError = class extends Error {
+  constructor(init) {
+    super(init.message || init.code || "Realtime connection rejected");
+    this.name = "RealtimeConnectionError";
+    this.code = init.code || "unknown";
+    this.closeCode = init.closeCode;
+    this.retryable = init.retryable ?? isRetryableRealtimeRejection(this.code);
+    this.details = init.details;
+    this.retryAfterMs = init.retryAfterMs;
+  }
+  /** `JSON.stringify(err)` 가 `{}` 가 되지 않도록 한다 (ApiError.toJSON 참조). */
+  toJSON() {
+    return {
+      name: this.name,
+      code: this.code,
+      message: this.message,
+      closeCode: this.closeCode,
+      retryable: this.retryable,
+      details: this.details,
+      retryAfterMs: this.retryAfterMs
+    };
+  }
+};
+function isRetryableRealtimeRejection(code) {
+  return code === "connection_limit_exceeded" || code === "server_at_capacity" || code === "rate_limited" || code === "auth_unavailable" || code === "internal_error";
+}
+var RealtimeRequestError = class extends Error {
+  constructor(init) {
+    super(init.message || init.code || "Realtime request failed");
+    this.name = "RealtimeRequestError";
+    this.code = init.code || "unknown";
+    this.category = init.category;
+  }
+  /** `JSON.stringify(err)` 가 `{}` 가 되지 않도록 한다 (ApiError.toJSON 참조). */
+  toJSON() {
+    return {
+      name: this.name,
+      code: this.code,
+      message: this.message,
+      category: this.category
+    };
+  }
+};
 
 // src/api/ai.ts
 function aiErrorToApiError(err) {
@@ -7874,6 +7917,44 @@ 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;
+function toConnectionRejection(msg) {
+  if (msg.event !== "error" || msg.request_id) return null;
+  const data = msg.data;
+  if (!data || typeof data.close_code !== "number") return null;
+  return new RealtimeConnectionError({
+    code: data.code,
+    message: data.message || msg.error,
+    closeCode: data.close_code,
+    retryable: data.retryable,
+    details: data.details,
+    retryAfterMs: typeof data.retry_after_ms === "number" && data.retry_after_ms > 0 ? data.retry_after_ms : void 0
+  });
+}
+var HandshakeFailedError = class extends Error {
+};
+var ConnectCancelledError = class extends Error {
+  constructor() {
+    super("Realtime connect cancelled by disconnect()");
+    this.name = "AbortError";
+  }
+};
+var MAX_HANDSHAKE_RETRIES = 2;
+function jitter(max) {
+  return Math.floor(Math.random() * Math.max(0, max));
+}
+function toSendPolicy(value) {
+  return value === "upstream" || value === "publishers_only" ? value : "open";
+}
+function toCategoryInfo(response) {
+  return {
+    category: response.category,
+    persist: response.persist,
+    historyCount: response.history_count,
+    readReceipt: response.read_receipt,
+    isPublisher: response.publisher === true,
+    sendPolicy: toSendPolicy(response.send_policy)
+  };
+}
 var RealtimeAPI = class {
   constructor(http, socketUrl) {
     this.ws = null;
@@ -7901,6 +7982,28 @@ var RealtimeAPI = class {
       fallback: "sse"
     };
     this.retryCount = 0;
+    /**
+     * 재연결 뒤 복구할 구독 상태. 연결이 끊긴 첫 순간에 떠 두고, 재연결이 성공해 복구한 뒤 비운다.
+     *
+     * 재연결 시도가 실패할 때마다 onclose → handleDisconnect 가 다시 불린다. 예전에는 그때마다 구독 맵을
+     * 새로 떴는데, 첫 끊김에서 이미 비워진 맵이라 빈 스냅샷으로 덮였다 — 첫 재연결 시도가 실패하면
+     * (서버 롤링 재시작 등) 재연결에 성공해도 구독이 하나도 복구되지 않았다.
+     */
+    this.pendingRestore = null;
+    /** 첫 연결 전에 direct 원본 힌트를 한 번 물었는지 (primeDirectRealtime). */
+    this.directRealtimePrimed = false;
+    /** disconnect() 마다 늘린다 — connect() 의 재시도 대기가 그 사이 취소됐는지 알아보는 데 쓴다. */
+    this.connectGeneration = 0;
+    /**
+     * connect() 가 첫 연결을 시도하는 중인지. 이때의 핸드셰이크 실패는 connect() 가 직접 다시 시도하거나
+     * 폴백하므로, onclose 가 백그라운드 재연결 체인(handleDisconnect)을 따로 시작하면 안 된다 — 두 경로가
+     * 동시에 연결을 열게 된다.
+     */
+    this.initialConnecting = false;
+    /** 다음 재연결 대기의 하한(ms) — 서버가 알려 준 retry_after_ms. handleDisconnect 가 한 번 쓰고 비운다. */
+    this.reconnectFloorMs = 0;
+    /** connect() 의 재시도 대기를 끝내는 함수 — disconnect() 가 기다림 없이 바로 취소하게 한다. */
+    this.cancelConnectWait = null;
     this.pendingRequests = /* @__PURE__ */ new Map();
     this.subscriptions = /* @__PURE__ */ new Map();
     this.streamSessions = /* @__PURE__ */ new Map();
@@ -7944,7 +8047,7 @@ var RealtimeAPI = class {
     if (this.state === "connected") {
       return;
     }
-    if (this.state === "connecting" && this.connectPromise) {
+    if (this.connectPromise) {
       return this.connectPromise;
     }
     this.options = { ...this.options, ...options };
@@ -7956,10 +8059,15 @@ var RealtimeAPI = class {
         `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();
+    this.connectPromise = this.primeDirectRealtime().then(
+      () => this.connectWithRetry()
+    );
     try {
       await this.connectPromise;
     } catch (e) {
+      if (e instanceof RealtimeConnectionError || e instanceof ConnectCancelledError) {
+        throw e;
+      }
       const hasAuth = !!(this.options.accessToken || this.http.getPublicKey());
       if (this.options.fallback !== "none" && hasAuth) {
         this.activateSseFallback(e);
@@ -7988,6 +8096,7 @@ var RealtimeAPI = class {
     this.activeTransport = "sse";
     this.state = "connected";
     this.retryCount = 0;
+    this.pendingRestore = null;
     this.log(
       `WS unavailable (${causeMsg}); using SSE fallback transport for AI streaming`
     );
@@ -8002,6 +8111,8 @@ var RealtimeAPI = class {
    * 연결 해제
    */
   disconnect() {
+    this.connectGeneration++;
+    this.cancelConnectWait?.();
     this.state = "disconnected";
     this.notifyStateChange();
     if (this.ws) {
@@ -8044,6 +8155,7 @@ var RealtimeAPI = class {
     this._appId = null;
     this.retryCount = 0;
     this.connectPromise = null;
+    this.pendingRestore = null;
   }
   /**
    * 카테고리 구독
@@ -8059,12 +8171,7 @@ var RealtimeAPI = class {
       action: "subscribe",
       request_id: requestId
     });
-    const info = {
-      category: response.category,
-      persist: response.persist,
-      historyCount: response.history_count,
-      readReceipt: response.read_receipt
-    };
+    const info = toCategoryInfo(response);
     const handlers = [];
     this.subscriptions.set(category, { info, handlers });
     const subscription = {
@@ -8120,7 +8227,7 @@ var RealtimeAPI = class {
     await this.sendRequest({
       category,
       action: "send",
-      data: { data, broadcast },
+      data: options.to ? { data, broadcast, to: options.to } : { data, broadcast },
       request_id: requestId
     });
   }
@@ -8826,7 +8933,92 @@ var RealtimeAPI = class {
     };
   }
   // Private methods
-  async doConnect() {
+  /**
+   * direct(저지연) 원본을 아직 모르면 첫 연결 전에 한 번 묻는다 — `GET /v1/public/edge-hints`.
+   *
+   * direct 원본은 core-server 응답 헤더(`X-CB-Realtime-Direct-Base`)로만 배운다. realtime 만 쓰는
+   * 페이지는 WS 를 열기 전에 REST 를 부르지 않아 배울 기회가 없었고, 첫 연결이 늘 Cloudflare 를 타
+   * 한국 사용자는 미국(LAX)을 거친 ~270ms 로 붙었다(platform-issue 01a15d9d 의 273ms). 응답 헤더는
+   * HttpClient 가 평소처럼 학습한다. 광고 대상이 아니면(해외, 킬 스위치) 빈 응답이라 원래 소켓
+   * URL 로 간다. 실패하거나 느리면(1.5초) 그냥 넘어간다 — 최적화일 뿐 연결의 전제가 아니다.
+   * 세션당 한 번만 묻는다.
+   */
+  async primeDirectRealtime() {
+    if (this.directRealtimePrimed) return;
+    this.directRealtimePrimed = true;
+    if (this.http.getDirectRealtimeBaseUrl()) {
+      return;
+    }
+    try {
+      await this.http.primeEdgeHints(1500);
+    } catch (e) {
+      this.log(
+        `edge hint lookup failed, using default socket URL: ${e instanceof Error ? e.message : String(e)}`
+      );
+    }
+  }
+  /**
+   * 첫 연결을 연결 제한 시간(`timeout`) 안에서 다시 시도한다 (6.6.0+, platform-issue 01a15e24).
+   *
+   * - 서버가 재시도 시각을 알려 준 거부(`retryAfterMs`, 예: 한 IP 에서 연결이 몰린 `rate_limited`):
+   *   그 시각에 지터를 더해 다시 붙는다. 공연 시작처럼 한꺼번에 들어올 때 앱이 재시도를 짜지 않아도 된다.
+   * - 이유 없는 핸드셰이크 실패: 두 번까지 백오프 후 다시 한다. 네트워크가 WebSocket 을 실제로 막으면
+   *   매번 실패하고, 앞단의 일시 거부는 다시 하면 붙는다 — 한 번 실패로 SSE 폴백하던 것이 연결 속도
+   *   제한을 "네트워크 차단" 으로 오진한 원인이었다.
+   * - 그 밖의 거부(자격증명, 동시접속 한도 등)와 시간 초과는 바로 던진다.
+   */
+  async connectWithRetry() {
+    const generation = this.connectGeneration;
+    const deadline = Date.now() + this.options.timeout;
+    let handshakeFailures = 0;
+    this.initialConnecting = true;
+    try {
+      for (let attempt = 1; ; attempt++) {
+        try {
+          await this.doConnect(Math.max(deadline - Date.now(), 1));
+          return;
+        } catch (e) {
+          let wait = null;
+          if (e instanceof RealtimeConnectionError) {
+            if (e.retryable && e.retryAfterMs !== void 0) {
+              wait = e.retryAfterMs + jitter(Math.min(100 * 2 ** attempt, 3e3));
+            } else if (e.code === "rate_limited") {
+              const base = Math.min(500 * 2 ** (attempt - 1), 8e3);
+              wait = base / 2 + jitter(base / 2);
+            }
+          } else if (e instanceof HandshakeFailedError && handshakeFailures < MAX_HANDSHAKE_RETRIES) {
+            handshakeFailures++;
+            const base = 500 * 2 ** (handshakeFailures - 1);
+            wait = base / 2 + jitter(base / 2);
+          }
+          if (wait === null || Date.now() + wait >= deadline) {
+            if (this.state === "connecting") {
+              this.state = "disconnected";
+              this.notifyStateChange();
+            }
+            throw e;
+          }
+          this.log(
+            `Connect attempt ${attempt} failed (${e instanceof Error ? e.message : String(e)}); retrying in ${wait}ms`
+          );
+          await new Promise((resolve) => {
+            const timer = setTimeout(resolve, wait);
+            this.cancelConnectWait = () => {
+              clearTimeout(timer);
+              resolve();
+            };
+          });
+          this.cancelConnectWait = null;
+          if (generation !== this.connectGeneration) {
+            throw new ConnectCancelledError();
+          }
+        }
+      }
+    } finally {
+      this.initialConnecting = false;
+    }
+  }
+  async doConnect(timeoutMs = this.options.timeout) {
     return new Promise((resolve, reject) => {
       this.state = "connecting";
       this.notifyStateChange();
@@ -8854,7 +9046,9 @@ var RealtimeAPI = class {
       if (this.userId) {
         url += `&user_id=${encodeURIComponent(this.userId)}`;
       }
+      url += "&reject_mode=close";
       let settled = false;
+      let rejection = null;
       const timeoutId = setTimeout(() => {
         if (!settled) {
           settled = true;
@@ -8870,7 +9064,7 @@ var RealtimeAPI = class {
             new Error(`Connection timeout after ${this.options.timeout}ms`)
           );
         }
-      }, this.options.timeout);
+      }, timeoutMs);
       try {
         this.log(`Connecting to ${wsUrl}`);
         this.ws = new WebSocket(url);
@@ -8882,6 +9076,11 @@ var RealtimeAPI = class {
           for (const line of messages) {
             try {
               const msg = JSON.parse(line);
+              const rejected = toConnectionRejection(msg);
+              if (rejected && !settled) {
+                rejection = rejected;
+                continue;
+              }
               this.handleServerMessage(msg, () => {
                 if (!settled) {
                   settled = true;
@@ -8899,16 +9098,45 @@ var RealtimeAPI = class {
           this.log(
             `WebSocket closed: code=${event.code}, reason=${event.reason}`
           );
+          if (event.code >= 4e3 && event.code <= 4999) {
+            const err = rejection ?? new RealtimeConnectionError({
+              code: event.reason || void 0,
+              closeCode: event.code
+            });
+            const wasConnected = this.state === "connected";
+            if (!settled) {
+              settled = true;
+              clearTimeout(timeoutId);
+            }
+            this.ws = null;
+            if (wasConnected) {
+              if (err.retryable) {
+                this.handleDisconnect();
+              } else {
+                this.failRealtime(err);
+              }
+              return;
+            }
+            this.state = "disconnected";
+            this.notifyStateChange();
+            reject(err);
+            return;
+          }
           if (!settled && this.state === "connecting") {
             settled = true;
             clearTimeout(timeoutId);
             if (usingDirect) this.http.disableDirectRealtime();
             reject(
-              new Error(
+              new HandshakeFailedError(
                 `Connection closed: ${event.reason || "unknown reason"}`
               )
             );
           }
+          if (this.initialConnecting && this.state === "connecting") {
+            this.state = "disconnected";
+            this.ws = null;
+            return;
+          }
           if (this.state === "connected" || this.state === "connecting") {
             this.handleDisconnect();
           }
@@ -8916,12 +9144,14 @@ var RealtimeAPI = class {
         this.ws.onerror = (error) => {
           this.log("WebSocket error occurred");
           this.logError("WebSocket error", error);
-          this.notifyError(new Error("WebSocket connection error"));
+          if (!this.initialConnecting) {
+            this.notifyError(new Error("WebSocket connection error"));
+          }
           if (!settled && this.state === "connecting") {
             settled = true;
             clearTimeout(timeoutId);
             if (usingDirect) this.http.disableDirectRealtime();
-            reject(new Error("Failed to connect"));
+            reject(new HandshakeFailedError("Failed to connect"));
           }
         };
       } catch (e) {
@@ -8985,7 +9215,8 @@ var RealtimeAPI = class {
             category: data.category,
             from: data.from,
             data: data.data,
-            sentAt: data.sent_at
+            sentAt: data.sent_at,
+            fromPublisher: data.from_publisher === true
           };
           sub.handlers.forEach((h) => h(message));
         }
@@ -8996,7 +9227,14 @@ var RealtimeAPI = class {
           const pending = this.pendingRequests.get(msg.request_id);
           if (pending) {
             clearTimeout(pending.timeout);
-            pending.reject(new Error(msg.error || "Unknown error"));
+            const errData = msg.data;
+            pending.reject(
+              new RealtimeRequestError({
+                code: errData?.code,
+                message: msg.error || "Unknown error",
+                category: msg.category
+              })
+            );
             this.pendingRequests.delete(msg.request_id);
           }
         } else {
@@ -9145,41 +9383,66 @@ var RealtimeAPI = class {
       }
     });
     this.streamSessions.clear();
-    const previousSubscriptions = /* @__PURE__ */ new Map();
-    for (const [category, sub] of this.subscriptions) {
-      previousSubscriptions.set(category, [...sub.handlers]);
+    if (!this.pendingRestore) {
+      const subscriptions = /* @__PURE__ */ new Map();
+      const infos = /* @__PURE__ */ new Map();
+      for (const [category, sub] of this.subscriptions) {
+        subscriptions.set(category, [...sub.handlers]);
+        infos.set(category, sub.info);
+      }
+      const presence = /* @__PURE__ */ new Map();
+      for (const [userId, handlers] of this.presenceSubscriptions) {
+        presence.set(userId, [...handlers]);
+      }
+      const typing = /* @__PURE__ */ new Map();
+      for (const [roomId, handlers] of this.typingHandlers) {
+        typing.set(roomId, [...handlers]);
+      }
+      this.pendingRestore = { subscriptions, infos, presence, typing };
     }
     this.subscriptions.clear();
-    const previousPresenceSubscriptions = /* @__PURE__ */ new Map();
-    for (const [userId, handlers] of this.presenceSubscriptions) {
-      previousPresenceSubscriptions.set(userId, [...handlers]);
-    }
     this.presenceSubscriptions.clear();
-    const previousTypingHandlers = /* @__PURE__ */ new Map();
-    for (const [roomId, handlers] of this.typingHandlers) {
-      previousTypingHandlers.set(roomId, [...handlers]);
-    }
     this.typingHandlers.clear();
     if (this.retryCount < this.options.maxRetries) {
       this.state = "reconnecting";
       this.notifyStateChange();
       this.retryCount++;
-      const delay = Math.min(
+      const base = Math.min(
         this.options.retryInterval * 2 ** (this.retryCount - 1),
         3e4
       );
+      const delay = Math.max(
+        Math.ceil(base / 2) + jitter(Math.floor(base / 2)),
+        this.reconnectFloorMs
+      );
+      this.reconnectFloorMs = 0;
       setTimeout(async () => {
         if (this.sseFallbackActive) return;
+        if (this.state !== "reconnecting") return;
         try {
           await this.doConnect();
           this.log("Reconnected successfully, restoring subscriptions...");
-          await this.restoreSubscriptions(
-            previousSubscriptions,
-            previousPresenceSubscriptions,
-            previousTypingHandlers
-          );
+          const snapshot = this.pendingRestore;
+          this.pendingRestore = null;
+          if (snapshot) {
+            await this.restoreSubscriptions(
+              snapshot.subscriptions,
+              snapshot.presence,
+              snapshot.typing,
+              snapshot.infos
+            );
+          }
         } catch (e) {
           this.logError("Reconnect failed", e);
+          if (e instanceof RealtimeConnectionError) {
+            if (e.retryable && this.retryCount < this.options.maxRetries) {
+              this.reconnectFloorMs = e.retryAfterMs ?? 0;
+              this.handleDisconnect();
+            } else {
+              this.failRealtime(e);
+            }
+            return;
+          }
           if (this.retryCount >= this.options.maxRetries && this.options.fallback !== "none" && !this.sseFallbackActive) {
             this.activateSseFallback(e);
           }
@@ -9197,11 +9460,23 @@ var RealtimeAPI = class {
       }
     }
   }
+  /**
+   * 재연결을 멈추고 앱에 알린다 — 서버가 재시도해도 소용없는 이유(자격증명, 할당량)로 거부했거나
+   * 재시도할 수 있는 거부가 maxRetries 를 다 썼다.
+   */
+  failRealtime(err) {
+    this.pendingRestore = null;
+    this.ws = null;
+    this._connectionId = null;
+    this.state = "disconnected";
+    this.notifyStateChange();
+    this.notifyError(err);
+  }
   /**
    * 이전 구독 상태를 복구합니다.
    * 재연결 성공 후 호출됩니다.
    */
-  async restoreSubscriptions(previousSubscriptions, previousPresenceSubscriptions, previousTypingHandlers) {
+  async restoreSubscriptions(previousSubscriptions, previousPresenceSubscriptions, previousTypingHandlers, previousInfos) {
     for (const [category, handlers] of previousSubscriptions) {
       try {
         this.log(`Restoring subscription: ${category}`);
@@ -9211,12 +9486,9 @@ var RealtimeAPI = class {
           action: "subscribe",
           request_id: requestId
         });
-        const info = {
-          category: response.category,
-          persist: response.persist,
-          historyCount: response.history_count,
-          readReceipt: response.read_receipt
-        };
+        const fresh = toCategoryInfo(response);
+        const info = previousInfos?.get(category) ?? fresh;
+        Object.assign(info, fresh);
         this.subscriptions.set(category, { info, handlers });
         this.log(`Restored subscription: ${category}`);
       } catch (e) {
@@ -9269,7 +9541,7 @@ var RealtimeAPI = class {
   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').`
+        `realtime.${feature}() requires a WebSocket connection, which could not be established (the network may block WebSocket, or the connection was repeatedly refused). Only AI streaming (realtime.stream) works in SSE fallback mode (cb.realtime.transport === 'sse').`
       );
     }
   }
@@ -9423,6 +9695,28 @@ function createTimeoutController(options = {}) {
     }
   };
 }
+function withAbort(promise, signal) {
+  if (!signal) return promise;
+  const reason = () => signal.reason ?? new DOMException("The operation was aborted.", "AbortError");
+  if (signal.aborted) {
+    promise.catch(() => void 0);
+    return Promise.reject(reason());
+  }
+  return new Promise((resolve, reject) => {
+    const onAbort = () => reject(reason());
+    signal.addEventListener("abort", onAbort, { once: true });
+    promise.then(
+      (value) => {
+        signal.removeEventListener("abort", onAbort);
+        resolve(value);
+      },
+      (error) => {
+        signal.removeEventListener("abort", onAbort);
+        reject(error);
+      }
+    );
+  });
+}
 
 // src/core/url-validation.ts
 var LOCAL_HOSTS = /* @__PURE__ */ new Set(["localhost", "127.0.0.1", "::1"]);
@@ -12790,14 +13084,14 @@ var HttpClient = class {
         if (credential) {
           headers["X-Public-Key"] = credential;
         }
-        const response = await fetch(
-          `${this.config.baseUrl}/v1/auth/re-issue`,
-          {
+        const response = await withAbort(
+          fetch(`${this.config.baseUrl}/v1/auth/re-issue`, {
             method: "POST",
             headers,
             credentials: "include",
             signal
-          }
+          }),
+          signal
         );
         if (!response.ok) {
           const status = response.status;
@@ -13134,38 +13428,71 @@ var HttpClient = class {
    */
   learnDirectOrigin(response) {
     if (!response.headers) return;
+    this.adoptDirectBases(
+      response.headers.get("X-CB-Direct-Base"),
+      response.headers.get("X-CB-Realtime-Direct-Base")
+    );
+  }
+  /**
+   * 광고된 direct 원본을 검증해 받아들인다. 응답 헤더(learnDirectOrigin)와 edge-hints 본문
+   * (primeEdgeHints)이 같은 검증을 거친다.
+   */
+  adoptDirectBases(advertised, advertisedRealtime) {
     const tail = (h) => h.split(".").slice(-2).join(".");
     let base = null;
     try {
       base = new URL(this.config.baseUrl);
     } catch {
     }
-    if (base && !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 (base && !this.directDisabled && !this.directBaseUrl && typeof advertised === "string" && 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) {
+    if (!this.directRealtimeDisabled && !this.directRealtimeBaseUrl && typeof advertisedRealtime === "string" && advertisedRealtime) {
       const expectedTail = base ? tail(base.hostname) : "connectbase.world";
-      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) === expectedTail) {
-            this.directRealtimeBaseUrl = next.origin;
-          }
-        } catch {
+      try {
+        const next = new URL(advertisedRealtime);
+        if (next.protocol === "wss:" && tail(next.hostname) === expectedTail) {
+          this.directRealtimeBaseUrl = next.origin;
         }
+      } catch {
+      }
+    }
+  }
+  /**
+   * realtime 첫 연결 전에 저지연 direct 원본 힌트를 묻는다 (`GET /v1/public/edge-hints`, 6.6.0+).
+   *
+   * **커스텀 헤더 없는 단순 GET** 이다. `X-Public-Key` 같은 헤더가 붙으면 브라우저가 CORS 사전 요청을
+   * 먼저 보내 Cloudflare 를 두 번 왕복하고, 앱의 "로컬 개발 origin 허용" 이 꺼진 localhost 페이지에서는
+   * 키 기반 opt-in 에 막혀 브라우저만 direct 를 못 썼다(Node 는 썼다 — platform-issue 01a15e24).
+   * 서버는 이 경로를 키 없이 열어 두고 같은 값을 본문으로도 준다. 본문을 읽으므로 CORS
+   * Expose-Headers 에도 기대지 않는다. 실패는 조용히 무시한다 — direct 는 최적화일 뿐이다.
+   */
+  async primeEdgeHints(timeoutMs) {
+    if (this.directRealtimeBaseUrl || this.directRealtimeDisabled) return;
+    const { signal, cleanup } = createTimeoutController({ timeout: timeoutMs });
+    try {
+      const response = await withAbort(
+        fetch(`${this.config.baseUrl}/v1/public/edge-hints`, {
+          method: "GET",
+          credentials: "omit",
+          signal
+        }),
+        signal
+      );
+      if (!response.ok) {
+        throw new Error(`edge-hints HTTP ${response.status}`);
       }
+      this.learnDirectOrigin(response);
+      const body = await withAbort(response.json(), signal);
+      this.adoptDirectBases(body?.direct_base, body?.realtime_direct_base);
+    } finally {
+      cleanup();
     }
   }
   /**
@@ -13199,11 +13526,14 @@ var HttpClient = class {
     });
     const origin = this.resolveOrigin(url, config?.baseUrl);
     try {
-      const response = await fetch(`${origin}${url}`, {
-        ...init,
-        credentials: fetchCredentialsForPath(url),
+      const response = await withAbort(
+        fetch(`${origin}${url}`, {
+          ...init,
+          credentials: fetchCredentialsForPath(url),
+          signal
+        }),
         signal
-      });
+      );
       if (!config?.baseUrl) {
         this.learnDirectOrigin(response);
       }
@@ -13211,11 +13541,14 @@ var HttpClient = class {
     } catch (err) {
       if (!config?.baseUrl && origin !== this.config.baseUrl && !isAbortError(err)) {
         this.directDisabled = true;
-        const response = await fetch(`${this.config.baseUrl}${url}`, {
-          ...init,
-          credentials: fetchCredentialsForPath(url),
+        const response = await withAbort(
+          fetch(`${this.config.baseUrl}${url}`, {
+            ...init,
+            credentials: fetchCredentialsForPath(url),
+            signal
+          }),
           signal
-        });
+        );
         return { response, ok: response.ok, status: response.status };
       }
       throw err;
@@ -14173,6 +14506,8 @@ export {
   GameRoomTransport,
   NativeAPI,
   OrganizationsAPI,
+  RealtimeConnectionError,
+  RealtimeRequestError,
   RolesAPI,
   SessionManager,
   VideoProcessingError,