@zbruceli/openclaw-dchat 0.1.11 → 0.3.0

package/src/nkn-bus.ts

@@ -5,12 +5,20 @@ import { NKN_SEED_RPC_SERVERS, type NknConnectionState } from "./types.js";
 export interface NknBusOptions {
   seed: string;
   numSubClients?: number;
+  /** Heartbeat echo-test interval in ms (default 60 000). Set 0 to disable. */
+  heartbeatIntervalMs?: number;
+  /** Consecutive heartbeat failures before reconnecting (default 3). */
+  heartbeatMaxFailures?: number;
 }
 
+/** Payload used for heartbeat echo-test messages (self → self). */
+const HEARTBEAT_ECHO_PREFIX = "__nkn_heartbeat_echo__:";
+
 /**
  * NKN MultiClient wrapper for D-Chat wire-format messaging.
- * Handles connect, send, receive, subscribe, and reconnection.
+ * Handles connect, send, receive, subscribe, heartbeat, and reconnection.
  */
+
 export class NknBus extends EventEmitter {
   private client: nkn.MultiClient | null = null;
   private state: NknConnectionState = "disconnected";
@@ -20,6 +28,14 @@ export class NknBus extends EventEmitter {
   private numSubClients: number;
   private abortSignal: AbortSignal | undefined;
 
+  private heartbeatIntervalMs: number = 60_000;
+  private heartbeatMaxFailures: number = 3;
+  private heartbeatTimer: ReturnType<typeof setTimeout> | null = null;
+  private heartbeatFailures: number = 0;
+  private pendingEchoId: string | null = null;
+  private pendingEchoResolve: (() => void) | null = null;
+  private isReconnecting: boolean = false;
+
   constructor() {
     super();
     this.numSubClients = 4;
@@ -40,6 +56,8 @@ export class NknBus extends EventEmitter {
 
     this.seed = opts.seed;
     this.numSubClients = opts.numSubClients ?? 4;
+    this.heartbeatIntervalMs = opts.heartbeatIntervalMs ?? 60_000;
+    this.heartbeatMaxFailures = opts.heartbeatMaxFailures ?? 3;
     this.abortSignal = abortSignal;
     this.setState("connecting");
 
@@ -86,9 +104,23 @@ export class NknBus extends EventEmitter {
         } else {
           data = payload;
         }
+
+        // Intercept heartbeat echo responses — don't emit as regular messages
+        if (data.startsWith(HEARTBEAT_ECHO_PREFIX)) {
+          const echoId = data.slice(HEARTBEAT_ECHO_PREFIX.length);
+          if (echoId === this.pendingEchoId && this.pendingEchoResolve) {
+            this.pendingEchoResolve();
+            this.pendingEchoResolve = null;
+            this.pendingEchoId = null;
+          }
+          return;
+        }
+
         this.emit("message", src, data);
       });
 
+      this.startHeartbeat();
+
       return this.address;
     } catch (err) {
       this.setState("disconnected");
@@ -105,6 +137,7 @@ export class NknBus extends EventEmitter {
   }
 
   async disconnect(): Promise<void> {
+    this.stopHeartbeat();
     if (this.reconnectTimer) {
       clearTimeout(this.reconnectTimer);
       this.reconnectTimer = null;
@@ -200,6 +233,185 @@ export class NknBus extends EventEmitter {
     this.on("message", handler);
   }
 
+  /** Start periodic heartbeat echo test (self → self). */
+  private startHeartbeat(): void {
+    if (this.heartbeatIntervalMs <= 0) return;
+    this.heartbeatFailures = 0;
+    this.scheduleNextHeartbeat();
+  }
+
+  private stopHeartbeat(): void {
+    if (this.heartbeatTimer) {
+      clearTimeout(this.heartbeatTimer);
+      this.heartbeatTimer = null;
+    }
+    // Reject any pending echo wait
+    this.pendingEchoResolve = null;
+    this.pendingEchoId = null;
+  }
+
+  private scheduleNextHeartbeat(): void {
+    if (this.heartbeatTimer) {
+      clearTimeout(this.heartbeatTimer);
+    }
+    this.heartbeatTimer = setTimeout(() => {
+      void this.runHeartbeat();
+    }, this.heartbeatIntervalMs);
+  }
+
+  private async runHeartbeat(): Promise<void> {
+    if (!this.client || this.state !== "connected" || !this.address) {
+      return;
+    }
+
+    const echoId = `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    const echoPayload = HEARTBEAT_ECHO_PREFIX + echoId;
+
+    try {
+      const echoReceived = await new Promise<boolean>((resolve) => {
+        this.pendingEchoId = echoId;
+        // Timeout: half the heartbeat interval or 15s, whichever is smaller
+        const timeout = Math.min(this.heartbeatIntervalMs / 2, 15_000);
+        const timer = setTimeout(() => {
+          this.pendingEchoResolve = null;
+          this.pendingEchoId = null;
+          resolve(false);
+        }, timeout);
+
+        this.pendingEchoResolve = () => {
+          clearTimeout(timer);
+          resolve(true);
+        };
+
+        // Send echo to self (fire-and-forget send, we wait for the message handler)
+        this.client!.send(this.address!, echoPayload, { noReply: true });
+      });
+
+      if (echoReceived) {
+        this.heartbeatFailures = 0;
+        this.emit("heartbeat", { success: true, failures: 0 });
+      } else {
+        this.heartbeatFailures++;
+        this.emit("heartbeat", { success: false, failures: this.heartbeatFailures });
+
+        if (this.heartbeatFailures >= this.heartbeatMaxFailures) {
+          this.emit("heartbeatReconnect", { failures: this.heartbeatFailures });
+          await this.reconnect();
+          return; // reconnect starts a new heartbeat loop
+        }
+      }
+    } catch {
+      this.heartbeatFailures++;
+      this.emit("heartbeat", { success: false, failures: this.heartbeatFailures });
+
+      if (this.heartbeatFailures >= this.heartbeatMaxFailures) {
+        this.emit("heartbeatReconnect", { failures: this.heartbeatFailures });
+        await this.reconnect();
+        return;
+      }
+    }
+
+    // Schedule next heartbeat if still connected
+    if (this.state === "connected") {
+      this.scheduleNextHeartbeat();
+    }
+  }
+
+  /** Close the current connection and create a new one using stored options. */
+  private async reconnect(): Promise<void> {
+    if (this.isReconnecting || !this.seed) return;
+    this.isReconnecting = true;
+
+    try {
+      this.stopHeartbeat();
+
+      // Close existing client
+      if (this.client) {
+        try {
+          this.client.close();
+        } catch {
+          // ignore close errors
+        }
+        this.client = null;
+      }
+      this.address = undefined;
+      this.setState("connecting");
+
+      // Create a fresh client
+      this.client = new nkn.MultiClient({
+        seed: this.seed,
+        numSubClients: this.numSubClients,
+        originalClient: false,
+        rpcServerAddr: NKN_SEED_RPC_SERVERS[0],
+      });
+
+      await new Promise<void>((resolve, reject) => {
+        const timeout = setTimeout(() => {
+          reject(new Error("NKN reconnection timeout after 30s"));
+        }, 30_000);
+
+        if (this.abortSignal?.aborted) {
+          clearTimeout(timeout);
+          reject(new Error("Aborted"));
+          return;
+        }
+
+        const onAbort = () => {
+          clearTimeout(timeout);
+          reject(new Error("Aborted"));
+        };
+        this.abortSignal?.addEventListener("abort", onAbort, { once: true });
+
+        this.client!.onConnect(() => {
+          clearTimeout(timeout);
+          this.abortSignal?.removeEventListener("abort", onAbort);
+          resolve();
+        });
+      });
+
+      this.address = this.client.addr;
+      this.setState("connected");
+
+      // Re-register message handler
+      this.client.onMessage(({ src, payload }: { src: string; payload: Uint8Array | string }) => {
+        let data: string;
+        if (payload instanceof Uint8Array) {
+          data = new TextDecoder().decode(payload);
+        } else {
+          data = payload;
+        }
+
+        if (data.startsWith(HEARTBEAT_ECHO_PREFIX)) {
+          const id = data.slice(HEARTBEAT_ECHO_PREFIX.length);
+          if (id === this.pendingEchoId && this.pendingEchoResolve) {
+            this.pendingEchoResolve();
+            this.pendingEchoResolve = null;
+            this.pendingEchoId = null;
+          }
+          return;
+        }
+
+        this.emit("message", src, data);
+      });
+
+      this.heartbeatFailures = 0;
+      this.startHeartbeat();
+    } catch (err) {
+      this.setState("disconnected");
+      if (this.client) {
+        try {
+          this.client.close();
+        } catch {
+          // ignore
+        }
+        this.client = null;
+      }
+      this.emit("reconnectFailed", err);
+    } finally {
+      this.isReconnecting = false;
+    }
+  }
+
   private ensureConnected(): void {
     if (!this.client || this.state !== "connected") {
       throw new Error("NKN client not connected");

package/src/wire.test.ts

@@ -8,6 +8,7 @@ import {
   isControlMessage,
   isDisplayableMessage,
   nknToInbound,
+  parseInlineMediaDataUri,
   parseNknPayload,
   receiptToNkn,
   stripNknSubClientPrefix,
@@ -172,6 +173,65 @@ describe("nknToInbound", () => {
     expect(result!.body).toBe("[Voice Message]");
   });
 
+  it("extracts IPFS hash from audio message with options.ipfsHash", () => {
+    const msg: MessageData = {
+      id: "msg-audio-ipfs-1",
+      contentType: "audio",
+      content: "QmAudioHash...",
+      options: {
+        ipfsHash: "QmAudioHash...",
+        ipfsEncrypt: 1,
+        ipfsEncryptAlgorithm: "AES/GCM/NoPadding",
+        ipfsEncryptKeyBytes: Array.from(Buffer.alloc(16, 0xab)),
+        ipfsEncryptNonceSize: 12,
+        fileType: 2,
+        mediaDuration: 5.3,
+      },
+      timestamp: Date.now(),
+    };
+    const result = nknToInbound("sender", msg, selfAddr);
+    expect(result!.body).toBe("[Voice Message]");
+    expect(result!.ipfsHash).toBe("QmAudioHash...");
+    expect(result!.ipfsOptions).toBeDefined();
+    expect(result!.ipfsOptions!.ipfsEncrypt).toBe(1);
+    expect(result!.ipfsOptions!.mediaDuration).toBe(5.3);
+  });
+
+  it("extracts IPFS hash from audio message content when options.ipfsHash is missing", () => {
+    const msg: MessageData = {
+      id: "msg-audio-ipfs-2",
+      contentType: "audio",
+      content: "QmAudioContentHash",
+      options: {
+        ipfsEncrypt: 1,
+        ipfsEncryptKeyBytes: Array.from(Buffer.alloc(16, 0xcd)),
+        ipfsEncryptNonceSize: 12,
+      },
+      timestamp: Date.now(),
+    };
+    const result = nknToInbound("sender", msg, selfAddr);
+    expect(result!.ipfsHash).toBe("QmAudioContentHash");
+    expect(result!.ipfsOptions).toBeDefined();
+  });
+
+  it("translates IPFS audio message (contentType ipfs, fileType 2)", () => {
+    const msg: MessageData = {
+      id: "msg-ipfs-audio",
+      contentType: "ipfs",
+      content: "QmIpfsAudio...",
+      options: {
+        ipfsHash: "QmIpfsAudio...",
+        fileType: 2,
+        mediaDuration: 12.5,
+      },
+      timestamp: Date.now(),
+    };
+    const result = nknToInbound("sender", msg, selfAddr);
+    expect(result!.body).toBe("[Audio]");
+    expect(result!.ipfsHash).toBe("QmIpfsAudio...");
+    expect(result!.ipfsOptions!.mediaDuration).toBe(12.5);
+  });
+
   it("returns null for control messages", () => {
     const receipt: MessageData = {
       id: "msg-6",
@@ -264,3 +324,74 @@ describe("stripNknSubClientPrefix", () => {
     expect(stripNknSubClientPrefix("cd3530abcdef")).toBe("cd3530abcdef");
   });
 });
+
+describe("parseInlineMediaDataUri", () => {
+  it("parses D-Chat markdown audio data-URI (audio/x-aac)", () => {
+    const raw = "![audio](data:audio/x-aac;base64,AAAA)";
+    const result = parseInlineMediaDataUri(raw);
+    expect(result).not.toBeNull();
+    expect(result!.mime).toBe("audio/x-aac");
+    expect(result!.buffer).toEqual(Buffer.from("AAAA", "base64"));
+  });
+
+  it("parses nMobile markdown audio data-URI (audio/aac)", () => {
+    const b64 = Buffer.from("hello audio").toString("base64");
+    const raw = `![audio](data:audio/aac;base64,${b64})`;
+    const result = parseInlineMediaDataUri(raw);
+    expect(result).not.toBeNull();
+    expect(result!.mime).toBe("audio/aac");
+    expect(result!.buffer.toString()).toBe("hello audio");
+  });
+
+  it("parses raw data-URI without markdown wrapper", () => {
+    const b64 = Buffer.from("raw data").toString("base64");
+    const raw = `data:audio/ogg;base64,${b64}`;
+    const result = parseInlineMediaDataUri(raw);
+    expect(result).not.toBeNull();
+    expect(result!.mime).toBe("audio/ogg");
+    expect(result!.buffer.toString()).toBe("raw data");
+  });
+
+  it("returns null for non-data-URI content", () => {
+    expect(parseInlineMediaDataUri("QmSomeIpfsHash")).toBeNull();
+    expect(parseInlineMediaDataUri("just plain text")).toBeNull();
+    expect(parseInlineMediaDataUri("")).toBeNull();
+  });
+
+  it("returns null for invalid base64", () => {
+    expect(parseInlineMediaDataUri("data:audio/aac;utf8,notbase64")).toBeNull();
+  });
+});
+
+describe("nknToInbound — inline audio", () => {
+  const selfAddr = "self-address-abc123";
+
+  it("sets inlineMediaDataUri for audio with data-URI content", () => {
+    const b64 = Buffer.from("aac-audio-data").toString("base64");
+    const msg: MessageData = {
+      id: "msg-voice-1",
+      contentType: "audio",
+      content: `![audio](data:audio/x-aac;base64,${b64})`,
+      options: { fileType: 2, fileExt: "aac", mediaDuration: 3.5 },
+      timestamp: Date.now(),
+    };
+    const result = nknToInbound("sender", msg, selfAddr);
+    expect(result!.body).toBe("[Voice Message]");
+    expect(result!.inlineMediaDataUri).toBe(msg.content);
+    // ipfsHash should also be set as fallback (content contains "data:" but also matches)
+    // but IPFS download will fail gracefully — inline path takes priority in channel.ts
+  });
+
+  it("does not set inlineMediaDataUri for audio without data-URI", () => {
+    const msg: MessageData = {
+      id: "msg-voice-2",
+      contentType: "audio",
+      content: "QmSomeHash",
+      options: { ipfsHash: "QmSomeHash" },
+      timestamp: Date.now(),
+    };
+    const result = nknToInbound("sender", msg, selfAddr);
+    expect(result!.inlineMediaDataUri).toBeUndefined();
+    expect(result!.ipfsHash).toBe("QmSomeHash");
+  });
+});

package/src/wire.ts

@@ -59,6 +59,8 @@ export interface InboundMessageResult {
   groupSubject?: string;
   ipfsHash?: string;
   ipfsOptions?: MessageOptions;
+  /** Raw inline media data-URI (e.g. "![audio](data:audio/aac;base64,...)") for voice messages. */
+  inlineMediaDataUri?: string;
 }
 
 /**
@@ -141,11 +143,36 @@ export function nknToInbound(
     senderId: src,
     senderName,
     groupSubject,
-    ipfsHash: msg.options?.ipfsHash || (ct === "ipfs" ? msg.content : undefined),
+    ipfsHash:
+      msg.options?.ipfsHash || (ct === "ipfs" || ct === "audio" ? msg.content : undefined),
     ipfsOptions: ct === "ipfs" || ct === "audio" ? msg.options : undefined,
+    // D-Chat/nMobile send voice messages inline as base64 data-URI in content
+    inlineMediaDataUri:
+      ct === "audio" && msg.content?.includes("data:") ? msg.content : undefined,
   };
 }
 
+/**
+ * Parse an inline media data-URI from nMobile/D-Chat format.
+ * Handles: "![audio](data:audio/aac;base64,...)" and raw "data:audio/aac;base64,..."
+ * Returns { mime, buffer } or null if not a valid data-URI.
+ */
+export function parseInlineMediaDataUri(
+  raw: string,
+): { mime: string; buffer: Buffer } | null {
+  // Extract data-URI from markdown image syntax: ![...](data:...)
+  const mdMatch = raw.match(/!\[.*?\]\((data:[^)]+)\)/);
+  const dataUri = mdMatch ? mdMatch[1] : raw.startsWith("data:") ? raw : null;
+  if (!dataUri) return null;
+
+  const match = dataUri.match(/^data:([^;]+);base64,(.+)$/s);
+  if (!match) return null;
+
+  const mime = match[1];
+  const buffer = Buffer.from(match[2], "base64");
+  return { mime, buffer };
+}
+
 /**
  * Build an outbound NKN MessageData from text.
  * Sets appropriate content type and topic/groupId fields.