connectbase-client 0.6.25 → 0.6.27

package/dist/index.js

@@ -464,6 +464,17 @@ var AuthAPI = class {
 // src/api/database.ts
 var DatabaseAPI = class {
   constructor(http) {
+    this.realtimeWs = null;
+    this.realtimeState = "disconnected";
+    this.realtimeHandlers = /* @__PURE__ */ new Map();
+    this.realtimeRetryCount = 0;
+    this.realtimeOptions = null;
+    this.pendingRequests = /* @__PURE__ */ new Map();
+    this.pingInterval = null;
+    this.realtimeOnStateChange = null;
+    this.realtimeOnError = null;
+    // 재연결 시 재구독용 메타데이터
+    this.activeSubscriptions = /* @__PURE__ */ new Map();
     this.http = http;
   }
   /**
@@ -861,6 +872,425 @@ var DatabaseAPI = class {
       `/v1/apps/${appId}/lifecycle/retention/${tableName}`
     );
   }
+  // ============ Realtime (Database Subscription) ============
+  /**
+   * 데이터베이스 실시간 연결
+   * data-server의 WebSocket에 연결하여 데이터 변경을 실시간으로 수신합니다.
+   *
+   * @example
+   * ```typescript
+   * // 연결
+   * cb.database.connectRealtime({
+   *     accessToken: 'your-jwt-token',
+   *     dataServerUrl: 'https://data.connectbase.world'
+   * })
+   *
+   * // 테이블 구독
+   * const sub = cb.database.subscribe('users', {
+   *     onSnapshot: (docs, info) => {
+   *         console.log('Initial data:', docs, 'total:', info.totalCount)
+   *     },
+   *     onChange: (changes) => {
+   *         changes.forEach(change => {
+   *             console.log(change.type, change.doc_id, change.data)
+   *         })
+   *     },
+   *     onError: (error) => console.error(error)
+   * })
+   *
+   * // 구독 해제
+   * sub.unsubscribe()
+   *
+   * // 연결 해제
+   * cb.database.disconnectRealtime()
+   * ```
+   */
+  connectRealtime(options) {
+    if (this.realtimeState === "connected") {
+      return Promise.resolve();
+    }
+    if (this.realtimeState === "connecting") {
+      return Promise.reject(new Error("Already connecting"));
+    }
+    this.realtimeOptions = options;
+    this.realtimeRetryCount = 0;
+    return this.doRealtimeConnect();
+  }
+  /**
+   * 데이터베이스 실시간 연결 해제
+   */
+  disconnectRealtime() {
+    this.realtimeOptions = null;
+    this.setRealtimeState("disconnected");
+    this.realtimeRetryCount = 0;
+    this.stopRealtimePing();
+    if (this.realtimeWs) {
+      this.realtimeWs.close();
+      this.realtimeWs = null;
+    }
+    this.pendingRequests.forEach((req) => {
+      clearTimeout(req.timeout);
+      req.reject(new Error("Connection closed"));
+    });
+    this.pendingRequests.clear();
+    this.realtimeHandlers.clear();
+    this.activeSubscriptions.clear();
+  }
+  /**
+   * 테이블 또는 문서의 실시간 변경 구독
+   *
+   * @param tableId 구독할 테이블 이름
+   * @param handlers 이벤트 핸들러 (onSnapshot, onChange, onError)
+   * @param options 구독 옵션 (docId, where, includeSelf 등)
+   * @returns 구독 해제 가능한 객체
+   */
+  subscribe(tableId, handlers, options) {
+    if (this.realtimeState !== "connected") {
+      throw new Error("Not connected. Call connectRealtime() first.");
+    }
+    const clientSubId = `csub_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`;
+    this.activeSubscriptions.set(clientSubId, { tableId, options, handlers });
+    const serverSubIdPromise = this.sendSubscribeRequest(tableId, handlers, options);
+    serverSubIdPromise.catch((err) => {
+      this.activeSubscriptions.delete(clientSubId);
+      handlers.onError?.(err instanceof Error ? err : new Error(String(err)));
+    });
+    return {
+      subscriptionId: clientSubId,
+      unsubscribe: () => {
+        this.activeSubscriptions.delete(clientSubId);
+        serverSubIdPromise.then((actualSubId) => {
+          this.realtimeHandlers.delete(actualSubId);
+          if (this.realtimeState === "connected") {
+            this.sendRealtimeMessage({
+              type: "unsubscribe",
+              request_id: this.generateRequestId(),
+              subscription_id: actualSubId
+            });
+          }
+        }).catch(() => {
+        });
+      }
+    };
+  }
+  /**
+   * 프레즌스 상태 설정
+   */
+  setPresence(status, device, metadata) {
+    if (this.realtimeState !== "connected") return;
+    this.sendRealtimeMessage({
+      type: "presence_set",
+      request_id: this.generateRequestId(),
+      status,
+      device,
+      metadata
+    });
+  }
+  /**
+   * 프레즌스 구독 (다른 사용자의 온라인 상태 감시)
+   */
+  subscribePresence(userIds, onPresence) {
+    if (this.realtimeState !== "connected") return;
+    this.realtimeHandlers.set("__presence__", {
+      onSnapshot: (docs) => {
+        const states = {};
+        for (const doc of docs) {
+          if (doc.data) {
+            states[doc.id] = doc.data;
+          }
+        }
+        onPresence(states);
+      }
+    });
+    this.sendRealtimeMessage({
+      type: "presence_subscribe",
+      request_id: this.generateRequestId(),
+      user_ids: userIds
+    });
+  }
+  /**
+   * 실시간 연결 상태 확인
+   */
+  isRealtimeConnected() {
+    return this.realtimeState === "connected";
+  }
+  /**
+   * 실시간 연결 상태 반환
+   */
+  getRealtimeState() {
+    return this.realtimeState;
+  }
+  /**
+   * 상태 변경 콜백 등록
+   */
+  onRealtimeStateChange(handler) {
+    this.realtimeOnStateChange = handler;
+    return () => {
+      this.realtimeOnStateChange = null;
+    };
+  }
+  /**
+   * 에러 콜백 등록
+   */
+  onRealtimeError(handler) {
+    this.realtimeOnError = handler;
+    return () => {
+      this.realtimeOnError = null;
+    };
+  }
+  // ============ Realtime Private Methods ============
+  setRealtimeState(state) {
+    if (this.realtimeState === state) return;
+    this.realtimeState = state;
+    this.realtimeOnStateChange?.(state);
+  }
+  doRealtimeConnect() {
+    if (!this.realtimeOptions) return Promise.reject(new Error("No realtime options"));
+    this.setRealtimeState("connecting");
+    const baseUrl = this.realtimeOptions.dataServerUrl || this.http.getBaseUrl();
+    const wsUrl = baseUrl.replace(/^http/, "ws");
+    const url = `${wsUrl}/v1/realtime/ws?access_token=${encodeURIComponent(this.realtimeOptions.accessToken)}`;
+    return new Promise((resolve, reject) => {
+      try {
+        this.realtimeWs = new WebSocket(url);
+        let settled = false;
+        const connectTimeout = setTimeout(() => {
+          if (!settled) {
+            settled = true;
+            if (this.realtimeWs) {
+              this.realtimeWs.close();
+              this.realtimeWs = null;
+            }
+            this.setRealtimeState("disconnected");
+            reject(new Error("Connection timeout"));
+          }
+        }, 15e3);
+        this.realtimeWs.onopen = () => {
+          if (!settled) {
+            settled = true;
+            clearTimeout(connectTimeout);
+          }
+          this.setRealtimeState("connected");
+          this.realtimeRetryCount = 0;
+          this.startRealtimePing();
+          this.debugLog("Database realtime connected");
+          this.resubscribeAll();
+          resolve();
+        };
+        this.realtimeWs.onmessage = (event) => {
+          try {
+            const msg = JSON.parse(event.data);
+            this.handleRealtimeMessage(msg);
+          } catch {
+            this.debugLog("Failed to parse realtime message");
+          }
+        };
+        this.realtimeWs.onclose = () => {
+          this.debugLog("Database realtime disconnected");
+          this.realtimeWs = null;
+          this.stopRealtimePing();
+          if (!settled) {
+            settled = true;
+            clearTimeout(connectTimeout);
+            reject(new Error("Connection closed during handshake"));
+          }
+          if (this.realtimeOptions && this.realtimeState !== "disconnected") {
+            this.attemptRealtimeReconnect();
+          }
+        };
+        this.realtimeWs.onerror = () => {
+          this.debugLog("Database realtime error");
+          this.realtimeOnError?.(new Error("WebSocket connection error"));
+        };
+      } catch (e) {
+        this.setRealtimeState("disconnected");
+        reject(e);
+      }
+    });
+  }
+  /**
+   * 서버에 subscribe 메시지를 보내고 서버 subscription_id를 반환하는 Promise
+   */
+  sendSubscribeRequest(tableId, handlers, options) {
+    const requestId = this.generateRequestId();
+    this.realtimeHandlers.set(requestId, handlers);
+    const query = options?.where ? {
+      filters: options.where.map((f) => ({
+        field: f.field,
+        operator: f.operator,
+        value: f.value
+      }))
+    } : void 0;
+    this.sendRealtimeMessage({
+      type: "subscribe",
+      request_id: requestId,
+      table_id: tableId,
+      doc_id: options?.docId,
+      query,
+      options: {
+        include_self: options?.includeSelf ?? false,
+        include_metadata_changes: options?.includeMetadataChanges ?? false
+      }
+    });
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        this.pendingRequests.delete(requestId);
+        this.realtimeHandlers.delete(requestId);
+        reject(new Error("Subscribe request timeout"));
+      }, 3e4);
+      this.pendingRequests.set(requestId, {
+        resolve: (value) => {
+          const actualSubId = value;
+          const h = this.realtimeHandlers.get(requestId);
+          if (h) {
+            this.realtimeHandlers.delete(requestId);
+            this.realtimeHandlers.set(actualSubId, h);
+          }
+          resolve(actualSubId);
+        },
+        reject,
+        timeout
+      });
+    });
+  }
+  /**
+   * 재연결 후 모든 활성 구독을 서버에 다시 등록
+   */
+  resubscribeAll() {
+    if (this.activeSubscriptions.size === 0) return;
+    this.realtimeHandlers.clear();
+    this.pendingRequests.forEach((req) => clearTimeout(req.timeout));
+    this.pendingRequests.clear();
+    this.debugLog(`Resubscribing ${this.activeSubscriptions.size} subscriptions`);
+    for (const [, meta] of this.activeSubscriptions) {
+      this.sendSubscribeRequest(meta.tableId, meta.handlers, meta.options).catch((err) => {
+        meta.handlers.onError?.(err instanceof Error ? err : new Error(String(err)));
+      });
+    }
+  }
+  handleRealtimeMessage(msg) {
+    const type = msg.type;
+    switch (type) {
+      case "subscribed": {
+        const requestId = msg.request_id;
+        const subscriptionId = msg.subscription_id;
+        const pending = this.pendingRequests.get(requestId);
+        if (pending) {
+          clearTimeout(pending.timeout);
+          pending.resolve(subscriptionId);
+          this.pendingRequests.delete(requestId);
+        }
+        break;
+      }
+      case "snapshot": {
+        const subId = msg.subscription_id;
+        const handlers = this.realtimeHandlers.get(subId);
+        if (handlers?.onSnapshot) {
+          const docs = msg.docs || [];
+          handlers.onSnapshot(docs, {
+            totalCount: msg.total_count || 0,
+            hasMore: msg.has_more || false
+          });
+        }
+        break;
+      }
+      case "change": {
+        const subId = msg.subscription_id;
+        const handlers = this.realtimeHandlers.get(subId);
+        if (handlers?.onChange) {
+          const changes = msg.changes || [];
+          handlers.onChange(changes);
+        }
+        break;
+      }
+      case "presence": {
+        const presenceHandlers = this.realtimeHandlers.get("__presence__");
+        if (presenceHandlers?.onSnapshot) {
+          const states = msg.states;
+          const docs = Object.entries(states || {}).map(([userId, state]) => ({
+            id: userId,
+            data: state,
+            exists: true
+          }));
+          presenceHandlers.onSnapshot(docs, { totalCount: docs.length, hasMore: false });
+        }
+        break;
+      }
+      case "error": {
+        const requestId = msg.request_id;
+        const errorMsg = msg.message || "Unknown error";
+        if (requestId) {
+          const pending = this.pendingRequests.get(requestId);
+          if (pending) {
+            clearTimeout(pending.timeout);
+            pending.reject(new Error(errorMsg));
+            this.pendingRequests.delete(requestId);
+          }
+          const handlers = this.realtimeHandlers.get(requestId);
+          if (handlers?.onError) {
+            handlers.onError(new Error(errorMsg));
+          }
+        } else {
+          this.realtimeOnError?.(new Error(errorMsg));
+        }
+        break;
+      }
+      case "pong":
+        break;
+      case "unsubscribed":
+      case "presence_set_ack":
+      case "presence_subscribed":
+      case "typing_subscribed":
+        break;
+    }
+  }
+  attemptRealtimeReconnect() {
+    const maxRetries = this.realtimeOptions?.maxRetries ?? 5;
+    const retryInterval = this.realtimeOptions?.retryInterval ?? 1e3;
+    if (this.realtimeRetryCount >= maxRetries) {
+      this.setRealtimeState("disconnected");
+      this.realtimeOnError?.(new Error("Realtime connection lost. Max retries exceeded."));
+      return;
+    }
+    this.setRealtimeState("connecting");
+    this.realtimeRetryCount++;
+    const delay = Math.min(retryInterval * Math.pow(2, this.realtimeRetryCount - 1), 3e4);
+    this.debugLog(`Reconnecting in ${delay}ms (attempt ${this.realtimeRetryCount}/${maxRetries})`);
+    setTimeout(() => {
+      if (this.realtimeOptions) {
+        this.doRealtimeConnect().catch((err) => {
+          this.debugLog(`Reconnect failed: ${err}`);
+        });
+      }
+    }, delay);
+  }
+  startRealtimePing() {
+    this.stopRealtimePing();
+    this.pingInterval = setInterval(() => {
+      if (this.realtimeState === "connected" && this.realtimeWs?.readyState === WebSocket.OPEN) {
+        this.sendRealtimeMessage({ type: "ping", timestamp: Date.now() });
+      }
+    }, 3e4);
+  }
+  stopRealtimePing() {
+    if (this.pingInterval) {
+      clearInterval(this.pingInterval);
+      this.pingInterval = null;
+    }
+  }
+  sendRealtimeMessage(msg) {
+    if (this.realtimeWs?.readyState === WebSocket.OPEN) {
+      this.realtimeWs.send(JSON.stringify(msg));
+    }
+  }
+  generateRequestId() {
+    return "req_" + Date.now() + "_" + Math.random().toString(36).substring(2, 9);
+  }
+  debugLog(message) {
+    if (this.realtimeOptions?.debug) {
+      console.log(`[DatabaseRealtime] ${message}`);
+    }
+  }
 };
 
 // src/api/storage.ts
