@m1heng-clawd/feishu 0.1.14 → 0.1.16

package/src/urgent-tools/actions.ts

@@ -0,0 +1,84 @@
+import type * as Lark from "@larksuiteoapi/node-sdk";
+import { runFeishuApiCall, type FeishuApiResponse } from "../tools-common/feishu-api.js";
+
+/**
+ * Urgency type for Feishu urgent messages.
+ * - "app": In-app buzz notification (default, no extra cost)
+ * - "sms": SMS push to the recipient's phone
+ * - "phone": Voice call to the recipient's phone
+ */
+export type FeishuUrgentType = "app" | "sms" | "phone";
+
+type UrgentPayload = {
+  data: { user_id_list: string[] };
+  params: { user_id_type: "open_id" | "user_id" | "union_id" };
+  path: { message_id: string };
+};
+
+interface UrgentResponse extends FeishuApiResponse {
+  data?: { invalid_user_id_list?: string[] };
+}
+
+type LarkMessageWithUrgent = Lark.Client["im"]["message"] & {
+  urgentApp?: (payload: UrgentPayload) => Promise<UrgentResponse>;
+  urgentSms?: (payload: UrgentPayload) => Promise<UrgentResponse>;
+  urgentPhone?: (payload: UrgentPayload) => Promise<UrgentResponse>;
+};
+
+/**
+ * Send an urgent (buzz) notification for an existing Feishu message.
+ *
+ * Calls the Feishu "urgent" API which sends a strong push notification
+ * to the specified recipients. The message must already be sent.
+ *
+ * Requires `im:message.urgent` scope (or `im:message.urgent:sms` / `im:message.urgent:phone` variants).
+ *
+ * Common errors:
+ * - Code 230024: Quota exceeded ("Reach the upper limit of urgent message").
+ *   Check tenant quota in Feishu admin console > Cost Center.
+ * - Invalid user IDs cause HTTP 400 with descriptive message (not returned in
+ *   `invalid_user_id_list` as documented).
+ *
+ * @see https://open.feishu.cn/document/server-docs/im-v1/message/urgent_app
+ * @see https://open.feishu.cn/document/server-docs/im-v1/message/urgent_sms
+ * @see https://open.feishu.cn/document/server-docs/im-v1/message/urgent_phone
+ */
+export async function urgentMessageFeishu(params: {
+  client: Lark.Client;
+  messageId: string;
+  userIds: string[];
+  urgentType?: FeishuUrgentType;
+}): Promise<{ invalidUserList: string[] }> {
+  const { client, messageId, userIds, urgentType = "app" } = params;
+
+  const larkMessage = client.im.message as LarkMessageWithUrgent;
+
+  const payload: UrgentPayload = {
+    path: { message_id: messageId },
+    params: { user_id_type: "open_id" },
+    data: { user_id_list: userIds },
+  };
+
+  const methodMap = {
+    app: larkMessage.urgentApp?.bind(larkMessage),
+    sms: larkMessage.urgentSms?.bind(larkMessage),
+    phone: larkMessage.urgentPhone?.bind(larkMessage),
+  } as const;
+
+  const method = methodMap[urgentType];
+  if (typeof method !== "function") {
+    throw new Error(
+      `Feishu urgent: SDK method not available for urgentType="${urgentType}". ` +
+        `Check that @larksuiteoapi/node-sdk is up to date.`,
+    );
+  }
+
+  const response = await runFeishuApiCall<UrgentResponse>(
+    `Feishu urgent message (${urgentType})`,
+    () => method(payload),
+  );
+
+  return {
+    invalidUserList: response.data?.invalid_user_id_list ?? [],
+  };
+}

package/src/urgent-tools/index.ts

@@ -0,0 +1,3 @@
+export { registerFeishuUrgentTools } from "./register.js";
+export { urgentMessageFeishu, type FeishuUrgentType } from "./actions.js";
+export { FeishuUrgentSchema, type FeishuUrgentParams } from "./schemas.js";

package/src/urgent-tools/register.ts

