@unicitylabs/sphere-sdk 0.6.1 → 0.6.2

package/dist/core/index.d.cts

@@ -63,6 +63,17 @@ interface GroupChatModuleConfig {
     /** Max reconnect attempts (default: 5) */
     maxReconnectAttempts?: number;
 }
+interface GroupMessagesPage {
+    messages: GroupMessageData[];
+    hasMore: boolean;
+    oldestTimestamp: number | null;
+}
+interface GetGroupMessagesPageOptions {
+    /** Max messages to return (default: 20) */
+    limit?: number;
+    /** Return messages older than this timestamp */
+    before?: number;
+}
 interface CreateGroupOptions {
     name: string;
     description?: string;
@@ -762,7 +773,7 @@ interface TrackedAddress extends TrackedAddressEntry {
     /** Primary nametag (from nametag cache, without @ prefix) */
     readonly nametag?: string;
 }
-type SphereEventType = 'transfer:incoming' | 'transfer:confirmed' | 'transfer:failed' | 'payment_request:incoming' | 'payment_request:accepted' | 'payment_request:rejected' | 'payment_request:paid' | 'payment_request:response' | 'message:dm' | 'message:read' | 'message:typing' | 'composing:started' | 'message:broadcast' | 'sync:started' | 'sync:completed' | 'sync:provider' | 'sync:error' | 'connection:changed' | 'nametag:registered' | 'nametag:recovered' | 'identity:changed' | 'address:activated' | 'address:hidden' | 'address:unhidden' | 'sync:remote-update' | 'groupchat:message' | 'groupchat:joined' | 'groupchat:left' | 'groupchat:kicked' | 'groupchat:group_deleted' | 'groupchat:updated' | 'groupchat:connection' | 'history:updated';
+type SphereEventType = 'transfer:incoming' | 'transfer:confirmed' | 'transfer:failed' | 'payment_request:incoming' | 'payment_request:accepted' | 'payment_request:rejected' | 'payment_request:paid' | 'payment_request:response' | 'message:dm' | 'message:read' | 'message:typing' | 'composing:started' | 'message:broadcast' | 'sync:started' | 'sync:completed' | 'sync:provider' | 'sync:error' | 'connection:changed' | 'nametag:registered' | 'nametag:recovered' | 'identity:changed' | 'address:activated' | 'address:hidden' | 'address:unhidden' | 'sync:remote-update' | 'groupchat:message' | 'groupchat:joined' | 'groupchat:left' | 'groupchat:kicked' | 'groupchat:group_deleted' | 'groupchat:updated' | 'groupchat:connection' | 'groupchat:ready' | 'communications:ready' | 'history:updated';
 interface SphereEventMap {
     'transfer:incoming': IncomingTransfer;
     'transfer:confirmed': TransferResult;
@@ -862,6 +873,12 @@ interface SphereEventMap {
     'groupchat:connection': {
         connected: boolean;
     };
+    'groupchat:ready': {
+        groupCount: number;
+    };
+    'communications:ready': {
+        conversationCount: number;
+    };
     'history:updated': TransactionHistoryEntry;
 }
 type SphereEventHandler<T extends SphereEventType> = (data: SphereEventMap[T]) => void;
@@ -1389,6 +1406,14 @@ interface TransportProvider extends BaseProvider {
      * and resolves after EOSE (End Of Stored Events).
      */
     fetchPendingEvents?(): Promise<void>;
+    /**
+     * Register a handler to be called when the chat subscription receives EOSE
+     * (End Of Stored Events), indicating that historical DMs have been delivered.
+     * The handler fires at most once per subscription lifecycle.
+     *
+     * @returns Unsubscribe function
+     */
+    onChatReady?(handler: () => void): () => void;
 }
 /**
  * Payload for sending instant split bundles
@@ -2951,6 +2976,7 @@ declare class GroupChatModule {
     getGroups(): GroupData[];
     getGroup(groupId: string): GroupData | null;
     getMessages(groupId: string): GroupMessageData[];
+    getMessagesPage(groupId: string, options?: GetGroupMessagesPageOptions): GroupMessagesPage;
     getMembers(groupId: string): GroupMemberData[];
     getMember(groupId: string, pubkey: string): GroupMemberData | null;
     getTotalUnreadCount(): number;

package/dist/core/index.d.ts

@@ -63,6 +63,17 @@ interface GroupChatModuleConfig {
     /** Max reconnect attempts (default: 5) */
     maxReconnectAttempts?: number;
 }
+interface GroupMessagesPage {
+    messages: GroupMessageData[];
+    hasMore: boolean;
+    oldestTimestamp: number | null;
+}
+interface GetGroupMessagesPageOptions {
+    /** Max messages to return (default: 20) */
+    limit?: number;
+    /** Return messages older than this timestamp */
+    before?: number;
+}
 interface CreateGroupOptions {
     name: string;
     description?: string;
@@ -762,7 +773,7 @@ interface TrackedAddress extends TrackedAddressEntry {
     /** Primary nametag (from nametag cache, without @ prefix) */
     readonly nametag?: string;
 }
-type SphereEventType = 'transfer:incoming' | 'transfer:confirmed' | 'transfer:failed' | 'payment_request:incoming' | 'payment_request:accepted' | 'payment_request:rejected' | 'payment_request:paid' | 'payment_request:response' | 'message:dm' | 'message:read' | 'message:typing' | 'composing:started' | 'message:broadcast' | 'sync:started' | 'sync:completed' | 'sync:provider' | 'sync:error' | 'connection:changed' | 'nametag:registered' | 'nametag:recovered' | 'identity:changed' | 'address:activated' | 'address:hidden' | 'address:unhidden' | 'sync:remote-update' | 'groupchat:message' | 'groupchat:joined' | 'groupchat:left' | 'groupchat:kicked' | 'groupchat:group_deleted' | 'groupchat:updated' | 'groupchat:connection' | 'history:updated';
+type SphereEventType = 'transfer:incoming' | 'transfer:confirmed' | 'transfer:failed' | 'payment_request:incoming' | 'payment_request:accepted' | 'payment_request:rejected' | 'payment_request:paid' | 'payment_request:response' | 'message:dm' | 'message:read' | 'message:typing' | 'composing:started' | 'message:broadcast' | 'sync:started' | 'sync:completed' | 'sync:provider' | 'sync:error' | 'connection:changed' | 'nametag:registered' | 'nametag:recovered' | 'identity:changed' | 'address:activated' | 'address:hidden' | 'address:unhidden' | 'sync:remote-update' | 'groupchat:message' | 'groupchat:joined' | 'groupchat:left' | 'groupchat:kicked' | 'groupchat:group_deleted' | 'groupchat:updated' | 'groupchat:connection' | 'groupchat:ready' | 'communications:ready' | 'history:updated';
 interface SphereEventMap {
     'transfer:incoming': IncomingTransfer;
     'transfer:confirmed': TransferResult;
@@ -862,6 +873,12 @@ interface SphereEventMap {
     'groupchat:connection': {
         connected: boolean;
     };
+    'groupchat:ready': {
+        groupCount: number;
+    };
+    'communications:ready': {
+        conversationCount: number;
+    };
     'history:updated': TransactionHistoryEntry;
 }
 type SphereEventHandler<T extends SphereEventType> = (data: SphereEventMap[T]) => void;
@@ -1389,6 +1406,14 @@ interface TransportProvider extends BaseProvider {
      * and resolves after EOSE (End Of Stored Events).
      */
     fetchPendingEvents?(): Promise<void>;
+    /**
+     * Register a handler to be called when the chat subscription receives EOSE
+     * (End Of Stored Events), indicating that historical DMs have been delivered.
+     * The handler fires at most once per subscription lifecycle.
+     *
+     * @returns Unsubscribe function
+     */
+    onChatReady?(handler: () => void): () => void;
 }
 /**
  * Payload for sending instant split bundles
@@ -2951,6 +2976,7 @@ declare class GroupChatModule {
     getGroups(): GroupData[];
     getGroup(groupId: string): GroupData | null;
     getMessages(groupId: string): GroupMessageData[];
+    getMessagesPage(groupId: string, options?: GetGroupMessagesPageOptions): GroupMessagesPage;
     getMembers(groupId: string): GroupMemberData[];
     getMember(groupId: string, pubkey: string): GroupMemberData | null;
     getTotalUnreadCount(): number;

package/dist/core/index.js

@@ -8299,6 +8299,12 @@ var CommunicationsModule = class {
     this.unsubscribeComposing = deps.transport.onComposing?.((indicator) => {
       this.handleComposingIndicator(indicator);
     }) ?? null;
+    if (deps.transport.onChatReady) {
+      deps.transport.onChatReady(() => {
+        const conversations = this.getConversations();
+        deps.emitEvent("communications:ready", { conversationCount: conversations.size });
+      });
+    }
   }
   /**
    * Load messages from storage.
@@ -8945,6 +8951,7 @@ var GroupChatModule = class {
         await this.subscribeToJoinedGroups();
       }
       this.deps.emitEvent("groupchat:connection", { connected: true });
+      this.deps.emitEvent("groupchat:ready", { groupCount: this.groups.size });
     } catch (error) {
       logger.error("GroupChat", "Failed to connect to relays", error);
       this.deps.emitEvent("groupchat:connection", { connected: false });
@@ -9579,6 +9586,19 @@ var GroupChatModule = class {
   getMessages(groupId) {
     return (this.messages.get(groupId) || []).sort((a, b) => a.timestamp - b.timestamp);
   }
+  getMessagesPage(groupId, options) {
+    const limit = options?.limit ?? 20;
+    const before = options?.before ?? Infinity;
+    const groupMessages = this.messages.get(groupId) ?? [];
+    const filtered = groupMessages.filter((m) => m.timestamp < before).sort((a, b) => b.timestamp - a.timestamp);
+    const page = filtered.slice(0, limit);
+    return {
+      messages: page.reverse(),
+      // chronological order
+      hasMore: filtered.length > limit,
+      oldestTimestamp: page.length > 0 ? page[0].timestamp : null
+    };
+  }
   getMembers(groupId) {
     return (this.members.get(groupId) || []).sort((a, b) => a.joinedAt - b.joinedAt);
   }