@@ -1307,7 +1737,9 @@ var RealtimeAPI = class {
       maxRetries: 5,
       retryInterval: 1e3,
       userId: "",
-      accessToken: ""
+      accessToken: "",
+      timeout: 3e4,
+      debug: false
     };
     this.retryCount = 0;
     this.pendingRequests = /* @__PURE__ */ new Map();
@@ -1545,6 +1977,12 @@ var RealtimeAPI = class {
   getState() {
     return this.state;
   }
+  /**
+   * 연결 여부 확인
+   */
+  isConnected() {
+    return this.state === "connected";
+  }
   /**
    * 상태 변경 핸들러 등록
    */
@@ -1570,53 +2008,97 @@ var RealtimeAPI = class {
     return new Promise((resolve, reject) => {
       this.state = "connecting";
       this.notifyStateChange();
+      this.log("Connecting...");
       const wsUrl = 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}`;
+        this.log("Using accessToken authentication");
       } else {
         const apiKey = this.http.getApiKey();
         if (!apiKey) {
-          reject(new Error("API Key or accessToken is required for realtime connection"));
+          const error = new Error("API Key or accessToken is required for realtime connection");
+          this.log("Connection failed: no API Key or accessToken");
+          reject(error);
           return;
         }
         url = `${wsUrl}/v1/realtime/auth?api_key=${encodeURIComponent(apiKey)}&client_id=${this.clientId}`;
+        this.log("Using API Key authentication");
       }
       if (this.userId) {
         url += `&user_id=${encodeURIComponent(this.userId)}`;
       }
+      let settled = false;
+      const timeoutId = setTimeout(() => {
+        if (!settled) {
+          settled = true;
+          this.log(`Connection timeout after ${this.options.timeout}ms`);
+          if (this.ws) {
+            this.ws.close();
+            this.ws = null;
+          }
+          this.state = "disconnected";
+          this.notifyStateChange();
+          reject(new Error(`Connection timeout after ${this.options.timeout}ms`));
+        }
+      }, this.options.timeout);
       try {
+        this.log(`Connecting to ${wsUrl}`);
         this.ws = new WebSocket(url);
         this.ws.onopen = () => {
+          this.log("WebSocket opened, waiting for connected event...");
         };
         this.ws.onmessage = (event) => {
           const messages = event.data.split("\n").filter((line) => line.trim());
           for (const line of messages) {
             try {
               const msg = JSON.parse(line);
-              this.handleServerMessage(msg, resolve);
+              this.handleServerMessage(msg, () => {
+                if (!settled) {
+                  settled = true;
+                  clearTimeout(timeoutId);
+                  this.log("Connected successfully");
+                  resolve();
+                }
+              });
             } catch (e) {
               console.error("[Realtime] Failed to parse message:", line, e);
             }
           }
         };
-        this.ws.onclose = () => {
+        this.ws.onclose = (event) => {
+          this.log(`WebSocket closed: code=${event.code}, reason=${event.reason}`);
+          if (!settled && this.state === "connecting") {
+            settled = true;
+            clearTimeout(timeoutId);
+            reject(new Error(`Connection closed: ${event.reason || "unknown reason"}`));
+          }
           if (this.state === "connected" || this.state === "connecting") {
             this.handleDisconnect();
           }
         };
         this.ws.onerror = (error) => {
+          this.log("WebSocket error occurred");
           console.error("[Realtime] WebSocket error:", error);
           this.notifyError(new Error("WebSocket connection error"));
-          if (this.state === "connecting") {
+          if (!settled && this.state === "connecting") {
+            settled = true;
+            clearTimeout(timeoutId);
             reject(new Error("Failed to connect"));
           }
         };
       } catch (e) {
+        settled = true;
+        clearTimeout(timeoutId);
         reject(e);
       }
     });
   }
+  log(message) {
+    if (this.options.debug) {
+      console.log(`[Realtime] ${message}`);
+    }
+  }
   handleServerMessage(msg, connectResolve) {
     switch (msg.event) {
       case "connected": {