multi-openim-channel 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,183 @@
+/**
+ * Public type surface for the multi-openim-channel plugin.
+ */
+import type { ApiService, CallbackEvent, MessageItem } from "@openim/client-sdk";
+export declare const CHANNEL_ID: "multi-openim";
+export type ChannelId = typeof CHANNEL_ID;
+export type TokenRefreshMode = "hook" | "off" | "http";
+/**
+ * Config-driven HTTP refresher. Every backend-specific string (URL, body
+ * shape, response field names, optional sidecar state file) is operator
+ * input. Placeholder substitution is applied to string templates (endpoint,
+ * header values, body string leaves, clearOnSuccess paths):
+ *
+ *   - `{accountId}`       — the account being refreshed
+ *   - `{state.<field>}`   — `stateFile[accountId][field]`, coerced to string
+ *                           (empty string when missing)
+ *
+ * Response extraction (`responseTokenPath` / `responseUserIdPath` /
+ * `stateWriteBack` values) uses dot-paths into the parsed JSON response;
+ * when an array is given, the first non-empty path wins.
+ */
+export interface HttpTokenRefreshConfig {
+    stateFile?: string;
+    endpoint: string;
+    method?: string;
+    headers?: Record<string, string>;
+    body?: unknown;
+    timeoutMs?: number;
+    responseTokenPath: string | string[];
+    responseUserIdPath?: string | string[];
+    stateWriteBack?: Record<string, string | string[]>;
+    clearOnSuccess?: string[];
+}
+export interface TokenRefreshConfig {
+    mode: TokenRefreshMode;
+    manualLoginMarkerPath?: string;
+    http?: HttpTokenRefreshConfig;
+}
+export interface AccountConfigRaw {
+    enabled?: boolean;
+    token?: string;
+    wsAddr?: string;
+    apiAddr?: string;
+    userID?: string;
+    platformID?: number;
+    requireMention?: boolean;
+    inboundWhitelist?: string[];
+    disableFriendSdk?: boolean;
+}
+export interface AccountConfig {
+    accountId: string;
+    enabled: boolean;
+    userID: string;
+    token: string;
+    wsAddr: string;
+    apiAddr: string;
+    platformID: number;
+    requireMention: boolean;
+    inboundWhitelist: string[];
+    disableFriendSdk: boolean;
+}
+export interface ChannelConfigRaw {
+    enabled?: boolean;
+    healthCheckIntervalMinutes?: number;
+    tokenRefresh?: Partial<TokenRefreshConfig>;
+    disableFriendSdk?: boolean;
+    accounts?: Record<string, AccountConfigRaw>;
+}
+export interface ChannelConfig {
+    enabled: boolean;
+    healthCheckIntervalMinutes: number;
+    tokenRefresh: TokenRefreshConfig;
+    disableFriendSdk: boolean;
+    accounts: Record<string, AccountConfig>;
+}
+export interface ClientHandlers {
+    onRecvNewMessage: (event: CallbackEvent<MessageItem>) => void;
+    onRecvNewMessages: (event: CallbackEvent<MessageItem[]>) => void;
+    onRecvOfflineNewMessages: (event: CallbackEvent<MessageItem[]>) => void;
+    onConnectFailed: (event: unknown) => void;
+    onUserTokenExpired: () => void;
+    onUserTokenInvalid: () => void;
+    onKickedOffline: () => void;
+}
+export interface ClientState {
+    sdk: ApiService;
+    config: AccountConfig;
+    handlers: ClientHandlers;
+    connected: boolean;
+    lastConnectedAt?: number;
+    lastError?: string;
+}
+export type TargetKind = "user" | "group";
+export interface ParsedTarget {
+    kind: TargetKind;
+    id: string;
+}
+export interface InboundMediaItem {
+    kind: "image" | "video" | "file";
+    url?: string;
+    mimeType?: string;
+    fileName?: string;
+    size?: number;
+    snapshotUrl?: string;
+}
+export type InboundKind = "text" | "image" | "video" | "file" | "mixed" | "unknown";
+export interface InboundBodyResult {
+    body: string;
+    kind: InboundKind;
+    media?: InboundMediaItem[];
+}
+/**
+ * Optional in-process refresher invoked when `tokenRefresh.mode === "hook"`.
+ * Returning null (or throwing) means recovery failed and the channel should
+ * fall back to writing a manual-login marker.
+ */
+export type TokenRefresherFn = (accountId: string, reason: string) => Promise<{
+    token: string;
+    userID?: string;
+} | null>;
+declare global {
+    var __multiOpenimTokenRefresher: TokenRefresherFn | undefined;
+}
+export interface PluginLogger {
+    info?(msg: string): void;
+    warn?(msg: string): void;
+    error?(msg: string): void;
+}
+export interface RegisterToolParams {
+    name: string;
+    description: string;
+    parameters: unknown;
+    execute(id: string, params: Record<string, unknown>): Promise<unknown> | unknown;
+}
+export interface RegisterServiceParams {
+    id: string;
+    start(): Promise<void> | void;
+    stop(): Promise<void> | void;
+}
+export interface PluginApi {
+    config?: unknown;
+    runtime?: unknown;
+    logger?: PluginLogger;
+    registerChannel?(spec: {
+        plugin: unknown;
+    }): void;
+    registerTool?(spec: RegisterToolParams): void;
+    registerService?(spec: RegisterServiceParams): void;
+    registerCli?(cb: (ctx: {
+        program: {
+            command(name: string): {
+                description(desc: string): {
+                    command(sub: string): {
+                        description(d: string): {
+                            action(handler: () => Promise<void> | void): void;
+                        };
+                    };
+                };
+            };
+        };
+    }) => void, opts?: {
+        commands?: string[];
+    }): void;
+}
+export interface GatewayLifecycleStatus {
+    accountId: string;
+    enabled?: boolean;
+    configured?: boolean;
+    running?: boolean;
+    connected?: boolean;
+    lastConnectedAt?: number;
+    lastError?: string | null;
+}
+export interface GatewayStartAccountCtx {
+    cfg: unknown;
+    accountId: string;
+    abortSignal?: AbortSignal;
+    setStatus?(status: GatewayLifecycleStatus): void;
+    log?: PluginLogger;
+}
+export interface GatewayStopAccountCtx {
+    accountId: string;
+}

