@unicitylabs/sphere-sdk 0.6.13 → 0.6.14

package/dist/index.d.cts

@@ -3519,6 +3519,12 @@ interface CommunicationsModuleConfig {
     maxPerConversation?: number;
     /** Enable read receipts */
     readReceipts?: boolean;
+    /** Cache messages in memory and storage (default: true).
+     *  When false, DMs flow through onDirectMessage handlers and events
+     *  but are never stored. Useful for anonymous/ephemeral agents.
+     *  Note: deduplication is skipped when caching is disabled, so duplicate
+     *  events may occur if the relay delivers the same message twice. */
+    cacheMessages?: boolean;
 }
 interface ConversationPage {
     messages: DirectMessage[];
@@ -4463,6 +4469,8 @@ interface SphereCreateOptions {
     groupChat?: GroupChatModuleConfig | boolean;
     /** Market module configuration. true = enable with defaults, object = custom config. */
     market?: MarketModuleConfig | boolean;
+    /** Communications module configuration. */
+    communications?: CommunicationsModuleConfig;
     /** Optional password to encrypt the wallet. If omitted, mnemonic is stored as plaintext. */
     password?: string;
     /**
@@ -4501,6 +4509,8 @@ interface SphereLoadOptions {
     groupChat?: GroupChatModuleConfig | boolean;
     /** Market module configuration. true = enable with defaults, object = custom config. */
     market?: MarketModuleConfig | boolean;
+    /** Communications module configuration. */
+    communications?: CommunicationsModuleConfig;
     /** Optional password to decrypt the wallet. Must match the password used during creation. */
     password?: string;
     /**
@@ -4547,6 +4557,8 @@ interface SphereImportOptions {
     groupChat?: GroupChatModuleConfig | boolean;
     /** Market module configuration. true = enable with defaults, object = custom config. */
     market?: MarketModuleConfig | boolean;
+    /** Communications module configuration. */
+    communications?: CommunicationsModuleConfig;
     /** Optional password to encrypt the wallet. If omitted, mnemonic/key is stored as plaintext. */
     password?: string;
     /**
@@ -4623,6 +4635,8 @@ interface SphereInitOptions {
      * Without this, a fresh wallet starts from "now" and misses older DMs.
      */
     dmSince?: number;
+    /** Communications module configuration. */
+    communications?: CommunicationsModuleConfig;
     /** Enable debug logging (default: false) */
     debug?: boolean;
     /** Optional callback to report initialization progress steps */
@@ -4672,6 +4686,7 @@ declare class Sphere {
     private _l1Config;
     private _groupChatConfig;
     private _marketConfig;
+    private _communicationsConfig;
     private eventHandlers;
     private _disabledProviders;
     private _providerEventCleanups;

package/dist/index.d.ts

@@ -3519,6 +3519,12 @@ interface CommunicationsModuleConfig {
     maxPerConversation?: number;
     /** Enable read receipts */
     readReceipts?: boolean;
+    /** Cache messages in memory and storage (default: true).
+     *  When false, DMs flow through onDirectMessage handlers and events
+     *  but are never stored. Useful for anonymous/ephemeral agents.
+     *  Note: deduplication is skipped when caching is disabled, so duplicate
+     *  events may occur if the relay delivers the same message twice. */
+    cacheMessages?: boolean;
 }
 interface ConversationPage {
     messages: DirectMessage[];
@@ -4463,6 +4469,8 @@ interface SphereCreateOptions {
     groupChat?: GroupChatModuleConfig | boolean;
     /** Market module configuration. true = enable with defaults, object = custom config. */
     market?: MarketModuleConfig | boolean;
+    /** Communications module configuration. */
+    communications?: CommunicationsModuleConfig;
     /** Optional password to encrypt the wallet. If omitted, mnemonic is stored as plaintext. */
     password?: string;
     /**
@@ -4501,6 +4509,8 @@ interface SphereLoadOptions {
     groupChat?: GroupChatModuleConfig | boolean;
     /** Market module configuration. true = enable with defaults, object = custom config. */
     market?: MarketModuleConfig | boolean;
+    /** Communications module configuration. */
+    communications?: CommunicationsModuleConfig;
     /** Optional password to decrypt the wallet. Must match the password used during creation. */
     password?: string;
     /**
@@ -4547,6 +4557,8 @@ interface SphereImportOptions {
     groupChat?: GroupChatModuleConfig | boolean;
     /** Market module configuration. true = enable with defaults, object = custom config. */
     market?: MarketModuleConfig | boolean;
+    /** Communications module configuration. */
+    communications?: CommunicationsModuleConfig;
     /** Optional password to encrypt the wallet. If omitted, mnemonic/key is stored as plaintext. */
     password?: string;
     /**
@@ -4623,6 +4635,8 @@ interface SphereInitOptions {
      * Without this, a fresh wallet starts from "now" and misses older DMs.
      */
     dmSince?: number;
+    /** Communications module configuration. */
+    communications?: CommunicationsModuleConfig;
     /** Enable debug logging (default: false) */
     debug?: boolean;
     /** Optional callback to report initialization progress steps */
@@ -4672,6 +4686,7 @@ declare class Sphere {
     private _l1Config;
     private _groupChatConfig;
     private _marketConfig;
+    private _communicationsConfig;
     private eventHandlers;
     private _disabledProviders;
     private _providerEventCleanups;

package/dist/index.js

@@ -11843,7 +11843,8 @@ var CommunicationsModule = class {
       autoSave: config?.autoSave ?? true,
       maxMessages: config?.maxMessages ?? 1e3,
       maxPerConversation: config?.maxPerConversation ?? 200,
-      readReceipts: config?.readReceipts ?? true
+      readReceipts: config?.readReceipts ?? true,
+      cacheMessages: config?.cacheMessages ?? true
     };
   }
   // ===========================================================================
@@ -11899,6 +11900,7 @@ var CommunicationsModule = class {
    * Falls back to legacy global 'direct_messages' key for migration.
    */
   async load() {
+    if (!this.config.cacheMessages) return;
     this.ensureInitialized();
     this.messages.clear();
     let data = await this.deps.storage.get(STORAGE_KEYS_ADDRESS.MESSAGES);
@@ -11958,9 +11960,11 @@ var CommunicationsModule = class {
       timestamp: Date.now(),
       isRead: false
     };
-    this.messages.set(message.id, message);
-    if (this.config.autoSave) {
-      await this.save();
+    if (this.config.cacheMessages) {
+      this.messages.set(message.id, message);
+      if (this.config.autoSave) {
+        await this.save();
+      }
     }
     return message;
   }
@@ -11999,7 +12003,7 @@ var CommunicationsModule = class {
         msg.isRead = true;
       }
     }
-    if (this.config.autoSave) {
+    if (this.config.cacheMessages && this.config.autoSave) {
       await this.save();
     }
     if (this.config.readReceipts && this.deps?.transport.sendReadReceipt) {
@@ -12047,6 +12051,7 @@ var CommunicationsModule = class {
    * Delete all messages in a conversation with a peer
    */
   async deleteConversation(peerPubkey) {
+    if (!this.config.cacheMessages) return;
     for (const [id, msg] of this.messages) {
       if (msg.senderPubkey === peerPubkey || msg.recipientPubkey === peerPubkey) {
         this.messages.delete(id);
@@ -12173,7 +12178,7 @@ var CommunicationsModule = class {
   handleIncomingMessage(msg) {
     const isHistorical = msg.timestamp < this.initializedAt;
     if (msg.isSelfWrap && msg.recipientTransportPubkey) {
-      if (this.messages.has(msg.id)) return;
+      if (this.config.cacheMessages && this.messages.has(msg.id)) return;
       const message2 = {
         id: msg.id,
         senderPubkey: this.deps.identity.chainPubkey,
@@ -12183,9 +12188,11 @@ var CommunicationsModule = class {
         timestamp: msg.timestamp,
         isRead: isHistorical
       };
-      this.messages.set(message2.id, message2);
+      if (this.config.cacheMessages) {
+        this.messages.set(message2.id, message2);
+      }
       this.deps.emitEvent("message:dm", message2);
-      if (this.config.autoSave) {
+      if (this.config.cacheMessages && this.config.autoSave) {
         this.save();
       }
       return;
@@ -12196,7 +12203,7 @@ var CommunicationsModule = class {
       if (tp === ownChainPubkey) return;
       if (ownChainPubkey.length === 66 && (ownChainPubkey.startsWith("02") || ownChainPubkey.startsWith("03")) && tp === ownChainPubkey.slice(2)) return;
     }
-    if (this.messages.has(msg.id)) return;
+    if (this.config.cacheMessages && this.messages.has(msg.id)) return;
     const message = {
       id: msg.id,
       senderPubkey: msg.senderTransportPubkey,
@@ -12206,7 +12213,9 @@ var CommunicationsModule = class {
       timestamp: msg.timestamp,
       isRead: isHistorical
     };
-    this.messages.set(message.id, message);
+    if (this.config.cacheMessages) {
+      this.messages.set(message.id, message);
+    }
     this.deps.emitEvent("message:dm", message);
     for (const handler of this.dmHandlers) {
       try {
@@ -12215,10 +12224,12 @@ var CommunicationsModule = class {
         logger.error("Communications", "Handler error:", error);
       }
     }
-    if (this.config.autoSave) {
-      this.save();
+    if (this.config.cacheMessages) {
+      if (this.config.autoSave) {
+        this.save();
+      }
+      this.pruneIfNeeded();
     }
-    this.pruneIfNeeded();
   }
   handleComposingIndicator(indicator) {
     const composing = {
@@ -16744,6 +16755,7 @@ var Sphere = class _Sphere {
   _l1Config;
   _groupChatConfig;
   _marketConfig;
+  _communicationsConfig;
   // Events
   eventHandlers = /* @__PURE__ */ new Map();
   // Provider management
@@ -16753,7 +16765,7 @@ var Sphere = class _Sphere {
   // ===========================================================================
   // Constructor (private)
   // ===========================================================================
-  constructor(storage, transport, oracle, tokenStorage, l1Config, priceProvider, groupChatConfig, marketConfig) {
+  constructor(storage, transport, oracle, tokenStorage, l1Config, priceProvider, groupChatConfig, marketConfig, communicationsConfig) {
     this._storage = storage;
     this._transport = transport;
     this._oracle = oracle;
@@ -16764,8 +16776,9 @@ var Sphere = class _Sphere {
     this._l1Config = l1Config;
     this._groupChatConfig = groupChatConfig;
     this._marketConfig = marketConfig;
+    this._communicationsConfig = communicationsConfig;
     this._payments = createPaymentsModule({ l1: l1Config });
-    this._communications = createCommunicationsModule();
+    this._communications = createCommunicationsModule(communicationsConfig);
     this._groupChat = groupChatConfig ? createGroupChatModule(groupChatConfig) : null;
     this._market = marketConfig ? createMarketModule(marketConfig) : null;
   }
@@ -16953,7 +16966,8 @@ var Sphere = class _Sphere {
       options.l1,
       options.price,
       groupChatConfig,
-      marketConfig
+      marketConfig,
+      options.communications
     );
     sphere._password = options.password ?? null;
     progress?.({ step: "storing_keys", message: "Storing wallet keys..." });
@@ -17011,7 +17025,8 @@ var Sphere = class _Sphere {
       options.l1,
       options.price,
       groupChatConfig,
-      marketConfig
+      marketConfig,
+      options.communications
     );
     sphere._password = options.password ?? null;
     if (!options.storage.isConnected()) {
@@ -17089,7 +17104,8 @@ var Sphere = class _Sphere {
       options.l1,
       options.price,
       groupChatConfig,
-      marketConfig
+      marketConfig,
+      options.communications
     );
     sphere._password = options.password ?? null;
     progress?.({ step: "storing_keys", message: "Storing wallet keys..." });
@@ -18155,7 +18171,7 @@ var Sphere = class _Sphere {
       addressTransport.setFallbackDmSince(this._dmSince);
     }
     const payments = createPaymentsModule({ l1: this._l1Config });
-    const communications = createCommunicationsModule();
+    const communications = createCommunicationsModule(this._communicationsConfig);
     const groupChat = this._groupChatConfig ? createGroupChatModule(this._groupChatConfig) : null;
     const market = this._marketConfig ? createMarketModule(this._marketConfig) : null;
     payments.initialize({