@soimy/dingtalk 2.7.0 → 3.0.0

package/src/send-service.ts

@@ -0,0 +1,281 @@
+import * as path from "node:path";
+import axios from "axios";
+import { getAccessToken } from "./auth";
+import {
+  deleteActiveCardByTarget,
+  getActiveCardIdByTarget,
+  getCardById,
+  isCardInTerminalState,
+  streamAICard,
+} from "./card-service";
+import { stripTargetPrefix } from "./config";
+import { getLogger } from "./logger-context";
+import { uploadMedia as uploadMediaUtil } from "./media-utils";
+import { detectMarkdownAndExtractTitle } from "./message-utils";
+import { resolveOriginalPeerId } from "./peer-id-registry";
+import type {
+  AxiosResponse,
+  DingTalkConfig,
+  Logger,
+  ProactiveMessagePayload,
+  SendMessageOptions,
+  SessionWebhookResponse,
+} from "./types";
+import { AICardStatus } from "./types";
+
+export { detectMediaTypeFromExtension } from "./media-utils";
+
+/**
+ * Wrapper to upload media with shared getAccessToken binding.
+ */
+export async function uploadMedia(
+  config: DingTalkConfig,
+  mediaPath: string,
+  mediaType: "image" | "voice" | "video" | "file",
+  log?: Logger,
+): Promise<string | null> {
+  return uploadMediaUtil(config, mediaPath, mediaType, getAccessToken, log);
+}
+
+export async function sendProactiveTextOrMarkdown(
+  config: DingTalkConfig,
+  target: string,
+  text: string,
+  options: SendMessageOptions = {},
+): Promise<AxiosResponse> {
+  const token = await getAccessToken(config, options.log);
+  const log = options.log || getLogger();
+
+  // Support group:/user: prefix and restore original case-sensitive conversationId.
+  const { targetId, isExplicitUser } = stripTargetPrefix(target);
+  const resolvedTarget = resolveOriginalPeerId(targetId);
+  const isGroup = !isExplicitUser && resolvedTarget.startsWith("cid");
+
+  const url = isGroup
+    ? "https://api.dingtalk.com/v1.0/robot/groupMessages/send"
+    : "https://api.dingtalk.com/v1.0/robot/oToMessages/batchSend";
+
+  const { useMarkdown, title } = detectMarkdownAndExtractTitle(text, options, "OpenClaw 提醒");
+
+  log?.debug?.(
+    `[DingTalk] Sending proactive message to ${isGroup ? "group" : "user"} ${resolvedTarget} with title "${title}"`,
+  );
+
+  // DingTalk proactive API uses message templates (sampleMarkdown / sampleText).
+  const msgKey = useMarkdown ? "sampleMarkdown" : "sampleText";
+  const msgParam = useMarkdown
+    ? JSON.stringify({ title, text })
+    : JSON.stringify({ content: text });
+
+  const payload: ProactiveMessagePayload = {
+    robotCode: config.robotCode || config.clientId,
+    msgKey,
+    msgParam,
+  };
+
+  if (isGroup) {
+    payload.openConversationId = resolvedTarget;
+  } else {
+    payload.userIds = [resolvedTarget];
+  }
+
+  const result = await axios({
+    url,
+    method: "POST",
+    data: payload,
+    headers: { "x-acs-dingtalk-access-token": token, "Content-Type": "application/json" },
+  });
+  return result.data;
+}
+
+export async function sendProactiveMedia(
+  config: DingTalkConfig,
+  target: string,
+  mediaPath: string,
+  mediaType: "image" | "voice" | "video" | "file",
+  options: SendMessageOptions & { accountId?: string } = {},
+): Promise<{ ok: boolean; error?: string; data?: any; messageId?: string }> {
+  const log = options.log || getLogger();
+
+  try {
+    // Upload first, then send by media_id.
+    const mediaId = await uploadMedia(config, mediaPath, mediaType, log);
+    if (!mediaId) {
+      return { ok: false, error: "Failed to upload media" };
+    }
+
+    const token = await getAccessToken(config, log);
+    const { targetId, isExplicitUser } = stripTargetPrefix(target);
+    const resolvedTarget = resolveOriginalPeerId(targetId);
+    const isGroup = !isExplicitUser && resolvedTarget.startsWith("cid");
+
+    const dingtalkApi = "https://api.dingtalk.com";
+    const url = isGroup
+      ? `${dingtalkApi}/v1.0/robot/groupMessages/send`
+      : `${dingtalkApi}/v1.0/robot/oToMessages/batchSend`;
+
+    // Build DingTalk template payload by media type.
+    let msgKey: string;
+    let msgParam: string;
+
+    if (mediaType === "image") {
+      msgKey = "sampleImageMsg";
+      msgParam = JSON.stringify({ photoURL: mediaId });
+    } else if (mediaType === "voice") {
+      msgKey = "sampleAudio";
+      msgParam = JSON.stringify({ mediaId, duration: "0" });
+    } else {
+      // sampleVideo requires picMediaId; fallback to sampleFile for broader compatibility.
+      const filename = path.basename(mediaPath);
+      const defaultExt = mediaType === "video" ? "mp4" : "file";
+      const ext = path.extname(mediaPath).slice(1) || defaultExt;
+      msgKey = "sampleFile";
+      msgParam = JSON.stringify({ mediaId, fileName: filename, fileType: ext });
+    }
+
+    const payload: ProactiveMessagePayload = {
+      robotCode: config.robotCode || config.clientId,
+      msgKey,
+      msgParam,
+    };
+
+    if (isGroup) {
+      payload.openConversationId = resolvedTarget;
+    } else {
+      payload.userIds = [resolvedTarget];
+    }
+
+    log?.debug?.(
+      `[DingTalk] Sending proactive ${mediaType} message to ${isGroup ? "group" : "user"} ${resolvedTarget}`,
+    );
+
+    const result = await axios({
+      url,
+      method: "POST",
+      data: payload,
+      headers: { "x-acs-dingtalk-access-token": token, "Content-Type": "application/json" },
+    });
+
+    const messageId = result.data?.processQueryKey || result.data?.messageId;
+    return { ok: true, data: result.data, messageId };
+  } catch (err: any) {
+    log?.error?.(`[DingTalk] Failed to send proactive media: ${err.message}`);
+    if (axios.isAxiosError(err) && err.response) {
+      log?.error?.(`[DingTalk] Response: ${JSON.stringify(err.response.data)}`);
+    }
+    return { ok: false, error: err.message };
+  }
+}
+
+export async function sendBySession(
+  config: DingTalkConfig,
+  sessionWebhook: string,
+  text: string,
+  options: SendMessageOptions = {},
+): Promise<AxiosResponse> {
+  const token = await getAccessToken(config, options.log);
+  const log = options.log || getLogger();
+
+  // Session webhook supports native media messages; prefer that when media info is available.
+  if (options.mediaPath && options.mediaType) {
+    const mediaId = await uploadMedia(config, options.mediaPath, options.mediaType, log);
+    if (mediaId) {
+      let body: any;
+
+      if (options.mediaType === "image") {
+        body = { msgtype: "image", image: { media_id: mediaId } };
+      } else if (options.mediaType === "voice") {
+        body = { msgtype: "voice", voice: { media_id: mediaId } };
+      } else if (options.mediaType === "video") {
+        body = { msgtype: "video", video: { media_id: mediaId } };
+      } else if (options.mediaType === "file") {
+        body = { msgtype: "file", file: { media_id: mediaId } };
+      }
+
+      if (body) {
+        const result = await axios({
+          url: sessionWebhook,
+          method: "POST",
+          data: body,
+          headers: { "x-acs-dingtalk-access-token": token, "Content-Type": "application/json" },
+        });
+        return result.data;
+      }
+    } else {
+      log?.warn?.("[DingTalk] Media upload failed, falling back to text description");
+    }
+  }
+
+  // Fallback to text/markdown reply payload.
+  const { useMarkdown, title } = detectMarkdownAndExtractTitle(text, options, "Clawdbot 消息");
+
+  let body: SessionWebhookResponse;
+  if (useMarkdown) {
+    let finalText = text;
+    if (options.atUserId) {
+      finalText = `${finalText} @${options.atUserId}`;
+    }
+    body = { msgtype: "markdown", markdown: { title, text: finalText } };
+  } else {
+    body = { msgtype: "text", text: { content: text } };
+  }
+
+  if (options.atUserId) {
+    body.at = { atUserIds: [options.atUserId], isAtAll: false };
+  }
+
+  const result = await axios({
+    url: sessionWebhook,
+    method: "POST",
+    data: body,
+    headers: { "x-acs-dingtalk-access-token": token, "Content-Type": "application/json" },
+  });
+  return result.data;
+}
+
+export async function sendMessage(
+  config: DingTalkConfig,
+  conversationId: string,
+  text: string,
+  options: SendMessageOptions & { sessionWebhook?: string; accountId?: string } = {},
+): Promise<{ ok: boolean; error?: string; data?: AxiosResponse }> {
+  try {
+    const messageType = config.messageType || "markdown";
+    const log = options.log || getLogger();
+
+    // Card mode: stream into active card if exists; otherwise fallback to markdown/session send.
+    if (messageType === "card" && options.accountId) {
+      const targetKey = `${options.accountId}:${conversationId}`;
+      const activeCardId = getActiveCardIdByTarget(targetKey);
+      if (activeCardId) {
+        const activeCard = getCardById(activeCardId);
+        if (activeCard && !isCardInTerminalState(activeCard.state)) {
+          try {
+            await streamAICard(activeCard, text, false, log);
+            return { ok: true };
+          } catch (err: any) {
+            // Mark failed and continue to markdown fallback to avoid message loss.
+            log?.warn?.(
+              `[DingTalk] AI Card streaming failed, fallback to markdown: ${err.message}`,
+            );
+            activeCard.state = AICardStatus.FAILED;
+            activeCard.lastUpdated = Date.now();
+          }
+        } else {
+          deleteActiveCardByTarget(targetKey);
+        }
+      }
+    }
+
+    if (options.sessionWebhook) {
+      await sendBySession(config, options.sessionWebhook, text, options);
+      return { ok: true };
+    }
+
+    const result = await sendProactiveTextOrMarkdown(config, conversationId, text, options);
+    return { ok: true, data: result };
+  } catch (err: any) {
+    options.log?.error?.(`[DingTalk] Send message failed: ${err.message}`);
+    return { ok: false, error: err.message };
+  }
+}

