connectbase-client 0.6.28 → 0.6.30

package/dist/index.js

@@ -1573,12 +1573,25 @@ var StorageAPI = class {
     );
   }
   /**
-   * 페이지 메타 목록 조회
+   * 페이지 메타 목록 조회 (페이지네이션 지원)
+   *
+   * @example
+   * ```ts
+   * // 기본 조회 (최대 20개)
+   * const { total_count, pages } = await cb.storage.listPageMetas('web-storage-id')
+   *
+   * // 페이지네이션
+   * const page2 = await cb.storage.listPageMetas('web-storage-id', { limit: 10, offset: 10 })
+   * ```
    */
-  async listPageMetas(webStorageId) {
+  async listPageMetas(webStorageId, options) {
     const prefix = this.getPublicPrefix();
+    const params = new URLSearchParams();
+    if (options?.limit != null) params.set("limit", String(options.limit));
+    if (options?.offset != null) params.set("offset", String(options.offset));
+    const query = params.toString();
     return this.http.get(
-      `${prefix}/storages/webs/${webStorageId}/page-metas`
+      `${prefix}/storages/webs/${webStorageId}/page-metas${query ? `?${query}` : ""}`
     );
   }
   /**
@@ -1747,6 +1760,15 @@ var RealtimeAPI = class {
     this.streamSessions = /* @__PURE__ */ new Map();
     this.stateHandlers = [];
     this.errorHandlers = [];
+    // Presence handlers
+    this.presenceHandlers = [];
+    this.presenceSubscriptions = /* @__PURE__ */ new Map();
+    // Typing handlers
+    this.typingHandlers = /* @__PURE__ */ new Map();
+    // Read receipt handlers
+    this.readReceiptHandlers = /* @__PURE__ */ new Map();
+    // 연결 중일 때 대기하는 Promise들
+    this.connectPromise = null;
     this.http = http;
     this.socketUrl = socketUrl;
     this.clientId = this.generateClientId();
@@ -1766,14 +1788,22 @@ var RealtimeAPI = class {
    * - userId: 사용자 식별자 (표시용)
    */
   async connect(options = {}) {
-    if (this.state === "connected" || this.state === "connecting") {
+    if (this.state === "connected") {
       return;
     }
+    if (this.state === "connecting" && this.connectPromise) {
+      return this.connectPromise;
+    }
     this.options = { ...this.options, ...options };
     if (options.userId) {
       this.userId = options.userId;
     }
-    return this.doConnect();
+    this.connectPromise = this.doConnect();
+    try {
+      await this.connectPromise;
+    } finally {
+      this.connectPromise = null;
+    }
   }
   /**
    * 연결 해제
@@ -1791,6 +1821,20 @@ var RealtimeAPI = class {
     });
     this.pendingRequests.clear();
     this.subscriptions.clear();
+    this.streamSessions.forEach((session) => {
+      if (session.handlers.onError) {
+        session.handlers.onError(new Error("Connection closed"));
+      }
+    });
+    this.streamSessions.clear();
+    this.presenceHandlers = [];
+    this.presenceSubscriptions.clear();
+    this.typingHandlers.clear();
+    this.readReceiptHandlers.clear();
+    this._connectionId = null;
+    this._appId = null;
+    this.retryCount = 0;
+    this.connectPromise = null;
   }
   /**
    * 카테고리 구독
@@ -1826,6 +1870,10 @@ var RealtimeAPI = class {
       },
       onMessage: (handler) => {
         handlers.push(handler);
+        return () => {
+          const idx = handlers.indexOf(handler);
+          if (idx > -1) handlers.splice(idx, 1);
+        };
       }
     };
     return subscription;
@@ -1933,21 +1981,26 @@ var RealtimeAPI = class {
       handlers,
       requestId
     });
-    this.sendRaw({
-      category: "",
-      action: "stream",
-      data: {
-        provider: options.provider,
-        model: options.model,
-        messages,
-        system: options.system,
-        temperature: options.temperature,
-        max_tokens: options.maxTokens,
-        session_id: sessionId,
-        metadata: options.metadata
-      },
-      request_id: requestId
-    });
+    try {
+      this.sendRaw({
+        category: "",
+        action: "stream",
+        data: {
+          provider: options.provider,
+          model: options.model,
+          messages,
+          system: options.system,
+          temperature: options.temperature,
+          max_tokens: options.maxTokens,
+          session_id: sessionId,
+          metadata: options.metadata
+        },
+        request_id: requestId
+      });
+    } catch (e) {
+      this.streamSessions.delete(sessionId);
+      throw e;
+    }
     return {
       sessionId,
       stop: async () => {
@@ -2003,6 +2056,344 @@ var RealtimeAPI = class {
       if (idx > -1) this.errorHandlers.splice(idx, 1);
     };
   }
+  // ========== Presence API ==========
+  /**
+   * 프레전스 상태 설정
+   * @param status 상태 (online, away, busy, offline)
+   * @param options 추가 옵션 (device, metadata)
+   *
+   * @example
+   * ```typescript
+   * await client.realtime.setPresence('online', {
+   *     device: 'web',
+   *     metadata: { nickname: 'John' }
+   * })
+   * ```
+   */
+  async setPresence(status, options = {}) {
+    if (this.state !== "connected") {
+      throw new Error("Not connected");
+    }
+    const requestId = this.generateRequestId();
+    await this.sendRequest({
+      category: "",
+      action: "presence_set",
+      data: {
+        status,
+        device: options.device,
+        metadata: options.metadata
+      },
+      request_id: requestId
+    });
+  }
+  /**
+   * 연결 해제 시 자동으로 설정될 프레전스 상태 지정
+   * @param status 연결 해제 시 변경할 상태
+   * @param metadata 연결 해제 시 업데이트할 메타데이터
+   *
+   * @example
+   * ```typescript
+   * // 연결이 끊기면 자동으로 offline으로 변경
+   * await client.realtime.setPresenceOnDisconnect('offline')
+   * ```
+   */
+  async setPresenceOnDisconnect(status, metadata) {
+    if (this.state !== "connected") {
+      throw new Error("Not connected");
+    }
+    const requestId = this.generateRequestId();
+    await this.sendRequest({
+      category: "",
+      action: "presence_on_disconnect",
+      data: { status, metadata },
+      request_id: requestId
+    });
+  }
+  /**
+   * 특정 사용자의 프레전스 조회
+   * @param userId 조회할 사용자 ID
+   * @returns 프레전스 정보
+   *
+   * @example
+   * ```typescript
+   * const presence = await client.realtime.getPresence('user-123')
+   * console.log(presence.status) // 'online'
+   * ```
+   */
+  async getPresence(userId) {
+    if (this.state !== "connected") {
+      throw new Error("Not connected");
+    }
+    const requestId = this.generateRequestId();
+    const response = await this.sendRequest({
+      category: "",
+      action: "presence_get",
+      data: { user_id: userId },
+      request_id: requestId
+    });
+    return {
+      userId: response.user_id,
+      status: response.status,
+      lastSeen: response.last_seen,
+      device: response.device,
+      metadata: response.metadata
+    };
+  }
+  /**
+   * 여러 사용자의 프레전스 조회
+   * @param userIds 조회할 사용자 ID 목록
+   * @returns 사용자별 프레전스 정보
+   *
+   * @example
+   * ```typescript
+   * const result = await client.realtime.getPresenceMany(['user-1', 'user-2'])
+   * console.log(result.users['user-1'].status)
+   * ```
+   */
+  async getPresenceMany(userIds) {
+    if (this.state !== "connected") {
+      throw new Error("Not connected");
+    }
+    const requestId = this.generateRequestId();
+    const response = await this.sendRequest({
+      category: "",
+      action: "presence_get_many",
+      data: { user_ids: userIds },
+      request_id: requestId
+    });
+    const users = {};
+    for (const [id, data] of Object.entries(response.users)) {
+      users[id] = {
+        userId: data.user_id,
+        status: data.status,
+        lastSeen: data.last_seen,
+        device: data.device,
+        metadata: data.metadata
+      };
+    }
+    return { users };
+  }
+  /**
+   * 특정 사용자의 프레전스 변경 구독
+   * @param userId 구독할 사용자 ID
+   * @param handler 프레전스 변경 핸들러
+   * @returns 구독 해제 함수
+   *
+   * @example
+   * ```typescript
+   * const unsubscribe = await client.realtime.subscribePresence('user-123', (presence) => {
+   *     console.log(`${presence.userId} is now ${presence.status}`)
+   * })
+   *
+   * // 나중에 구독 해제
+   * unsubscribe()
+   * ```
+   */
+  async subscribePresence(userId, handler) {
+    if (this.state !== "connected") {
+      throw new Error("Not connected");
+    }
+    if (!this.presenceSubscriptions.has(userId)) {
+      const requestId = this.generateRequestId();
+      await this.sendRequest({
+        category: "",
+        action: "presence_subscribe",
+        data: { user_id: userId },
+        request_id: requestId
+      });
+      this.presenceSubscriptions.set(userId, []);
+    }
+    const handlers = this.presenceSubscriptions.get(userId);
+    handlers.push(handler);
+    return () => {
+      const idx = handlers.indexOf(handler);
+      if (idx > -1) handlers.splice(idx, 1);
+      if (handlers.length === 0) {
+        this.presenceSubscriptions.delete(userId);
+        if (this.state === "connected") {
+          const requestId = this.generateRequestId();
+          this.sendRequest({
+            category: "",
+            action: "presence_unsubscribe",
+            data: { user_id: userId },
+            request_id: requestId
+          }).catch((e) => {
+            this.log(`Failed to unsubscribe presence for ${userId}: ${e}`);
+          });
+        }
+      }
+    };
+  }
+  /**
+   * 전체 프레전스 변경 이벤트 구독
+   * @param handler 프레전스 변경 핸들러
+   * @returns 구독 해제 함수
+   *
+   * @example
+   * ```typescript
+   * const unsubscribe = client.realtime.onPresenceChange((presence) => {
+   *     if (presence.eventType === 'join') {
+   *         console.log(`${presence.userId} joined`)
+   *     }
+   * })
+   * ```
+   */
+  onPresenceChange(handler) {
+    this.presenceHandlers.push(handler);
+    return () => {
+      const idx = this.presenceHandlers.indexOf(handler);
+      if (idx > -1) this.presenceHandlers.splice(idx, 1);
+    };
+  }
+  // ========== Typing API ==========
+  /**
+   * 타이핑 시작 알림
+   * @param roomId 타이핑 중인 룸/채널 ID (category 이름)
+   *
+   * @example
+   * ```typescript
+   * // 입력 시작 시
+   * input.addEventListener('focus', () => {
+   *     client.realtime.startTyping('chat-room-1')
+   * })
+   * ```
+   */
+  async startTyping(roomId) {
+    if (this.state !== "connected") {
+      throw new Error("Not connected");
+    }
+    const requestId = this.generateRequestId();
+    await this.sendRequest({
+      category: "",
+      action: "typing_start",
+      data: { room_id: roomId },
+      request_id: requestId
+    });
+  }
+  /**
+   * 타이핑 종료 알림
+   * @param roomId 타이핑을 종료할 룸/채널 ID
+   *
+   * @example
+   * ```typescript
+   * // 입력 종료 또는 메시지 전송 시
+   * input.addEventListener('blur', () => {
+   *     client.realtime.stopTyping('chat-room-1')
+   * })
+   * ```
+   */
+  async stopTyping(roomId) {
+    if (this.state !== "connected") {
+      throw new Error("Not connected");
+    }
+    const requestId = this.generateRequestId();
+    await this.sendRequest({
+      category: "",
+      action: "typing_stop",
+      data: { room_id: roomId },
+      request_id: requestId
+    });
+  }
+  /**
+   * 타이핑 상태 변경 구독
+   * @param roomId 구독할 룸/채널 ID
+   * @param handler 타이핑 상태 변경 핸들러
+   * @returns 구독 해제 함수
+   *
+   * @example
+   * ```typescript
+   * const unsubscribe = await client.realtime.onTypingChange('chat-room-1', (typing) => {
+   *     if (typing.users.length > 0) {
+   *         indicator.textContent = `${typing.users.join(', ')} is typing...`
+   *     } else {
+   *         indicator.textContent = ''
+   *     }
+   * })
+   * ```
+   */
+  async onTypingChange(roomId, handler) {
+    if (this.state !== "connected") {
+      throw new Error("Not connected");
+    }
+    if (!this.typingHandlers.has(roomId)) {
+      const requestId = this.generateRequestId();
+      await this.sendRequest({
+        category: "",
+        action: "typing_subscribe",
+        data: { room_id: roomId },
+        request_id: requestId
+      });
+      this.typingHandlers.set(roomId, []);
+    }
+    const handlers = this.typingHandlers.get(roomId);
+    handlers.push(handler);
+    return () => {
+      const idx = handlers.indexOf(handler);
+      if (idx > -1) handlers.splice(idx, 1);
+      if (handlers.length === 0) {
+        this.typingHandlers.delete(roomId);
+        if (this.state === "connected") {
+          const requestId = this.generateRequestId();
+          this.sendRequest({
+            category: "",
+            action: "typing_unsubscribe",
+            data: { room_id: roomId },
+            request_id: requestId
+          }).catch((e) => {
+            this.log(`Failed to unsubscribe typing for ${roomId}: ${e}`);
+          });
+        }
+      }
+    };
+  }
+  // ========== Read Receipt API ==========
+  /**
+   * 메시지 읽음 표시
+   * @param category 카테고리 이름
+   * @param messageIds 읽음 처리할 메시지 ID 목록
+   *
+   * @example
+   * ```typescript
+   * // 메시지를 읽었을 때
+   * await client.realtime.markRead('chat-room-1', ['msg-1', 'msg-2'])
+   * ```
+   */
+  async markRead(category, messageIds) {
+    if (this.state !== "connected") {
+      throw new Error("Not connected");
+    }
+    const requestId = this.generateRequestId();
+    await this.sendRequest({
+      category,
+      action: "mark_read",
+      data: { message_ids: messageIds },
+      request_id: requestId
+    });
+  }
+  /**
+   * 읽음 확인 이벤트 구독
+   * @param category 구독할 카테고리 이름
+   * @param handler 읽음 확인 핸들러
+   * @returns 구독 해제 함수
+   *
+   * @example
+   * ```typescript
+   * const unsubscribe = client.realtime.onReadReceipt('chat-room-1', (receipt) => {
+   *     console.log(`${receipt.readerId} read messages: ${receipt.messageIds.join(', ')}`)
+   * })
+   * ```
+   */
+  onReadReceipt(category, handler) {
+    if (!this.readReceiptHandlers.has(category)) {
+      this.readReceiptHandlers.set(category, []);
+    }
+    const handlers = this.readReceiptHandlers.get(category);
+    handlers.push(handler);
+    return () => {
+      const idx = handlers.indexOf(handler);
+      if (idx > -1) handlers.splice(idx, 1);
+    };
+  }
   // Private methods
   async doConnect() {
     return new Promise((resolve, reject) => {
@@ -2194,26 +2585,174 @@ var RealtimeAPI = class {
         }
         break;
       }
+      // Presence events
+      case "presence":
+      case "presence_status": {
+        const data = msg.data;
+        const presence = {
+          userId: data.user_id,
+          status: data.status,
+          lastSeen: data.last_seen,
+          device: data.device,
+          metadata: data.metadata,
+          eventType: data.event_type
+        };
+        this.presenceHandlers.forEach((h) => h(presence));
+        const userHandlers = this.presenceSubscriptions.get(data.user_id);
+        if (userHandlers) {
+          userHandlers.forEach((h) => h(presence));
+        }
+        if (msg.request_id) {
+          const pending = this.pendingRequests.get(msg.request_id);
+          if (pending) {
+            clearTimeout(pending.timeout);
+            pending.resolve(msg.data);
+            this.pendingRequests.delete(msg.request_id);
+          }
+        }
+        break;
+      }
+      // Typing events
+      case "typing": {
+        const data = msg.data;
+        const typing = {
+          roomId: data.room_id,
+          users: data.users
+        };
+        const typingHandlers = this.typingHandlers.get(data.room_id);
+        if (typingHandlers) {
+          typingHandlers.forEach((h) => h(typing));
+        }
+        break;
+      }
+      // Read receipt events
+      case "read_receipt": {
+        const data = msg.data;
+        const receipt = {
+          category: data.category,
+          messageIds: data.message_ids,
+          readerId: data.reader_id,
+          readAt: data.read_at
+        };
+        const receiptHandlers = this.readReceiptHandlers.get(data.category);
+        if (receiptHandlers) {
+          receiptHandlers.forEach((h) => h(receipt));
+        }
+        break;
+      }
     }
   }
   handleDisconnect() {
     this.ws = null;
     this._connectionId = null;
+    this.streamSessions.forEach((session) => {
+      if (session.handlers.onError) {
+        session.handlers.onError(new Error("Connection lost"));
+      }
+    });
+    this.streamSessions.clear();
+    const previousSubscriptions = /* @__PURE__ */ new Map();
+    for (const [category, sub] of this.subscriptions) {
+      previousSubscriptions.set(category, [...sub.handlers]);
+    }
+    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++;
-      setTimeout(() => {
-        this.doConnect().catch((e) => {
+      const delay = Math.min(
+        this.options.retryInterval * Math.pow(2, this.retryCount - 1),
+        3e4
+      );
+      setTimeout(async () => {
+        try {
+          await this.doConnect();
+          this.log("Reconnected successfully, restoring subscriptions...");
+          await this.restoreSubscriptions(
+            previousSubscriptions,
+            previousPresenceSubscriptions,
+            previousTypingHandlers
+          );
+        } catch (e) {
           console.error("[Realtime] Reconnect failed:", e);
-        });
-      }, this.options.retryInterval * this.retryCount);
+        }
+      }, delay);
     } else {
       this.state = "disconnected";
       this.notifyStateChange();
       this.notifyError(new Error("Connection lost. Max retries exceeded."));
     }
   }
+  /**
+   * 이전 구독 상태를 복구합니다.
+   * 재연결 성공 후 호출됩니다.
+   */
+  async restoreSubscriptions(previousSubscriptions, previousPresenceSubscriptions, previousTypingHandlers) {
+    for (const [category, handlers] of previousSubscriptions) {
+      try {
+        this.log(`Restoring subscription: ${category}`);
+        const requestId = this.generateRequestId();
+        const response = await this.sendRequest({
+          category,
+          action: "subscribe",
+          request_id: requestId
+        });
+        const info = {
+          category: response.category,
+          persist: response.persist,
+          historyCount: response.history_count,
+          readReceipt: response.read_receipt
+        };
+        this.subscriptions.set(category, { info, handlers });
+        this.log(`Restored subscription: ${category}`);
+      } catch (e) {
+        console.error(`[Realtime] Failed to restore subscription for ${category}:`, e);
+        this.notifyError(new Error(`Failed to restore subscription: ${category}`));
+      }
+    }
+    for (const [userId, handlers] of previousPresenceSubscriptions) {
+      try {
+        this.log(`Restoring presence subscription: ${userId}`);
+        const requestId = this.generateRequestId();
+        await this.sendRequest({
+          category: "",
+          action: "presence_subscribe",
+          data: { user_id: userId },
+          request_id: requestId
+        });
+        this.presenceSubscriptions.set(userId, handlers);
+        this.log(`Restored presence subscription: ${userId}`);
+      } catch (e) {
+        console.error(`[Realtime] Failed to restore presence subscription for ${userId}:`, e);
+      }
+    }
+    for (const [roomId, handlers] of previousTypingHandlers) {
+      try {
+        this.log(`Restoring typing subscription: ${roomId}`);
+        const requestId = this.generateRequestId();
+        await this.sendRequest({
+          category: "",
+          action: "typing_subscribe",
+          data: { room_id: roomId },
+          request_id: requestId
+        });
+        this.typingHandlers.set(roomId, handlers);
+        this.log(`Restored typing subscription: ${roomId}`);
+      } catch (e) {
+        console.error(`[Realtime] Failed to restore typing subscription for ${roomId}:`, e);
+      }
+    }
+  }
   sendRequest(message) {
     return new Promise((resolve, reject) => {
       if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
@@ -2223,7 +2762,7 @@ var RealtimeAPI = class {
       const timeout = setTimeout(() => {
         this.pendingRequests.delete(message.request_id);
         reject(new Error("Request timeout"));
-      }, 3e4);
+      }, this.options.timeout);
       this.pendingRequests.set(message.request_id, {
         resolve,
         reject,