@m1heng-clawd/feishu 0.1.13 → 0.1.15

package/src/tools-config.ts

@@ -2,7 +2,7 @@ import type { FeishuToolsConfig } from "./types.js";
 
 /**
  * Default tool configuration.
- * - doc, wiki, drive, scopes, task: enabled by default
+ * - doc, wiki, drive, scopes, task, chat: enabled by default
  * - perm: disabled by default (sensitive operation)
  */
 export const DEFAULT_TOOLS_CONFIG: Required<FeishuToolsConfig> = {
@@ -12,11 +12,18 @@ export const DEFAULT_TOOLS_CONFIG: Required<FeishuToolsConfig> = {
   perm: false,
   scopes: true,
   task: true,
+  chat: true,
+  urgent: true,
 };
 
 /**
  * Resolve tools config with defaults.
+ * Only includes keys that are present in the input config or defaults.
  */
 export function resolveToolsConfig(cfg?: FeishuToolsConfig): Required<FeishuToolsConfig> {
-  return { ...DEFAULT_TOOLS_CONFIG, ...cfg };
+  const res = {} as Required<FeishuToolsConfig>;
+  for (const key in DEFAULT_TOOLS_CONFIG) {
+    res[key] = cfg?.[key] ?? DEFAULT_TOOLS_CONFIG[key];
+  }
+  return res;
 }

package/src/types.ts

@@ -30,13 +30,17 @@ export type FeishuMessageContext = {
   senderId: string;
   senderOpenId: string;
   senderName?: string;
-  chatType: "p2p" | "group";
+  chatType: "p2p" | "group" | "private";
   mentionedBot: boolean;
   hasAnyMention?: boolean;
   rootId?: string;
   parentId?: string;
   content: string;
   contentType: string;
+  /** Media placeholder token (e.g. <media:audio>) when inbound message is media. */
+  placeholder?: string;
+  /** Raw provider payload string (original event.message.content). */
+  rawPayload?: string;
   /** Mention forward targets (excluding the bot itself) */
   mentionTargets?: MentionTarget[];
   /** Extracted message body (after removing @ placeholders) */
@@ -69,6 +73,9 @@ export type FeishuToolsConfig = {
   perm?: boolean;
   scopes?: boolean;
   task?: boolean;
+  chat?: boolean;
+  /** Enable the feishu_urgent tool (buzz/urgent notifications). Enabled by default. */
+  urgent?: boolean;
 };
 
 export type DynamicAgentCreationConfig = {

package/src/typing.ts

@@ -7,13 +7,94 @@ import { resolveFeishuAccount } from "./accounts.js";
 // Full list: https://github.com/go-lark/lark/blob/main/emoji.go
 const TYPING_EMOJI = "Typing"; // Typing indicator emoji
 
+/**
+ * Feishu API error codes that indicate the caller should back off.
+ * These must propagate to the typing circuit breaker so the keepalive loop
+ * can trip and stop retrying.
+ *
+ * - 99991400: Rate limit (too many requests per second)
+ * - 99991403: Monthly API call quota exceeded
+ * - 429: Standard HTTP 429 returned as a Feishu SDK error code
+ *
+ * @see https://open.feishu.cn/document/server-docs/api-call-guide/generic-error-code
+ */
+const FEISHU_BACKOFF_CODES = new Set([99991400, 99991403, 429]);
+
+/**
+ * Custom error class for Feishu backoff conditions detected from non-throwing
+ * SDK responses. Carries a numeric `.code` so that `isFeishuBackoffError()`
+ * recognises it when the error is caught downstream.
+ */
+export class FeishuBackoffError extends Error {
+  code: number;
+  constructor(code: number) {
+    super(`Feishu API backoff: code ${code}`);
+    this.name = "FeishuBackoffError";
+    this.code = code;
+  }
+}
+
+/**
+ * Check whether an error represents a rate-limit or quota-exceeded condition
+ * from the Feishu API that should stop the typing keepalive loop.
+ *
+ * Handles two shapes:
+ * 1. AxiosError with `response.status` and `response.data.code`
+ * 2. Feishu SDK error with a top-level `code` property
+ */
+export function isFeishuBackoffError(err: unknown): boolean {
+  if (typeof err !== "object" || err === null) {
+    return false;
+  }
+
+  // AxiosError shape: err.response.status / err.response.data.code
+  const response = (err as { response?: { status?: number; data?: { code?: number } } }).response;
+  if (response) {
+    if (response.status === 429) {
+      return true;
+    }
+    if (typeof response.data?.code === "number" && FEISHU_BACKOFF_CODES.has(response.data.code)) {
+      return true;
+    }
+  }
+
+  // Feishu SDK error shape: err.code
+  const code = (err as { code?: number }).code;
+  if (typeof code === "number" && FEISHU_BACKOFF_CODES.has(code)) {
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Check whether a Feishu SDK response object contains a backoff error code.
+ *
+ * The Feishu SDK sometimes returns a normal response (no throw) with an
+ * API-level error code in the response body. This must be detected so the
+ * circuit breaker can trip.
+ */
+export function getBackoffCodeFromResponse(response: unknown): number | undefined {
+  if (typeof response !== "object" || response === null) {
+    return undefined;
+  }
+  const code = (response as { code?: number }).code;
+  if (typeof code === "number" && FEISHU_BACKOFF_CODES.has(code)) {
+    return code;
+  }
+  return undefined;
+}
+
 export type TypingIndicatorState = {
   messageId: string;
   reactionId: string | null;
 };
 
 /**
- * Add a typing indicator (reaction) to a message
+ * Add a typing indicator (reaction) to a message.
+ *
+ * Rate-limit and quota errors are re-thrown so the circuit breaker in
+ * `createTypingCallbacks` can trip and stop the keepalive loop.
  */
 export async function addTypingIndicator(params: {
   cfg: ClawdbotConfig;
@@ -36,17 +117,33 @@ export async function addTypingIndicator(params: {
       },
     });
 
+    // Feishu SDK may return a normal response with an API-level error code
+    // instead of throwing. Detect backoff codes and throw to trip the breaker.
+    const backoffCode = getBackoffCodeFromResponse(response);
+    if (backoffCode !== undefined) {
+      console.log(
+        `[feishu] typing indicator response contains backoff code ${backoffCode}, stopping keepalive`,
+      );
+      throw new FeishuBackoffError(backoffCode);
+    }
+
     const reactionId = (response as any)?.data?.reaction_id ?? null;
     return { messageId, reactionId };
   } catch (err) {
-    // Silently fail - typing indicator is not critical
+    if (isFeishuBackoffError(err)) {
+      console.log(`[feishu] typing indicator hit rate-limit/quota, stopping keepalive`);
+      throw err;
+    }
+    // Silently fail for other non-critical errors (e.g. message deleted, permission issues)
     console.log(`[feishu] failed to add typing indicator: ${err}`);
     return { messageId, reactionId: null };
   }
 }
 
 /**
- * Remove a typing indicator (reaction) from a message
+ * Remove a typing indicator (reaction) from a message.
+ *
+ * Rate-limit and quota errors are re-thrown for the same reason as above.
  */
 export async function removeTypingIndicator(params: {
   cfg: ClawdbotConfig;
@@ -62,14 +159,27 @@ export async function removeTypingIndicator(params: {
   const client = createFeishuClient(account);
 
   try {
-    await client.im.messageReaction.delete({
+    const result = await client.im.messageReaction.delete({
       path: {
         message_id: state.messageId,
         reaction_id: state.reactionId,
       },
     });
+
+    // Check for backoff codes in non-throwing SDK responses
+    const backoffCode = getBackoffCodeFromResponse(result);
+    if (backoffCode !== undefined) {
+      console.log(
+        `[feishu] typing indicator removal response contains backoff code ${backoffCode}, stopping keepalive`,
+      );
+      throw new FeishuBackoffError(backoffCode);
+    }
   } catch (err) {
-    // Silently fail - cleanup is not critical
+    if (isFeishuBackoffError(err)) {
+      console.log(`[feishu] typing indicator removal hit rate-limit/quota, stopping keepalive`);
+      throw err;
+    }
+    // Silently fail for other non-critical errors
     console.log(`[feishu] failed to remove typing indicator: ${err}`);
   }
 }

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>;