package/dist/types.js

@@ -0,0 +1,4 @@
+/**
+ * Public type surface for the multi-openim-channel plugin.
+ */
+export const CHANNEL_ID = "multi-openim";

package/dist/utils.d.ts

@@ -0,0 +1,6 @@
+export declare function safeStringify(value: unknown): string;
+export declare function toFiniteNumber(value: unknown, fallback: number): number;
+export declare function formatSdkError(error: unknown): string;
+export declare function truncate(text: string, max: number): string;
+export declare function logTag(sub?: string): string;
+export declare function decodeJwtPayload(token: string): Record<string, unknown> | null;

package/dist/utils.js

@@ -0,0 +1,68 @@
+import { CHANNEL_ID } from "./types.js";
+export function safeStringify(value) {
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+export function toFiniteNumber(value, fallback) {
+    if (typeof value === "number") {
+        return Number.isFinite(value) ? value : fallback;
+    }
+    if (value === null || value === undefined)
+        return fallback;
+    const n = parseInt(String(value), 10);
+    return Number.isFinite(n) ? n : fallback;
+}
+export function formatSdkError(error) {
+    if (error && typeof error === "object") {
+        const e = error;
+        const parts = [];
+        if ("event" in e && e.event !== undefined)
+            parts.push(`event=${String(e.event)}`);
+        if ("errCode" in e && e.errCode !== undefined)
+            parts.push(`errCode=${String(e.errCode)}`);
+        if ("errMsg" in e && e.errMsg !== undefined)
+            parts.push(`errMsg=${String(e.errMsg)}`);
+        if ("operationID" in e && e.operationID !== undefined)
+            parts.push(`operationID=${String(e.operationID)}`);
+        if ("data" in e && e.data !== undefined && e.data !== null)
+            parts.push(`data=${safeStringify(e.data)}`);
+        if (parts.length > 0)
+            return parts.join(", ");
+        if (error instanceof Error)
+            return error.message;
+    }
+    return safeStringify(error);
+}
+export function truncate(text, max) {
+    if (text.length <= max)
+        return text;
+    return `${text.slice(0, Math.max(0, max - 1))}…`;
+}
+export function logTag(sub) {
+    return sub ? `[${CHANNEL_ID}][${sub}]` : `[${CHANNEL_ID}]`;
+}
+export function decodeJwtPayload(token) {
+    if (typeof token !== "string")
+        return null;
+    const parts = token.split(".");
+    if (parts.length < 2)
+        return null;
+    const payload = parts[1];
+    if (!payload)
+        return null;
+    try {
+        const normalized = payload.replace(/-/g, "+").replace(/_/g, "/");
+        const padding = (4 - (normalized.length % 4)) % 4;
+        const padded = normalized + "=".repeat(padding);
+        const json = Buffer.from(padded, "base64").toString("utf8");
+        const parsed = JSON.parse(json);
+        return parsed && typeof parsed === "object" ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}

package/openclaw.plugin.json

@@ -0,0 +1,258 @@
+{
+  "id": "multi-openim-channel",
+  "name": "Multi-OpenIM Channel",
+  "version": "0.1.0",
+  "description": "Multi-account / multi-server OpenIM channel plugin for OpenClaw, with config-driven HTTP token refresh and an optional friend-API guard",
+  "author": "Multi-OpenIM",
+  "channels": ["multi-openim"],
+  "contracts": {
+    "tools": [
+      "multi_openim_send_text",
+      "multi_openim_send_image",
+      "multi_openim_send_video",
+      "multi_openim_send_file"
+    ]
+  },
+  "channelConfigs": {
+    "multi-openim": {
+      "label": "Multi-OpenIM",
+      "description": "OpenIM channel supporting multiple accounts and multiple servers in one gateway process. Token refresh is fully configuration-driven (HTTP request templates, no subprocess); friend SDK methods are stubbed by default so external systems can own friend relationships.",
+      "schema": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "enabled": { "type": "boolean", "default": true },
+          "healthCheckIntervalMinutes": { "type": "number", "default": 30, "minimum": 1 },
+          "disableFriendSdk": { "type": "boolean", "default": true },
+          "tokenRefresh": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "mode": { "type": "string", "enum": ["hook", "off", "http"], "default": "hook" },
+              "manualLoginMarkerPath": { "type": "string" },
+              "http": {
+                "type": "object",
+                "additionalProperties": false,
+                "properties": {
+                  "stateFile": { "type": "string" },
+                  "endpoint": { "type": "string" },
+                  "method": { "type": "string", "default": "POST" },
+                  "headers": {
+                    "type": "object",
+                    "additionalProperties": { "type": "string" }
+                  },
+                  "body": {},
+                  "timeoutMs": { "type": "number", "default": 15000, "minimum": 1 },
+                  "responseTokenPath": {
+                    "oneOf": [
+                      { "type": "string" },
+                      { "type": "array", "items": { "type": "string" } }
+                    ]
+                  },
+                  "responseUserIdPath": {
+                    "oneOf": [
+                      { "type": "string" },
+                      { "type": "array", "items": { "type": "string" } }
+                    ]
+                  },
+                  "stateWriteBack": {
+                    "type": "object",
+                    "additionalProperties": {
+                      "oneOf": [
+                        { "type": "string" },
+                        { "type": "array", "items": { "type": "string" } }
+                      ]
+                    }
+                  },
+                  "clearOnSuccess": {
+                    "type": "array",
+                    "items": { "type": "string" }
+                  }
+                },
+                "required": ["endpoint", "responseTokenPath"]
+              }
+            }
+          },
+          "accounts": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "enabled": { "type": "boolean", "default": true },
+                "token": { "type": "string", "description": "OpenIM JWT token" },
+                "wsAddr": { "type": "string", "description": "OpenIM WebSocket endpoint, e.g. ws://127.0.0.1:10001" },
+                "apiAddr": { "type": "string", "description": "OpenIM REST endpoint, e.g. http://127.0.0.1:10002" },
+                "userID": { "type": "string", "description": "Optional, auto-derived from JWT claim" },
+                "platformID": { "type": "number", "description": "Optional, auto-derived from JWT claim; default 5" },
+                "requireMention": { "type": "boolean", "default": true },
+                "inboundWhitelist": { "type": "array", "items": { "type": "string" }, "default": [] },
+                "disableFriendSdk": { "type": "boolean" }
+              },
+              "required": ["token", "wsAddr", "apiAddr"]
+            }
+          }
+        }
+      }
+    }
+  },
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "enabled": {
+        "type": "boolean",
+        "default": true,
+        "description": "Whether the channel is enabled"
+      },
+      "healthCheckIntervalMinutes": {
+        "type": "number",
+        "default": 30,
+        "minimum": 1,
+        "description": "Per-channel health-monitor interval override; takes precedence over the gateway global default"
+      },
+      "tokenRefresh": {
+        "type": "object",
+        "additionalProperties": false,
+        "description": "How the plugin recovers from OnUserTokenExpired / OnUserTokenInvalid / OnConnectFailed / OnKickedOffline. The plugin never spawns subprocesses; recovery is either a config-driven HTTP request (mode='http') or an in-process hook (mode='hook').",
+        "properties": {
+          "mode": {
+            "type": "string",
+            "enum": ["hook", "off", "http"],
+            "default": "hook",
+            "description": "http = call the configured tokenRefresh.http endpoint and parse the response (recommended); hook = call globalThis.__multiOpenimTokenRefresher(accountId, reason); off = skip recovery, write the manual-login marker immediately"
+          },
+          "manualLoginMarkerPath": {
+            "type": "string",
+            "description": "Template for the manual-login marker path. <accountId> is inserted before the extension so N accounts produce N independent files. Defaults to ~/.openclaw/multi-openim/manual-login.json (i.e. manual-login.<accountId>.json)."
+          },
+          "http": {
+            "type": "object",
+            "additionalProperties": false,
+            "description": "Fully config-driven HTTP refresh. Templates support {accountId} and {state.<field>} placeholders, where state.<field> reads stateFile[accountId][field]. The channel never embeds backend-specific strings — every backend detail is declared here. On success the new token is written back to ~/.openclaw/openclaw.json (channels.multi-openim.accounts.<id>.token) so it survives gateway restarts.",
+            "properties": {
+              "stateFile": {
+                "type": "string",
+                "description": "Optional JSON file keyed by accountId. Read before the request to resolve {state.X} placeholders; written-back after when stateWriteBack is set."
+              },
+              "endpoint": {
+                "type": "string",
+                "description": "URL template, e.g. \"{state.server_url}/refresh\""
+              },
+              "method": {
+                "type": "string",
+                "default": "POST",
+                "description": "HTTP method"
+              },
+              "headers": {
+                "type": "object",
+                "additionalProperties": { "type": "string" },
+                "description": "Headers; values may contain placeholders"
+              },
+              "body": {
+                "description": "Request body. Object → JSON-encoded after recursive placeholder substitution on string leaves; string → sent verbatim after substitution; omitted → no body"
+              },
+              "timeoutMs": {
+                "type": "number",
+                "default": 15000,
+                "minimum": 1,
+                "description": "Request timeout in milliseconds"
+              },
+              "responseTokenPath": {
+                "oneOf": [
+                  { "type": "string" },
+                  { "type": "array", "items": { "type": "string" } }
+                ],
+                "description": "Dot-path(s) into the response JSON to extract the new IM token. First non-empty wins."
+              },
+              "responseUserIdPath": {
+                "oneOf": [
+                  { "type": "string" },
+                  { "type": "array", "items": { "type": "string" } }
+                ],
+                "description": "Optional dot-path(s) for a rotated userID. First non-empty wins."
+              },
+              "stateWriteBack": {
+                "type": "object",
+                "additionalProperties": {
+                  "oneOf": [
+                    { "type": "string" },
+                    { "type": "array", "items": { "type": "string" } }
+                  ]
+                },
+                "description": "Persist response fields back to stateFile under the accountId key. Maps <state-field> → response dot-path(s). Ignored when stateFile is unset."
+              },
+              "clearOnSuccess": {
+                "type": "array",
+                "items": { "type": "string" },
+                "description": "Extra paths to delete on a successful refresh. Supports {accountId} placeholder."
+              }
+            },
+            "required": ["endpoint", "responseTokenPath"]
+          }
+        }
+      },
+      "disableFriendSdk": {
+        "type": "boolean",
+        "default": true,
+        "description": "When true (default), all OpenIM SDK friend-related APIs (addFriend / acceptFriendApplication / ...) are replaced with throwing stubs. Recommended when an external system owns friend relationships; set false to expose the raw SDK behavior."
+      },
+      "accounts": {
+        "type": "object",
+        "description": "Multi-account configuration keyed by accountId. Top-level single-account fallback is NOT supported; use accounts.<id>.",
+        "additionalProperties": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "enabled": { "type": "boolean", "default": true },
+            "token": {
+              "type": "string",
+              "description": "OpenIM JWT token. userID / platformID are auto-derived from JWT claims when omitted."
+            },
+            "wsAddr": {
+              "type": "string",
+              "description": "OpenIM WebSocket endpoint, e.g. ws://127.0.0.1:10001"
+            },
+            "apiAddr": {
+              "type": "string",
+              "description": "OpenIM REST endpoint, e.g. http://127.0.0.1:10002"
+            },
+            "userID": {
+              "type": "string",
+              "description": "OpenIM userID. Optional; auto-derived from JWT 'UserID' claim if omitted."
+            },
+            "platformID": {
+              "type": "number",
+              "description": "OpenIM platformID. Optional; auto-derived from JWT 'PlatformID' claim or defaults to 5."
+            },
+            "requireMention": {
+              "type": "boolean",
+              "default": true,
+              "description": "Whether group messages must @-mention this account to trigger a reply"
+            },
+            "inboundWhitelist": {
+              "type": "array",
+              "items": { "type": "string" },
+              "default": [],
+              "description": "Optional sender allowlist. When non-empty, only listed senders can trigger a reply (and in groups they must @-mention)."
+            },
+            "disableFriendSdk": {
+              "type": "boolean",
+              "description": "Per-account override of the channel-level disableFriendSdk"
+            }
+          },
+          "required": ["token", "wsAddr", "apiAddr"]
+        }
+      }
+    }
+  },
+  "uiHints": {
+    "token": { "label": "Token", "sensitive": true },
+    "wsAddr": { "label": "WebSocket Endpoint", "placeholder": "ws://127.0.0.1:10001" },
+    "apiAddr": { "label": "API Endpoint", "placeholder": "http://127.0.0.1:10002" },
+    "requireMention": { "label": "Require @-mention in group" },
+    "inboundWhitelist": { "label": "Inbound sender whitelist" },
+    "disableFriendSdk": { "label": "Disable OpenIM SDK friend APIs (recommended)" },
+    "healthCheckIntervalMinutes": { "label": "Health-monitor interval (minutes)" }
+  }
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "multi-openim-channel",
+  "version": "0.1.0",
+  "description": "Multi-account / multi-server OpenIM channel plugin for OpenClaw, with config-driven token refresh and an optional friend-API guard",
+  "license": "MIT",
+  "author": "Multi-OpenIM",
+  "type": "module",
+  "main": "./dist/index.js",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "openclaw.plugin.json",
+    "README.md",
+    "SCHEMA.md",
+    "LICENSE"
+  ],
+  "openclaw": {
+    "extensions": [
+      "./dist/index.js"
+    ],
+    "channel": {
+      "id": "multi-openim",
+      "label": "Multi-OpenIM",
+      "selectionLabel": "Multi-OpenIM",
+      "docsPath": "/channels/multi-openim",
+      "blurb": "Multi-account / multi-server OpenIM channel via @openim/client-sdk",
+      "order": 70,
+      "aliases": ["multi-openim", "multi-openim-im", "mopenim"]
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "watch": "tsc --watch",
+    "clean": "rm -rf dist",
+    "validate": "node scripts/validate-build.mjs",
+    "smoke": "node scripts/smoke-connect.mjs",
+    "prepublishOnly": "npm run clean && npm run build && npm run validate"
+  },
+  "dependencies": {
+    "@openim/client-sdk": "^3.8.3"
+  },
+  "peerDependencies": {
+    "openclaw": "*"
+  },
+  "peerDependenciesMeta": {
+    "openclaw": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.4.0"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}