@@ -0,0 +1,64 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { hasFeishuToolEnabledForAnyAccount, withFeishuToolClient } from "../tools-common/tool-exec.js";
+import { errorResult, json } from "../tools-common/feishu-api.js";
+import { urgentMessageFeishu } from "./actions.js";
+import { FeishuUrgentSchema, type FeishuUrgentParams } from "./schemas.js";
+
+export function registerFeishuUrgentTools(api: OpenClawPluginApi) {
+  if (!api.config) {
+    api.logger.debug?.("feishu_urgent: No config available, skipping");
+    return;
+  }
+
+  if (!hasFeishuToolEnabledForAnyAccount(api.config)) {
+    api.logger.debug?.("feishu_urgent: No Feishu accounts configured, skipping");
+    return;
+  }
+
+  if (!hasFeishuToolEnabledForAnyAccount(api.config, "urgent")) {
+    api.logger.debug?.("feishu_urgent: urgent tool disabled in config");
+    return;
+  }
+
+  api.registerTool(
+    {
+      name: "feishu_urgent",
+      label: "Feishu Urgent",
+      description:
+        "Send an urgent (buzz) notification for an existing Feishu message. " +
+        "Supported urgent_type values: app (in-app buzz, default), sms (SMS push), phone (voice call). " +
+        "Requires the message_id of an already-sent message and the open_id list of recipients to buzz. " +
+        "Use this to escalate important messages that require immediate attention.",
+      parameters: FeishuUrgentSchema,
+      async execute(_toolCallId, params) {
+        const p = params as FeishuUrgentParams;
+        try {
+          return await withFeishuToolClient({
+            api,
+            toolName: "feishu_urgent",
+            requiredTool: "urgent",
+            run: async ({ client }) => {
+              const result = await urgentMessageFeishu({
+                client,
+                messageId: p.message_id,
+                userIds: p.user_ids,
+                urgentType: p.urgent_type ?? "app",
+              });
+              return json({
+                ok: true,
+                message_id: p.message_id,
+                urgent_type: p.urgent_type ?? "app",
+                invalid_user_list: result.invalidUserList,
+              });
+            },
+          });
+        } catch (err) {
+          return errorResult(err);
+        }
+      },
+    },
+    { name: "feishu_urgent" },
+  );
+
+  api.logger.debug?.("feishu_urgent: Registered feishu_urgent tool");
+}

package/src/urgent-tools/schemas.ts

@@ -0,0 +1,25 @@
+import { Type, type Static } from "@sinclair/typebox";
+
+const URGENT_TYPE_VALUES = ["app", "sms", "phone"] as const;
+
+export const FeishuUrgentSchema = Type.Object({
+  message_id: Type.String({
+    description: "Message ID to send urgent notification for (e.g. om_xxx). The message must already be sent.",
+  }),
+  user_ids: Type.Array(Type.String(), {
+    description:
+      "List of open_id values to buzz. Recipients must be members of the chat where the message was sent.",
+    minItems: 1,
+  }),
+  urgent_type: Type.Optional(
+    Type.Unsafe<(typeof URGENT_TYPE_VALUES)[number]>({
+      type: "string",
+      enum: [...URGENT_TYPE_VALUES],
+      description:
+        "Urgency delivery method: app (in-app buzz, default), sms (SMS push), phone (voice call). Note: sms and phone may incur cost on the tenant.",
+      default: "app",
+    }),
+  ),
+});
+
+export type FeishuUrgentParams = Static<typeof FeishuUrgentSchema>;

package/src/wiki-tools/actions.ts

@@ -7,6 +7,13 @@ const WIKI_ACCESS_HINT =
   "To grant wiki access: Open wiki space -> Settings -> Members -> Add the bot. " +
   "See: https://open.feishu.cn/document/server-docs/docs/wiki-v2/wiki-qa#a40ad4ca";
 
