@unicitylabs/sphere-sdk 0.4.4 → 0.4.6

package/dist/index.d.cts

@@ -3266,6 +3266,7 @@ declare class CommunicationsModule {
     private dmHandlers;
     private composingHandlers;
     private broadcastHandlers;
+    private initializedAt;
     constructor(config?: CommunicationsModuleConfig);
     /**
      * Initialize module with dependencies
@@ -3344,6 +3345,12 @@ declare class CommunicationsModule {
      * Subscribe to incoming broadcasts
      */
     onBroadcast(handler: (message: BroadcastMessage) => void): () => void;
+    /**
+     * Resolve a peer's nametag by their transport pubkey.
+     * Uses transport.resolveTransportPubkeyInfo() for live lookup from relay binding events.
+     * Returns undefined if transport doesn't support resolution or peer has no nametag.
+     */
+    resolvePeerNametag(peerPubkey: string): Promise<string | undefined>;
     private handleIncomingMessage;
     private handleComposingIndicator;
     private handleIncomingBroadcast;
@@ -3394,6 +3401,11 @@ declare class GroupChatModule {
     private destroyConnection;
     connect(): Promise<void>;
     getConnectionStatus(): boolean;
+    /**
+     * Refresh subscriptions after load() switched to a different address.
+     * Clears old subscriptions, restores groups if needed, and re-subscribes.
+     */
+    private refreshSubscriptions;
     private doConnect;
     private scheduleReconnect;
     private subscribeToJoinedGroups;
@@ -3661,15 +3673,7 @@ declare const STORAGE_KEYS_GLOBAL: {
     readonly TRACKED_ADDRESSES: "tracked_addresses";
     /** Last processed Nostr wallet event timestamp (unix seconds), keyed per pubkey */
     readonly LAST_WALLET_EVENT_TS: "last_wallet_event_ts";
-    /** Group chat: joined groups */
-    readonly GROUP_CHAT_GROUPS: "group_chat_groups";
-    /** Group chat: messages */
-    readonly GROUP_CHAT_MESSAGES: "group_chat_messages";
-    /** Group chat: members */
-    readonly GROUP_CHAT_MEMBERS: "group_chat_members";
-    /** Group chat: processed event IDs for deduplication */
-    readonly GROUP_CHAT_PROCESSED_EVENTS: "group_chat_processed_events";
-    /** Group chat: last used relay URL (stale data detection) */
+    /** Group chat: last used relay URL (stale data detection) — global, same relay for all addresses */
     readonly GROUP_CHAT_RELAY_URL: "group_chat_relay_url";
     /** Cached token registry JSON (fetched from remote) */
     readonly TOKEN_REGISTRY_CACHE: "token_registry_cache";
@@ -3701,6 +3705,14 @@ declare const STORAGE_KEYS_ADDRESS: {
     readonly TRANSACTION_HISTORY: "transaction_history";
     /** Pending V5 finalization tokens (unconfirmed instant split tokens) */
     readonly PENDING_V5_TOKENS: "pending_v5_tokens";
+    /** Group chat: joined groups for this address */
+    readonly GROUP_CHAT_GROUPS: "group_chat_groups";
+    /** Group chat: messages for this address */
+    readonly GROUP_CHAT_MESSAGES: "group_chat_messages";
+    /** Group chat: members for this address */
+    readonly GROUP_CHAT_MEMBERS: "group_chat_members";
+    /** Group chat: processed event IDs for deduplication */
+    readonly GROUP_CHAT_PROCESSED_EVENTS: "group_chat_processed_events";
 };
 /** @deprecated Use STORAGE_KEYS_GLOBAL and STORAGE_KEYS_ADDRESS instead */
 declare const STORAGE_KEYS: {
@@ -3716,6 +3728,14 @@ declare const STORAGE_KEYS: {
     readonly TRANSACTION_HISTORY: "transaction_history";
     /** Pending V5 finalization tokens (unconfirmed instant split tokens) */
     readonly PENDING_V5_TOKENS: "pending_v5_tokens";
+    /** Group chat: joined groups for this address */
+    readonly GROUP_CHAT_GROUPS: "group_chat_groups";
+    /** Group chat: messages for this address */
+    readonly GROUP_CHAT_MESSAGES: "group_chat_messages";
+    /** Group chat: members for this address */
+    readonly GROUP_CHAT_MEMBERS: "group_chat_members";
+    /** Group chat: processed event IDs for deduplication */
+    readonly GROUP_CHAT_PROCESSED_EVENTS: "group_chat_processed_events";
     /** Encrypted BIP39 mnemonic */
     readonly MNEMONIC: "mnemonic";
     /** Encrypted master private key */
@@ -3740,15 +3760,7 @@ declare const STORAGE_KEYS: {
     readonly TRACKED_ADDRESSES: "tracked_addresses";
     /** Last processed Nostr wallet event timestamp (unix seconds), keyed per pubkey */
     readonly LAST_WALLET_EVENT_TS: "last_wallet_event_ts";
-    /** Group chat: joined groups */
-    readonly GROUP_CHAT_GROUPS: "group_chat_groups";
-    /** Group chat: messages */
-    readonly GROUP_CHAT_MESSAGES: "group_chat_messages";
-    /** Group chat: members */
-    readonly GROUP_CHAT_MEMBERS: "group_chat_members";
-    /** Group chat: processed event IDs for deduplication */
-    readonly GROUP_CHAT_PROCESSED_EVENTS: "group_chat_processed_events";
-    /** Group chat: last used relay URL (stale data detection) */
+    /** Group chat: last used relay URL (stale data detection) — global, same relay for all addresses */
     readonly GROUP_CHAT_RELAY_URL: "group_chat_relay_url";
     /** Cached token registry JSON (fetched from remote) */
     readonly TOKEN_REGISTRY_CACHE: "token_registry_cache";

package/dist/index.d.ts

@@ -3266,6 +3266,7 @@ declare class CommunicationsModule {
     private dmHandlers;
     private composingHandlers;
     private broadcastHandlers;
+    private initializedAt;
     constructor(config?: CommunicationsModuleConfig);
     /**
      * Initialize module with dependencies
@@ -3344,6 +3345,12 @@ declare class CommunicationsModule {
      * Subscribe to incoming broadcasts
      */
     onBroadcast(handler: (message: BroadcastMessage) => void): () => void;
+    /**
+     * Resolve a peer's nametag by their transport pubkey.
+     * Uses transport.resolveTransportPubkeyInfo() for live lookup from relay binding events.
+     * Returns undefined if transport doesn't support resolution or peer has no nametag.
+     */
+    resolvePeerNametag(peerPubkey: string): Promise<string | undefined>;
     private handleIncomingMessage;
     private handleComposingIndicator;
     private handleIncomingBroadcast;
@@ -3394,6 +3401,11 @@ declare class GroupChatModule {
     private destroyConnection;
     connect(): Promise<void>;
     getConnectionStatus(): boolean;
+    /**
+     * Refresh subscriptions after load() switched to a different address.
+     * Clears old subscriptions, restores groups if needed, and re-subscribes.
+     */
+    private refreshSubscriptions;
     private doConnect;
     private scheduleReconnect;
     private subscribeToJoinedGroups;
@@ -3661,15 +3673,7 @@ declare const STORAGE_KEYS_GLOBAL: {
     readonly TRACKED_ADDRESSES: "tracked_addresses";
     /** Last processed Nostr wallet event timestamp (unix seconds), keyed per pubkey */
     readonly LAST_WALLET_EVENT_TS: "last_wallet_event_ts";
-    /** Group chat: joined groups */
-    readonly GROUP_CHAT_GROUPS: "group_chat_groups";
-    /** Group chat: messages */
-    readonly GROUP_CHAT_MESSAGES: "group_chat_messages";
-    /** Group chat: members */
-    readonly GROUP_CHAT_MEMBERS: "group_chat_members";
-    /** Group chat: processed event IDs for deduplication */
-    readonly GROUP_CHAT_PROCESSED_EVENTS: "group_chat_processed_events";
-    /** Group chat: last used relay URL (stale data detection) */
+    /** Group chat: last used relay URL (stale data detection) — global, same relay for all addresses */
     readonly GROUP_CHAT_RELAY_URL: "group_chat_relay_url";
     /** Cached token registry JSON (fetched from remote) */
     readonly TOKEN_REGISTRY_CACHE: "token_registry_cache";
@@ -3701,6 +3705,14 @@ declare const STORAGE_KEYS_ADDRESS: {
     readonly TRANSACTION_HISTORY: "transaction_history";
     /** Pending V5 finalization tokens (unconfirmed instant split tokens) */
     readonly PENDING_V5_TOKENS: "pending_v5_tokens";
+    /** Group chat: joined groups for this address */
+    readonly GROUP_CHAT_GROUPS: "group_chat_groups";
+    /** Group chat: messages for this address */
+    readonly GROUP_CHAT_MESSAGES: "group_chat_messages";
+    /** Group chat: members for this address */
+    readonly GROUP_CHAT_MEMBERS: "group_chat_members";
+    /** Group chat: processed event IDs for deduplication */
+    readonly GROUP_CHAT_PROCESSED_EVENTS: "group_chat_processed_events";
 };
 /** @deprecated Use STORAGE_KEYS_GLOBAL and STORAGE_KEYS_ADDRESS instead */
 declare const STORAGE_KEYS: {
@@ -3716,6 +3728,14 @@ declare const STORAGE_KEYS: {
     readonly TRANSACTION_HISTORY: "transaction_history";
     /** Pending V5 finalization tokens (unconfirmed instant split tokens) */
     readonly PENDING_V5_TOKENS: "pending_v5_tokens";
+    /** Group chat: joined groups for this address */
+    readonly GROUP_CHAT_GROUPS: "group_chat_groups";
+    /** Group chat: messages for this address */
+    readonly GROUP_CHAT_MESSAGES: "group_chat_messages";
+    /** Group chat: members for this address */
+    readonly GROUP_CHAT_MEMBERS: "group_chat_members";
+    /** Group chat: processed event IDs for deduplication */
+    readonly GROUP_CHAT_PROCESSED_EVENTS: "group_chat_processed_events";
     /** Encrypted BIP39 mnemonic */
     readonly MNEMONIC: "mnemonic";
     /** Encrypted master private key */
@@ -3740,15 +3760,7 @@ declare const STORAGE_KEYS: {
     readonly TRACKED_ADDRESSES: "tracked_addresses";
     /** Last processed Nostr wallet event timestamp (unix seconds), keyed per pubkey */
     readonly LAST_WALLET_EVENT_TS: "last_wallet_event_ts";
-    /** Group chat: joined groups */
-    readonly GROUP_CHAT_GROUPS: "group_chat_groups";
-    /** Group chat: messages */
-    readonly GROUP_CHAT_MESSAGES: "group_chat_messages";
-    /** Group chat: members */
-    readonly GROUP_CHAT_MEMBERS: "group_chat_members";
-    /** Group chat: processed event IDs for deduplication */
-    readonly GROUP_CHAT_PROCESSED_EVENTS: "group_chat_processed_events";
-    /** Group chat: last used relay URL (stale data detection) */
+    /** Group chat: last used relay URL (stale data detection) — global, same relay for all addresses */
     readonly GROUP_CHAT_RELAY_URL: "group_chat_relay_url";
     /** Cached token registry JSON (fetched from remote) */
     readonly TOKEN_REGISTRY_CACHE: "token_registry_cache";

package/dist/index.js

@@ -2503,15 +2503,7 @@ var STORAGE_KEYS_GLOBAL = {
   TRACKED_ADDRESSES: "tracked_addresses",
   /** Last processed Nostr wallet event timestamp (unix seconds), keyed per pubkey */
   LAST_WALLET_EVENT_TS: "last_wallet_event_ts",
-  /** Group chat: joined groups */
-  GROUP_CHAT_GROUPS: "group_chat_groups",
-  /** Group chat: messages */
-  GROUP_CHAT_MESSAGES: "group_chat_messages",
-  /** Group chat: members */
-  GROUP_CHAT_MEMBERS: "group_chat_members",
-  /** Group chat: processed event IDs for deduplication */
-  GROUP_CHAT_PROCESSED_EVENTS: "group_chat_processed_events",
-  /** Group chat: last used relay URL (stale data detection) */
+  /** Group chat: last used relay URL (stale data detection) — global, same relay for all addresses */
   GROUP_CHAT_RELAY_URL: "group_chat_relay_url",
   /** Cached token registry JSON (fetched from remote) */
   TOKEN_REGISTRY_CACHE: "token_registry_cache",
@@ -2534,7 +2526,15 @@ var STORAGE_KEYS_ADDRESS = {
   /** Transaction history for this address */
   TRANSACTION_HISTORY: "transaction_history",
   /** Pending V5 finalization tokens (unconfirmed instant split tokens) */
-  PENDING_V5_TOKENS: "pending_v5_tokens"
+  PENDING_V5_TOKENS: "pending_v5_tokens",
+  /** Group chat: joined groups for this address */
+  GROUP_CHAT_GROUPS: "group_chat_groups",
+  /** Group chat: messages for this address */
+  GROUP_CHAT_MESSAGES: "group_chat_messages",
+  /** Group chat: members for this address */
+  GROUP_CHAT_MEMBERS: "group_chat_members",
+  /** Group chat: processed event IDs for deduplication */
+  GROUP_CHAT_PROCESSED_EVENTS: "group_chat_processed_events"
 };
 var STORAGE_KEYS = {
   ...STORAGE_KEYS_GLOBAL,
@@ -7645,6 +7645,8 @@ var CommunicationsModule = class {
   dmHandlers = /* @__PURE__ */ new Set();
   composingHandlers = /* @__PURE__ */ new Set();
   broadcastHandlers = /* @__PURE__ */ new Set();
+  // Timestamp of module initialization — messages older than this are historical
+  initializedAt = 0;
   constructor(config) {
     this.config = {
       autoSave: config?.autoSave ?? true,
@@ -7663,6 +7665,7 @@ var CommunicationsModule = class {
     this.unsubscribeMessages?.();
     this.unsubscribeComposing?.();
     this.deps = deps;
+    this.initializedAt = Date.now();
     this.unsubscribeMessages = deps.transport.onMessage((msg) => {
       this.handleIncomingMessage(msg);
     });
@@ -7951,9 +7954,27 @@ var CommunicationsModule = class {
     return () => this.broadcastHandlers.delete(handler);
   }
   // ===========================================================================
+  // Public API - Peer Resolution
+  // ===========================================================================
+  /**
+   * Resolve a peer's nametag by their transport pubkey.
+   * Uses transport.resolveTransportPubkeyInfo() for live lookup from relay binding events.
+   * Returns undefined if transport doesn't support resolution or peer has no nametag.
+   */
+  async resolvePeerNametag(peerPubkey) {
+    if (!this.deps?.transport.resolveTransportPubkeyInfo) return void 0;
+    try {
+      const info = await this.deps.transport.resolveTransportPubkeyInfo(peerPubkey);
+      return info?.nametag;
+    } catch {
+      return void 0;
+    }
+  }
+  // ===========================================================================
   // Private: Message Handling
   // ===========================================================================
   handleIncomingMessage(msg) {
+    const isHistorical = msg.timestamp < this.initializedAt;
     if (msg.isSelfWrap && msg.recipientTransportPubkey) {
       if (this.messages.has(msg.id)) return;
       const message2 = {
@@ -7963,7 +7984,7 @@ var CommunicationsModule = class {
         recipientPubkey: msg.recipientTransportPubkey,
         content: msg.content,
         timestamp: msg.timestamp,
-        isRead: false
+        isRead: isHistorical
       };
       this.messages.set(message2.id, message2);
       this.deps.emitEvent("message:dm", message2);
@@ -7981,7 +8002,7 @@ var CommunicationsModule = class {
       recipientPubkey: this.deps.identity.chainPubkey,
       content: msg.content,
       timestamp: msg.timestamp,
-      isRead: false
+      isRead: isHistorical
     };
     this.messages.set(message.id, message);
     this.deps.emitEvent("message:dm", message);
@@ -8157,22 +8178,24 @@ var GroupChatModule = class {
   async load() {
     this.ensureInitialized();
     const storage = this.deps.storage;
-    const groupsJson = await storage.get(STORAGE_KEYS_GLOBAL.GROUP_CHAT_GROUPS);
+    this.groups.clear();
+    this.messages.clear();
+    this.members.clear();
+    this.processedEventIds.clear();
+    const groupsJson = await storage.get(STORAGE_KEYS_ADDRESS.GROUP_CHAT_GROUPS);
     if (groupsJson) {
       try {
         const parsed = JSON.parse(groupsJson);
-        this.groups.clear();
         for (const g of parsed) {
           this.groups.set(g.id, g);
         }
       } catch {
       }
     }
-    const messagesJson = await storage.get(STORAGE_KEYS_GLOBAL.GROUP_CHAT_MESSAGES);
+    const messagesJson = await storage.get(STORAGE_KEYS_ADDRESS.GROUP_CHAT_MESSAGES);
     if (messagesJson) {
       try {
         const parsed = JSON.parse(messagesJson);
-        this.messages.clear();
         for (const m of parsed) {
           const groupId = m.groupId;
           if (!this.messages.has(groupId)) {
@@ -8183,11 +8206,10 @@ var GroupChatModule = class {
       } catch {
       }
     }
-    const membersJson = await storage.get(STORAGE_KEYS_GLOBAL.GROUP_CHAT_MEMBERS);
+    const membersJson = await storage.get(STORAGE_KEYS_ADDRESS.GROUP_CHAT_MEMBERS);
     if (membersJson) {
       try {
         const parsed = JSON.parse(membersJson);
-        this.members.clear();
         for (const m of parsed) {
           const groupId = m.groupId;
           if (!this.members.has(groupId)) {
@@ -8198,7 +8220,7 @@ var GroupChatModule = class {
       } catch {
       }
     }
-    const processedJson = await storage.get(STORAGE_KEYS_GLOBAL.GROUP_CHAT_PROCESSED_EVENTS);
+    const processedJson = await storage.get(STORAGE_KEYS_ADDRESS.GROUP_CHAT_PROCESSED_EVENTS);
     if (processedJson) {
       try {
         const parsed = JSON.parse(processedJson);
@@ -8252,7 +8274,10 @@ var GroupChatModule = class {
   // Connection
   // ===========================================================================
   async connect() {
-    if (this.connected) return;
+    if (this.connected) {
+      await this.refreshSubscriptions();
+      return;
+    }
     if (this.connectPromise) {
       return this.connectPromise;
     }
@@ -8266,6 +8291,28 @@ var GroupChatModule = class {
   getConnectionStatus() {
     return this.connected;
   }
+  /**
+   * Refresh subscriptions after load() switched to a different address.
+   * Clears old subscriptions, restores groups if needed, and re-subscribes.
+   */
+  async refreshSubscriptions() {
+    if (!this.client) return;
+    for (const subId of this.subscriptionIds) {
+      try {
+        this.client.unsubscribe(subId);
+      } catch {
+      }
+    }
+    this.subscriptionIds = [];
+    const secretKey = Buffer.from(this.deps.identity.privateKey, "hex");
+    this.keyManager = NostrKeyManager.fromPrivateKey(secretKey);
+    if (this.groups.size === 0) {
+      await this.restoreJoinedGroups();
+    } else {
+      await this.subscribeToJoinedGroups();
+    }
+    this.deps.emitEvent("groupchat:connection", { connected: true });
+  }
   async doConnect() {
     this.ensureInitialized();
     if (!this.keyManager) {
@@ -8281,12 +8328,12 @@ var GroupChatModule = class {
       await this.client.connect(...this.config.relays);
       this.connected = true;
       this.reconnectAttempts = 0;
-      this.deps.emitEvent("groupchat:connection", { connected: true });
       if (this.groups.size === 0) {
         await this.restoreJoinedGroups();
       } else {
         await this.subscribeToJoinedGroups();
       }
+      this.deps.emitEvent("groupchat:connection", { connected: true });
     } catch (error) {
       console.error("[GroupChat] Failed to connect to relays", error);
       this.deps.emitEvent("groupchat:connection", { connected: false });
@@ -9269,7 +9316,7 @@ var GroupChatModule = class {
   async persistGroups() {
     if (!this.deps) return;
     const data = Array.from(this.groups.values());
-    await this.deps.storage.set(STORAGE_KEYS_GLOBAL.GROUP_CHAT_GROUPS, JSON.stringify(data));
+    await this.deps.storage.set(STORAGE_KEYS_ADDRESS.GROUP_CHAT_GROUPS, JSON.stringify(data));
   }
   async persistMessages() {
     if (!this.deps) return;
@@ -9277,7 +9324,7 @@ var GroupChatModule = class {
     for (const msgs of this.messages.values()) {
       allMessages.push(...msgs);
     }
-    await this.deps.storage.set(STORAGE_KEYS_GLOBAL.GROUP_CHAT_MESSAGES, JSON.stringify(allMessages));
+    await this.deps.storage.set(STORAGE_KEYS_ADDRESS.GROUP_CHAT_MESSAGES, JSON.stringify(allMessages));
   }
   async persistMembers() {
     if (!this.deps) return;
@@ -9285,12 +9332,12 @@ var GroupChatModule = class {
     for (const mems of this.members.values()) {
       allMembers.push(...mems);
     }
-    await this.deps.storage.set(STORAGE_KEYS_GLOBAL.GROUP_CHAT_MEMBERS, JSON.stringify(allMembers));
+    await this.deps.storage.set(STORAGE_KEYS_ADDRESS.GROUP_CHAT_MEMBERS, JSON.stringify(allMembers));
   }
   async persistProcessedEvents() {
     if (!this.deps) return;
     const arr = Array.from(this.processedEventIds);
-    await this.deps.storage.set(STORAGE_KEYS_GLOBAL.GROUP_CHAT_PROCESSED_EVENTS, JSON.stringify(arr));
+    await this.deps.storage.set(STORAGE_KEYS_ADDRESS.GROUP_CHAT_PROCESSED_EVENTS, JSON.stringify(arr));
   }
   // ===========================================================================
   // Private — Relay URL Change Detection