@clanker-chain/mqtt-node-client 0.0.1

package/README.md

@@ -0,0 +1,34 @@
+# mqtt-node-client
+
+Thin MQTT client for clanker-chain bots. Connect with a JWT password (from identity_issue_mqtt_token), publish/subscribe using the topic layout in bot-comms.md, and poll for received messages.
+
+## Usage
+
+```js
+import { MqttClient, topicForInbox, topicForAnnounce } from "mqtt-node-client";
+import { IdentityClient } from "identity-node-client";
+
+const identity = new IdentityClient({ botId: "openclaw.france.prod-1", operatorId: "org.openclaw.pat" });
+const mqtt = new MqttClient();
+
+await mqtt.connect({
+  brokerUrl: "mqtt://localhost:1883",
+  clientId: "openclaw.france.prod-1",
+  getPassword: () => identity.issueMqttToken(300),
+});
+
+await mqtt.subscribe(["bots/france-bot/inbox", "bots/all/announce"]);
+mqtt.publishToInbox("tooter-bot", { type: "coordination", body: { action: "ping" } });
+const messages = await mqtt.poll(500);
+await mqtt.disconnect();
+```
+
+## API
+
+- `connect(options)` — options: brokerUrl, clientId, getPassword (async), optional username.
+- `publish(topic, payload, { qos, retain })`
+- `publishToInbox(toBotName, envelope)`, `publishAnnounce(envelope)`
+- `subscribe(topics[])`, `unsubscribe(topics[])`
+- `poll(timeoutMs)` — returns received messages since last poll; waits up to timeoutMs if buffer empty.
+- `disconnect()`
+- Helpers: `topicForInbox(botName)`, `topicForAnnounce()`, `topicForDmCoordination(bot1, bot2)`, `topicForStatus(botName)`

package/dist/index.d.ts

@@ -0,0 +1,48 @@
+import type { MqttConnectOptions, MqttPublishOptions, ReceivedMessage } from "./types.js";
+export type { MqttConnectOptions, MqttMessageEnvelope, MqttPublishOptions, ReceivedMessage } from "./types.js";
+/** Topic for a bot's inbox (direct messages to that bot). */
+export declare function topicForInbox(botName: string): string;
+/** Topic for bot join/leave announcements. */
+export declare function topicForAnnounce(): string;
+/** Topic for private coordination between two bots (display names). */
+export declare function topicForDmCoordination(bot1: string, bot2: string): string;
+/** Topic for a bot's status (heartbeat, retained). */
+export declare function topicForStatus(botName: string): string;
+export declare class MqttClient {
+    private client;
+    private received;
+    /**
+     * Connect to the broker. Uses getPassword() for the CONNECT password (e.g. JWT from identity_issue_mqtt_token).
+     */
+    connect(options: MqttConnectOptions): Promise<void>;
+    /**
+     * Publish a payload (object or string) to a topic.
+     */
+    publish(topic: string, payload: unknown, options?: MqttPublishOptions): void;
+    /**
+     * Publish to a bot's inbox (convenience).
+     */
+    publishToInbox(toBotName: string, envelope: unknown): void;
+    /**
+     * Publish to bots/all/announce (convenience).
+     */
+    publishAnnounce(envelope: unknown): void;
+    /**
+     * Subscribe to one or more topics.
+     */
+    subscribe(topics: string[]): Promise<void>;
+    /**
+     * Unsubscribe from one or more topics.
+     */
+    unsubscribe(topics: string[]): Promise<void>;
+    /**
+     * Return messages received since last poll and clear the buffer.
+     * Waits up to timeoutMs for at least one message if the buffer is empty.
+     */
+    poll(timeoutMs?: number): Promise<ReceivedMessage[]>;
+    /**
+     * Disconnect from the broker.
+     */
+    disconnect(): Promise<void>;
+    get connected(): boolean;
+}

package/dist/index.js

