@unicitylabs/sphere-sdk 0.6.2 → 0.6.3

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

@@ -195,6 +195,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,
@@ -476,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;
@@ -493,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;
@@ -526,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.
@@ -1133,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
      */
@@ -1282,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,6 +195,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,
@@ -476,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;
@@ -493,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;
@@ -526,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.
@@ -1133,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
      */
@@ -1282,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
   // ===========================================================================
@@ -1291,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();
@@ -1333,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.
@@ -2240,6 +2295,10 @@ var NostrTransportProvider = class {
   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;
@@ -2266,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);
@@ -2274,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;
@@ -4241,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).
@@ -4254,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";
@@ -4304,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;
@@ -4424,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;
@@ -4456,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() };
   }
@@ -4466,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() });
@@ -4476,7 +4562,7 @@ var IpfsStorageProvider = class {
       const metaUpdate = {
         ...data._meta,
         version: this.dataVersion,
-        ipnsName: this.ipnsName,
+        ipnsName,
         updatedAt: Date.now()
       };
       if (this.remoteCid) {
@@ -4488,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) {
@@ -4509,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
@@ -4568,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");
       }
@@ -4871,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