openclaw-extension-typex 1.0.19 → 1.0.21

package/README.md

@@ -18,3 +18,11 @@ Onboarding: select TypeX and confirm the install prompt to fetch the plugin auto
 
 Once the actual TypeX provider is implemented in the core `openclaw` repo, you can extend
 this plugin to wire outbound messaging and gateway/runtime logic.
+
+## Local checks
+
+```bash
+git config core.hooksPath .githooks
+npm run commitlint -- "feat(typex): add delivery flow"
+npm run verify:domain
+```

package/dist/agent-tools-send.d.ts

@@ -0,0 +1,50 @@
+import type { ChannelAgentTool } from "openclaw/plugin-sdk/channel-contract";
+import type { OpenClawConfig } from "openclaw/plugin-sdk/channel-core";
+type ResolvedPeerTarget = {
+    kind: "chat";
+    id: string;
+    name: string;
+    matchedBy: "feed";
+} | {
+    kind: "user";
+    id: string;
+    name: string;
+    matchedBy: "contact";
+};
+type ResolvedGroupMember = {
+    id: string;
+    name: string;
+};
+type ExecuteTypeXSendByNameParams = {
+    cfg?: OpenClawConfig;
+    recipient: string;
+    message?: string;
+    mediaPath?: string;
+    mediaPaths?: string[];
+    accountId?: string | null;
+};
+type ExecuteTypeXSendInGroupParams = {
+    cfg?: OpenClawConfig;
+    chatId: string;
+    memberName: string;
+    message?: string;
+    mediaPath?: string;
+    mediaPaths?: string[];
+    accountId?: string | null;
+};
+export declare function executeTypeXSendByName(params: ExecuteTypeXSendByNameParams): Promise<{
+    target: ResolvedPeerTarget;
+    sent: string[];
+}>;
+export declare function executeTypeXSendInGroup(params: ExecuteTypeXSendInGroupParams): Promise<{
+    chatId: string;
+    member: ResolvedGroupMember;
+    sent: string[];
+}>;
+export declare function createTypeXSendByNameTool(params: {
+    cfg?: OpenClawConfig;
+}): ChannelAgentTool;
+export declare function createTypeXSendInGroupTool(params: {
+    cfg?: OpenClawConfig;
+}): ChannelAgentTool;
+export {};

package/dist/agent-tools-send.js

