@unicitylabs/sphere-sdk 0.6.13 → 0.6.14

package/dist/core/index.d.cts

@@ -3110,6 +3110,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[];
@@ -3748,6 +3754,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;
     /**
@@ -3786,6 +3794,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;
     /**
@@ -3832,6 +3842,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;
     /**
@@ -3908,6 +3920,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 */
@@ -3972,6 +3986,7 @@ declare class Sphere {
     private _l1Config;
     private _groupChatConfig;
     private _marketConfig;
+    private _communicationsConfig;
     private eventHandlers;
     private _disabledProviders;
     private _providerEventCleanups;

package/dist/core/index.d.ts

@@ -3110,6 +3110,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[];
@@ -3748,6 +3754,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;
     /**
@@ -3786,6 +3794,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;
     /**
@@ -3832,6 +3842,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;
     /**
@@ -3908,6 +3920,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 */
@@ -3972,6 +3986,7 @@ declare class Sphere {
     private _l1Config;
     private _groupChatConfig;
     private _marketConfig;
+    private _communicationsConfig;
     private eventHandlers;
     private _disabledProviders;
     private _providerEventCleanups;

package/dist/core/index.js

@@ -11574,7 +11574,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
     };
   }
   // ===========================================================================
@@ -11630,6 +11631,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);
@@ -11689,9 +11691,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;
   }
@@ -11730,7 +11734,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) {
@@ -11778,6 +11782,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);
@@ -11904,7 +11909,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,
@@ -11914,9 +11919,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;
@@ -11927,7 +11934,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,
@@ -11937,7 +11944,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 {
@@ -11946,10 +11955,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 = {
@@ -16560,6 +16571,7 @@ var Sphere = class _Sphere {
   _l1Config;
   _groupChatConfig;
   _marketConfig;
+  _communicationsConfig;
   // Events
   eventHandlers = /* @__PURE__ */ new Map();
   // Provider management
@@ -16569,7 +16581,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;
@@ -16580,8 +16592,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;
   }
@@ -16769,7 +16782,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..." });
@@ -16827,7 +16841,8 @@ var Sphere = class _Sphere {
       options.l1,
       options.price,
       groupChatConfig,
-      marketConfig
+      marketConfig,
+      options.communications
     );
     sphere._password = options.password ?? null;
     if (!options.storage.isConnected()) {
@@ -16905,7 +16920,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..." });
@@ -17971,7 +17987,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({