@unicitylabs/sphere-sdk 0.6.13-dev.3 → 0.6.14

package/README.md

@@ -550,6 +550,31 @@ const { sphere } = await Sphere.init({
 
 Once the SDK processes DMs, the timestamp is persisted and `dmSince` is ignored on subsequent connects.
 
+### Ephemeral Mode (No Caching)
+
+For anonymous agents or LLM bots that don't need message history, disable DM caching:
+
+```typescript
+const { sphere } = await Sphere.init({
+  ...providers,
+  communications: { cacheMessages: false },
+});
+
+// Stream-only: receive, process, forget
+sphere.communications.onDirectMessage((msg) => {
+  processAndReply(msg);
+});
+
+// sendDM still works — message is sent but not stored locally
+await sphere.communications.sendDM('@alice', 'response');
+```
+
+When `cacheMessages` is `false`:
+- `onDirectMessage()` handlers and `message:dm` events fire normally
+- Messages are never stored in memory or persisted to storage
+- `getConversation()` / `getConversations()` return empty results
+- Deduplication is skipped (duplicate relay deliveries may trigger duplicate events)
+
 ## L1 (ALPHA Blockchain) Operations
 
 Access L1 payments through `sphere.payments.l1`:

package/dist/core/index.cjs

@@ -11654,7 +11654,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
     };
   }
   // ===========================================================================
@@ -11710,6 +11711,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);
@@ -11769,9 +11771,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;
   }
@@ -11810,7 +11814,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) {
@@ -11858,6 +11862,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);
@@ -11984,7 +11989,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,
@@ -11994,9 +11999,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;
@@ -12007,7 +12014,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,
@@ -12017,7 +12024,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 {
@@ -12026,10 +12035,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 = {
@@ -16636,6 +16647,7 @@ var Sphere = class _Sphere {
   _l1Config;
   _groupChatConfig;
   _marketConfig;
+  _communicationsConfig;
   // Events
   eventHandlers = /* @__PURE__ */ new Map();
   // Provider management
@@ -16645,7 +16657,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;
@@ -16656,8 +16668,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;
   }
@@ -16845,7 +16858,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..." });
@@ -16903,7 +16917,8 @@ var Sphere = class _Sphere {
       options.l1,
       options.price,
       groupChatConfig,
-      marketConfig
+      marketConfig,
+      options.communications
     );
     sphere._password = options.password ?? null;
     if (!options.storage.isConnected()) {
@@ -16981,7 +16996,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..." });
@@ -18047,7 +18063,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({