@unicitylabs/sphere-sdk 0.6.1 → 0.6.3

package/dist/index.d.cts

@@ -64,6 +64,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;
@@ -1303,7 +1314,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;
@@ -1403,6 +1414,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;
@@ -1705,6 +1722,13 @@ interface TokenStorageProvider<TData = unknown> extends BaseProvider {
      * Clear all data
      */
     clear?(): Promise<boolean>;
+    /**
+     * Create a new independent instance of this provider for a different address.
+     * Used by per-address module architecture — each address gets its own
+     * TokenStorageProvider instance to avoid cross-address data contamination.
+     * If not implemented, the provider cannot be used in multi-address mode.
+     */
+    createForAddress?(): TokenStorageProvider<TData>;
     /**
      * Subscribe to storage events
      */
@@ -1961,12 +1985,30 @@ interface TransportProvider extends BaseProvider {
      * @returns Unsubscribe function
      */
     onInstantSplitReceived?(handler: InstantSplitBundleHandler): () => void;
+    /**
+     * Set fallback 'since' timestamp for event subscriptions.
+     * Used when switching to an address that has never subscribed before.
+     * The transport uses this instead of 'now' as the initial since filter,
+     * ensuring events sent while the address was inactive are not missed.
+     * Consumed once by the next subscription setup, then cleared.
+     *
+     * @param sinceSeconds - Unix timestamp in seconds
+     */
+    setFallbackSince?(sinceSeconds: number): void;
     /**
      * Fetch pending events from transport (one-shot query).
      * Creates a temporary subscription, processes events through normal handlers,
      * 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
@@ -3656,6 +3698,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;
@@ -4602,6 +4645,11 @@ declare class Sphere {
     private _communications;
     private _groupChat;
     private _market;
+    private _addressModules;
+    private _transportMux;
+    private _l1Config;
+    private _groupChatConfig;
+    private _marketConfig;
     private eventHandlers;
     private _disabledProviders;
     private _providerEventCleanups;
@@ -4997,9 +5045,28 @@ declare class Sphere {
      */
     private postSwitchSync;
     /**
-     * Re-initialize modules after address switch
+     * Create a new set of per-address modules for the given index.
+     * Each address gets its own PaymentsModule, CommunicationsModule, etc.
+     * Modules are fully independent — they have their own token storage,
+     * and can sync/finalize/split in background regardless of active address.
+     *
+     * @param index - HD address index
+     * @param identity - Full identity for this address
+     * @param tokenStorageProviders - Token storage providers for this address
+     */
+    private initializeAddressModules;
+    /**
+     * Ensure the transport multiplexer exists and register an address.
+     * Creates the mux on first call. Returns an AddressTransportAdapter
+     * that routes events for this address independently.
+     * @returns AddressTransportAdapter or null if transport is not Nostr-based
+     */
+    private ensureTransportMux;
+    /**
+     * Get per-address modules for any address index (creates lazily if needed).
+     * This allows accessing any address's modules without switching.
      */
-    private reinitializeModulesForNewAddress;
+    getAddressPayments(index: number): PaymentsModule | undefined;
     /**
      * Derive address at a specific index
      *

package/dist/index.d.ts

@@ -64,6 +64,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;
@@ -1303,7 +1314,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;
@@ -1403,6 +1414,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;
@@ -1705,6 +1722,13 @@ interface TokenStorageProvider<TData = unknown> extends BaseProvider {
      * Clear all data
      */
     clear?(): Promise<boolean>;
+    /**
+     * Create a new independent instance of this provider for a different address.
+     * Used by per-address module architecture — each address gets its own
+     * TokenStorageProvider instance to avoid cross-address data contamination.
+     * If not implemented, the provider cannot be used in multi-address mode.
+     */
+    createForAddress?(): TokenStorageProvider<TData>;
     /**
      * Subscribe to storage events
      */
@@ -1961,12 +1985,30 @@ interface TransportProvider extends BaseProvider {
      * @returns Unsubscribe function
      */
     onInstantSplitReceived?(handler: InstantSplitBundleHandler): () => void;
+    /**
+     * Set fallback 'since' timestamp for event subscriptions.
+     * Used when switching to an address that has never subscribed before.
+     * The transport uses this instead of 'now' as the initial since filter,
+     * ensuring events sent while the address was inactive are not missed.
+     * Consumed once by the next subscription setup, then cleared.
+     *
+     * @param sinceSeconds - Unix timestamp in seconds
+     */
+    setFallbackSince?(sinceSeconds: number): void;
     /**
      * Fetch pending events from transport (one-shot query).
      * Creates a temporary subscription, processes events through normal handlers,
      * 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
@@ -3656,6 +3698,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;
@@ -4602,6 +4645,11 @@ declare class Sphere {
     private _communications;
     private _groupChat;
     private _market;
+    private _addressModules;
+    private _transportMux;
+    private _l1Config;
+    private _groupChatConfig;
+    private _marketConfig;
     private eventHandlers;
     private _disabledProviders;
     private _providerEventCleanups;
@@ -4997,9 +5045,28 @@ declare class Sphere {
      */
     private postSwitchSync;
     /**
-     * Re-initialize modules after address switch
+     * Create a new set of per-address modules for the given index.
+     * Each address gets its own PaymentsModule, CommunicationsModule, etc.
+     * Modules are fully independent — they have their own token storage,
+     * and can sync/finalize/split in background regardless of active address.
+     *
+     * @param index - HD address index
+     * @param identity - Full identity for this address
+     * @param tokenStorageProviders - Token storage providers for this address
+     */
+    private initializeAddressModules;
+    /**
+     * Ensure the transport multiplexer exists and register an address.
+     * Creates the mux on first call. Returns an AddressTransportAdapter
+     * that routes events for this address independently.
+     * @returns AddressTransportAdapter or null if transport is not Nostr-based
+     */
+    private ensureTransportMux;
+    /**
+     * Get per-address modules for any address index (creates lazily if needed).
+     * This allows accessing any address's modules without switching.
      */
-    private reinitializeModulesForNewAddress;
+    getAddressPayments(index: number): PaymentsModule | undefined;
     /**
      * Derive address at a specific index
      *