connectbase-client 6.5.0 → 6.6.1

package/dist/index.js

@@ -37,6 +37,7 @@ __export(index_exports, {
   NativeAPI: () => NativeAPI,
   OrganizationsAPI: () => OrganizationsAPI,
   RealtimeConnectionError: () => RealtimeConnectionError,
+  RealtimeRequestError: () => RealtimeRequestError,
   RolesAPI: () => RolesAPI,
   SessionManager: () => SessionManager,
   VideoProcessingError: () => VideoProcessingError,
@@ -291,6 +292,7 @@ var RealtimeConnectionError = class extends Error {
     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() {
@@ -300,13 +302,31 @@ var RealtimeConnectionError = class extends Error {
       message: this.message,
       closeCode: this.closeCode,
       retryable: this.retryable,
-      details: this.details
+      details: this.details,
+      retryAfterMs: this.retryAfterMs
     };
   }
 };
 function isRetryableRealtimeRejection(code) {
-  return code === "connection_limit_exceeded" || code === "server_at_capacity" || code === "auth_unavailable" || code === "internal_error";
+  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) {
@@ -7958,9 +7978,35 @@ function toConnectionRejection(msg) {
     message: data.message || msg.error,
     closeCode: data.close_code,
     retryable: data.retryable,
-    details: data.details
+    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;
@@ -7998,6 +8044,18 @@ var RealtimeAPI = class {
     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();
@@ -8054,12 +8112,12 @@ var RealtimeAPI = class {
       );
     }
     this.connectPromise = this.primeDirectRealtime().then(
-      () => this.doConnect()
+      () => this.connectWithRetry()
     );
     try {
       await this.connectPromise;
     } catch (e) {
-      if (e instanceof RealtimeConnectionError) {
+      if (e instanceof RealtimeConnectionError || e instanceof ConnectCancelledError) {
         throw e;
       }
       const hasAuth = !!(this.options.accessToken || this.http.getPublicKey());
@@ -8105,6 +8163,8 @@ var RealtimeAPI = class {
    * 연결 해제
    */
   disconnect() {
+    this.connectGeneration++;
+    this.cancelConnectWait?.();
     this.state = "disconnected";
     this.notifyStateChange();
     if (this.ws) {
@@ -8163,12 +8223,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 = {
@@ -8224,7 +8279,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
     });
   }
@@ -8943,18 +8998,79 @@ var RealtimeAPI = class {
   async primeDirectRealtime() {
     if (this.directRealtimePrimed) return;
     this.directRealtimePrimed = true;
-    if (this.http.getDirectRealtimeBaseUrl() || !this.http.getPublicKey()) {
+    if (this.http.getDirectRealtimeBaseUrl()) {
       return;
     }
     try {
-      await this.http.get("/v1/public/edge-hints", { timeout: 1500 });
+      await this.http.primeEdgeHints(1500);
     } catch (e) {
       this.log(
         `edge hint lookup failed, using default socket URL: ${e instanceof Error ? e.message : String(e)}`
       );
     }
   }
-  async doConnect() {
+  /**
+   * 첫 연결을 연결 제한 시간(`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();
@@ -9000,7 +9116,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);
@@ -9063,11 +9179,16 @@ var RealtimeAPI = class {
             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();
           }
@@ -9075,12 +9196,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) {
@@ -9144,7 +9267,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));
         }
@@ -9155,7 +9279,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 {
@@ -9306,8 +9437,10 @@ var RealtimeAPI = class {
     this.streamSessions.clear();
     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) {
@@ -9317,7 +9450,7 @@ var RealtimeAPI = class {
       for (const [roomId, handlers] of this.typingHandlers) {
         typing.set(roomId, [...handlers]);
       }
-      this.pendingRestore = { subscriptions, presence, typing };
+      this.pendingRestore = { subscriptions, infos, presence, typing };
     }
     this.subscriptions.clear();
     this.presenceSubscriptions.clear();
@@ -9326,10 +9459,15 @@ var RealtimeAPI = class {
       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;
@@ -9342,13 +9480,15 @@ var RealtimeAPI = class {
             await this.restoreSubscriptions(
               snapshot.subscriptions,
               snapshot.presence,
-              snapshot.typing
+              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);
@@ -9388,7 +9528,7 @@ var RealtimeAPI = class {
    * 이전 구독 상태를 복구합니다.
    * 재연결 성공 후 호출됩니다.
    */
-  async restoreSubscriptions(previousSubscriptions, previousPresenceSubscriptions, previousTypingHandlers) {
+  async restoreSubscriptions(previousSubscriptions, previousPresenceSubscriptions, previousTypingHandlers, previousInfos) {
     for (const [category, handlers] of previousSubscriptions) {
       try {
         this.log(`Restoring subscription: ${category}`);
@@ -9398,12 +9538,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) {
@@ -9456,7 +9593,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').`
       );
     }
   }
@@ -9610,6 +9747,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"]);
@@ -12977,14 +13136,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;
@@ -13321,40 +13480,73 @@ 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();
+    }
+  }
   /**
    * SDK 인증 헤더를 **주입하지 않는** raw fetch. 저지연 원본 선택과 폴백만 얹는다.
    *
@@ -13386,11 +13578,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);
       }
@@ -13398,11 +13593,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;
@@ -14362,6 +14560,7 @@ var index_default = ConnectBase;
   NativeAPI,
   OrganizationsAPI,
   RealtimeConnectionError,
+  RealtimeRequestError,
   RolesAPI,
   SessionManager,
   VideoProcessingError,