multi-openim-channel 0.1.0

package/dist/token-refresh.js

@@ -0,0 +1,383 @@
+/**
+ * Token-refresh orchestration. Invoked from clients.ts when the SDK reports
+ * a token-related failure (OnUserTokenExpired / OnUserTokenInvalid /
+ * OnConnectFailed / OnKickedOffline / initial login() rejection).
+ *
+ * Three modes, picked by `tokenRefresh.mode`:
+ *
+ *   - "http": a fully config-driven HTTP request, performed in-process via
+ *     the standard `fetch`. Reads context from an optional state JSON file
+ *     keyed by accountId, substitutes `{accountId}` / `{state.<field>}`
+ *     placeholders into the configured endpoint / headers / body, posts
+ *     the request, extracts the new token by dot-path from the response,
+ *     optionally writes-back response fields into the state file, and
+ *     patches the gateway's openclaw.json so the new token survives a
+ *     restart. The channel does not embed any backend-specific strings.
+ *
+ *   - "hook": call `globalThis.__multiOpenimTokenRefresher(accountId,
+ *     reason)`. Power-user escape hatch when refresh logic is too
+ *     imperative for HTTP-template config.
+ *
+ *   - "off": skip recovery, write the manual-login marker immediately.
+ *
+ * The plugin never spawns subprocesses; both recovery paths are pure JS.
+ */
+import { mkdirSync, readFileSync, unlinkSync, writeFileSync, } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { CHANNEL_ID } from "./types.js";
+import { formatSdkError, logTag, truncate } from "./utils.js";
+/**
+ * Cap on how long a user-supplied JS hook may run before we treat it as
+ * failure. A hooked refresher that hangs (network stall, internal deadlock)
+ * would otherwise pin the per-account refresh flag indefinitely. The HTTP
+ * path has its own timeout via AbortSignal.timeout, so this guard applies
+ * only to `mode: "hook"`.
+ */
+const HOOK_TIMEOUT_MS = 30_000;
+/**
+ * Resolve the per-account marker file path. `manualLoginMarkerPath` is a
+ * template into which the accountId is inserted:
+ *
+ *   "/path/to/manual-login.json"  → "/path/to/manual-login.<accountId>.json"
+ *   "/path/to/markers/"           → "/path/to/markers/<accountId>.json"
+ *   "/path/no-ext"                → "/path/no-ext.<accountId>"
+ */
+export function resolveManualLoginMarkerPath(cfg, accountId) {
+    const base = cfg.manualLoginMarkerPath;
+    if (!base)
+        return undefined;
+    const id = String(accountId || "").trim() || "unknown";
+    if (base.endsWith("/") || base.endsWith("\\")) {
+        return `${base}${id}.json`;
+    }
+    const dotIdx = base.lastIndexOf(".");
+    const slashIdx = Math.max(base.lastIndexOf("/"), base.lastIndexOf("\\"));
+    if (dotIdx > slashIdx) {
+        return `${base.slice(0, dotIdx)}.${id}${base.slice(dotIdx)}`;
+    }
+    return `${base}.${id}`;
+}
+export function writeManualLoginMarker(ctx, accountId, detail) {
+    const path = resolveManualLoginMarkerPath(ctx.channel.tokenRefresh, accountId);
+    if (!path)
+        return;
+    try {
+        mkdirSync(dirname(path), { recursive: true });
+    }
+    catch {
+        // ignore: writeFileSync below will surface a real failure
+    }
+    const payload = {
+        accountId: String(accountId || ""),
+        at: new Date().toISOString(),
+        status: "manual_login_required",
+        detail: truncate(String(detail ?? ""), 2_000),
+    };
+    try {
+        writeFileSync(path, JSON.stringify(payload, null, 2), "utf8");
+        ctx.logger.error?.(`${logTag("token-refresh")} manual-login required for account=${payload.accountId}; marker=${path}`);
+        ctx.logger.error?.(`${logTag("token-refresh")} JSON: ${JSON.stringify({
+            type: "MANUAL_LOGIN_REQUIRED",
+            accountId: payload.accountId,
+            ts: payload.at,
+        })}`);
+    }
+    catch (e) {
+        ctx.logger.error?.(`${logTag("token-refresh")} failed to write marker ${path}: ${formatSdkError(e)}`);
+    }
+}
+export function clearManualLoginMarker(cfg, accountId) {
+    const path = resolveManualLoginMarkerPath(cfg, accountId);
+    if (!path)
+        return;
+    try {
+        unlinkSync(path);
+    }
+    catch {
+        // ignore: not present is fine
+    }
+}
+async function callHook(ctx, accountId, reason) {
+    const refresher = globalThis.__multiOpenimTokenRefresher;
+    if (typeof refresher !== "function") {
+        return { ok: false, error: "no globalThis.__multiOpenimTokenRefresher registered", via: "no-hook" };
+    }
+    const timeoutMarker = Symbol("hook-timeout");
+    let timer;
+    const timeoutPromise = new Promise((resolve) => {
+        timer = setTimeout(() => resolve(timeoutMarker), HOOK_TIMEOUT_MS);
+    });
+    try {
+        const settled = await Promise.race([refresher(accountId, reason), timeoutPromise]);
+        if (settled === timeoutMarker) {
+            ctx.logger.warn?.(`${logTag("token-refresh")} hook timed out after ${HOOK_TIMEOUT_MS}ms for account=${accountId}`);
+            return { ok: false, error: `hook timeout after ${HOOK_TIMEOUT_MS}ms`, via: "hook" };
+        }
+        const result = settled;
+        if (!result || typeof result !== "object" || typeof result.token !== "string" || !result.token) {
+            return { ok: false, error: "hook returned no token", via: "hook" };
+        }
+        return {
+            ok: true,
+            token: result.token,
+            userID: typeof result.userID === "string" && result.userID ? result.userID : undefined,
+            via: "hook",
+        };
+    }
+    catch (e) {
+        const msg = formatSdkError(e);
+        ctx.logger.warn?.(`${logTag("token-refresh")} hook threw for account=${accountId}: ${truncate(msg, 200)}`);
+        return { ok: false, error: msg, via: "hook" };
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+function substituteTemplate(template, accountId, state) {
+    return template.replace(/\{(accountId|state\.[A-Za-z0-9_]+)\}/g, (_match, key) => {
+        if (key === "accountId")
+            return accountId;
+        const field = key.slice("state.".length);
+        const v = state[field];
+        if (v == null)
+            return "";
+        return String(v);
+    });
+}
+function deepSubstitute(value, accountId, state) {
+    if (typeof value === "string") {
+        return substituteTemplate(value, accountId, state);
+    }
+    if (Array.isArray(value)) {
+        return value.map((v) => deepSubstitute(v, accountId, state));
+    }
+    if (value && typeof value === "object") {
+        const out = {};
+        for (const [k, v] of Object.entries(value)) {
+            out[k] = deepSubstitute(v, accountId, state);
+        }
+        return out;
+    }
+    return value;
+}
+function getByDotPath(root, path) {
+    if (root == null)
+        return undefined;
+    const parts = path.split(".").filter((p) => p.length > 0);
+    let cur = root;
+    for (const p of parts) {
+        if (cur && typeof cur === "object" && p in cur) {
+            cur = cur[p];
+        }
+        else {
+            return undefined;
+        }
+    }
+    return cur;
+}
+function firstNonEmptyString(root, paths) {
+    for (const p of paths) {
+        const v = getByDotPath(root, p);
+        if (typeof v === "string" && v.length > 0)
+            return v;
+        if (typeof v === "number" && Number.isFinite(v))
+            return String(v);
+    }
+    return "";
+}
+function asArray(v) {
+    if (!v)
+        return [];
+    return Array.isArray(v) ? v : [v];
+}
+function readStateFile(ctx, http, accountId) {
+    if (!http.stateFile)
+        return { all: {}, account: {} };
+    try {
+        const raw = readFileSync(http.stateFile, "utf8");
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+            const all = parsed;
+            const entry = all[accountId];
+            const account = entry && typeof entry === "object" ? entry : {};
+            return { all, account };
+        }
+    }
+    catch (e) {
+        ctx.logger.warn?.(`${logTag("token-refresh")} stateFile=${http.stateFile} read failed: ${truncate(formatSdkError(e), 200)}`);
+    }
+    return { all: {}, account: {} };
+}
+function writeStateFile(ctx, path, all) {
+    try {
+        mkdirSync(dirname(path), { recursive: true });
+    }
+    catch {
+        // ignore: directory may already exist; failures surface in writeFileSync
+    }
+    try {
+        writeFileSync(path, JSON.stringify(all, null, 2), "utf8");
+    }
+    catch (e) {
+        ctx.logger.warn?.(`${logTag("token-refresh")} stateFile=${path} write failed: ${truncate(formatSdkError(e), 200)}`);
+    }
+}
+/**
+ * Persist the refreshed token back to the gateway's own config file so a
+ * restart resumes with the new JWT. Only `channels.<CHANNEL_ID>.accounts.<id>.token`
+ * is touched; sibling fields are left intact.
+ */
+function patchOpenclawConfigToken(ctx, accountId, newToken) {
+    const path = String(process.env.OPENCLAW_CONFIG_PATH ?? "").trim() || join(homedir(), ".openclaw", "openclaw.json");
+    let cfg;
+    try {
+        cfg = JSON.parse(readFileSync(path, "utf8"));
+        if (!cfg || typeof cfg !== "object" || Array.isArray(cfg))
+            cfg = {};
+    }
+    catch (e) {
+        ctx.logger.warn?.(`${logTag("token-refresh")} openclaw config ${path} read failed; skipping persistent token writeback: ${truncate(formatSdkError(e), 200)}`);
+        return;
+    }
+    const channels = (cfg.channels && typeof cfg.channels === "object" && !Array.isArray(cfg.channels)
+        ? cfg.channels
+        : (cfg.channels = {}));
+    const block = (channels[CHANNEL_ID] && typeof channels[CHANNEL_ID] === "object"
+        ? channels[CHANNEL_ID]
+        : (channels[CHANNEL_ID] = {}));
+    const accounts = (block.accounts && typeof block.accounts === "object" && !Array.isArray(block.accounts)
+        ? block.accounts
+        : (block.accounts = {}));
+    const entry = (accounts[accountId] && typeof accounts[accountId] === "object"
+        ? accounts[accountId]
+        : (accounts[accountId] = {}));
+    entry.token = newToken;
+    try {
+        writeFileSync(path, JSON.stringify(cfg, null, 2), "utf8");
+    }
+    catch (e) {
+        ctx.logger.warn?.(`${logTag("token-refresh")} openclaw config ${path} write failed: ${truncate(formatSdkError(e), 200)}`);
+    }
+}
+async function callHttp(ctx, accountId, reason) {
+    const http = ctx.channel.tokenRefresh.http;
+    if (!http) {
+        return { ok: false, error: "tokenRefresh.http config missing", via: "no-http" };
+    }
+    const { all, account: stateForAccount } = readStateFile(ctx, http, accountId);
+    const subst = (s) => substituteTemplate(s, accountId, stateForAccount);
+    const url = subst(http.endpoint);
+    if (!url) {
+        return { ok: false, error: "endpoint template resolved to empty", via: "http" };
+    }
+    const headers = {};
+    for (const [k, v] of Object.entries(http.headers ?? {})) {
+        headers[k] = subst(v);
+    }
+    let body;
+    if (http.body !== undefined && http.body !== null) {
+        if (typeof http.body === "string") {
+            body = subst(http.body);
+        }
+        else {
+            body = JSON.stringify(deepSubstitute(http.body, accountId, stateForAccount));
+            const hasContentType = Object.keys(headers).some((k) => k.toLowerCase() === "content-type");
+            if (!hasContentType)
+                headers["content-type"] = "application/json";
+        }
+    }
+    const method = String(http.method ?? "POST").trim().toUpperCase() || "POST";
+    const timeoutMs = Number.isFinite(http.timeoutMs) ? Number(http.timeoutMs) : 15_000;
+    ctx.logger.info?.(`${logTag("token-refresh")} HTTP refresh account=${accountId} ${method} ${url} (reason=${truncate(reason, 100)})`);
+    let res;
+    try {
+        res = await fetch(url, {
+            method,
+            headers,
+            body,
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+    }
+    catch (e) {
+        return { ok: false, error: `fetch failed: ${truncate(formatSdkError(e), 300)}`, via: "http" };
+    }
+    if (!res.ok) {
+        let detail = `HTTP ${res.status}`;
+        try {
+            const text = await res.text();
+            if (text)
+                detail += ` ${truncate(text, 300)}`;
+        }
+        catch {
+            // body read failed; status alone is informative enough
+        }
+        return { ok: false, error: detail, via: "http" };
+    }
+    let payload;
+    try {
+        payload = await res.json();
+    }
+    catch (e) {
+        return { ok: false, error: `response not JSON: ${truncate(formatSdkError(e), 200)}`, via: "http" };
+    }
+    const tokenPaths = asArray(http.responseTokenPath);
+    const newToken = firstNonEmptyString(payload, tokenPaths);
+    if (!newToken) {
+        return {
+            ok: false,
+            error: `response missing token at any of [${tokenPaths.join(", ")}]`,
+            via: "http",
+        };
+    }
+    const userIdPaths = asArray(http.responseUserIdPath);
+    const newUserId = userIdPaths.length > 0 ? firstNonEmptyString(payload, userIdPaths) : "";
+    if (http.stateFile && http.stateWriteBack) {
+        const prevEntry = (all[accountId] && typeof all[accountId] === "object"
+            ? all[accountId]
+            : {});
+        const updEntry = { ...prevEntry };
+        let touched = false;
+        for (const [field, pathSpec] of Object.entries(http.stateWriteBack)) {
+            const v = firstNonEmptyString(payload, asArray(pathSpec));
+            if (v) {
+                updEntry[field] = v;
+                touched = true;
+            }
+        }
+        if (touched) {
+            all[accountId] = updEntry;
+            writeStateFile(ctx, http.stateFile, all);
+        }
+    }
+    patchOpenclawConfigToken(ctx, accountId, newToken);
+    for (const p of http.clearOnSuccess ?? []) {
+        const resolved = subst(p);
+        if (!resolved)
+            continue;
+        try {
+            unlinkSync(resolved);
+        }
+        catch {
+            // ignore: not present is fine
+        }
+    }
+    return {
+        ok: true,
+        token: newToken,
+        userID: newUserId || undefined,
+        via: "http",
+    };
+}
+export async function refreshAccountToken(args) {
+    const { ctx, accountId, reason } = args;
+    const mode = ctx.channel.tokenRefresh.mode;
+    if (mode === "off") {
+        return { ok: false, error: "tokenRefresh.mode = off", via: "off" };
+    }
+    if (mode === "http") {
+        return callHttp(ctx, accountId, reason);
+    }
+    return callHook(ctx, accountId, reason);
+}

package/dist/tools.d.ts

@@ -0,0 +1,7 @@
+/**
+ * MCP tool registration. `accountId` is required on every call — there is no
+ * "first connected wins" fallback, so an agent that omits it cannot
+ * accidentally fire into the wrong account.
+ */
+import type { PluginApi } from "./types.js";
+export declare function registerTools(api: PluginApi): void;

package/dist/tools.js

@@ -0,0 +1,153 @@
+/**
+ * MCP tool registration. `accountId` is required on every call — there is no
+ * "first connected wins" fallback, so an agent that omits it cannot
+ * accidentally fire into the wrong account.
+ */
+import { getConnectedClient, listConnectedAccountIds } from "./clients.js";
+import { sendFileToTarget, sendImageToTarget, sendTextToTarget, sendVideoToTarget, } from "./media.js";
+import { parseTarget } from "./targets.js";
+import { formatSdkError, logTag } from "./utils.js";
+function errText(text) {
+    return { content: [{ type: "text", text }] };
+}
+function ensureTargetAndClient(params) {
+    const target = parseTarget(params.target);
+    if (!target) {
+        return {
+            ok: false,
+            result: errText("Invalid target format. Expected user:<id> or group:<id>."),
+        };
+    }
+    const accountId = String(params.accountId ?? "").trim();
+    if (!accountId) {
+        const available = listConnectedAccountIds();
+        return {
+            ok: false,
+            result: errText(`accountId is required (no default fallback). Connected accounts: [${available.join(", ") || "none"}]`),
+        };
+    }
+    const client = getConnectedClient(accountId);
+    if (!client) {
+        const available = listConnectedAccountIds();
+        return {
+            ok: false,
+            result: errText(`multi-openim account "${accountId}" is not connected. Connected: [${available.join(", ") || "none"}]`),
+        };
+    }
+    return { ok: true, target, client };
+}
+function commonAccountIdParam() {
+    return {
+        type: "string",
+        description: "Required. Which connected multi-openim account to send from (e.g. \"primary\", \"team-b\").",
+    };
+}
+export function registerTools(api) {
+    if (typeof api.registerTool !== "function") {
+        api.logger?.warn?.(`${logTag("tools")} api.registerTool not available; skipping MCP tools`);
+        return;
+    }
+    const register = api.registerTool.bind(api);
+    register({
+        name: "multi_openim_send_text",
+        description: "Send a text message via multi-openim. target format: user:ID or group:ID.",
+        parameters: {
+            type: "object",
+            properties: {
+                target: { type: "string", description: "user:<id> or group:<id>" },
+                text: { type: "string", description: "Text body to send" },
+                accountId: commonAccountIdParam(),
+            },
+            required: ["target", "text", "accountId"],
+        },
+        async execute(_id, params) {
+            const checked = ensureTargetAndClient(params);
+            if (!checked.ok)
+                return checked.result;
+            try {
+                await sendTextToTarget(checked.client, checked.target, String(params.text ?? ""));
+                return errText("Sent successfully");
+            }
+            catch (e) {
+                return errText(`Send failed: ${formatSdkError(e)}`);
+            }
+        },
+    });
+    register({
+        name: "multi_openim_send_image",
+        description: "Send an image via multi-openim. `image` supports a local path (file:// supported) or http(s) URL.",
+        parameters: {
+            type: "object",
+            properties: {
+                target: { type: "string", description: "user:<id> or group:<id>" },
+                image: { type: "string", description: "Local path (file:// supported) or http(s) URL" },
+                accountId: commonAccountIdParam(),
+            },
+            required: ["target", "image", "accountId"],
+        },
+        async execute(_id, params) {
+            const checked = ensureTargetAndClient(params);
+            if (!checked.ok)
+                return checked.result;
+            try {
+                await sendImageToTarget(checked.client, checked.target, String(params.image ?? ""));
+                return errText("Image sent successfully");
+            }
+            catch (e) {
+                return errText(`Send failed: ${formatSdkError(e)}`);
+            }
+        },
+    });
+    register({
+        name: "multi_openim_send_video",
+        description: "Send a video via multi-openim (delivered as a file message). `video` supports a local path or URL.",
+        parameters: {
+            type: "object",
+            properties: {
+                target: { type: "string", description: "user:<id> or group:<id>" },
+                video: { type: "string", description: "Local path (file:// supported) or http(s) URL" },
+                name: { type: "string", description: "Optional filename override (recommended for URL input)" },
+                accountId: commonAccountIdParam(),
+            },
+            required: ["target", "video", "accountId"],
+        },
+        async execute(_id, params) {
+            const checked = ensureTargetAndClient(params);
+            if (!checked.ok)
+                return checked.result;
+            try {
+                await sendVideoToTarget(checked.client, checked.target, String(params.video ?? ""), params.name ? String(params.name) : undefined);
+                return errText("Video sent successfully as a file");
+            }
+            catch (e) {
+                return errText(`Send failed: ${formatSdkError(e)}`);
+            }
+        },
+    });
+    register({
+        name: "multi_openim_send_file",
+        description: "Send a file via multi-openim. `file` supports a local path or URL; `name` is optional.",
+        parameters: {
+            type: "object",
+            properties: {
+                target: { type: "string", description: "user:<id> or group:<id>" },
+                file: { type: "string", description: "Local path (file:// supported) or http(s) URL" },
+                name: { type: "string", description: "Optional filename override" },
+                accountId: commonAccountIdParam(),
+            },
+            required: ["target", "file", "accountId"],
+        },
+        async execute(_id, params) {
+            const checked = ensureTargetAndClient(params);
+            if (!checked.ok)
+                return checked.result;
+            try {
+                await sendFileToTarget(checked.client, checked.target, String(params.file ?? ""), params.name ? String(params.name) : undefined);
+                return errText("File sent successfully");
+            }
+            catch (e) {
+                return errText(`Send failed: ${formatSdkError(e)}`);
+            }
+        },
+    });
+}