@unicitylabs/sphere-sdk 0.6.1 → 0.6.3

package/dist/impl/nodejs/index.d.cts

@@ -195,12 +195,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
@@ -468,6 +486,8 @@ declare class NostrTransportProvider implements TransportProvider {
     private storage;
     /** In-memory max event timestamp to avoid read-before-write races in updateLastEventTimestamp. */
     private lastEventTs;
+    /** Fallback 'since' timestamp for first-time address subscriptions (consumed once). */
+    private fallbackSince;
     private identity;
     private keyManager;
     private status;
@@ -485,6 +505,25 @@ declare class NostrTransportProvider implements TransportProvider {
     private broadcastHandlers;
     private eventCallbacks;
     constructor(config: NostrTransportProviderConfig);
+    /**
+     * Get the WebSocket factory (used by MultiAddressTransportMux to share the same factory).
+     */
+    getWebSocketFactory(): WebSocketFactory;
+    /**
+     * Get the configured relay URLs.
+     */
+    getConfiguredRelays(): string[];
+    /**
+     * Get the storage adapter.
+     */
+    getStorageAdapter(): TransportStorageAdapter | null;
+    /**
+     * Suppress event subscriptions — unsubscribe wallet/chat filters
+     * but keep the connection alive for resolve/identity-binding operations.
+     * Used when MultiAddressTransportMux takes over event handling.
+     */
+    suppressSubscriptions(): void;
+    private _subscriptionsSuppressed;
     connect(): Promise<void>;
     disconnect(): Promise<void>;
     isConnected(): boolean;
@@ -518,6 +557,7 @@ declare class NostrTransportProvider implements TransportProvider {
      */
     isRelayConnected(relayUrl: string): boolean;
     setIdentity(identity: FullIdentity): Promise<void>;
+    setFallbackSince(sinceSeconds: number): void;
     /**
      * Get the Nostr-format public key (32 bytes / 64 hex chars)
      * This is the x-coordinate only, without the 02/03 prefix.
@@ -535,6 +575,7 @@ declare class NostrTransportProvider implements TransportProvider {
     onReadReceipt(handler: ReadReceiptHandler): () => void;
     sendTypingIndicator(recipientTransportPubkey: string): Promise<void>;
     onTypingIndicator(handler: TypingIndicatorHandler): () => void;
+    onChatReady(handler: () => void): () => void;
     onComposing(handler: ComposingHandler): () => void;
     sendComposingIndicator(recipientPubkey: string, content: string): Promise<void>;
     /**
@@ -604,6 +645,8 @@ declare class NostrTransportProvider implements TransportProvider {
     private queryEvents;
     private walletSubscriptionId;
     private chatSubscriptionId;
+    private chatEoseHandlers;
+    private chatEoseFired;
     private subscribeToEvents;
     private subscribeToTags;
     private decryptContent;
@@ -1122,6 +1165,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
      */
@@ -1271,6 +1321,10 @@ declare class FileTokenStorageProvider implements TokenStorageProvider<TxfStorag
     hasHistoryEntry(dedupKey: string): Promise<boolean>;
     clearHistory(): Promise<void>;
     importHistoryEntries(entries: HistoryRecord[]): Promise<number>;
+    /**
+     * Create an independent instance for a different address.
+     */
+    createForAddress(): FileTokenStorageProvider;
 }
 declare function createFileTokenStorageProvider(config: FileTokenStorageConfig | string): FileTokenStorageProvider;
 

package/dist/impl/nodejs/index.d.ts

@@ -195,12 +195,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
@@ -468,6 +486,8 @@ declare class NostrTransportProvider implements TransportProvider {
     private storage;
     /** In-memory max event timestamp to avoid read-before-write races in updateLastEventTimestamp. */
     private lastEventTs;
+    /** Fallback 'since' timestamp for first-time address subscriptions (consumed once). */
+    private fallbackSince;
     private identity;
     private keyManager;
     private status;
@@ -485,6 +505,25 @@ declare class NostrTransportProvider implements TransportProvider {
     private broadcastHandlers;
     private eventCallbacks;
     constructor(config: NostrTransportProviderConfig);
+    /**
+     * Get the WebSocket factory (used by MultiAddressTransportMux to share the same factory).
+     */
+    getWebSocketFactory(): WebSocketFactory;
+    /**
+     * Get the configured relay URLs.
+     */
+    getConfiguredRelays(): string[];
+    /**
+     * Get the storage adapter.
+     */
+    getStorageAdapter(): TransportStorageAdapter | null;
+    /**
+     * Suppress event subscriptions — unsubscribe wallet/chat filters
+     * but keep the connection alive for resolve/identity-binding operations.
+     * Used when MultiAddressTransportMux takes over event handling.
+     */
+    suppressSubscriptions(): void;
+    private _subscriptionsSuppressed;
     connect(): Promise<void>;
     disconnect(): Promise<void>;
     isConnected(): boolean;
@@ -518,6 +557,7 @@ declare class NostrTransportProvider implements TransportProvider {
      */
     isRelayConnected(relayUrl: string): boolean;
     setIdentity(identity: FullIdentity): Promise<void>;
+    setFallbackSince(sinceSeconds: number): void;
     /**
      * Get the Nostr-format public key (32 bytes / 64 hex chars)
      * This is the x-coordinate only, without the 02/03 prefix.
@@ -535,6 +575,7 @@ declare class NostrTransportProvider implements TransportProvider {
     onReadReceipt(handler: ReadReceiptHandler): () => void;
     sendTypingIndicator(recipientTransportPubkey: string): Promise<void>;
     onTypingIndicator(handler: TypingIndicatorHandler): () => void;
+    onChatReady(handler: () => void): () => void;
     onComposing(handler: ComposingHandler): () => void;
     sendComposingIndicator(recipientPubkey: string, content: string): Promise<void>;
     /**
@@ -604,6 +645,8 @@ declare class NostrTransportProvider implements TransportProvider {
     private queryEvents;
     private walletSubscriptionId;
     private chatSubscriptionId;
+    private chatEoseHandlers;
+    private chatEoseFired;
     private subscribeToEvents;
     private subscribeToTags;
     private decryptContent;
@@ -1122,6 +1165,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
      */
@@ -1271,6 +1321,10 @@ declare class FileTokenStorageProvider implements TokenStorageProvider<TxfStorag
     hasHistoryEntry(dedupKey: string): Promise<boolean>;
     clearHistory(): Promise<void>;
     importHistoryEntries(entries: HistoryRecord[]): Promise<number>;
+    /**
+     * Create an independent instance for a different address.
+     */
+    createForAddress(): FileTokenStorageProvider;
 }
 declare function createFileTokenStorageProvider(config: FileTokenStorageConfig | string): FileTokenStorageProvider;
 

package/dist/impl/nodejs/index.js

@@ -319,7 +319,7 @@ import * as path2 from "path";
 var META_FILE = "_meta.json";
 var TOMBSTONES_FILE = "_tombstones.json";
 var HISTORY_FILE = "_history.json";
-var FileTokenStorageProvider = class {
+var FileTokenStorageProvider = class _FileTokenStorageProvider {
   id = "file-token-storage";
   name = "File Token Storage";
   type = "local";
@@ -546,6 +546,12 @@ var FileTokenStorageProvider = class {
     }
     return imported;
   }
+  /**
+   * Create an independent instance for a different address.
+   */
+  createForAddress() {
+    return new _FileTokenStorageProvider({ tokensDir: this.baseTokensDir });
+  }
 };
 function createFileTokenStorageProvider(config) {
   return new FileTokenStorageProvider(config);
@@ -1081,6 +1087,8 @@ var NostrTransportProvider = class {
   storage = null;
   /** In-memory max event timestamp to avoid read-before-write races in updateLastEventTimestamp. */
   lastEventTs = 0;
+  /** Fallback 'since' timestamp for first-time address subscriptions (consumed once). */
+  fallbackSince = null;
   identity = null;
   keyManager = null;
   status = "disconnected";
@@ -1113,6 +1121,48 @@ var NostrTransportProvider = class {
     };
     this.storage = config.storage ?? null;
   }
+  /**
+   * Get the WebSocket factory (used by MultiAddressTransportMux to share the same factory).
+   */
+  getWebSocketFactory() {
+    return this.config.createWebSocket;
+  }
+  /**
+   * Get the configured relay URLs.
+   */
+  getConfiguredRelays() {
+    return [...this.config.relays];
+  }
+  /**
+   * Get the storage adapter.
+   */
+  getStorageAdapter() {
+    return this.storage;
+  }
+  /**
+   * Suppress event subscriptions — unsubscribe wallet/chat filters
+   * but keep the connection alive for resolve/identity-binding operations.
+   * Used when MultiAddressTransportMux takes over event handling.
+   */
+  suppressSubscriptions() {
+    if (!this.nostrClient) return;
+    if (this.walletSubscriptionId) {
+      this.nostrClient.unsubscribe(this.walletSubscriptionId);
+      this.walletSubscriptionId = null;
+    }
+    if (this.chatSubscriptionId) {
+      this.nostrClient.unsubscribe(this.chatSubscriptionId);
+      this.chatSubscriptionId = null;
+    }
+    if (this.mainSubscriptionId) {
+      this.nostrClient.unsubscribe(this.mainSubscriptionId);
+      this.mainSubscriptionId = null;
+    }
+    this._subscriptionsSuppressed = true;
+    logger.debug("Nostr", "Subscriptions suppressed \u2014 mux handles event routing");
+  }
+  // Flag to prevent re-subscription after suppressSubscriptions()
+  _subscriptionsSuppressed = false;
   // ===========================================================================
   // BaseProvider Implementation
   // ===========================================================================
@@ -1180,6 +1230,7 @@ var NostrTransportProvider = class {
     this.mainSubscriptionId = null;
     this.walletSubscriptionId = null;
     this.chatSubscriptionId = null;
+    this.chatEoseFired = false;
     this.status = "disconnected";
     this.emitEvent({ type: "transport:disconnected", timestamp: Date.now() });
     logger.debug("Nostr", "Disconnected from all relays");
@@ -1290,6 +1341,8 @@ var NostrTransportProvider = class {
   // ===========================================================================
   async setIdentity(identity) {
     this.identity = identity;
+    this.processedEventIds.clear();
+    this.lastEventTs = 0;
     const secretKey = Buffer2.from(identity.privateKey, "hex");
     this.keyManager = NostrKeyManager.fromPrivateKey(secretKey);
     const nostrPubkey = this.keyManager.getPublicKeyHex();
@@ -1332,6 +1385,9 @@ var NostrTransportProvider = class {
       await this.subscribeToEvents();
     }
   }
+  setFallbackSince(sinceSeconds) {
+    this.fallbackSince = sinceSeconds;
+  }
   /**
    * Get the Nostr-format public key (32 bytes / 64 hex chars)
    * This is the x-coordinate only, without the 02/03 prefix.
@@ -1503,6 +1559,20 @@ var NostrTransportProvider = class {
     this.typingIndicatorHandlers.add(handler);
     return () => this.typingIndicatorHandlers.delete(handler);
   }
+  onChatReady(handler) {
+    if (this.chatEoseFired) {
+      try {
+        handler();
+      } catch {
+      }
+      return () => {
+      };
+    }
+    this.chatEoseHandlers.push(handler);
+    return () => {
+      this.chatEoseHandlers = this.chatEoseHandlers.filter((h) => h !== handler);
+    };
+  }
   // ===========================================================================
   // Composing Indicators (NIP-59 kind 25050)
   // ===========================================================================
@@ -2220,8 +2290,15 @@ var NostrTransportProvider = class {
   // Track subscription IDs for cleanup
   walletSubscriptionId = null;
   chatSubscriptionId = null;
+  // Chat EOSE handlers — fired once when relay finishes delivering stored DMs
+  chatEoseHandlers = [];
+  chatEoseFired = false;
   async subscribeToEvents() {
     logger.debug("Nostr", "subscribeToEvents called, identity:", !!this.identity, "keyManager:", !!this.keyManager, "nostrClient:", !!this.nostrClient);
+    if (this._subscriptionsSuppressed) {
+      logger.debug("Nostr", "subscribeToEvents: suppressed \u2014 mux handles event routing");
+      return;
+    }
     if (!this.identity || !this.keyManager || !this.nostrClient) {
       logger.debug("Nostr", "subscribeToEvents: skipped - no identity, keyManager, or nostrClient");
       return;
@@ -2248,7 +2325,13 @@ var NostrTransportProvider = class {
         if (stored) {
           since = parseInt(stored, 10);
           this.lastEventTs = since;
+          this.fallbackSince = null;
           logger.debug("Nostr", "Resuming from stored event timestamp:", since);
+        } else if (this.fallbackSince !== null) {
+          since = this.fallbackSince;
+          this.lastEventTs = since;
+          this.fallbackSince = null;
+          logger.debug("Nostr", "Using fallback since timestamp:", since);
         } else {
           since = Math.floor(Date.now() / 1e3);
           logger.debug("Nostr", "No stored timestamp, starting from now:", since);
@@ -2256,6 +2339,7 @@ var NostrTransportProvider = class {
       } catch (err) {
         logger.debug("Nostr", "Failed to read last event timestamp, falling back to now:", err);
         since = Math.floor(Date.now() / 1e3);
+        this.fallbackSince = null;
       }
     } else {
       since = Math.floor(Date.now() / 1e3) - 86400;
@@ -2309,6 +2393,16 @@ var NostrTransportProvider = class {
       },
       onEndOfStoredEvents: () => {
         logger.debug("Nostr", "Chat subscription ready (EOSE)");
+        if (!this.chatEoseFired) {
+          this.chatEoseFired = true;
+          for (const handler of this.chatEoseHandlers) {
+            try {
+              handler();
+            } catch {
+            }
+          }
+          this.chatEoseHandlers = [];
+        }
       },
       onError: (_subId, error) => {
         logger.debug("Nostr", "Chat subscription error:", error);
@@ -4213,11 +4307,17 @@ var AsyncSerialQueue = class {
 var WriteBuffer = class {
   /** Full TXF data from save() calls — latest wins */
   txfData = null;
+  /** IPNS context captured at save() time — ensures flush writes to the correct
+   *  IPNS record even if identity changes between save() and flush(). */
+  capturedIpnsKeyPair = null;
+  capturedIpnsName = null;
   get isEmpty() {
     return this.txfData === null;
   }
   clear() {
     this.txfData = null;
+    this.capturedIpnsKeyPair = null;
+    this.capturedIpnsName = null;
   }
   /**
    * Merge another buffer's contents into this one (for rollback).
@@ -4226,12 +4326,14 @@ var WriteBuffer = class {
   mergeFrom(other) {
     if (other.txfData && !this.txfData) {
       this.txfData = other.txfData;
+      this.capturedIpnsKeyPair = other.capturedIpnsKeyPair;
+      this.capturedIpnsName = other.capturedIpnsName;
     }
   }
 };
 
 // impl/shared/ipfs/ipfs-storage-provider.ts
-var IpfsStorageProvider = class {
+var IpfsStorageProvider = class _IpfsStorageProvider {
   id = "ipfs";
   name = "IPFS Storage";
   type = "p2p";
@@ -4276,7 +4378,12 @@ var IpfsStorageProvider = class {
   flushDebounceMs;
   /** Set to true during shutdown to prevent new flushes */
   isShuttingDown = false;
+  /** Stored config for createForAddress() cloning */
+  _config;
+  _statePersistenceCtor;
   constructor(config, statePersistence) {
+    this._config = config;
+    this._statePersistenceCtor = statePersistence;
     const gateways = config?.gateways ?? getIpfsGatewayUrls();
     this.debug = config?.debug ?? false;
     this.ipnsLifetimeMs = config?.ipnsLifetimeMs ?? 99 * 365 * 24 * 60 * 60 * 1e3;
@@ -4396,6 +4503,7 @@ var IpfsStorageProvider = class {
   }
   async shutdown() {
     this.isShuttingDown = true;
+    logger.debug("IPFS-Storage", `shutdown: ipnsName=${this.ipnsName?.slice(0, 20)}..., pendingEmpty=${this.pendingBuffer.isEmpty}, capturedIpns=${this.pendingBuffer.capturedIpnsName?.slice(0, 20) ?? "none"}`);
     if (this.flushTimer) {
       clearTimeout(this.flushTimer);
       this.flushTimer = null;
@@ -4428,6 +4536,8 @@ var IpfsStorageProvider = class {
       return { success: false, error: "Not initialized", timestamp: Date.now() };
     }
     this.pendingBuffer.txfData = data;
+    this.pendingBuffer.capturedIpnsKeyPair = this.ipnsKeyPair;
+    this.pendingBuffer.capturedIpnsName = this.ipnsName;
     this.scheduleFlush();
     return { success: true, timestamp: Date.now() };
   }
@@ -4438,8 +4548,12 @@ var IpfsStorageProvider = class {
    * Perform the actual upload + IPNS publish synchronously.
    * Called by executeFlush() and sync() — never by public save().
    */
-  async _doSave(data) {
-    if (!this.ipnsKeyPair || !this.ipnsName) {
+  async _doSave(data, overrideIpns) {
+    const ipnsKeyPair = overrideIpns?.keyPair ?? this.ipnsKeyPair;
+    const ipnsName = overrideIpns?.name ?? this.ipnsName;
+    const metaAddr = data?._meta?.address;
+    logger.debug("IPFS-Storage", `_doSave: ipnsName=${ipnsName?.slice(0, 20)}..., override=${!!overrideIpns}, meta.address=${metaAddr?.slice(0, 20) ?? "none"}`);
+    if (!ipnsKeyPair || !ipnsName) {
       return { success: false, error: "Not initialized", timestamp: Date.now() };
     }
     this.emitEvent({ type: "storage:saving", timestamp: Date.now() });
@@ -4448,7 +4562,7 @@ var IpfsStorageProvider = class {
       const metaUpdate = {
         ...data._meta,
         version: this.dataVersion,
-        ipnsName: this.ipnsName,
+        ipnsName,
         updatedAt: Date.now()
       };
       if (this.remoteCid) {
@@ -4460,13 +4574,13 @@ var IpfsStorageProvider = class {
       const baseSeq = this.ipnsSequenceNumber > this.lastKnownRemoteSequence ? this.ipnsSequenceNumber : this.lastKnownRemoteSequence;
       const newSeq = baseSeq + 1n;
       const marshalledRecord = await createSignedRecord(
-        this.ipnsKeyPair,
+        ipnsKeyPair,
         cid,
         newSeq,
         this.ipnsLifetimeMs
       );
       const publishResult = await this.httpClient.publishIpns(
-        this.ipnsName,
+        ipnsName,
         marshalledRecord
       );
       if (!publishResult.success) {
@@ -4481,14 +4595,14 @@ var IpfsStorageProvider = class {
       this.ipnsSequenceNumber = newSeq;
       this.lastCid = cid;
       this.remoteCid = cid;
-      this.cache.setIpnsRecord(this.ipnsName, {
+      this.cache.setIpnsRecord(ipnsName, {
         cid,
         sequence: newSeq,
         gateway: "local"
       });
       this.cache.setContent(cid, updatedData);
-      this.cache.markIpnsFresh(this.ipnsName);
-      await this.statePersistence.save(this.ipnsName, {
+      this.cache.markIpnsFresh(ipnsName);
+      await this.statePersistence.save(ipnsName, {
         sequenceNumber: newSeq.toString(),
         lastCid: cid,
         version: this.dataVersion
@@ -4540,7 +4654,8 @@ var IpfsStorageProvider = class {
       const baseData = active.txfData ?? {
         _meta: { version: 0, address: this.identity?.directAddress ?? "", formatVersion: "2.0", updatedAt: 0 }
       };
-      const result = await this._doSave(baseData);
+      const overrideIpns = active.capturedIpnsKeyPair && active.capturedIpnsName ? { keyPair: active.capturedIpnsKeyPair, name: active.capturedIpnsName } : void 0;
+      const result = await this._doSave(baseData, overrideIpns);
       if (!result.success) {
         throw new SphereError(result.error ?? "Save failed", "STORAGE_ERROR");
       }
@@ -4843,6 +4958,13 @@ var IpfsStorageProvider = class {
   log(message) {
     logger.debug("IPFS-Storage", message);
   }
+  /**
+   * Create an independent instance for a different address.
+   * Shares the same gateway/timeout config but has fresh IPNS state.
+   */
+  createForAddress() {
+    return new _IpfsStorageProvider(this._config, this._statePersistenceCtor);
+  }
 };
 
 // impl/nodejs/ipfs/nodejs-ipfs-state-persistence.ts