@unicitylabs/sphere-sdk 0.6.2 → 0.6.3

package/dist/index.d.cts

@@ -1722,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
      */
@@ -1978,6 +1985,16 @@ 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,
@@ -4628,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;
@@ -5023,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

@@ -1722,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
      */
@@ -1978,6 +1985,16 @@ 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,
@@ -4628,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;
@@ -5023,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
      *