@openclaw-channel/socket-chat 1.0.0

package/src/outbound.test.ts

@@ -0,0 +1,176 @@
+import { describe, expect, it } from "vitest";
+import {
+  buildMediaPayload,
+  buildTextPayload,
+  looksLikeSocketChatTargetId,
+  normalizeSocketChatTarget,
+  parseSocketChatTarget,
+} from "./outbound.js";
+
+// ---------------------------------------------------------------------------
+// parseSocketChatTarget
+// ---------------------------------------------------------------------------
+
+describe("parseSocketChatTarget", () => {
+  it("parses a direct contact ID", () => {
+    const result = parseSocketChatTarget("wxid_abc123");
+    expect(result).toEqual({ isGroup: false, contactId: "wxid_abc123" });
+  });
+
+  it("parses a group target without mentions", () => {
+    const result = parseSocketChatTarget("group:roomid_xxx");
+    expect(result).toEqual({ isGroup: true, groupId: "roomid_xxx" });
+  });
+
+  it("parses a group target with single mention", () => {
+    const result = parseSocketChatTarget("group:roomid_xxx@wxid_a");
+    expect(result).toEqual({ isGroup: true, groupId: "roomid_xxx", mentionIds: ["wxid_a"] });
+  });
+
+  it("parses a group target with multiple mentions", () => {
+    const result = parseSocketChatTarget("group:roomid_xxx@wxid_a,wxid_b,wxid_c");
+    expect(result).toEqual({
+      isGroup: true,
+      groupId: "roomid_xxx",
+      mentionIds: ["wxid_a", "wxid_b", "wxid_c"],
+    });
+  });
+
+  it("trims whitespace from target string", () => {
+    const result = parseSocketChatTarget("  wxid_trim  ");
+    expect(result).toEqual({ isGroup: false, contactId: "wxid_trim" });
+  });
+
+  it("filters empty mention ids", () => {
+    const result = parseSocketChatTarget("group:roomid@wxid_a,,wxid_b");
+    expect(result.isGroup).toBe(true);
+    if (result.isGroup) {
+      expect(result.mentionIds).toEqual(["wxid_a", "wxid_b"]);
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// normalizeSocketChatTarget
+// ---------------------------------------------------------------------------
+
+describe("normalizeSocketChatTarget", () => {
+  it("returns the target unchanged for native IDs", () => {
+    expect(normalizeSocketChatTarget("wxid_abc")).toBe("wxid_abc");
+    expect(normalizeSocketChatTarget("group:roomid_xxx")).toBe("group:roomid_xxx");
+  });
+
+  it("strips socket-chat: prefix (case-insensitive)", () => {
+    expect(normalizeSocketChatTarget("socket-chat:wxid_abc")).toBe("wxid_abc");
+    expect(normalizeSocketChatTarget("Socket-Chat:wxid_abc")).toBe("wxid_abc");
+    expect(normalizeSocketChatTarget("SOCKET-CHAT:wxid_abc")).toBe("wxid_abc");
+  });
+
+  it("returns undefined for empty/whitespace-only strings", () => {
+    expect(normalizeSocketChatTarget("")).toBeUndefined();
+    expect(normalizeSocketChatTarget("   ")).toBeUndefined();
+  });
+
+  it("trims surrounding whitespace", () => {
+    expect(normalizeSocketChatTarget("  wxid_abc  ")).toBe("wxid_abc");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// looksLikeSocketChatTargetId
+// ---------------------------------------------------------------------------
+
+describe("looksLikeSocketChatTargetId", () => {
+  it("recognizes wxid_ prefix", () => {
+    expect(looksLikeSocketChatTargetId("wxid_abc123")).toBe(true);
+  });
+
+  it("recognizes roomid_ prefix", () => {
+    expect(looksLikeSocketChatTargetId("roomid_xyz")).toBe(true);
+  });
+
+  it("recognizes group: prefix", () => {
+    expect(looksLikeSocketChatTargetId("group:roomid_xxx")).toBe(true);
+  });
+
+  it("rejects arbitrary strings", () => {
+    expect(looksLikeSocketChatTargetId("alice")).toBe(false);
+    expect(looksLikeSocketChatTargetId("user@example.com")).toBe(false);
+    expect(looksLikeSocketChatTargetId("")).toBe(false);
+  });
+
+  it("trims leading whitespace before checking", () => {
+    expect(looksLikeSocketChatTargetId("  wxid_abc")).toBe(true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// buildTextPayload
+// ---------------------------------------------------------------------------
+
+describe("buildTextPayload", () => {
+  it("builds a DM text payload", () => {
+    const payload = buildTextPayload("wxid_abc", "hello");
+    expect(payload.isGroup).toBe(false);
+    expect(payload.contactId).toBe("wxid_abc");
+    expect(payload.messages).toEqual([{ type: 1, content: "hello" }]);
+    expect(payload.mentionIds).toBeUndefined();
+  });
+
+  it("builds a group text payload", () => {
+    const payload = buildTextPayload("group:roomid_xxx", "hi group");
+    expect(payload.isGroup).toBe(true);
+    expect(payload.groupId).toBe("roomid_xxx");
+    expect(payload.messages).toEqual([{ type: 1, content: "hi group" }]);
+  });
+
+  it("extracts mentions from group target string", () => {
+    const payload = buildTextPayload("group:roomid_xxx@wxid_a,wxid_b", "hi");
+    expect(payload.mentionIds).toEqual(["wxid_a", "wxid_b"]);
+  });
+
+  it("allows explicit override of mentionIds", () => {
+    const payload = buildTextPayload("group:roomid_xxx", "hi", { mentionIds: ["wxid_override"] });
+    expect(payload.mentionIds).toEqual(["wxid_override"]);
+  });
+
+  it("sets mentionIds to undefined when empty", () => {
+    const payload = buildTextPayload("group:roomid_xxx", "hi", { mentionIds: [] });
+    expect(payload.mentionIds).toBeUndefined();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// buildMediaPayload
+// ---------------------------------------------------------------------------
+
+describe("buildMediaPayload", () => {
+  it("builds a media-only payload without caption", () => {
+    const payload = buildMediaPayload("wxid_abc", "https://img.example.com/photo.jpg");
+    expect(payload.isGroup).toBe(false);
+    expect(payload.messages).toEqual([
+      { type: 2, url: "https://img.example.com/photo.jpg" },
+    ]);
+  });
+
+  it("includes caption text before image when provided", () => {
+    const payload = buildMediaPayload("wxid_abc", "https://img.example.com/photo.jpg", "Look at this");
+    expect(payload.messages).toEqual([
+      { type: 1, content: "Look at this" },
+      { type: 2, url: "https://img.example.com/photo.jpg" },
+    ]);
+  });
+
+  it("skips empty caption", () => {
+    const payload = buildMediaPayload("wxid_abc", "https://img.example.com/photo.jpg", "   ");
+    expect(payload.messages).toEqual([
+      { type: 2, url: "https://img.example.com/photo.jpg" },
+    ]);
+  });
+
+  it("builds group media payload", () => {
+    const payload = buildMediaPayload("group:roomid_xxx", "https://img.example.com/photo.jpg");
+    expect(payload.isGroup).toBe(true);
+    expect(payload.groupId).toBe("roomid_xxx");
+  });
+});

package/src/outbound.ts

@@ -0,0 +1,175 @@
+import type { MqttClient } from "mqtt";
+import type { ChannelOutboundAdapter } from "openclaw/plugin-sdk";
+import { DEFAULT_ACCOUNT_ID } from "./config.js";
+import { getActiveMqttClient, getActiveMqttConfig } from "./mqtt-client.js";
+import type { SocketChatMqttConfig, SocketChatOutboundPayload } from "./types.js";
+
+/**
+ * 解析 outbound "to" 字符串，得到发送目标
+ *
+ * 格式约定：
+ *   - 私聊：contactId，例如 "wxid_abc123"
+ *   - 群聊：以 "group:" 前缀，例如 "group:roomid_xxx"
+ *   - 群聊带 @：以 "group:roomid_xxx@wxid_a,wxid_b"（@ 后面逗号分隔 mentionIds）
+ */
+export function parseSocketChatTarget(to: string): Omit<SocketChatOutboundPayload, "messages"> {
+  const trimmed = to.trim();
+
+  if (trimmed.startsWith("group:")) {
+    const withoutPrefix = trimmed.slice("group:".length);
+    const atIdx = withoutPrefix.indexOf("@");
+    if (atIdx !== -1) {
+      const groupId = withoutPrefix.slice(0, atIdx);
+      const mentionIds = withoutPrefix
+        .slice(atIdx + 1)
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+      return { isGroup: true, groupId, mentionIds };
+    }
+    return { isGroup: true, groupId: withoutPrefix };
+  }
+
+  return { isGroup: false, contactId: trimmed };
+}
+
+/**
+ * 规范化 outbound 目标字符串（去掉前后空格，去掉 socket-chat: 前缀）
+ */
+export function normalizeSocketChatTarget(raw: string): string | undefined {
+  const trimmed = raw
+    .trim()
+    .replace(/^socket-chat:/i, "")
+    .trim();
+  return trimmed || undefined;
+}
+
+/**
+ * 判断字符串是否像一个 socket-chat 原生 ID
+ * wxid_xxx / roomid_xxx 格式，或带 group: 前缀
+ */
+export function looksLikeSocketChatTargetId(s: string): boolean {
+  return /^(wxid_|roomid_|group:)/.test(s.trim());
+}
+
+/**
+ * 构建纯文本发送 payload
+ */
+export function buildTextPayload(
+  to: string,
+  text: string,
+  opts: { mentionIds?: string[] } = {},
+): SocketChatOutboundPayload {
+  const base = parseSocketChatTarget(to);
+  const mentionIds =
+    opts.mentionIds ?? (base.isGroup ? base.mentionIds : undefined);
+  return {
+    ...base,
+    mentionIds: mentionIds?.length ? mentionIds : undefined,
+    messages: [{ type: 1, content: text }],
+  };
+}
+
+/**
+ * 构建图片发送 payload（可附带文字 caption）
+ */
+export function buildMediaPayload(
+  to: string,
+  imageUrl: string,
+  caption?: string,
+): SocketChatOutboundPayload {
+  const base = parseSocketChatTarget(to);
+  const messages: SocketChatOutboundPayload["messages"] = [];
+  if (caption?.trim()) {
+    messages.push({ type: 1, content: caption });
+  }
+  messages.push({ type: 2, url: imageUrl });
+  return { ...base, messages };
+}
+
+/**
+ * 通过已连接的 MQTT client 发送出站消息
+ */
+export async function sendSocketChatMessage(params: {
+  mqttClient: MqttClient;
+  mqttConfig: SocketChatMqttConfig;
+  payload: SocketChatOutboundPayload;
+}): Promise<{ messageId: string }> {
+  const { mqttClient, mqttConfig, payload } = params;
+  return new Promise((resolve, reject) => {
+    const body = JSON.stringify(payload);
+    mqttClient.publish(mqttConfig.sendTopic, body, { qos: 1 }, (err?: Error) => {
+      if (err) {
+        reject(new Error(`MQTT publish failed: ${err.message}`));
+        return;
+      }
+      // 平台不返回 messageId，用本地时间戳生成一个
+      resolve({ messageId: `sc-${Date.now()}` });
+    });
+  });
+}
+
+// ---------------------------------------------------------------------------
+// ChannelOutboundAdapter 实现
+// ---------------------------------------------------------------------------
+
+/**
+ * socket-chat 出站适配器。
+ *
+ * 通过注册表查找当前账号的活跃 MQTT client 发送消息：
+ *   - sendText：发送纯文字
+ *   - sendMedia：优先发图片（type:2），无 mediaUrl 时退化为纯文字
+ *   - resolveTarget：规范化目标地址（strip socket-chat: 前缀）
+ */
+export const socketChatOutbound: ChannelOutboundAdapter = {
+  deliveryMode: "direct",
+  textChunkLimit: 4096,
+
+  resolveTarget: ({ to }) => {
+    const normalized = to ? normalizeSocketChatTarget(to) : undefined;
+    if (!normalized) {
+      return { ok: false, error: new Error(`Invalid socket-chat target: "${to}"`) };
+    }
+    return { ok: true, to: normalized };
+  },
+
+  sendText: async ({ to, text, accountId }) => {
+    const resolvedAccountId = accountId ?? DEFAULT_ACCOUNT_ID;
+    const client = getActiveMqttClient(resolvedAccountId);
+    const mqttConfig = getActiveMqttConfig(resolvedAccountId);
+
+    if (!client || !mqttConfig) {
+      throw new Error(
+        `[socket-chat] No active MQTT connection for account "${resolvedAccountId}". ` +
+        "Is the gateway running?",
+      );
+    }
+
+    const payload = buildTextPayload(to, text);
+    const result = await sendSocketChatMessage({ mqttClient: client, mqttConfig, payload });
+    return { channel: "socket-chat", messageId: result.messageId };
+  },
+
+  sendMedia: async ({ to, text, mediaUrl, accountId }) => {
+    const resolvedAccountId = accountId ?? DEFAULT_ACCOUNT_ID;
+    const client = getActiveMqttClient(resolvedAccountId);
+    const mqttConfig = getActiveMqttConfig(resolvedAccountId);
+
+    if (!client || !mqttConfig) {
+      throw new Error(
+        `[socket-chat] No active MQTT connection for account "${resolvedAccountId}".`,
+      );
+    }
+
+    // 有图片 URL 时发图片（可附带 caption），否则退化为纯文字
+    if (mediaUrl) {
+      const payload = buildMediaPayload(to, mediaUrl, text);
+      const result = await sendSocketChatMessage({ mqttClient: client, mqttConfig, payload });
+      return { channel: "socket-chat", messageId: result.messageId };
+    }
+
+    const payload = buildTextPayload(to, text);
+    const result = await sendSocketChatMessage({ mqttClient: client, mqttConfig, payload });
+    return { channel: "socket-chat", messageId: result.messageId };
+  },
+};

package/src/probe.ts

@@ -0,0 +1,49 @@
+import { fetchMqttConfig } from "./api.js";
+import type { ResolvedSocketChatAccount } from "./config.js";
+
+export type SocketChatProbeResult = {
+  ok: boolean;
+  error?: string;
+  host?: string;
+  port?: string;
+  robotId?: string;
+  userId?: string;
+  reciveTopic?: string;
+  sendTopic?: string;
+};
+
+/**
+ * 探测账号连通性：
+ * 1. 调用 GET /api/openclaw/chat/config 验证 API key 有效性
+ * 2. 返回获取到的连接信息摘要
+ */
+export async function probeSocketChatAccount(params: {
+  account: ResolvedSocketChatAccount;
+  timeoutMs: number;
+}): Promise<SocketChatProbeResult> {
+  const { account, timeoutMs } = params;
+
+  if (!account.apiKey || !account.apiBaseUrl) {
+    return { ok: false, error: "apiKey or apiBaseUrl not configured" };
+  }
+
+  try {
+    const config = await fetchMqttConfig({
+      apiBaseUrl: account.apiBaseUrl,
+      apiKey: account.apiKey,
+      timeoutMs,
+    });
+    return {
+      ok: true,
+      host: config.host,
+      port: config.port,
+      robotId: config.robotId,
+      userId: config.userId,
+      reciveTopic: config.reciveTopic,
+      sendTopic: config.sendTopic,
+    };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return { ok: false, error: message };
+  }
+}

package/src/runtime.ts

@@ -0,0 +1,14 @@
+import type { PluginRuntime } from "openclaw/plugin-sdk";
+
+let runtime: PluginRuntime | null = null;
+
+export function setSocketChatRuntime(next: PluginRuntime): void {
+  runtime = next;
+}
+
+export function getSocketChatRuntime(): PluginRuntime {
+  if (!runtime) {
+    throw new Error("socket-chat runtime not initialized");
+  }
+  return runtime;
+}

package/src/types.ts

@@ -0,0 +1,98 @@
+// Socket Chat inbound/outbound 消息类型定义
+
+/**
+ * MQTT 收到的入站消息格式（reciveTopic）
+ */
+export type SocketChatInboundMessage = {
+  /** 消息文字内容 */
+  content: string;
+  /** 机器人 ID（robotId，即本 bot 账号标识） */
+  robotId: string;
+  /** 发送者 ID */
+  senderId: string;
+  /** 发送者昵称 */
+  senderName: string;
+  /** 是否是群消息 */
+  isGroup: boolean;
+  /** 群 ID（isGroup=true 时存在） */
+  groupId?: string;
+  /** 群名称（isGroup=true 时存在） */
+  groupName?: string;
+  /** 11 位时间戳（毫秒） */
+  timestamp: number;
+  /** 消息唯一 ID */
+  messageId: string;
+  /** 消息类型：文字 / 图片 / 视频 / 文件 / 语音 / 名片 / h5链接 / 视频号 / 位置 / 历史记录 */
+  type?: string;
+  /** 媒体文件 URL（图片/视频/文件/语音等，OSS 链接或 base64） */
+  url?: string;
+  /** 额外媒体元数据（视频号、名片、h5链接等结构化信息） */
+  mediaInfo?: Record<string, unknown>;
+};
+
+/**
+ * 单条发送消息体
+ * type: 1=文字, 2=纯图片
+ */
+export type SocketChatOutboundMessage =
+  | { type: 1; content: string }
+  | { type: 2; url: string };
+
+/**
+ * MQTT 发送的出站消息格式（sendTopic）
+ */
+export type SocketChatOutboundPayload = {
+  /** 是否发给群 */
+  isGroup: boolean;
+  /** 群 ID（isGroup=true 时传） */
+  groupId?: string;
+  /** 私聊用户 ID（isGroup=false 时传） */
+  contactId?: string;
+  /** 群组中 @提及的用户 ID 列表 */
+  mentionIds?: string[];
+  /** 消息列表（支持多条） */
+  messages: SocketChatOutboundMessage[];
+};
+
+/**
+ * 从 GET /api/openclaw/chat/config 获取的 MQTT 连接配置
+ */
+export type SocketChatMqttConfig = {
+  host: string;
+  port: string;
+  username: string;
+  password: string;
+  clientId: string;
+  reciveTopic: string;
+  sendTopic: string;
+  /** 机器人自身的 ID（用于识别是否是自己发出的消息） */
+  robotId: string;
+  /** 当前用户/账号 ID */
+  userId: string;
+};
+
+/**
+ * 出站目标解析结果
+ */
+export type SocketChatTarget =
+  | { isGroup: false; contactId: string }
+  | { isGroup: true; groupId: string; mentionIds?: string[] };
+
+/**
+ * MQTT 运行时状态 patch（传给 ctx.setStatus）
+ */
+export type SocketChatStatusPatch = {
+  accountId?: string;
+  running?: boolean;
+  connected?: boolean;
+  lastConnectedAt?: number | null;
+  lastDisconnect?: string | null;
+  lastEventAt?: number | null;
+  lastStartAt?: number | null;
+  lastStopAt?: number | null;
+  lastError?: string | null;
+  reconnectAttempts?: number;
+  lastInboundAt?: number | null;
+  lastOutboundAt?: number | null;
+  mode?: string;
+};

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "outDir": "./dist",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "lib": ["ES2022", "DOM"]
+  },
+  "include": ["index.ts", "src/**/*.ts"],
+  "exclude": ["node_modules", "dist"]
+}

package/vitest.config.ts

@@ -0,0 +1,25 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { defineConfig } from "vitest/config";
+
+const dir = path.dirname(fileURLToPath(import.meta.url));
+const openclawSrc = path.join(dir, "..", "openclaw", "src");
+
+export default defineConfig({
+  resolve: {
+    alias: [
+      // Point directly to the allowlist-match module to avoid pulling in the
+      // entire plugin-sdk dependency tree (which includes json5 and other
+      // modules that fail to load outside the openclaw workspace).
+      {
+        find: "openclaw/plugin-sdk",
+        replacement: path.join(dir, "src", "__sdk-stub__.ts"),
+      },
+    ],
+  },
+  test: {
+    include: ["src/**/*.test.ts", "src/**/*.integration.test.ts"],
+    environment: "node",
+    testTimeout: 15_000,
+  },
+});