@@ -0,0 +1,353 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.executeTypeXSendByName = executeTypeXSendByName;
+exports.executeTypeXSendInGroup = executeTypeXSendInGroup;
+exports.createTypeXSendByNameTool = createTypeXSendByNameTool;
+exports.createTypeXSendInGroupTool = createTypeXSendInGroupTool;
+const promises_1 = require("node:fs/promises");
+const node_path_1 = require("node:path");
+const account_id_1 = require("openclaw/plugin-sdk/account-id");
+const client_js_1 = require("./client/client.js");
+const types_js_1 = require("./client/types.js");
+const TYPEX_IMAGE_SEND_MSG_TYPE = 2;
+const TYPEX_SEND_BY_NAME_SCHEMA = {
+    type: "object",
+    properties: {
+        recipient: { type: "string", minLength: 1 },
+        message: { type: "string" },
+        mediaPath: { type: "string" },
+        accountId: { type: "string" },
+    },
+    required: ["recipient"],
+    additionalProperties: false,
+};
+const TYPEX_SEND_IN_GROUP_SCHEMA = {
+    type: "object",
+    properties: {
+        chatId: { type: "string", minLength: 1, description: "当前 TypeX 群聊 chat_id，可传 chat:123 形式。" },
+        memberName: { type: "string", minLength: 1 },
+        message: { type: "string" },
+        mediaPath: { type: "string" },
+        accountId: { type: "string" },
+    },
+    required: ["chatId", "memberName"],
+    additionalProperties: false,
+};
+function normalizeName(value) {
+    return (value ?? "").trim().toLowerCase().replace(/\s+/g, "");
+}
+function normalizeChatId(value) {
+    return value.trim().replace(/^chat:/i, "").replace(/^group:/i, "");
+}
+function resolveTypeXClient(cfg, accountId) {
+    const typexCfg = (cfg?.channels?.["openclaw-extension-typex"] ?? {});
+    const resolvedAccountId = accountId?.trim() || account_id_1.DEFAULT_ACCOUNT_ID;
+    const client = (0, client_js_1.getTypeXClient)(resolvedAccountId, { typexCfg });
+    return { client, accountId: resolvedAccountId };
+}
+function dedupeByKey(items, getKey) {
+    const seen = new Set();
+    const result = [];
+    for (const item of items) {
+        const key = getKey(item).trim();
+        if (!key || seen.has(key)) {
+            continue;
+        }
+        seen.add(key);
+        result.push(item);
+    }
+    return result;
+}
+function filterMembersByName(items, query) {
+    const normalizedQuery = normalizeName(query);
+    const exact = items.filter((item) => normalizeName(item.name) === normalizedQuery);
+    if (exact.length > 0) {
+        return exact;
+    }
+    return items.filter((item) => normalizeName(item.name).includes(normalizedQuery));
+}
+function filterMembersMentionedInSentence(items, sentence) {
+    const normalizedSentence = normalizeName(sentence);
+    if (!normalizedSentence) {
+        return [];
+    }
+    return items.filter((item) => {
+        const normalizedMemberName = normalizeName(item.name);
+        return normalizedMemberName.length > 0 && normalizedSentence.includes(normalizedMemberName);
+    });
+}
+async function resolvePeerTargetByName(params) {
+    const { client } = resolveTypeXClient(params.cfg, params.accountId);
+    if (client.mode !== "user") {
+        throw new Error("typex_send_by_name 需要使用 TypeX user 账号。");
+    }
+    const contacts = await client.searchContactsByName(params.recipient);
+    const uniqueMatchingContacts = dedupeByKey(contacts
+        .map((contact) => ({
+        friendId: String(contact.friend_id ?? ""),
+        name: String(contact.name ?? contact.friend_id ?? ""),
+    }))
+        .filter((entry) => entry.friendId), (entry) => entry.friendId);
+    if (uniqueMatchingContacts.length === 1) {
+        return {
+            kind: "user",
+            id: uniqueMatchingContacts[0].friendId,
+            name: uniqueMatchingContacts[0].name,
+            matchedBy: "contact",
+        };
+    }
+    if (uniqueMatchingContacts.length > 1) {
+        throw new Error(`找到多个名为 ${params.recipient} 的联系人，请说得更具体一点。`);
+    }
+    const feeds = await client.searchFeedsByName(params.recipient);
+    const uniqueMatchingFeeds = dedupeByKey(feeds
+        .map((feed) => ({
+        chatId: String(feed.chat_id ?? ""),
+        name: String(feed.name ?? feed.chat_id ?? ""),
+    }))
+        .filter((entry) => entry.chatId), (entry) => entry.chatId);
+    if (uniqueMatchingFeeds.length === 1) {
+        return {
+            kind: "chat",
+            id: uniqueMatchingFeeds[0].chatId,
+            name: uniqueMatchingFeeds[0].name,
+            matchedBy: "feed",
+        };
+    }
+    if (uniqueMatchingFeeds.length > 1) {
+        throw new Error(`找到多个名为 ${params.recipient} 的会话，请说得更具体一点。`);
+    }
+    throw new Error(`没有找到名为 ${params.recipient} 的会话或联系人。`);
+}
+async function buildUploadedMediaPayload(params) {
+    const { client } = resolveTypeXClient(params.cfg, params.accountId);
+    const filePath = params.mediaPath.trim();
+    const fileName = (0, node_path_1.basename)(filePath);
+    const buffer = await (0, promises_1.readFile)(filePath);
+    const ext = (0, node_path_1.extname)(fileName).toLowerCase();
+    const isImage = [".jpg", ".jpeg", ".png", ".gif", ".webp", ".bmp"].includes(ext);
+    const fileType = isImage ? "image" : "application";
+    const upload = client.mode === "bot"
+        ? await client.uploadResource(fileName, fileType, buffer, params.chatId)
+        : await client.uploadUserResource(fileName, fileType, buffer, params.chatId);
+    if (isImage) {
+        return {
+            msgType: TYPEX_IMAGE_SEND_MSG_TYPE,
+            content: {
+                object_url: upload.address || upload.objectKey,
+                thumb_url: upload.address || upload.objectKey,
+                width: upload.width || 800,
+                height: upload.height || 600,
+            },
+            kindLabel: "image",
+        };
+    }
+    return {
+        msgType: types_js_1.TypeXMessageEnum.file,
+        content: {
+            object_url: upload.address || upload.objectKey,
+            file_name: fileName,
+            file_size: buffer.length,
+            file_type: "application/octet-stream",
+        },
+        kindLabel: "file",
+    };
+}
+function formatToolTextResult(text, details) {
+    return {
+        content: [{ type: "text", text }],
+        details,
+    };
+}
+async function executeTypeXSendByName(params) {
+    const recipient = String(params.recipient ?? "").trim();
+    const message = String(params.message ?? "").trim();
+    const mediaPaths = [
+        ...((params.mediaPaths ?? []).map((entry) => String(entry ?? "").trim()).filter(Boolean)),
+        ...([params.mediaPath].map((entry) => String(entry ?? "").trim()).filter(Boolean)),
+    ];
+    if (!recipient) {
+        throw new Error("recipient 不能为空。");
+    }
+    if (!message && mediaPaths.length === 0) {
+        throw new Error("message 和 mediaPath 至少要提供一个。");
+    }
+    const target = await resolvePeerTargetByName({
+        cfg: params.cfg,
+        recipient,
+        accountId: params.accountId,
+    });
+    const { client, accountId } = resolveTypeXClient(params.cfg, params.accountId);
+    const sent = [];
+    for (const mediaPath of mediaPaths) {
+        if (target.kind !== "chat") {
+            throw new Error("按联系人直发图片/文件需要已有会话 chat_id；当前只找到了联系人，没有可上传资源的会话。");
+        }
+        const uploaded = await buildUploadedMediaPayload({
+            cfg: params.cfg,
+            accountId,
+            chatId: target.id,
+            mediaPath,
+        });
+        await client.sendDelegatedChatMessage(target.id, uploaded.content, uploaded.msgType);
+        sent.push(uploaded.kindLabel);
+    }
+    if (message) {
+        if (target.kind === "chat") {
+            await client.sendDelegatedChatMessage(target.id, { text: message }, types_js_1.TypeXMessageEnum.text);
+        }
+        else {
+            await client.sendDelegatedContactMessage(target.id, { text: message }, types_js_1.TypeXMessageEnum.text);
+        }
+        sent.push("text");
+    }
+    return {
+        target,
+        sent,
+    };
+}
+async function executeTypeXSendInGroup(params) {
+    const rawChatId = String(params.chatId ?? "").trim();
+    const memberName = String(params.memberName ?? "").trim();
+    const message = String(params.message ?? "").trim();
+    const mediaPaths = [
+        ...((params.mediaPaths ?? []).map((entry) => String(entry ?? "").trim()).filter(Boolean)),
+        ...([params.mediaPath].map((entry) => String(entry ?? "").trim()).filter(Boolean)),
+    ];
+    if (!rawChatId || !memberName) {
+        throw new Error("chatId 和 memberName 不能为空。");
+    }
+    if (!message && mediaPaths.length === 0) {
+        throw new Error("message 和 mediaPath 至少要提供一个。");
+    }
+    const chatId = normalizeChatId(rawChatId);
+    const member = await resolveGroupMemberByName({
+        cfg: params.cfg,
+        chatId,
+        memberName,
+        accountId: params.accountId,
+    });
+    const { client, accountId } = resolveTypeXClient(params.cfg, params.accountId);
+    const sent = [];
+    for (const mediaPath of mediaPaths) {
+        const uploaded = await buildUploadedMediaPayload({
+            cfg: params.cfg,
+            accountId,
+            chatId,
+            mediaPath,
+        });
+        await client.sendBotGroupMessage(chatId, uploaded.content, uploaded.msgType, {
+            atUserIds: [member.id],
+            atMentions: [{ id: member.id, name: member.name }],
+        });
+        sent.push(uploaded.kindLabel);
+    }
+    if (message) {
+        await client.sendBotGroupMessage(chatId, message, types_js_1.TypeXMessageEnum.text, {
+            atUserIds: [member.id],
+            atMentions: [{ id: member.id, name: member.name }],
+        });
+        sent.push("text");
+    }
+    return {
+        chatId,
+        member,
+        sent,
+    };
+}
+function createTypeXSendByNameTool(params) {
+    return {
+        label: "TypeX Send By Name",
+        name: "typex_send_by_name",
+        description: "当用户在 TypeX 单聊里明确要求“发给某人/转给某人”时，用这个工具。它会按名字查找 TypeX 会话或联系人，并以当前登录的 user 身份代发文本或本地图片/文件。",
+        parameters: TYPEX_SEND_BY_NAME_SCHEMA,
+        execute: async (_toolCallId, rawArgs) => {
+            const args = rawArgs;
+            const recipient = String(args.recipient ?? "").trim();
+            const message = String(args.message ?? "").trim();
+            const mediaPath = String(args.mediaPath ?? "").trim();
+            if (!recipient) {
+                throw new Error("recipient 不能为空。");
+            }
+            if (!message && !mediaPath) {
+                throw new Error("message 和 mediaPath 至少要提供一个。");
+            }
+            const { target, sent } = await executeTypeXSendByName({
+                cfg: params.cfg,
+                recipient,
+                message,
+                mediaPath,
+                accountId: args.accountId,
+            });
+            return formatToolTextResult(`已向 ${target.name || recipient} 发送 ${sent.join(" + ")}。`, {
+                ok: true,
+                channel: "openclaw-extension-typex",
+                tool: "typex_send_by_name",
+                targetKind: target.kind,
+                targetId: target.id,
+                matchedBy: target.matchedBy,
+                sent,
+            });
+        },
+    };
+}
+async function resolveGroupMemberByName(params) {
+    const { client } = resolveTypeXClient(params.cfg, params.accountId);
+    if (client.mode !== "bot") {
+        throw new Error("typex_send_in_group 需要使用 TypeX bot 账号。");
+    }
+    const members = dedupeByKey((await client.listGroupMembers(params.chatId))
+        .map((member) => ({
+        id: String(member.user_id ?? ""),
+        name: String(member.name ?? member.user_id ?? ""),
+    }))
+        .filter((entry) => entry.id), (entry) => entry.id);
+    const directMatches = filterMembersByName(members, params.memberName).filter((entry) => entry.id);
+    const matches = directMatches.length > 0
+        ? directMatches
+        : filterMembersMentionedInSentence(members, params.memberName).filter((entry) => entry.id);
+    if (matches.length === 1) {
+        return matches[0];
+    }
+    if (matches.length > 1) {
+        throw new Error(`当前群里有多个成员匹配 ${params.memberName}，请说得更具体一点。`);
+    }
+    throw new Error(`当前群里没有找到名为 ${params.memberName} 的成员。`);
+}
+function createTypeXSendInGroupTool(params) {
+    return {
+        label: "TypeX Send In Group",
+        name: "typex_send_in_group",
+        description: "当用户在 TypeX 群聊里要求 bot 给某个群成员发消息时，用这个工具。它会在当前群里按名字找成员，并以 bot 身份在该群中 @ 对方发送文本或本地图片/文件。",
+        parameters: TYPEX_SEND_IN_GROUP_SCHEMA,
+        execute: async (_toolCallId, rawArgs) => {
+            const args = rawArgs;
+            const rawChatId = String(args.chatId ?? "").trim();
+            const memberName = String(args.memberName ?? "").trim();
+            const message = String(args.message ?? "").trim();
+            const mediaPath = String(args.mediaPath ?? "").trim();
+            if (!rawChatId || !memberName) {
+                throw new Error("chatId 和 memberName 不能为空。");
+            }
+            if (!message && !mediaPath) {
+                throw new Error("message 和 mediaPath 至少要提供一个。");
+            }
+            const { chatId, member, sent } = await executeTypeXSendInGroup({
+                cfg: params.cfg,
+                chatId: rawChatId,
+                memberName,
+                message,
+                mediaPath,
+                accountId: args.accountId,
+            });
+            return formatToolTextResult(`已在群 ${chatId} 中发送给 ${member.name || memberName}：${sent.join(" + ")}。`, {
+                ok: true,
+                channel: "openclaw-extension-typex",
+                tool: "typex_send_in_group",
+                chatId,
+                memberId: member.id,
+                sent,
+            });
+        },
+    };
+}