+function requireString(value: unknown, field: string): string {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new Error(`${field} is required`);
+  }
+  return value;
+}
+
 async function listSpaces(client: WikiClient) {
   const res = await runWikiApiCall("wiki.space.list", () => client.wiki.space.list({}));
   const spaces =
@@ -140,26 +147,37 @@ export async function runWikiAction(client: WikiClient, params: FeishuWikiParams
     case "spaces":
       return listSpaces(client);
     case "nodes":
-      return listNodes(client, params.space_id, params.parent_node_token);
+      return listNodes(client, requireString(params.space_id, "space_id"), params.parent_node_token);
     case "get":
-      return getNode(client, params.token);
+      return getNode(client, requireString(params.token, "token"));
     case "search":
       return {
         error:
           "Search is not available. Use feishu_wiki with action: 'nodes' to browse or action: 'get' to lookup by token.",
       };
     case "create":
-      return createNode(client, params.space_id, params.title, params.obj_type, params.parent_node_token);
+      return createNode(
+        client,
+        requireString(params.space_id, "space_id"),
+        requireString(params.title, "title"),
+        params.obj_type,
+        params.parent_node_token,
+      );
     case "move":
       return moveNode(
         client,
-        params.space_id,
-        params.node_token,
+        requireString(params.space_id, "space_id"),
+        requireString(params.node_token, "node_token"),
         params.target_space_id,
         params.target_parent_token,
       );
     case "rename":
-      return renameNode(client, params.space_id, params.node_token, params.title);
+      return renameNode(
+        client,
+        requireString(params.space_id, "space_id"),
+        requireString(params.node_token, "node_token"),
+        requireString(params.title, "title"),
+      );
     default:
       return { error: `Unknown action: ${(params as any).action}` };
   }

package/src/wiki-tools/schemas.ts

@@ -1,55 +1,36 @@
 import { Type, type Static } from "@sinclair/typebox";
 
-export const FeishuWikiSchema = Type.Union([
-  Type.Object({
-    action: Type.Literal("spaces"),
-  }),
-  Type.Object({
-    action: Type.Literal("nodes"),
-    space_id: Type.String({ description: "Knowledge space ID" }),
-    parent_node_token: Type.Optional(
-      Type.String({ description: "Parent node token (optional, omit for root)" }),
-    ),
-  }),
-  Type.Object({
-    action: Type.Literal("get"),
-    token: Type.String({ description: "Wiki node token (from URL /wiki/XXX)" }),
-  }),
-  Type.Object({
-    action: Type.Literal("search"),
-    query: Type.String({ description: "Search query" }),
-    space_id: Type.Optional(Type.String({ description: "Limit search to this space (optional)" })),
-  }),
-  Type.Object({
-    action: Type.Literal("create"),
-    space_id: Type.String({ description: "Knowledge space ID" }),
-    title: Type.String({ description: "Node title" }),
-    obj_type: Type.Optional(
-      Type.Union([Type.Literal("docx"), Type.Literal("sheet"), Type.Literal("bitable")], {
-        description: "Object type (default: docx)",
-      }),
-    ),
-    parent_node_token: Type.Optional(
-      Type.String({ description: "Parent node token (optional, omit for root)" }),
-    ),
-  }),
-  Type.Object({
-    action: Type.Literal("move"),
-    space_id: Type.String({ description: "Source knowledge space ID" }),
-    node_token: Type.String({ description: "Node token to move" }),
-    target_space_id: Type.Optional(
-      Type.String({ description: "Target space ID (optional, same space if omitted)" }),
-    ),
-    target_parent_token: Type.Optional(
-      Type.String({ description: "Target parent node token (optional, root if omitted)" }),
-    ),
-  }),
-  Type.Object({
-    action: Type.Literal("rename"),
-    space_id: Type.String({ description: "Knowledge space ID" }),
-    node_token: Type.String({ description: "Node token to rename" }),
-    title: Type.String({ description: "New title" }),
-  }),
-]);
+function stringEnum<T extends readonly string[]>(
+  values: T,
+  options: { description?: string; default?: T[number] } = {},
+) {
+  return Type.Unsafe<T[number]>({ type: "string", enum: [...values], ...options });
+}
+
+const WIKI_ACTION_VALUES = ["spaces", "nodes", "get", "search", "create", "move", "rename"] as const;
+const WIKI_OBJ_TYPE_VALUES = ["docx", "sheet", "bitable"] as const;
+
+export const FeishuWikiSchema = Type.Object({
+  action: stringEnum(WIKI_ACTION_VALUES, { description: "Wiki action" }),
+  space_id: Type.Optional(Type.String({ description: "Knowledge space ID" })),
+  parent_node_token: Type.Optional(
+    Type.String({ description: "Parent node token (optional, omit for root)" }),
+  ),
+  token: Type.Optional(Type.String({ description: "Wiki node token (from URL /wiki/XXX)" })),
+  query: Type.Optional(Type.String({ description: "Search query" })),
+  title: Type.Optional(Type.String({ description: "Node title / new title" })),
+  obj_type: Type.Optional(
+    stringEnum(WIKI_OBJ_TYPE_VALUES, {
+      description: "Object type for create action (default: docx)",
+    }),
+  ),
+  node_token: Type.Optional(Type.String({ description: "Node token" })),
+  target_space_id: Type.Optional(
+    Type.String({ description: "Target space ID (optional, same space if omitted)" }),
+  ),
+  target_parent_token: Type.Optional(
+    Type.String({ description: "Target parent node token (optional, root if omitted)" }),
+  ),
+});
 
 export type FeishuWikiParams = Static<typeof FeishuWikiSchema>;