@@ -0,0 +1,166 @@
+import mqtt from "mqtt";
+/** Topic for a bot's inbox (direct messages to that bot). */
+export function topicForInbox(botName) {
+    return `bots/${botName}/inbox`;
+}
+/** Topic for bot join/leave announcements. */
+export function topicForAnnounce() {
+    return "bots/all/announce";
+}
+/** Topic for private coordination between two bots (display names). */
+export function topicForDmCoordination(bot1, bot2) {
+    const segment = [bot1, bot2].sort().join("-");
+    return `dm/${segment}/coordination`;
+}
+/** Topic for a bot's status (heartbeat, retained). */
+export function topicForStatus(botName) {
+    return `bots/${botName}/status`;
+}
+const defaultPublishOptions = { qos: 1, retain: false };
+export class MqttClient {
+    constructor() {
+        this.client = null;
+        this.received = [];
+    }
+    /**
+     * Connect to the broker. Uses getPassword() for the CONNECT password (e.g. JWT from identity_issue_mqtt_token).
+     */
+    async connect(options) {
+        if (this.client) {
+            throw new Error("Already connected");
+        }
+        const password = await options.getPassword();
+        const username = options.username ?? options.clientId;
+        return new Promise((resolve, reject) => {
+            const c = mqtt.connect(options.brokerUrl, {
+                clientId: options.clientId,
+                username,
+                password,
+                clean: false,
+                reconnectPeriod: 0,
+            });
+            c.on("message", (topic, payload) => {
+                let parsed;
+                try {
+                    parsed = JSON.parse(payload.toString());
+                }
+                catch {
+                    parsed = payload.toString();
+                }
+                this.received.push({
+                    topic,
+                    payload: parsed,
+                    qos: 0,
+                    timestamp: new Date().toISOString(),
+                });
+            });
+            c.once("connect", () => {
+                this.client = c;
+                resolve();
+            });
+            c.once("error", (err) => {
+                this.client = null;
+                reject(err);
+            });
+        });
+    }
+    /**
+     * Publish a payload (object or string) to a topic.
+     */
+    publish(topic, payload, options = {}) {
+        if (!this.client?.connected) {
+            throw new Error("Not connected");
+        }
+        const opts = { ...defaultPublishOptions, ...options };
+        const body = typeof payload === "string" ? payload : JSON.stringify(payload);
+        this.client.publish(topic, body, {
+            qos: opts.qos ?? 1,
+            retain: opts.retain ?? false,
+        });
+    }
+    /**
+     * Publish to a bot's inbox (convenience).
+     */
+    publishToInbox(toBotName, envelope) {
+        this.publish(topicForInbox(toBotName), envelope, { qos: 1 });
+    }
+    /**
+     * Publish to bots/all/announce (convenience).
+     */
+    publishAnnounce(envelope) {
+        this.publish(topicForAnnounce(), envelope, { qos: 1 });
+    }
+    /**
+     * Subscribe to one or more topics.
+     */
+    subscribe(topics) {
+        if (!this.client?.connected) {
+            return Promise.reject(new Error("Not connected"));
+        }
+        return new Promise((resolve, reject) => {
+            this.client.subscribe(topics, (err) => {
+                if (err)
+                    reject(err);
+                else
+                    resolve();
+            });
+        });
+    }
+    /**
+     * Unsubscribe from one or more topics.
+     */
+    unsubscribe(topics) {
+        if (!this.client?.connected) {
+            return Promise.reject(new Error("Not connected"));
+        }
+        return new Promise((resolve, reject) => {
+            this.client.unsubscribe(topics, (err) => {
+                if (err)
+                    reject(err);
+                else
+                    resolve();
+            });
+        });
+    }
+    /**
+     * Return messages received since last poll and clear the buffer.
+     * Waits up to timeoutMs for at least one message if the buffer is empty.
+     */
+    poll(timeoutMs = 100) {
+        if (!this.client?.connected) {
+            return Promise.reject(new Error("Not connected"));
+        }
+        if (this.received.length > 0) {
+            const out = this.received;
+            this.received = [];
+            return Promise.resolve(out);
+        }
+        return new Promise((resolve) => {
+            const t = setTimeout(() => resolve([]), timeoutMs);
+            const handler = () => {
+                clearTimeout(t);
+                this.client.removeListener("message", handler);
+                const out = this.received;
+                this.received = [];
+                resolve(out);
+            };
+            this.client.once("message", handler);
+        });
+    }
+    /**
+     * Disconnect from the broker.
+     */
+    async disconnect() {
+        if (!this.client)
+            return;
+        return new Promise((resolve) => {
+            this.client.end(false, {}, () => {
+                this.client = null;
+                resolve();
+            });
+        });
+    }
+    get connected() {
+        return this.client?.connected ?? false;
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Message envelope shape per bot-comms.md (subset used by the client).
+ */
+export interface MqttMessageEnvelope {
+    from?: string;
+    from_id?: string;
+    operator_id?: string;
+    to?: string;
+    to_id?: string;
+    type: string;
+    subtype?: string;
+    channel?: string;
+    timestamp?: string;
+    message_id?: string;
+    correlation_id?: string;
+    body?: unknown;
+    signature?: string;
+    signature_scheme?: string;
+    [key: string]: unknown;
+}
+export interface MqttConnectOptions {
+    brokerUrl: string;
+    clientId: string;
+    /** Called to get the MQTT password (e.g. JWT from identity_issue_mqtt_token). */
+    getPassword: () => Promise<string>;
+    /** Optional username; defaults to clientId. */
+    username?: string;
+}
+export interface MqttPublishOptions {
+    qos?: 0 | 1 | 2;
+    retain?: boolean;
+}
+export interface ReceivedMessage {
+    topic: string;
+    payload: unknown;
+    qos: number;
+    timestamp: string;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@clanker-chain/mqtt-node-client",
+  "version": "0.0.1",
+  "private": false,
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc -p tsconfig.json"
+  },
+  "dependencies": {
+    "mqtt": "^5.12.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0",
+    "@types/node": "^22.10.2"
+  }
+}

package/src/index.ts

@@ -0,0 +1,185 @@
+import mqtt from "mqtt";
+import type {
+  MqttConnectOptions,
+  MqttPublishOptions,
+  ReceivedMessage,
+} from "./types.js";
+
+export type { MqttConnectOptions, MqttMessageEnvelope, MqttPublishOptions, ReceivedMessage } from "./types.js";
+
+/** Topic for a bot's inbox (direct messages to that bot). */
+export function topicForInbox(botName: string): string {
+  return `bots/${botName}/inbox`;
+}
+
+/** Topic for bot join/leave announcements. */
+export function topicForAnnounce(): string {
+  return "bots/all/announce";
+}
+
+/** Topic for private coordination between two bots (display names). */
+export function topicForDmCoordination(bot1: string, bot2: string): string {
+  const segment = [bot1, bot2].sort().join("-");
+  return `dm/${segment}/coordination`;
+}
+
+/** Topic for a bot's status (heartbeat, retained). */
+export function topicForStatus(botName: string): string {
+  return `bots/${botName}/status`;
+}
+
+const defaultPublishOptions: MqttPublishOptions = { qos: 1, retain: false };
+
+export class MqttClient {
+  private client: mqtt.MqttClient | null = null;
+  private received: ReceivedMessage[] = [];
+
+  /**
+   * Connect to the broker. Uses getPassword() for the CONNECT password (e.g. JWT from identity_issue_mqtt_token).
+   */
+  async connect(options: MqttConnectOptions): Promise<void> {
+    if (this.client) {
+      throw new Error("Already connected");
+    }
+    const password = await options.getPassword();
+    const username = options.username ?? options.clientId;
+    return new Promise((resolve, reject) => {
+      const c = mqtt.connect(options.brokerUrl, {
+        clientId: options.clientId,
+        username,
+        password,
+        clean: false,
+        reconnectPeriod: 0,
+      });
+      c.on("message", (topic: string, payload: Buffer) => {
+        let parsed: unknown;
+        try {
+          parsed = JSON.parse(payload.toString());
+        } catch {
+          parsed = payload.toString();
+        }
+        this.received.push({
+          topic,
+          payload: parsed,
+          qos: 0,
+          timestamp: new Date().toISOString(),
+        });
+      });
+      c.once("connect", () => {
+        this.client = c;
+        resolve();
+      });
+      c.once("error", (err) => {
+        this.client = null;
+        reject(err);
+      });
+    });
+  }
+
+  /**
+   * Publish a payload (object or string) to a topic.
+   */
+  publish(
+    topic: string,
+    payload: unknown,
+    options: MqttPublishOptions = {}
+  ): void {
+    if (!this.client?.connected) {
+      throw new Error("Not connected");
+    }
+    const opts = { ...defaultPublishOptions, ...options };
+    const body =
+      typeof payload === "string" ? payload : JSON.stringify(payload);
+    this.client.publish(topic, body, {
+      qos: opts.qos ?? 1,
+      retain: opts.retain ?? false,
+    });
+  }
+
+  /**
+   * Publish to a bot's inbox (convenience).
+   */
+  publishToInbox(toBotName: string, envelope: unknown): void {
+    this.publish(topicForInbox(toBotName), envelope, { qos: 1 });
+  }
+
+  /**
+   * Publish to bots/all/announce (convenience).
+   */
+  publishAnnounce(envelope: unknown): void {
+    this.publish(topicForAnnounce(), envelope, { qos: 1 });
+  }
+
+  /**
+   * Subscribe to one or more topics.
+   */
+  subscribe(topics: string[]): Promise<void> {
+    if (!this.client?.connected) {
+      return Promise.reject(new Error("Not connected"));
+    }
+    return new Promise((resolve, reject) => {
+      this.client!.subscribe(topics, (err) => {
+        if (err) reject(err);
+        else resolve();
+      });
+    });
+  }
+
+  /**
+   * Unsubscribe from one or more topics.
+   */
+  unsubscribe(topics: string[]): Promise<void> {
+    if (!this.client?.connected) {
+      return Promise.reject(new Error("Not connected"));
+    }
+    return new Promise((resolve, reject) => {
+      this.client!.unsubscribe(topics, (err) => {
+        if (err) reject(err);
+        else resolve();
+      });
+    });
+  }
+
+  /**
+   * Return messages received since last poll and clear the buffer.
+   * Waits up to timeoutMs for at least one message if the buffer is empty.
+   */
+  poll(timeoutMs: number = 100): Promise<ReceivedMessage[]> {
+    if (!this.client?.connected) {
+      return Promise.reject(new Error("Not connected"));
+    }
+    if (this.received.length > 0) {
+      const out = this.received;
+      this.received = [];
+      return Promise.resolve(out);
+    }
+    return new Promise((resolve) => {
+      const t = setTimeout(() => resolve([]), timeoutMs);
+      const handler = () => {
+        clearTimeout(t);
+        this.client!.removeListener("message", handler);
+        const out = this.received;
+        this.received = [];
+        resolve(out);
+      };
+      this.client!.once("message", handler);
+    });
+  }
+
+  /**
+   * Disconnect from the broker.
+   */
+  async disconnect(): Promise<void> {
+    if (!this.client) return;
+    return new Promise((resolve) => {
+      this.client!.end(false, {}, () => {
+        this.client = null;
+        resolve();
+      });
+    });
+  }
+
+  get connected(): boolean {
+    return this.client?.connected ?? false;
+  }
+}

package/src/types.ts

@@ -0,0 +1,41 @@
+/**
+ * Message envelope shape per bot-comms.md (subset used by the client).
+ */
+export interface MqttMessageEnvelope {
+  from?: string;
+  from_id?: string;
+  operator_id?: string;
+  to?: string;
+  to_id?: string;
+  type: string;
+  subtype?: string;
+  channel?: string;
+  timestamp?: string;
+  message_id?: string;
+  correlation_id?: string;
+  body?: unknown;
+  signature?: string;
+  signature_scheme?: string;
+  [key: string]: unknown;
+}
+
+export interface MqttConnectOptions {
+  brokerUrl: string;
+  clientId: string;
+  /** Called to get the MQTT password (e.g. JWT from identity_issue_mqtt_token). */
+  getPassword: () => Promise<string>;
+  /** Optional username; defaults to clientId. */
+  username?: string;
+}
+
+export interface MqttPublishOptions {
+  qos?: 0 | 1 | 2;
+  retain?: boolean;
+}
+
+export interface ReceivedMessage {
+  topic: string;
+  payload: unknown;
+  qos: number;
+  timestamp: string;
+}

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "node",
+    "declaration": true,
+    "outDir": "dist",
+    "strict": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "skipLibCheck": true,
+    "types": ["node"]
+  },
+  "include": ["src/**/*.ts"]
+}