package/dist/client/accounts.d.ts

@@ -1,4 +1,4 @@
-import type { OpenClawConfig } from "openclaw/plugin-sdk";
+import type { OpenClawConfig } from "openclaw/plugin-sdk/channel-core";
 import type { TypeXAccountConfig } from "../types.js";
 export type TypeXTokenSource = "config" | "file" | "env" | "none";
 export type ResolvedTypeXAccount = {

package/dist/client/accounts.js

@@ -7,7 +7,7 @@ exports.listTypeXAccountIds = listTypeXAccountIds;
 exports.resolveDefaultTypeXAccountId = resolveDefaultTypeXAccountId;
 exports.resolveTypeXAccount = resolveTypeXAccount;
 const node_fs_1 = __importDefault(require("node:fs"));
-const plugin_sdk_1 = require("openclaw/plugin-sdk");
+const account_id_1 = require("openclaw/plugin-sdk/account-id");
 function readFileIfExists(filePath) {
     if (!filePath) {
         return undefined;
@@ -28,8 +28,8 @@ function resolveAccountConfig(cfg, accountId) {
     if (direct) {
         return direct;
     }
-    const normalized = (0, plugin_sdk_1.normalizeAccountId)(accountId);
-    const matchKey = Object.keys(accounts).find((key) => (0, plugin_sdk_1.normalizeAccountId)(key) === normalized);
+    const normalized = (0, account_id_1.normalizeAccountId)(accountId);
+    const matchKey = Object.keys(accounts).find((key) => (0, account_id_1.normalizeAccountId)(key) === normalized);
     return matchKey ? accounts[matchKey] : undefined;
 }
 function mergeTypeXAccountConfig(cfg, accountId) {
@@ -55,29 +55,29 @@ function listTypeXAccountIds(cfg) {
     const baseConfigured = Boolean(typexCfg?.appId?.trim() && (typexCfg?.appSecret?.trim() || Boolean(typexCfg?.appSecretFile)));
     const envConfigured = Boolean(process.env.TYPEX_APP_ID?.trim() && process.env.TYPEX_APP_SECRET?.trim());
     if (baseConfigured || envConfigured) {
-        ids.add(plugin_sdk_1.DEFAULT_ACCOUNT_ID);
+        ids.add(account_id_1.DEFAULT_ACCOUNT_ID);
     }
     if (accounts) {
         for (const id of Object.keys(accounts)) {
-            ids.add((0, plugin_sdk_1.normalizeAccountId)(id));
+            ids.add((0, account_id_1.normalizeAccountId)(id));
         }
     }
     return Array.from(ids);
 }
 function resolveDefaultTypeXAccountId(cfg) {
     const ids = listTypeXAccountIds(cfg);
-    if (ids.includes(plugin_sdk_1.DEFAULT_ACCOUNT_ID)) {
-        return plugin_sdk_1.DEFAULT_ACCOUNT_ID;
+    if (ids.includes(account_id_1.DEFAULT_ACCOUNT_ID)) {
+        return account_id_1.DEFAULT_ACCOUNT_ID;
     }
-    return ids[0] ?? plugin_sdk_1.DEFAULT_ACCOUNT_ID;
+    return ids[0] ?? account_id_1.DEFAULT_ACCOUNT_ID;
 }
 function resolveTypeXAccount(params) {
-    const accountId = (0, plugin_sdk_1.normalizeAccountId)(params.accountId);
+    const accountId = (0, account_id_1.normalizeAccountId)(params.accountId);
     const baseEnabled = params.cfg.channels?.['openclaw-extension-typex']?.enabled !== false;
     const merged = mergeTypeXAccountConfig(params.cfg, accountId);
     const accountEnabled = merged.enabled !== false;
     const enabled = baseEnabled && accountEnabled;
-    const allowEnv = accountId === plugin_sdk_1.DEFAULT_ACCOUNT_ID;
+    const allowEnv = accountId === account_id_1.DEFAULT_ACCOUNT_ID;
     const envAppId = allowEnv ? process.env.TYPEX_APP_ID?.trim() : undefined;
     const envAppSecret = allowEnv ? process.env.TYPEX_APP_SECRET?.trim() : undefined;
     const appId = merged.appId?.trim() || envAppId || "";

package/dist/client/client.d.ts

@@ -1,4 +1,14 @@
-import { TypeXMessageEnum, type TypeXClientOptions, type TypeXMessageEntry } from "./types.js";
+import { TypeXMessageEnum, type TypeXClientOptions, type TypeXContactSearchEntry, type TypeXFeedSearchEntry, type TypeXGroupMemberEntry, type TypeXMessageEntry } from "./types.js";
+type TypeXSendOptions = {
+    replyMsgId?: string;
+    receiverId?: string;
+    isDelegate?: boolean;
+    atUserIds?: string[];
+    atMentions?: Array<{
+        id: string;
+        name: string;
+    }>;
+};
 export declare class TypeXClient {
     private options;
     private accessToken?;
@@ -7,16 +17,22 @@ export declare class TypeXClient {
     get mode(): "user" | "bot";
     getAccessToken(): Promise<string>;
     getCurUserId(): Promise<string>;
+    private getAuthHeaders;
+    private postJson;
     fetchQrcodeUrl(): Promise<any>;
     checkLoginStatus(qrcodeId: string): Promise<boolean>;
+    private executeSendMessage;
+    sendUserChatMessage(chatId: string, content: string | object, msgType?: TypeXMessageEnum): Promise<any>;
+    sendDelegatedChatMessage(chatId: string, content: string | object, msgType?: TypeXMessageEnum): Promise<any>;
+    sendDelegatedContactMessage(receiverId: string, content: string | object, msgType?: TypeXMessageEnum): Promise<any>;
+    sendBotGroupMessage(chatId: string, content: string | object, msgType?: TypeXMessageEnum, options?: Pick<TypeXSendOptions, "replyMsgId" | "atUserIds" | "atMentions">): Promise<any>;
     /**
-     * Send a message to a specific chat (group or DM).
-     * @param to  chat_id to send to
-     * @param content  message text or object
+     * Compatibility wrapper. Prefer the explicit methods above for new call sites.
      */
-    sendMessage(to: string, content: string | object, msgType?: TypeXMessageEnum, options?: {
-        replyMsgId?: string;
-    }): Promise<any>;
+    sendMessage(to: string, content: string | object, msgType?: TypeXMessageEnum, options?: TypeXSendOptions): Promise<any>;
+    searchFeedsByName(name: string): Promise<TypeXFeedSearchEntry[]>;
+    searchContactsByName(name: string): Promise<TypeXContactSearchEntry[]>;
+    listGroupMembers(chatId: string): Promise<TypeXGroupMemberEntry[]>;
     /**
      * Upload resource for the robot to send.
      * @param fileName Name of the file
@@ -25,6 +41,7 @@ export declare class TypeXClient {
      * @param chatId Optional chat_id
      */
     uploadResource(fileName: string, fileType: "image" | "audio" | "video" | "application", fileContent: Buffer | Blob, chatId?: string): Promise<any>;
+    uploadUserResource(fileName: string, fileType: "image" | "audio" | "video" | "application", fileContent: Buffer | Blob, chatId: string): Promise<any>;
     /**
      * Fetch messages. Dispatches to user or bot endpoint based on mode.
      */
@@ -33,7 +50,6 @@ export declare class TypeXClient {
     private fetchUserMessages;
     /**
      * Pull messages for a bot account (Bearer token auth).
-     * TODO: replace /open/bot/message with the actual endpoint path once confirmed.
      */
     private fetchBotMessages;
     /**
@@ -48,5 +64,29 @@ export declare class TypeXClient {
         buffer: Buffer;
         mimeType: string;
     } | null>;
+    /**
+     * Search feeds by name (User mode)
+     */
+    fetchFeedsByName(name: string): Promise<Array<{
+        id: string;
+        name: string;
+    }>>;
+    /**
+     * Search contacts by name (User mode)
+     */
+    fetchContactsByName(name: string): Promise<Array<{
+        id: string;
+        name: string;
+        alias?: string;
+    }>>;
+    /**
+     * Search group members by name (Bot mode)
+     */
+    fetchGroupMembersByName(name: string): Promise<Array<{
+        id: string;
+        name: string;
+        group_alias?: string;
+    }>>;
 }
 export declare function getTypeXClient(accountId?: string, manualOptions?: TypeXClientOptions): TypeXClient;
+export {};