@soimy/dingtalk 3.1.3 → 3.2.0

package/src/channel.ts

@@ -1,7 +1,10 @@
 import { randomUUID } from "node:crypto";
 import { DWClient, TOPIC_ROBOT } from "dingtalk-stream";
-import type { OpenClawConfig } from "openclaw/plugin-sdk";
-import { buildChannelConfigSchema } from "openclaw/plugin-sdk";
+import type {
+  ChannelMessageActionAdapter,
+  OpenClawConfig,
+} from "openclaw/plugin-sdk";
+import * as pluginSdk from "openclaw/plugin-sdk";
 import { getAccessToken } from "./auth";
 import { createAICard, streamAICard, finishAICard } from "./card-service";
 import { getConfig, isConfigured, resolveRelativePath, stripTargetPrefix } from "./config";
@@ -10,15 +13,10 @@ import { ConnectionManager } from "./connection-manager";
 import { isMessageProcessed, markMessageProcessed } from "./dedup";
 import { handleDingTalkMessage } from "./inbound-handler";
 import { getLogger } from "./logger-context";
+import { prepareMediaInput, resolveOutboundMediaType } from "./media-utils";
 import { dingtalkOnboardingAdapter } from "./onboarding.js";
 import { resolveOriginalPeerId } from "./peer-id-registry";