package/src/signature.ts

@@ -0,0 +1,15 @@
+import { createHmac } from "node:crypto";
+
+/**
+ * Generate DingTalk custom-bot style signature.
+ * Sign payload format: `${timestamp}\n${secret}`
+ */
+export function generateDingTalkSignature(timestamp: string | number, secret: string): string {
+  if (!secret) {
+    throw new Error("secret is required for DingTalk signature generation");
+  }
+
+  const timestampText = String(timestamp);
+  const payload = `${timestampText}\n${secret}`;
+  return createHmac("sha256", secret).update(payload).digest("base64");
+}

package/src/types.ts

@@ -11,11 +11,20 @@
 
 import type {
   OpenClawConfig,
+  OpenClawPluginApi,
   ChannelLogSink as SDKChannelLogSink,
   ChannelAccountSnapshot as SDKChannelAccountSnapshot,
   ChannelGatewayContext as SDKChannelGatewayContext,
   ChannelPlugin as SDKChannelPlugin,
-} from 'openclaw/plugin-sdk';
+} from "openclaw/plugin-sdk";
+
+export interface DingtalkPluginModule {
+  id: string;
+  name: string;
+  description?: string;
+  configSchema?: unknown;
+  register?: (api: OpenClawPluginApi) => void | Promise<void>;
+}
 
 /**
  * DingTalk channel configuration (extends base OpenClaw config)
@@ -28,12 +37,12 @@ export interface DingTalkConfig extends OpenClawConfig {
   agentId?: string;
   name?: string;
   enabled?: boolean;
-  dmPolicy?: 'open' | 'pairing' | 'allowlist';
-  groupPolicy?: 'open' | 'allowlist';
+  dmPolicy?: "open" | "pairing" | "allowlist";
+  groupPolicy?: "open" | "allowlist";
   allowFrom?: string[];
   showThinking?: boolean;
   debug?: boolean;
-  messageType?: 'markdown' | 'card';
+  messageType?: "markdown" | "card";
   cardTemplateId?: string;
   cardTemplateKey?: string;
   groups?: Record<string, { systemPrompt?: string }>;
@@ -56,12 +65,12 @@ export interface DingTalkChannelConfig {
   corpId?: string;
   agentId?: string;
   name?: string;
-  dmPolicy?: 'open' | 'pairing' | 'allowlist';
-  groupPolicy?: 'open' | 'allowlist';
+  dmPolicy?: "open" | "pairing" | "allowlist";
+  groupPolicy?: "open" | "allowlist";
   allowFrom?: string[];
   showThinking?: boolean;
   debug?: boolean;
-  messageType?: 'markdown' | 'card';
+  messageType?: "markdown" | "card";
   cardTemplateId?: string;
   cardTemplateKey?: string;
   groups?: Record<string, { systemPrompt?: string }>;
@@ -123,8 +132,9 @@ export interface DingTalkInboundMessage {
   createAt: number;
   text?: {
     content: string;
-    isReplyMsg?: boolean;        // 是否是回复消息
-    repliedMsg?: {               // 被回复的消息
+    isReplyMsg?: boolean; // 是否是回复消息
+    repliedMsg?: {
+      // 被回复的消息
       content?: {
         text?: string;
         richText?: Array<{
@@ -147,13 +157,13 @@ export interface DingTalkInboundMessage {
       atName?: string;
       downloadCode?: string; // For picture type in richText
     }>;
-    quoteContent?: string;       // 替代引用格式
+    quoteContent?: string; // 替代引用格式
   };
   // Legacy 引用格式
   quoteMessage?: {
     msgId?: string;
     msgtype?: string;
-    text?: { content: string; };
+    text?: { content: string };
     senderNick?: string;
     senderId?: string;
   };
@@ -190,7 +200,7 @@ export interface SendMessageOptions {
   mediaPath?: string;
   filePath?: string;
   mediaUrl?: string;
-  mediaType?: 'image' | 'voice' | 'video' | 'file';
+  mediaType?: "image" | "voice" | "video" | "file";
 }
 
 /**
@@ -262,7 +272,7 @@ export interface AxiosRequestConfig {
   method?: string;
   data?: any;
   headers?: Record<string, string>;
-  responseType?: 'arraybuffer' | 'json' | 'text';
+  responseType?: "arraybuffer" | "json" | "text";
 }
 
 /**
@@ -391,7 +401,7 @@ export interface SendMediaParams {
  * DingTalk outbound handler configuration
  */
 export interface DingTalkOutboundHandler {
-  deliveryMode: 'direct' | 'queued' | 'batch';
+  deliveryMode: "direct" | "queued" | "batch";
   resolveTarget: (params: ResolveTargetParams) => TargetResolutionResult;
   sendText: (params: SendTextParams) => Promise<{ ok: boolean; data?: any; error?: any }>;
   sendMedia?: (params: SendMediaParams) => Promise<{ ok: boolean; data?: any; error?: any }>;
@@ -401,10 +411,10 @@ export interface DingTalkOutboundHandler {
  * AI Card status constants
  */
 export const AICardStatus = {
-  PROCESSING: '1',
-  INPUTING: '2',
-  FINISHED: '3',
-  FAILED: '5',
+  PROCESSING: "1",
+  INPUTING: "2",
+  FINISHED: "3",
+  FAILED: "5",
 } as const;
 
 /**
@@ -442,11 +452,11 @@ export interface AICardStreamingRequest {
  * Connection state enum for lifecycle management
  */
 export enum ConnectionState {
-  DISCONNECTED = 'DISCONNECTED',
-  CONNECTING = 'CONNECTING',
-  CONNECTED = 'CONNECTED',
-  DISCONNECTING = 'DISCONNECTING',
-  FAILED = 'FAILED',
+  DISCONNECTED = "DISCONNECTED",
+  CONNECTING = "CONNECTING",
+  CONNECTED = "CONNECTED",
+  DISCONNECTING = "DISCONNECTING",
+  FAILED = "FAILED",
 }
 
 /**
@@ -473,14 +483,16 @@ export interface ConnectionAttemptResult {
 
 // ============ Onboarding Helper Functions ============
 
-const DEFAULT_ACCOUNT_ID = 'default';
+const DEFAULT_ACCOUNT_ID = "default";
 
 /**
  * List all DingTalk account IDs from config
  */
 export function listDingTalkAccountIds(cfg: OpenClawConfig): string[] {
   const dingtalk = cfg.channels?.dingtalk as DingTalkChannelConfig | undefined;
-  if (!dingtalk) return [];
+  if (!dingtalk) {
+    return [];
+  }
 
   const accountIds: string[] = [];
 
@@ -508,15 +520,18 @@ export interface ResolvedDingTalkAccount extends DingTalkConfig {
 /**
  * Resolve a specific DingTalk account configuration
  */
-export function resolveDingTalkAccount(cfg: OpenClawConfig, accountId?: string | null): ResolvedDingTalkAccount {
+export function resolveDingTalkAccount(
+  cfg: OpenClawConfig,
+  accountId?: string | null,
+): ResolvedDingTalkAccount {
   const id = accountId || DEFAULT_ACCOUNT_ID;
   const dingtalk = cfg.channels?.dingtalk as DingTalkChannelConfig | undefined;
 
   // If default account, return top-level config
   if (id === DEFAULT_ACCOUNT_ID) {
     const config: DingTalkConfig = {
-      clientId: dingtalk?.clientId ?? '',
-      clientSecret: dingtalk?.clientSecret ?? '',
+      clientId: dingtalk?.clientId ?? "",
+      clientSecret: dingtalk?.clientSecret ?? "",
       robotCode: dingtalk?.robotCode,
       corpId: dingtalk?.corpId,
       agentId: dingtalk?.agentId,
@@ -556,8 +571,8 @@ export function resolveDingTalkAccount(cfg: OpenClawConfig, accountId?: string |
 
   // Account doesn't exist, return empty config
   return {
-    clientId: '',
-    clientSecret: '',
+    clientId: "",
+    clientSecret: "",
     accountId: id,
     configured: false,
   };

package/src/utils.ts

@@ -1,7 +1,7 @@
-import * as fs from 'node:fs';
-import * as path from 'node:path';
-import * as os from 'node:os';
-import type { Logger, RetryOptions } from './types';
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import type { Logger, RetryOptions } from "./types";
 
 /**
  * Mask sensitive fields in data for safe logging
@@ -12,23 +12,23 @@ export function maskSensitiveData(data: unknown): any {
     return data;
   }
 
-  if (typeof data !== 'object') {
+  if (typeof data !== "object") {
     return data as string | number;
   }
 
   const masked = JSON.parse(JSON.stringify(data)) as Record<string, any>;
-  const sensitiveFields = ['token', 'accessToken'];
+  const sensitiveFields = new Set(["token", "accessToken"]);
 
   function maskObj(obj: any): void {
     for (const key in obj) {
-      if (sensitiveFields.includes(key)) {
+      if (sensitiveFields.has(key)) {
         const val = obj[key];
-        if (typeof val === 'string' && val.length > 6) {
-          obj[key] = val.slice(0, 3) + '*'.repeat(val.length - 6) + val.slice(-3);
-        } else if (typeof val === 'string') {
-          obj[key] = '*'.repeat(val.length);
+        if (typeof val === "string" && val.length > 6) {
+          obj[key] = val.slice(0, 3) + "*".repeat(val.length - 6) + val.slice(-3);
+        } else if (typeof val === "string") {
+          obj[key] = "*".repeat(val.length);
         }
-      } else if (typeof obj[key] === 'object' && obj[key] !== null) {
+      } else if (typeof obj[key] === "object" && obj[key] !== null) {
         maskObj(obj[key]);
       }
     }
@@ -53,7 +53,9 @@ export function cleanupOrphanedTempFiles(log?: Logger): number {
     const maxAge = 24 * 60 * 60 * 1000;
 
     for (const file of files) {
-      if (!dingtalkPattern.test(file)) continue;
+      if (!dingtalkPattern.test(file)) {
+        continue;
+      }
 
       const filePath = path.join(tempDir, file);
       try {
@@ -82,7 +84,10 @@ export function cleanupOrphanedTempFiles(log?: Logger): number {
  * Retry logic for API calls with exponential backoff
  * Handles transient failures like 401 token expiry
  */
-export async function retryWithBackoff<T>(fn: () => Promise<T>, options: RetryOptions = {}): Promise<T> {
+export async function retryWithBackoff<T>(
+  fn: () => Promise<T>,
+  options: RetryOptions = {},
+): Promise<T> {
   const { maxRetries = 3, baseDelayMs = 100, log } = options;
 
   for (let attempt = 1; attempt <= maxRetries; attempt++) {
@@ -90,7 +95,8 @@ export async function retryWithBackoff<T>(fn: () => Promise<T>, options: RetryOp
       return await fn();
     } catch (err: any) {
       const statusCode = err.response?.status;
-      const isRetryable = statusCode === 401 || statusCode === 429 || (statusCode && statusCode >= 500);
+      const isRetryable =
+        statusCode === 401 || statusCode === 429 || (statusCode && statusCode >= 500);
 
       if (!isRetryable || attempt === maxRetries) {
         throw err;
@@ -102,5 +108,12 @@ export async function retryWithBackoff<T>(fn: () => Promise<T>, options: RetryOp
     }
   }
 
-  throw new Error('Retry exhausted without returning');
+  throw new Error("Retry exhausted without returning");
+}
+
+/**
+ * Get current timestamp in ISO-compatible epoch milliseconds for status tracking.
+ */
+export function getCurrentTimestamp(): number {
+  return Date.now();
 }

package/clawbot.plugin.json

@@ -1,9 +0,0 @@
-{
-  "id": "dingtalk",
-  "channels": ["dingtalk"],
-  "configSchema": {
-    "type": "object",
-    "additionalProperties": true,
-    "properties": {}
-  }
-}

package/src/AGENTS.md

@@ -1,63 +0,0 @@
-# SOURCE DIRECTORY
-
-**Parent:** `./AGENTS.md`
-
-## OVERVIEW
-
-All DingTalk plugin implementation logic.
-
-## STRUCTURE
-
-```
-src/
-├── channel.ts        # Main plugin definition, API calls, message handling, AI Card
-├── types.ts          # Type definitions (30+ interfaces, AI Card types)
-├── runtime.ts        # Runtime getter/setter pattern
-└── config-schema.ts  # Zod validation for configuration
-```
-
-## WHERE TO LOOK
-
-| Task                      | Location               | Notes                                        |
-| ------------------------- | ---------------------- | -------------------------------------------- |
-| Channel plugin definition | `channel.ts:862`       | `dingtalkPlugin` export                      |
-| AI Card operations        | `channel.ts:374-600`   | createAICard, streamAICard, finishAICard     |
-| Message sending           | `channel.ts:520-700`   | sendMessage, sendBySession                   |
-| Token management          | `channel.ts:156-177`   | getAccessToken with cache                    |
-| Message processing        | `channel.ts:643-859`   | handleDingTalkMessage, extractMessageContent |
-| Type exports              | `types.ts`             | All interfaces/constants                     |
-| Public API exports        | `channel.ts:1068-1076` | sendBySession, createAICard, etc.            |
-
-## CONVENTIONS
-
-Same as root. No src-specific deviations.
-
-## ANTI-PATTERNS
-
-**Prohibited:**
-
-- Mutating module-level state outside of initialized functions
-- Creating multiple AI Card instances for same conversationId (use cached)
-- Calling DingTalk APIs without access token
-- Suppressing errors in async handlers
-
-## UNIQUE STYLES
-
-**AI Card State Machine:**
-
-- States: PROCESSING → INPUTING → FINISHED/FAILED
-- Cached in `Map<string, AICardInstance>` with TTL cleanup
-- Terminal states (FINISHED/FAILED) cleaned after 1 hour
-
-**Access Token Caching:**
-
-- Module-level variables: `accessToken`, `accessTokenExpiry`
-- Refresh 60s before expiry
-- Retry logic for 401/429/5xx errors
-
-**Message Type Handling:**
-
-- `text`: Plain text messages
-- `richText`: Extract text + @mentions
-- `picture/audio/video/file`: Download to `/tmp/dingtalk_*`
-- Auto-detect Markdown syntax for auto-formatting

package/src/openclaw-channel-dingtalk.code-workspace

@@ -1,17 +0,0 @@
-{
-	"folders": [
-		{
-			"path": ".."
-		},
-		{
-			"path": "../../.."
-		}
-	],
-	"settings": {
-		"chat.tools.terminal.autoApprove": {
-			"npm --prefix /Users/sym/Repo/openclaw/extensions/openclaw-channel-dingtalk": true,
-			"pnpm": true,
-			"/usr/bin/git": true
-		}
-	}
-}