@unicitylabs/sphere-sdk 0.3.8 → 0.3.9

package/dist/index.d.cts

@@ -1162,7 +1162,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: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';
+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' | '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';
 interface SphereEventMap {
     'transfer:incoming': IncomingTransfer;
     'transfer:confirmed': TransferResult;
@@ -1173,6 +1173,15 @@ interface SphereEventMap {
     'payment_request:paid': IncomingPaymentRequest$1;
     'payment_request:response': PaymentRequestResponse;
     'message:dm': DirectMessage;
+    'message:read': {
+        messageIds: string[];
+        peerPubkey: string;
+    };
+    'message:typing': {
+        senderPubkey: string;
+        senderNametag?: string;
+        timestamp: number;
+    };
     'message:broadcast': BroadcastMessage;
     'sync:started': {
         source: string;
@@ -1542,6 +1551,27 @@ interface TransportProvider extends BaseProvider {
      * @returns Unsubscribe function
      */
     onPaymentRequestResponse?(handler: PaymentRequestResponseHandler): () => void;
+    /**
+     * Send a read receipt for a message
+     * @param recipientTransportPubkey - Transport pubkey of the message sender
+     * @param messageEventId - Event ID of the message being acknowledged
+     */
+    sendReadReceipt?(recipientTransportPubkey: string, messageEventId: string): Promise<void>;
+    /**
+     * Subscribe to incoming read receipts
+     * @returns Unsubscribe function
+     */
+    onReadReceipt?(handler: ReadReceiptHandler): () => void;
+    /**
+     * Send typing indicator to a recipient
+     * @param recipientTransportPubkey - Transport pubkey of the conversation partner
+     */
+    sendTypingIndicator?(recipientTransportPubkey: string): Promise<void>;
+    /**
+     * Subscribe to incoming typing indicators
+     * @returns Unsubscribe function
+     */
+    onTypingIndicator?(handler: TypingIndicatorHandler): () => void;
     /**
      * Get list of configured relay URLs
      */
@@ -1631,6 +1661,10 @@ interface IncomingMessage {
     content: string;
     timestamp: number;
     encrypted: boolean;
+    /** Set when this is a self-wrap replay (sent message recovered from relay) */
+    isSelfWrap?: boolean;
+    /** Recipient pubkey — only present on self-wrap replays */
+    recipientTransportPubkey?: string;
 }
 type MessageHandler = (message: IncomingMessage) => void;
 interface TokenTransferPayload {
@@ -1752,6 +1786,24 @@ interface PeerInfo {
     /** Event timestamp */
     timestamp: number;
 }
+interface IncomingReadReceipt {
+    /** Transport-specific pubkey of the sender who read the message */
+    senderTransportPubkey: string;
+    /** Event ID of the message that was read */
+    messageEventId: string;
+    /** Timestamp */
+    timestamp: number;
+}
+type ReadReceiptHandler = (receipt: IncomingReadReceipt) => void;
+interface IncomingTypingIndicator {
+    /** Transport-specific pubkey of the sender who is typing */
+    senderTransportPubkey: string;
+    /** Sender's nametag (if known) */
+    senderNametag?: string;
+    /** Timestamp */
+    timestamp: number;
+}
+type TypingIndicatorHandler = (indicator: IncomingTypingIndicator) => void;
 
 /**
  * L1 Payments Sub-Module
@@ -3202,6 +3254,10 @@ declare class CommunicationsModule {
      * Get unread count
      */
     getUnreadCount(peerPubkey?: string): number;
+    /**
+     * Send typing indicator to a peer
+     */
+    sendTypingIndicator(peerPubkey: string): Promise<void>;
     /**
      * Subscribe to incoming DMs
      */

package/dist/index.d.ts

@@ -1162,7 +1162,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: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';
+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' | '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';
 interface SphereEventMap {
     'transfer:incoming': IncomingTransfer;
     'transfer:confirmed': TransferResult;
@@ -1173,6 +1173,15 @@ interface SphereEventMap {
     'payment_request:paid': IncomingPaymentRequest$1;
     'payment_request:response': PaymentRequestResponse;
     'message:dm': DirectMessage;
+    'message:read': {
+        messageIds: string[];
+        peerPubkey: string;
+    };
+    'message:typing': {
+        senderPubkey: string;
+        senderNametag?: string;
+        timestamp: number;
+    };
     'message:broadcast': BroadcastMessage;
     'sync:started': {
         source: string;
@@ -1542,6 +1551,27 @@ interface TransportProvider extends BaseProvider {
      * @returns Unsubscribe function
      */
     onPaymentRequestResponse?(handler: PaymentRequestResponseHandler): () => void;
+    /**
+     * Send a read receipt for a message
+     * @param recipientTransportPubkey - Transport pubkey of the message sender
+     * @param messageEventId - Event ID of the message being acknowledged
+     */
+    sendReadReceipt?(recipientTransportPubkey: string, messageEventId: string): Promise<void>;
+    /**
+     * Subscribe to incoming read receipts
+     * @returns Unsubscribe function
+     */
+    onReadReceipt?(handler: ReadReceiptHandler): () => void;
+    /**
+     * Send typing indicator to a recipient
+     * @param recipientTransportPubkey - Transport pubkey of the conversation partner
+     */
+    sendTypingIndicator?(recipientTransportPubkey: string): Promise<void>;
+    /**
+     * Subscribe to incoming typing indicators
+     * @returns Unsubscribe function
+     */
+    onTypingIndicator?(handler: TypingIndicatorHandler): () => void;
     /**
      * Get list of configured relay URLs
      */
@@ -1631,6 +1661,10 @@ interface IncomingMessage {
     content: string;
     timestamp: number;
     encrypted: boolean;
+    /** Set when this is a self-wrap replay (sent message recovered from relay) */
+    isSelfWrap?: boolean;
+    /** Recipient pubkey — only present on self-wrap replays */
+    recipientTransportPubkey?: string;
 }
 type MessageHandler = (message: IncomingMessage) => void;
 interface TokenTransferPayload {
@@ -1752,6 +1786,24 @@ interface PeerInfo {
     /** Event timestamp */
     timestamp: number;
 }
+interface IncomingReadReceipt {
+    /** Transport-specific pubkey of the sender who read the message */
+    senderTransportPubkey: string;
+    /** Event ID of the message that was read */
+    messageEventId: string;
+    /** Timestamp */
+    timestamp: number;
+}
+type ReadReceiptHandler = (receipt: IncomingReadReceipt) => void;
+interface IncomingTypingIndicator {
+    /** Transport-specific pubkey of the sender who is typing */
+    senderTransportPubkey: string;
+    /** Sender's nametag (if known) */
+    senderNametag?: string;
+    /** Timestamp */
+    timestamp: number;
+}
+type TypingIndicatorHandler = (indicator: IncomingTypingIndicator) => void;
 
 /**
  * L1 Payments Sub-Module
@@ -3202,6 +3254,10 @@ declare class CommunicationsModule {
      * Get unread count
      */
     getUnreadCount(peerPubkey?: string): number;
+    /**
+     * Send typing indicator to a peer
+     */
+    sendTypingIndicator(peerPubkey: string): Promise<void>;
     /**
      * Subscribe to incoming DMs
      */

package/dist/index.js

@@ -7595,6 +7595,28 @@ var CommunicationsModule = class {
     this.unsubscribeMessages = deps.transport.onMessage((msg) => {
       this.handleIncomingMessage(msg);
     });
+    if (deps.transport.onReadReceipt) {
+      deps.transport.onReadReceipt((receipt) => {
+        const msg = this.messages.get(receipt.messageEventId);
+        if (msg && msg.senderPubkey === this.deps.identity.chainPubkey) {
+          msg.isRead = true;
+          this.save();
+          this.deps.emitEvent("message:read", {
+            messageIds: [receipt.messageEventId],
+            peerPubkey: receipt.senderTransportPubkey
+          });
+        }
+      });
+    }
+    if (deps.transport.onTypingIndicator) {
+      deps.transport.onTypingIndicator((indicator) => {
+        this.deps.emitEvent("message:typing", {
+          senderPubkey: indicator.senderTransportPubkey,
+          senderNametag: indicator.senderNametag,
+          timestamp: indicator.timestamp
+        });
+      });
+    }
   }
   /**
    * Load messages from storage
@@ -7638,7 +7660,7 @@ var CommunicationsModule = class {
       recipientPubkey,
       content,
       timestamp: Date.now(),
-      isRead: true
+      isRead: false
     };
     this.messages.set(message.id, message);
     if (this.config.autoSave) {
@@ -7684,6 +7706,16 @@ var CommunicationsModule = class {
     if (this.config.autoSave) {
       await this.save();
     }
+    if (this.config.readReceipts && this.deps?.transport.sendReadReceipt) {
+      for (const id of messageIds) {
+        const msg = this.messages.get(id);
+        if (msg && msg.senderPubkey !== this.deps.identity.chainPubkey) {
+          this.deps.transport.sendReadReceipt(msg.senderPubkey, id).catch((err) => {
+            console.warn("[Communications] Failed to send read receipt:", err);
+          });
+        }
+      }
+    }
   }
   /**
    * Get unread count
@@ -7697,6 +7729,15 @@ var CommunicationsModule = class {
     }
     return messages.length;
   }
+  /**
+   * Send typing indicator to a peer
+   */
+  async sendTypingIndicator(peerPubkey) {
+    this.ensureInitialized();
+    if (this.deps.transport.sendTypingIndicator) {
+      await this.deps.transport.sendTypingIndicator(peerPubkey);
+    }
+  }
   /**
    * Subscribe to incoming DMs
    */
@@ -7766,7 +7807,26 @@ var CommunicationsModule = class {
   // Private: Message Handling
   // ===========================================================================
   handleIncomingMessage(msg) {
+    if (msg.isSelfWrap && msg.recipientTransportPubkey) {
+      if (this.messages.has(msg.id)) return;
+      const message2 = {
+        id: msg.id,
+        senderPubkey: this.deps.identity.chainPubkey,
+        senderNametag: msg.senderNametag,
+        recipientPubkey: msg.recipientTransportPubkey,
+        content: msg.content,
+        timestamp: msg.timestamp,
+        isRead: false
+      };
+      this.messages.set(message2.id, message2);
+      this.deps.emitEvent("message:dm", message2);
+      if (this.config.autoSave) {
+        this.save();
+      }
+      return;
+    }
     if (msg.senderTransportPubkey === this.deps?.identity.chainPubkey) return;
+    if (this.messages.has(msg.id)) return;
     const message = {
       id: msg.id,
       senderPubkey: msg.senderTransportPubkey,
@@ -12059,12 +12119,22 @@ var Sphere = class _Sphere {
       return;
     }
     try {
-      if (this._identity?.directAddress && this._transport.resolve) {
+      const transportPubkey = this._identity?.chainPubkey?.slice(2);
+      if (transportPubkey && this._transport.resolve) {
         try {
-          const existing = await this._transport.resolve(this._identity.directAddress);
+          const existing = await this._transport.resolve(transportPubkey);
           if (existing) {
-            if (existing.nametag && !this._identity.nametag) {
-              this._identity.nametag = existing.nametag;
+            let recoveredNametag = existing.nametag;
+            let fromLegacy = false;
+            if (!recoveredNametag && !this._identity?.nametag && this._transport.recoverNametag) {
+              try {
+                recoveredNametag = await this._transport.recoverNametag() ?? void 0;
+                if (recoveredNametag) fromLegacy = true;
+              } catch {
+              }
+            }
+            if (recoveredNametag && !this._identity?.nametag) {
+              this._identity.nametag = recoveredNametag;
               await this._updateCachedProxyAddress();
               const entry = await this.ensureAddressTracked(this._currentAddressIndex);
               let nametags = this._addressNametags.get(entry.addressId);
@@ -12073,10 +12143,20 @@ var Sphere = class _Sphere {
                 this._addressNametags.set(entry.addressId, nametags);
               }
               if (!nametags.has(0)) {
-                nametags.set(0, existing.nametag);
+                nametags.set(0, recoveredNametag);
                 await this.persistAddressNametags();
               }
-              this.emitEvent("nametag:recovered", { nametag: existing.nametag });
+              this.emitEvent("nametag:recovered", { nametag: recoveredNametag });
+              if (fromLegacy) {
+                await this._transport.publishIdentityBinding(
+                  this._identity.chainPubkey,
+                  this._identity.l1Address,
+                  this._identity.directAddress || "",
+                  recoveredNametag
+                );
+                console.log(`[Sphere] Migrated legacy binding with nametag @${recoveredNametag}`);
+                return;
+              }
             }
             console.log("[Sphere] Existing binding found, skipping re-publish");
             return;