-import {
-  detectMediaTypeFromExtension,
-  sendMessage,
-  sendProactiveMedia,
-  sendBySession,
-  uploadMedia,
-} from "./send-service";
+import { sendMessage, sendProactiveMedia, sendBySession, uploadMedia } from "./send-service";
 import type {
   DingTalkInboundMessage,
   GatewayStartContext,
@@ -30,7 +28,8 @@ import type {
 import { ConnectionState } from "./types";
 import { cleanupOrphanedTempFiles, formatDingTalkErrorPayloadLog, getCurrentTimestamp } from "./utils";
 
-const processingDedupKeys = new Set<string>();
+const INFLIGHT_TTL_MS = 5 * 60 * 1000; // 5 min safety net for hung handlers
+const processingDedupKeys = new Map<string, number>(); // key → timestamp when acquired
 const inboundCountersByAccount = new Map<
   string,
   {
@@ -70,6 +69,132 @@ function logInboundCounters(log: any, accountId: string, reason: string): void {
   );
 }
 
+function readBooleanLikeParam(params: Record<string, unknown>, key: string): boolean | undefined {
+  const value = params[key];
+  if (typeof value === "boolean") {
+    return value;
+  }
+  if (typeof value === "number") {
+    if (value === 1) {
+      return true;
+    }
+    if (value === 0) {
+      return false;
+    }
+    return undefined;
+  }
+  if (typeof value === "string") {
+    const normalized = value.trim().toLowerCase();
+    if (["1", "true", "yes", "y", "on"].includes(normalized)) {
+      return true;
+    }
+    if (["0", "false", "no", "n", "off"].includes(normalized)) {
+      return false;
+    }
+  }
+  return undefined;
+}
+
+const dingtalkMessageActions: ChannelMessageActionAdapter = {
+  listActions: () => ["send"],
+  supportsAction: ({ action }) => action === "send",
+  extractToolSend: ({ args }) => pluginSdk.extractToolSend(args, "sendMessage"),
+  handleAction: async ({ action, params, cfg, accountId, dryRun }) => {
+    if (action !== "send") {
+      throw new Error(`Action ${action} is not supported for provider dingtalk.`);
+    }
+
+    const to = pluginSdk.readStringParam(params, "to", { required: true });
+    const mediaInput =
+      pluginSdk.readStringParam(params, "media", { trim: false }) ??
+      pluginSdk.readStringParam(params, "path", { trim: false }) ??
+      pluginSdk.readStringParam(params, "filePath", { trim: false }) ??
+      pluginSdk.readStringParam(params, "mediaUrl", { trim: false });
+
+    const hasMedia = Boolean(mediaInput && mediaInput.trim());
+    const caption = pluginSdk.readStringParam(params, "caption", { allowEmpty: true }) ?? "";
+    let message =
+      pluginSdk.readStringParam(params, "message", {
+        required: !hasMedia,
+        allowEmpty: true,
+      }) ?? "";
+
+    if (!message.trim() && caption.trim()) {
+      message = caption;
+    }
+
+    const asVoice = readBooleanLikeParam(params, "asVoice") === true;
+    const requestedMediaType = pluginSdk.readStringParam(params, "mediaType");
+
+    const target = resolveOriginalPeerId(stripTargetPrefix(to).targetId);
+
+    if (dryRun) {
+      return pluginSdk.jsonResult({
+        ok: true,
+        dryRun: true,
+        to: target,
+        hasMedia,
+        asVoice,
+      });
+    }
+
+    const log = getLogger();
+    const config = getConfig(cfg, accountId ?? undefined);
+
+    if (hasMedia && mediaInput) {
+      const mediaPath = resolveRelativePath(mediaInput);
+      const mediaType = resolveOutboundMediaType({
+        mediaType: requestedMediaType ?? undefined,
+        mediaPath,
+        asVoice,
+      });
+      const result = await sendProactiveMedia(config, target, mediaPath, mediaType, {
+        log,
+        accountId: accountId ?? undefined,
+      });
+
+      if (!result.ok) {
+        throw new Error(result.error || "send media failed");
+      }
+
+      return pluginSdk.jsonResult({
+        ok: true,
+        to: target,
+        mediaType,
+        messageId: result.messageId ?? null,
+        result: result.data ?? null,
+      });
+    }
+
+    if (asVoice) {
+      throw new Error(
+        "DingTalk send with asVoice requires media/path/filePath/mediaUrl pointing to an audio file.",
+      );
+    }
+
+    if (!message.trim()) {
+      throw new Error("send requires message when media is not provided");
+    }
+
+    const result = await sendMessage(config, target, message, {
+      log,
+      accountId: accountId ?? undefined,
+    });
+
+    if (!result.ok) {
+      throw new Error(result.error || "send message failed");
+    }
+
+    const data = result.data as any;
+    return pluginSdk.jsonResult({
+      ok: true,
+      to: target,
+      messageId: data?.processQueryKey || data?.messageId || null,
+      result: data ?? null,
+    });
+  },
+};
+
 // DingTalk Channel Definition (assembly layer).
 // Heavy logic is delegated to service modules for maintainability.
 export const dingtalkPlugin: DingTalkChannelPlugin = {
@@ -82,7 +207,7 @@ export const dingtalkPlugin: DingTalkChannelPlugin = {
     blurb: "钉钉企业内部机器人，使用 Stream 模式，无需公网 IP。",
     aliases: ["dd", "ding"],
   },
-  configSchema: buildChannelConfigSchema(DingTalkConfigSchema),
+  configSchema: pluginSdk.buildChannelConfigSchema(DingTalkConfigSchema),
   onboarding: dingtalkOnboardingAdapter,
   capabilities: {
     chatTypes: ["direct", "group"] as Array<"direct" | "group">,
@@ -153,6 +278,7 @@ export const dingtalkPlugin: DingTalkChannelPlugin = {
       hint: "<conversationId>",
     },
   },
+  actions: dingtalkMessageActions,
   outbound: {
     deliveryMode: "direct" as const,
     resolveTarget: ({ to }: any) => {
@@ -172,20 +298,18 @@ export const dingtalkPlugin: DingTalkChannelPlugin = {
       try {
         const result = await sendMessage(config, to, text, { log, accountId });
         getLogger()?.debug?.(`[DingTalk] sendText: "${text}" result: ${JSON.stringify(result)}`);
-        if (result.ok) {
-          const data = result.data as any;
-          const messageId = String(data?.processQueryKey || data?.messageId || randomUUID());
-          return {
-            channel: "dingtalk",
-            messageId,
-            meta: result.data
-              ? { data: result.data as unknown as Record<string, unknown> }
-              : undefined,
-          };
+        if (!result.ok) {
+          throw new Error(result.error || "sendText failed");
         }
-        throw new Error(
-          typeof result.error === "string" ? result.error : JSON.stringify(result.error),
-        );
+        const data = result.data as any;
+        const messageId = String(data?.processQueryKey || data?.messageId || randomUUID());
+        return {
+          channel: "dingtalk",
+          messageId,
+          meta: result.data
+            ? { data: result.data as unknown as Record<string, unknown> }
+            : undefined,
+        };
       } catch (err: any) {
         if (err?.response?.data !== undefined) {
           log?.error?.(formatDingTalkErrorPayloadLog("outbound.sendText", err.response.data));
@@ -205,6 +329,7 @@ export const dingtalkPlugin: DingTalkChannelPlugin = {
       filePath,
       mediaUrl,
       mediaType: providedMediaType,
+      asVoice,
       accountId,
       log,
     }: any) => {
@@ -231,18 +356,47 @@ export const dingtalkPlugin: DingTalkChannelPlugin = {
         );
       }
 
-      const actualMediaPath = resolveRelativePath(rawMediaPath);
+      let preparedMedia;
+      try {
+        try {
+          preparedMedia = await prepareMediaInput(rawMediaPath, log, config.mediaUrlAllowlist);
+        } catch (err: any) {
+          if (err?.response?.data !== undefined) {
+            log?.error?.(formatDingTalkErrorPayloadLog("outbound.sendMedia.prepare", err.response.data));
+          }
+          const errorCode = typeof err?.code === "string" ? `[${err.code}] ` : "";
+          throw new Error(`remote media preparation failed: ${errorCode}${err?.message || "unknown error"}`, {
+            cause: err,
+          });
+        }
 
-      getLogger()?.debug?.(
-        `[DingTalk] sendMedia resolved path: rawMediaPath=${rawMediaPath}, actualMediaPath=${actualMediaPath}`,
-      );
+        const actualMediaPath = preparedMedia.cleanup
+          ? preparedMedia.path
+          : resolveRelativePath(preparedMedia.path);
 
-      try {
-        const mediaType = providedMediaType || detectMediaTypeFromExtension(actualMediaPath);
-        const result = await sendProactiveMedia(config, to, actualMediaPath, mediaType, {
-          log,
-          accountId,
+        getLogger()?.debug?.(
+          `[DingTalk] sendMedia resolved path: rawMediaPath=${rawMediaPath}, actualMediaPath=${actualMediaPath}`,
+        );
+
+        const mediaType = resolveOutboundMediaType({
+          mediaType: typeof providedMediaType === "string" ? providedMediaType : undefined,
+          mediaPath: actualMediaPath,
+          asVoice: asVoice === true,
         });
+        let result;
+        try {
+          result = await sendProactiveMedia(config, to, actualMediaPath, mediaType, {
+            log,
+            accountId,
+          });
+        } catch (err: any) {
+          if (err?.response?.data !== undefined) {
+            log?.error?.(formatDingTalkErrorPayloadLog("outbound.sendMedia.send", err.response.data));
+          }
+          throw new Error(`proactive media send failed: ${err?.message || "unknown error"}`, {
+            cause: err,
+          });
+        }
         getLogger()?.debug?.(
           `[DingTalk] sendMedia: ${mediaType} file=${actualMediaPath} result: ${JSON.stringify(result)}`,
         );
@@ -273,6 +427,8 @@ export const dingtalkPlugin: DingTalkChannelPlugin = {
             : err?.message || "sendMedia failed",
           { cause: err },
         );
+      } finally {
+        await preparedMedia?.cleanup?.();
       }
     },
   },
@@ -288,25 +444,35 @@ export const dingtalkPlugin: DingTalkChannelPlugin = {
 
       cleanupOrphanedTempFiles(ctx.log);
 
+      const useConnectionManager = config.useConnectionManager ?? true;
+
       const client = new DWClient({
         clientId: config.clientId,
         clientSecret: config.clientSecret,
         debug: config.debug || false,
-        keepAlive: true,
+        keepAlive: !useConnectionManager,
       });
 
-      // Disable built-in reconnect so ConnectionManager owns all retry/backoff behavior.
-      (client as any).config.autoReconnect = false;
+      (client as any).config.autoReconnect = !useConnectionManager;
 
       client.registerCallbackListener(TOPIC_ROBOT, async (res: any) => {
         const messageId = res.headers?.messageId;
         const stats = getInboundCounters(account.accountId);
         stats.received += 1;
-        try {
-          if (messageId) {
+        const acknowledge = () => {
+          if (!messageId) {
+            return;
+          }
+          try {
             client.socketCallBackResponse(messageId, { success: true });
             stats.acked += 1;
+          } catch (ackError: any) {
+            ctx.log?.warn?.(
+              `[${account.accountId}] Failed to acknowledge callback ${messageId}: ${ackError.message}`,
+            );
           }
+        };
+        try {
           const data = JSON.parse(res.data) as DingTalkInboundMessage;
 
           // Message deduplication key is bot-scoped to avoid cross-account conflicts.
@@ -326,6 +492,7 @@ export const dingtalkPlugin: DingTalkChannelPlugin = {
               dingtalkConfig: config,
             });
             stats.processed += 1;
+            acknowledge();
             if (stats.received % INBOUND_COUNTER_LOG_EVERY === 0) {
               logInboundCounters(ctx.log, account.accountId, "periodic");
             }
@@ -335,20 +502,31 @@ export const dingtalkPlugin: DingTalkChannelPlugin = {
           if (isMessageProcessed(dedupKey)) {
             ctx.log?.debug?.(`[${account.accountId}] Skipping duplicate message: ${dedupKey}`);
             stats.dedupSkipped += 1;
+            acknowledge();
             logInboundCounters(ctx.log, account.accountId, "dedup-skipped");
             return;
           }
 
-          if (processingDedupKeys.has(dedupKey)) {
-            ctx.log?.debug?.(
-              `[${account.accountId}] Skipping in-flight duplicate message: ${dedupKey}`,
-            );
-            stats.inflightSkipped += 1;
-            logInboundCounters(ctx.log, account.accountId, "inflight-skipped");
-            return;
+          const inflightSince = processingDedupKeys.get(dedupKey);
+          if (inflightSince !== undefined) {
+            if (Date.now() - inflightSince > INFLIGHT_TTL_MS) {
+              ctx.log?.warn?.(
+                `[${account.accountId}] Releasing stale in-flight lock for ${dedupKey} (held ${Date.now() - inflightSince}ms > TTL ${INFLIGHT_TTL_MS}ms)`,
+              );
+              processingDedupKeys.delete(dedupKey);
+            } else {
+              ctx.log?.debug?.(
+                `[${account.accountId}] Skipping in-flight duplicate message: ${dedupKey}`,
+              );
+              stats.inflightSkipped += 1;
+              // Do not acknowledge in-flight duplicates before the original handler succeeds.
+              // If the original later fails, early-acking the duplicate can suppress server redelivery.
+              logInboundCounters(ctx.log, account.accountId, "inflight-skipped");
+              return;
+            }
           }
 
-          processingDedupKeys.add(dedupKey);
+          processingDedupKeys.set(dedupKey, Date.now());
           try {
             await handleDingTalkMessage({
               cfg,
@@ -360,6 +538,7 @@ export const dingtalkPlugin: DingTalkChannelPlugin = {
             });
             stats.processed += 1;
             markMessageProcessed(dedupKey);
+            acknowledge();
             if (stats.received % INBOUND_COUNTER_LOG_EVERY === 0) {
               logInboundCounters(ctx.log, account.accountId, "periodic");
             }
@@ -375,6 +554,94 @@ export const dingtalkPlugin: DingTalkChannelPlugin = {
 
       // Guard against duplicate stop paths (abort signal + explicit stop).
       let stopped = false;
+      let nativeStopResolve: (() => void) | undefined;
+      const nativeStopPromise = new Promise<void>((resolve) => {
+        nativeStopResolve = resolve;
+      });
+      let connectionManager: ConnectionManager | undefined;
+
+      const stopClient = () => {
+        if (stopped) {
+          return;
+        }
+        stopped = true;
+        ctx.log?.info?.(`[${account.accountId}] Stopping DingTalk Stream client...`);
+        if (useConnectionManager) {
+          connectionManager?.stop();
+        } else {
+          try {
+            client.disconnect();
+          } catch (err: any) {
+            ctx.log?.warn?.(`[${account.accountId}] Error during disconnect: ${err.message}`);
+          }
+          nativeStopResolve?.();
+        }
+
+        ctx.setStatus({
+          ...ctx.getStatus(),
+          running: false,
+          lastStopAt: getCurrentTimestamp(),
+        });
+
+        ctx.log?.info?.(`[${account.accountId}] DingTalk Stream client stopped`);
+      };
+
+      if (abortSignal) {
+        if (abortSignal.aborted) {
+          ctx.log?.warn?.(
+            `[${account.accountId}] Abort signal already active, skipping connection`,
+          );
+
+          ctx.setStatus({
+            ...ctx.getStatus(),
+            running: false,
+            lastStopAt: getCurrentTimestamp(),
+            lastError: "Connection aborted before start",
+          });
+
+          throw new Error("Connection aborted before start");
+        }
+
+        abortSignal.addEventListener("abort", () => {
+          if (stopped) {
+            return;
+          }
+          ctx.log?.info?.(
+            `[${account.accountId}] Abort signal received, stopping DingTalk Stream client...`,
+          );
+          stopClient();
+        });
+      }
+
+      if (!useConnectionManager) {
+        try {
+          await client.connect();
+          if (!stopped) {
+            ctx.setStatus({
+              ...ctx.getStatus(),
+              running: true,
+              lastStartAt: getCurrentTimestamp(),
+              lastError: null,
+            });
+            ctx.log?.info?.(`[${account.accountId}] DingTalk Stream client connected successfully`);
+            await nativeStopPromise;
+          }
+        } catch (err: any) {
+          ctx.log?.error?.(`[${account.accountId}] Failed to establish connection: ${err.message}`);
+          ctx.setStatus({
+            ...ctx.getStatus(),
+            running: false,
+            lastError: err.message || "Connection failed",
+          });
+          throw err;
+        }
+
+        return {
+          stop: () => {
+            stopClient();
+          },
+        };
+      }
 
       const connectionConfig: ConnectionManagerConfig = {
         maxAttempts: config.maxConnectionAttempts ?? 10,
@@ -397,6 +664,22 @@ export const dingtalkPlugin: DingTalkChannelPlugin = {
               lastError: null,
             });
           } else if (state === ConnectionState.FAILED || state === ConnectionState.DISCONNECTED) {
+            // Clear stale in-flight locks for this account on disconnect.
+            // DingTalk will redeliver unacknowledged messages on reconnect; without
+            // this cleanup the redelivered messages would be silently skipped forever.
+            const robotKey = config.robotCode || config.clientId || account.accountId;
+            let cleared = 0;
+            for (const key of processingDedupKeys.keys()) {
+              if (key.startsWith(`${robotKey}:`)) {
+                processingDedupKeys.delete(key);
+                cleared++;
+              }
+            }
+            if (cleared > 0) {
+              ctx.log?.info?.(
+                `[${account.accountId}] Cleared ${cleared} stale in-flight lock(s) on disconnect`,
+              );
+            }
             ctx.setStatus({
               ...ctx.getStatus(),
               running: false,
@@ -412,48 +695,13 @@ export const dingtalkPlugin: DingTalkChannelPlugin = {
           `jitter=${connectionConfig.jitter}`,
       );
 
-      const connectionManager = new ConnectionManager(
+      connectionManager = new ConnectionManager(
         client,
         account.accountId,
         connectionConfig,
         ctx.log,
       );
 
-      // Register abort listener before connect() so startup can be cancelled safely.
-      if (abortSignal) {
-        if (abortSignal.aborted) {
-          ctx.log?.warn?.(
-            `[${account.accountId}] Abort signal already active, skipping connection`,
-          );
-
-          ctx.setStatus({
-            ...ctx.getStatus(),
-            running: false,
-            lastStopAt: getCurrentTimestamp(),
-            lastError: "Connection aborted before start",
-          });
-
-          throw new Error("Connection aborted before start");
-        }
-
-        abortSignal.addEventListener("abort", () => {
-          if (stopped) {
-            return;
-          }
-          stopped = true;
-          ctx.log?.info?.(
-            `[${account.accountId}] Abort signal received, stopping DingTalk Stream client...`,
-          );
-          connectionManager.stop();
-
-          ctx.setStatus({
-            ...ctx.getStatus(),
-            running: false,
-            lastStopAt: getCurrentTimestamp(),
-          });
-        });
-      }
-
       try {
         await connectionManager.connect();
 
@@ -486,20 +734,7 @@ export const dingtalkPlugin: DingTalkChannelPlugin = {
 
       return {
         stop: () => {
-          if (stopped) {
-            return;
-          }
-          stopped = true;
-          ctx.log?.info?.(`[${account.accountId}] Stopping DingTalk Stream client...`);
-          connectionManager.stop();
-
-          ctx.setStatus({
-            ...ctx.getStatus(),
-            running: false,
-            lastStopAt: getCurrentTimestamp(),
-          });
-
-          ctx.log?.info?.(`[${account.accountId}] DingTalk Stream client stopped`);
+          stopClient();
         },
       };
     },

package/src/config-schema.ts

@@ -31,6 +31,8 @@ const DingTalkAccountConfigSchema = z.object({
   /** List of allowed user IDs for allowlist policy */
   allowFrom: z.array(z.string()).optional(),
 
+  mediaUrlAllowlist: z.array(z.string()).optional(),
+
   /** Show thinking indicator while processing */
   showThinking: z.boolean().optional().default(true),
 
@@ -47,7 +49,7 @@ const DingTalkAccountConfigSchema = z.object({
   cardTemplateId: z.string().optional(),
 
   /** Card template key for streaming updates
-   * Default: 'msgContent' - maps to the content field in the card template
+   * Default: 'content' - maps to the content field in the card template
    * This key is used in the streaming API to update specific fields in the card.
    */
   cardTemplateKey: z.string().optional().default("content"),
@@ -79,6 +81,12 @@ const DingTalkAccountConfigSchema = z.object({
   /** Maximum number of runtime reconnect cycles before giving up (default: 10) */
   maxReconnectCycles: z.number().int().min(1).optional().default(10),
 
+  /** Whether to use ConnectionManager (default: true). When false, rely on DWClient native keepAlive+autoReconnect. */
+  useConnectionManager: z.boolean().optional().default(true),
+
+  /** Maximum inbound media file size in MB (overrides runtime default when set) */
+  mediaMaxMb: z.number().int().min(1).optional(),
+
   proactivePermissionHint: z
     .object({
       enabled: z.boolean().optional().default(true),

package/src/connection-manager.ts

@@ -129,7 +129,20 @@ export class ConnectionManager {
     );
 
     try {
-      // Call DWClient connect method
+      // Ensure previous connection resources (heartbeat timers, old sockets) are
+      // fully cleaned up before establishing a new connection.  The DWClient
+      // _connect() method does not clear its internal heartbeat interval, so a
+      // stale timer from a prior session can terminate the newly created socket
+      // before it finishes the handshake (manifests as code-1006 / "WebSocket was
+      // closed before the connection was established").
+      try {
+        this.client.disconnect();
+      } catch (disconnectErr: any) {
+        this.log?.debug?.(
+          `[${this.accountId}] pre-connect cleanup disconnect failed: ${disconnectErr.message}`,
+        );
+      }
+
       await this.client.connect();
 
       // Re-check stopped flag after async connect() completes