@unicitylabs/sphere-sdk 0.6.0 → 0.6.2

package/dist/core/index.d.cts

@@ -29,6 +29,8 @@ interface GroupData {
     unreadCount?: number;
     lastMessageTime?: number;
     lastMessageText?: string;
+    /** Only admins and moderators can post; other members are read-only (NIP-29 "write-restricted" tag) */
+    writeRestricted?: boolean;
     /** When the current user joined this group locally (used to filter old events) */
     localJoinedAt?: number;
 }
@@ -61,11 +63,24 @@ 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;
     picture?: string;
     visibility?: GroupVisibility;
+    /** Only admins and moderators can post; other members are read-only */
+    writeRestricted?: boolean;
 }
 
 /**
@@ -758,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;
@@ -858,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;
@@ -1385,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
@@ -2947,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;
@@ -2962,6 +2992,12 @@ declare class GroupChatModule {
      */
     canModerateGroup(groupId: string): Promise<boolean>;
     isCurrentUserRelayAdmin(): Promise<boolean>;
+    /**
+     * Check if current user can write messages to a group.
+     * For write-restricted groups, only admins/moderators can post.
+     * For normal groups, any member can post.
+     */
+    canWriteToGroup(groupId: string): boolean;
     getCurrentUserRole(groupId: string): GroupRole | null;
     onMessage(handler: (message: GroupMessageData) => void): () => void;
     getRelayUrls(): string[];

package/dist/core/index.d.ts

@@ -29,6 +29,8 @@ interface GroupData {
     unreadCount?: number;
     lastMessageTime?: number;
     lastMessageText?: string;
+    /** Only admins and moderators can post; other members are read-only (NIP-29 "write-restricted" tag) */
+    writeRestricted?: boolean;
     /** When the current user joined this group locally (used to filter old events) */
     localJoinedAt?: number;
 }
@@ -61,11 +63,24 @@ 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;
     picture?: string;
     visibility?: GroupVisibility;
+    /** Only admins and moderators can post; other members are read-only */
+    writeRestricted?: boolean;
 }
 
 /**
@@ -758,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;
@@ -858,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;
@@ -1385,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
@@ -2947,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;
@@ -2962,6 +2992,12 @@ declare class GroupChatModule {
      */
     canModerateGroup(groupId: string): Promise<boolean>;
     isCurrentUserRelayAdmin(): Promise<boolean>;
+    /**
+     * Check if current user can write messages to a group.
+     * For write-restricted groups, only admins/moderators can post.
+     * For normal groups, any member can post.
+     */
+    canWriteToGroup(groupId: string): boolean;
     getCurrentUserRole(groupId: string): GroupRole | null;
     onMessage(handler: (message: GroupMessageData) => void): () => void;
     getRelayUrls(): string[];

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 });
@@ -9063,17 +9070,23 @@ var GroupChatModule = class {
     const group = this.groups.get(groupId);
     if (!group) return;
     if (event.kind === NIP29_KINDS.GROUP_METADATA) {
-      if (!event.content || event.content.trim() === "") return;
-      try {
-        const metadata = JSON.parse(event.content);
-        group.name = metadata.name || group.name;
-        group.description = metadata.about || group.description;
-        group.picture = metadata.picture || group.picture;
-        group.updatedAt = event.created_at * 1e3;
-        this.groups.set(groupId, group);
-        this.persistGroups();
-      } catch {
+      if (event.content && event.content.trim()) {
+        try {
+          const metadata = JSON.parse(event.content);
+          group.name = metadata.name || group.name;
+          group.description = metadata.about || group.description;
+          group.picture = metadata.picture || group.picture;
+          if (metadata["write-restricted"] === true) group.writeRestricted = true;
+          else group.writeRestricted = void 0;
+        } catch {
+        }
       }
+      for (const tag of event.tags) {
+        if (tag[0] === "write-restricted") group.writeRestricted = true;
+      }
+      group.updatedAt = event.created_at * 1e3;
+      this.groups.set(groupId, group);
+      this.persistGroups();
     } else if (event.kind === NIP29_KINDS.GROUP_MEMBERS) {
       this.updateMembersFromEvent(groupId, event);
     } else if (event.kind === NIP29_KINDS.GROUP_ADMINS) {
@@ -9377,7 +9390,8 @@ var GroupChatModule = class {
           picture: options.picture,
           closed: true,
           private: isPrivate,
-          hidden: isPrivate
+          hidden: isPrivate,
+          ...options.writeRestricted ? { "write-restricted": true } : {}
         })
       });
       if (!eventId) return null;
@@ -9572,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);
   }
@@ -9678,6 +9705,17 @@ var GroupChatModule = class {
     const admins = await this.fetchRelayAdmins();
     return admins.has(myPubkey);
   }
+  /**
+   * Check if current user can write messages to a group.
+   * For write-restricted groups, only admins/moderators can post.
+   * For normal groups, any member can post.
+   */
+  canWriteToGroup(groupId) {
+    const group = this.groups.get(groupId);
+    if (!group) return false;
+    if (!group.writeRestricted) return true;
+    return this.isCurrentUserModerator(groupId);
+  }
   getCurrentUserRole(groupId) {
     const myPubkey = this.getMyPublicKey();
     if (!myPubkey) return null;
@@ -10052,6 +10090,7 @@ var GroupChatModule = class {
       let description;
       let picture;
       let isPrivate = false;
+      let writeRestricted = false;
       if (event.content && event.content.trim()) {
         try {
           const metadata = JSON.parse(event.content);
@@ -10059,6 +10098,7 @@ var GroupChatModule = class {
           description = metadata.about || metadata.description;
           picture = metadata.picture;
           isPrivate = metadata.private === true;
+          if (metadata["write-restricted"] === true) writeRestricted = true;
         } catch {
         }
       }
@@ -10068,6 +10108,7 @@ var GroupChatModule = class {
         if (tag[0] === "picture" && tag[1]) picture = tag[1];
         if (tag[0] === "private") isPrivate = true;
         if (tag[0] === "public" && tag[1] === "false") isPrivate = true;
+        if (tag[0] === "write-restricted") writeRestricted = true;
       }
       return {
         id: groupId,
@@ -10076,6 +10117,7 @@ var GroupChatModule = class {
         description,
         picture,
         visibility: isPrivate ? GroupVisibility.PRIVATE : GroupVisibility.PUBLIC,
+        writeRestricted: writeRestricted || void 0,
         createdAt: event.created_at * 1e3
       };
     } catch {