@soimy/dingtalk 2.6.5

package/src/config-schema.ts

@@ -0,0 +1,92 @@
+import { z } from 'zod';
+
+/**
+ * DingTalk configuration schema using Zod
+ * Mirrors the structure needed for proper control-ui rendering
+ */
+export const DingTalkConfigSchema: z.ZodTypeAny = z.object({
+  /** Account name (optional display name) */
+  name: z.string().optional(),
+
+  /** Whether this channel is enabled */
+  enabled: z.boolean().optional().default(true),
+
+  /** DingTalk App Key (Client ID) - required for authentication */
+  clientId: z.string().optional(),
+
+  /** DingTalk App Secret (Client Secret) - required for authentication */
+  clientSecret: z.string().optional(),
+
+  /** DingTalk Robot Code for media download */
+  robotCode: z.string().optional(),
+
+  /** DingTalk Corporation ID */
+  corpId: z.string().optional(),
+
+  /** DingTalk Application ID (Agent ID) */
+  agentId: z.union([z.string(), z.number()]).optional(),
+
+  /** Direct message policy: open, pairing, or allowlist */
+  dmPolicy: z.enum(['open', 'pairing', 'allowlist']).optional().default('open'),
+
+  /** Group message policy: open or allowlist */
+  groupPolicy: z.enum(['open', 'allowlist']).optional().default('open'),
+
+  /** List of allowed user IDs for allowlist policy */
+  allowFrom: z.array(z.string()).optional(),
+
+  /** Show thinking indicator while processing */
+  showThinking: z.boolean().optional().default(true),
+
+  /** Enable debug logging */
+  debug: z.boolean().optional().default(false),
+
+  /** Message type for replies: markdown or card */
+  messageType: z.enum(['markdown', 'card']).optional().default('markdown'),
+
+  /** Card template ID for AI interactive cards
+   * obtain the template ID from DingTalk Developer Console.
+   * ref: https://github.com/soimy/openclaw-channel-dingtalk/blob/main/README.md#3-%E5%BB%BA%E7%AB%8B%E5%8D%A1%E7%89%87%E6%A8%A1%E6%9D%BF%E5%8F%AF%E9%80%89
+   */
+  cardTemplateId: z.string().optional(),
+
+  /** Card template key for streaming updates
+   * Default: 'msgContent' - 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'),
+
+  /** Per-group configuration, keyed by conversationId (supports "*" wildcard) */
+  groups: z
+    .record(
+      z.string(),
+      z.object({
+        systemPrompt: z.string().optional(),
+      })
+    )
+    .optional(),
+
+  /** Multi-account configuration */
+  accounts: z
+    .record(
+      z.string(),
+      z.lazy(() => DingTalkConfigSchema)
+    )
+    .optional(),
+
+  /** Connection robustness configuration */
+
+  /** Maximum number of connection attempts before giving up (default: 10) */
+  maxConnectionAttempts: z.number().int().min(1).optional().default(10),
+
+  /** Initial reconnection delay in milliseconds (default: 1000ms) */
+  initialReconnectDelay: z.number().int().min(100).optional().default(1000),
+
+  /** Maximum reconnection delay in milliseconds for exponential backoff (default: 60000ms = 1 minute) */
+  maxReconnectDelay: z.number().int().min(1000).optional().default(60000),
+
+  /** Jitter factor for reconnection delay randomization (0-1, default: 0.3) */
+  reconnectJitter: z.number().min(0).max(1).optional().default(0.3),
+});
+
+export type DingTalkConfig = z.infer<typeof DingTalkConfigSchema>;

package/src/connection-manager.ts

@@ -0,0 +1,434 @@
+/**
+ * Connection Manager for DingTalk Stream Client
+ *
+ * Provides robust connection lifecycle management with:
+ * - Exponential backoff with jitter for reconnection attempts
+ * - Configurable max attempts and delay parameters
+ * - Connection state tracking and event handling
+ * - Proper cleanup of timers and resources
+ * - Structured logging for all connection events
+ */
+
+import type { DWClient } from 'dingtalk-stream';
+import type { ConnectionState, ConnectionManagerConfig, ConnectionAttemptResult, Logger } from './types';
+import { ConnectionState as ConnectionStateEnum } from './types';
+
+/**
+ * ConnectionManager handles the robust connection lifecycle for DWClient
+ */
+export class ConnectionManager {
+  private config: ConnectionManagerConfig;
+  private log?: Logger;
+  private accountId: string;
+
+  // Connection state tracking
+  private state: ConnectionState = ConnectionStateEnum.DISCONNECTED;
+  private attemptCount: number = 0;
+  private reconnectTimer?: NodeJS.Timeout;
+  private stopped: boolean = false;
+
+  // Runtime monitoring resources
+  private healthCheckInterval?: NodeJS.Timeout;
+  private socketCloseHandler?: (code: number, reason: string) => void;
+  private socketErrorHandler?: (error: Error) => void;
+  private monitoredSocket?: any; // Store the socket instance we attached listeners to
+
+  // Sleep abort control
+  private sleepTimeout?: NodeJS.Timeout;
+  private sleepResolve?: () => void;
+
+  // Client reference
+  private client: DWClient;
+
+  constructor(client: DWClient, accountId: string, config: ConnectionManagerConfig, log?: Logger) {
+    this.client = client;
+    this.accountId = accountId;
+    this.config = config;
+    this.log = log;
+  }
+
+  private notifyStateChange(error?: string): void {
+    if (this.config.onStateChange) {
+      this.config.onStateChange(this.state, error);
+    }
+  }
+
+  /**
+   * Calculate next reconnection delay with exponential backoff and jitter
+   * Formula: delay = min(initialDelay * 2^attempt, maxDelay) * (1 ± jitter)
+   * @param attempt Zero-based attempt number (0 for first retry, 1 for second, etc.)
+   */
+  private calculateNextDelay(attempt: number): number {
+    const { initialDelay, maxDelay, jitter } = this.config;
+
+    // Exponential backoff: initialDelay * 2^attempt
+    // For attempt=0 (first retry), this gives initialDelay * 1 = initialDelay
+    const exponentialDelay = initialDelay * Math.pow(2, attempt);
+
+    // Cap at maxDelay
+    const cappedDelay = Math.min(exponentialDelay, maxDelay);
+
+    // Apply jitter: randomize ± jitter%
+    const jitterAmount = cappedDelay * jitter;
+    const randomJitter = (Math.random() * 2 - 1) * jitterAmount;
+    const finalDelay = Math.max(100, cappedDelay + randomJitter); // Minimum 100ms
+
+    return Math.floor(finalDelay);
+  }
+
+  /**
+   * Attempt to connect with retry logic
+   */
+  private async attemptConnection(): Promise<ConnectionAttemptResult> {
+    if (this.stopped) {
+      return { success: false, attempt: this.attemptCount, error: new Error('Connection manager stopped') };
+    }
+
+    this.attemptCount++;
+    this.state = ConnectionStateEnum.CONNECTING;
+    this.notifyStateChange();
+
+    this.log?.info?.(`[${this.accountId}] Connection attempt ${this.attemptCount}/${this.config.maxAttempts}...`);
+
+    try {
+      // Call DWClient connect method
+      await this.client.connect();
+
+      // Re-check stopped flag after async connect() completes
+      // This prevents race condition where stop() is called during connection
+      if (this.stopped) {
+        this.log?.warn?.(
+          `[${this.accountId}] Connection succeeded but manager was stopped during connect - disconnecting`
+        );
+        try {
+          this.client.disconnect();
+        } catch (disconnectErr: any) {
+          this.log?.debug?.(`[${this.accountId}] Error during post-connect disconnect: ${disconnectErr.message}`);
+        }
+        return {
+          success: false,
+          attempt: this.attemptCount,
+          error: new Error('Connection manager stopped during connect'),
+        };
+      }
+
+      // Connection successful
+      this.state = ConnectionStateEnum.CONNECTED;
+      this.notifyStateChange();
+      const successfulAttempt = this.attemptCount;
+      this.attemptCount = 0; // Reset counter on success
+
+      this.log?.info?.(`[${this.accountId}] DingTalk Stream client connected successfully`);
+
+      return { success: true, attempt: successfulAttempt };
+    } catch (err: any) {
+      this.log?.error?.(`[${this.accountId}] Connection attempt ${this.attemptCount} failed: ${err.message}`);
+
+      // Check if we've exceeded max attempts
+      if (this.attemptCount >= this.config.maxAttempts) {
+        this.state = ConnectionStateEnum.FAILED;
+        this.notifyStateChange('Max connection attempts reached');
+        this.log?.error?.(
+          `[${this.accountId}] Max connection attempts (${this.config.maxAttempts}) reached. Giving up.`
+        );
+        return { success: false, attempt: this.attemptCount, error: err };
+      }
+
+      // Calculate next retry delay (use attemptCount-1 for zero-based exponent)
+      // This ensures first retry uses 2^0 = 1x initialDelay
+      const nextDelay = this.calculateNextDelay(this.attemptCount - 1);
+
+      this.log?.warn?.(
+        `[${this.accountId}] Will retry connection in ${(nextDelay / 1000).toFixed(2)}s (attempt ${this.attemptCount + 1}/${this.config.maxAttempts})`
+      );
+
+      return { success: false, attempt: this.attemptCount, error: err, nextDelay };
+    }
+  }
+
+  /**
+   * Connect with robust retry logic
+   */
+  public async connect(): Promise<void> {
+    if (this.stopped) {
+      throw new Error('Cannot connect: connection manager is stopped');
+    }
+
+    // Clear any existing reconnect timer
+    this.clearReconnectTimer();
+
+    this.log?.info?.(`[${this.accountId}] Starting DingTalk Stream client with robust connection...`);
+
+    // Keep trying until success or max attempts reached
+    while (!this.stopped && this.state !== ConnectionStateEnum.CONNECTED) {
+      const result = await this.attemptConnection();
+
+      if (result.success) {
+        // Connection successful
+        this.setupRuntimeReconnection();
+        return;
+      }
+
+      // Check if connection was stopped during connect
+      if (result.error?.message === 'Connection manager stopped during connect') {
+        this.log?.info?.(`[${this.accountId}] Connection cancelled: manager stopped during connect`);
+        throw new Error('Connection cancelled: connection manager stopped');
+      }
+
+      if (!result.nextDelay || this.attemptCount >= this.config.maxAttempts) {
+        // No more retries
+        throw new Error(`Failed to connect after ${this.attemptCount} attempts`);
+      }
+
+      // Wait before next attempt
+      await this.sleep(result.nextDelay);
+    }
+  }
+
+  /**
+   * Setup runtime reconnection handlers
+   * Monitors DWClient connection state for automatic reconnection
+   */
+  private setupRuntimeReconnection(): void {
+    this.log?.debug?.(`[${this.accountId}] Setting up runtime reconnection monitoring`);
+
+    // Clean up any existing monitoring resources before setting up new ones
+    this.cleanupRuntimeMonitoring();
+
+    // Access DWClient internals to monitor connection state
+    const client = this.client as any;
+
+    // Monitor client's 'connected' property changes
+    // We'll set up an interval to periodically check connection health
+    this.healthCheckInterval = setInterval(() => {
+      if (this.stopped) {
+        if (this.healthCheckInterval) {
+          clearInterval(this.healthCheckInterval);
+        }
+        return;
+      }
+
+      // If we believe we're connected but DWClient disagrees, trigger reconnection
+      if (this.state === ConnectionStateEnum.CONNECTED && !client.connected) {
+        this.log?.warn?.(`[${this.accountId}] Connection health check failed - detected disconnection`);
+        if (this.healthCheckInterval) {
+          clearInterval(this.healthCheckInterval);
+        }
+        this.handleRuntimeDisconnection();
+      }
+    }, 5000); // Check every 5 seconds
+
+    // Additionally, if we have access to the socket, monitor its events
+    // The DWClient uses 'ws' WebSocket library which extends EventEmitter
+    if (client.socket) {
+      const socket = client.socket;
+      // Store the socket instance we're attaching listeners to
+      this.monitoredSocket = socket;
+
+      // Handler for socket close event
+      this.socketCloseHandler = (code: number, reason: string) => {
+        this.log?.warn?.(`[${this.accountId}] WebSocket closed event (code: ${code}, reason: ${reason || 'none'})`);
+
+        // Only trigger reconnection if we were previously connected and not stopping
+        if (!this.stopped && this.state === ConnectionStateEnum.CONNECTED) {
+          if (this.healthCheckInterval) {
+            clearInterval(this.healthCheckInterval);
+          }
+          this.handleRuntimeDisconnection();
+        }
+      };
+
+      // Handler for socket error event
+      this.socketErrorHandler = (error: Error) => {
+        this.log?.error?.(`[${this.accountId}] WebSocket error event: ${error?.message || 'Unknown error'}`);
+      };
+
+      // Listen to socket events
+      // Use 'once' for close to avoid duplicate reconnection triggers
+      socket.once('close', this.socketCloseHandler);
+      // Use 'once' for error as well to prevent accumulation across reconnects
+      socket.once('error', this.socketErrorHandler);
+    }
+  }
+
+  /**
+   * Clean up runtime monitoring resources (intervals and event listeners)
+   */
+  private cleanupRuntimeMonitoring(): void {
+    // Clear health check interval
+    if (this.healthCheckInterval) {
+      clearInterval(this.healthCheckInterval);
+      this.healthCheckInterval = undefined;
+      this.log?.debug?.(`[${this.accountId}] Health check interval cleared`);
+    }
+
+    // Remove socket event listeners from the stored socket instance
+    if (this.monitoredSocket) {
+      const socket = this.monitoredSocket;
+
+      if (this.socketCloseHandler) {
+        socket.removeListener('close', this.socketCloseHandler);
+        this.socketCloseHandler = undefined;
+      }
+      if (this.socketErrorHandler) {
+        socket.removeListener('error', this.socketErrorHandler);
+        this.socketErrorHandler = undefined;
+      }
+
+      this.log?.debug?.(`[${this.accountId}] Socket event listeners removed from monitored socket`);
+      this.monitoredSocket = undefined;
+    }
+  }
+
+  /**
+   * Handle runtime disconnection and trigger reconnection
+   */
+  private handleRuntimeDisconnection(): void {
+    if (this.stopped) return;
+
+    this.log?.warn?.(`[${this.accountId}] Runtime disconnection detected, initiating reconnection...`);
+
+    this.state = ConnectionStateEnum.DISCONNECTED;
+    this.notifyStateChange('Runtime disconnection detected');
+    this.attemptCount = 0; // Reset attempt counter for runtime reconnection
+
+    // Clear any existing timer
+    this.clearReconnectTimer();
+
+    // Start reconnection with initial delay
+    const delay = this.calculateNextDelay(0);
+    this.log?.info?.(`[${this.accountId}] Scheduling reconnection in ${(delay / 1000).toFixed(2)}s`);
+
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnect().catch((err) => {
+        this.log?.error?.(`[${this.accountId}] Reconnection failed: ${err.message}`);
+      });
+    }, delay);
+  }
+
+  /**
+   * Reconnect after runtime disconnection
+   */
+  private async reconnect(): Promise<void> {
+    if (this.stopped) return;
+
+    this.log?.info?.(`[${this.accountId}] Attempting to reconnect...`);
+
+    try {
+      await this.connect();
+      this.log?.info?.(`[${this.accountId}] Reconnection successful`);
+    } catch (err: any) {
+      if (this.stopped) return;
+
+      this.log?.error?.(`[${this.accountId}] Reconnection failed: ${err.message}`);
+      this.state = ConnectionStateEnum.FAILED;
+      this.notifyStateChange(err.message);
+
+      // Continue runtime recovery instead of getting stuck in FAILED.
+      const delay = this.calculateNextDelay(0);
+      this.attemptCount = 0;
+      this.clearReconnectTimer();
+      this.log?.warn?.(
+        `[${this.accountId}] Reconnection cycle failed; scheduling next reconnect in ${(delay / 1000).toFixed(2)}s`
+      );
+      this.reconnectTimer = setTimeout(() => {
+        void this.reconnect();
+      }, delay);
+    }
+  }
+
+  /**
+   * Stop the connection manager and cleanup resources
+   */
+  public stop(): void {
+    if (this.stopped) return;
+
+    this.log?.info?.(`[${this.accountId}] Stopping connection manager...`);
+
+    this.stopped = true;
+    this.state = ConnectionStateEnum.DISCONNECTING;
+
+    // Clear reconnect timer
+    this.clearReconnectTimer();
+
+    // Cancel any in-flight sleep (retry delay)
+    this.cancelSleep();
+
+    // Clean up runtime monitoring resources
+    this.cleanupRuntimeMonitoring();
+
+    // Disconnect client
+    try {
+      this.client.disconnect();
+    } catch (err: any) {
+      this.log?.warn?.(`[${this.accountId}] Error during disconnect: ${err.message}`);
+    }
+
+    this.state = ConnectionStateEnum.DISCONNECTED;
+    this.log?.info?.(`[${this.accountId}] Connection manager stopped`);
+  }
+
+  /**
+   * Clear reconnection timer
+   */
+  private clearReconnectTimer(): void {
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = undefined;
+      this.log?.debug?.(`[${this.accountId}] Reconnect timer cleared`);
+    }
+  }
+
+  /**
+   * Sleep utility for retry delays
+   * Returns a promise that resolves after ms or can be cancelled via cancelSleep()
+   */
+  private sleep(ms: number): Promise<void> {
+    return new Promise((resolve) => {
+      this.sleepResolve = resolve;
+      this.sleepTimeout = setTimeout(() => {
+        this.sleepTimeout = undefined;
+        this.sleepResolve = undefined;
+        resolve();
+      }, ms);
+    });
+  }
+
+  /**
+   * Cancel any in-flight sleep operation
+   * Resolves the pending promise immediately so await unblocks
+   */
+  private cancelSleep(): void {
+    if (this.sleepTimeout) {
+      clearTimeout(this.sleepTimeout);
+      this.sleepTimeout = undefined;
+      this.log?.debug?.(`[${this.accountId}] Sleep timeout cancelled`);
+    }
+    // Resolve the pending promise so await unblocks immediately
+    if (this.sleepResolve) {
+      this.sleepResolve();
+      this.sleepResolve = undefined;
+    }
+  }
+
+  /**
+   * Get current connection state
+   */
+  public getState(): ConnectionState {
+    return this.state;
+  }
+
+  /**
+   * Check if connection is active
+   */
+  public isConnected(): boolean {
+    return this.state === ConnectionStateEnum.CONNECTED;
+  }
+
+  /**
+   * Check if connection manager is stopped
+   */
+  public isStopped(): boolean {
+    return this.stopped;
+  }
+}

package/src/media-utils.ts

@@ -0,0 +1,132 @@
+// src/media-utils.ts
+
+/**
+ * Media handling utilities for DingTalk channel plugin.
+ * Provides functions for media type detection and file upload to DingTalk media servers.
+ */
+
+import * as path from 'path';
+import * as fs from 'fs';
+import { promises as fsPromises } from 'fs';
+import axios from 'axios';
+import FormData from 'form-data';
+import type { DingTalkConfig, Logger } from './types';
+
+export type DingTalkMediaType = 'image' | 'voice' | 'video' | 'file';
+
+/**
+ * Detect media type from file extension
+ * Matches DingTalk's supported media types:
+ * - image: jpg, gif, png, bmp (max 20MB)
+ * - voice: amr, mp3, wav (max 2MB)
+ * - video: mp4 (max 20MB)
+ * - file: doc, docx, xls, xlsx, ppt, pptx, zip, pdf, rar (max 20MB)
+ *
+ * @param filePath Path to the media file
+ * @returns Detected media type
+ */
+export function detectMediaTypeFromExtension(filePath: string): DingTalkMediaType {
+  const ext = path.extname(filePath).toLowerCase();
+
+  if (['.jpg', '.jpeg', '.png', '.gif', '.bmp'].includes(ext)) {
+    return 'image';
+  } else if (['.mp3', '.amr', '.wav'].includes(ext)) {
+    return 'voice';
+  } else if (['.mp4', '.avi', '.mov'].includes(ext)) {
+    return 'video';
+  }
+
+  return 'file';
+}
+
+/**
+ * File size limits for DingTalk media types (in bytes)
+ */
+const FILE_SIZE_LIMITS: Record<DingTalkMediaType, number> = {
+  image: 20 * 1024 * 1024, // 20MB
+  voice: 2 * 1024 * 1024, // 2MB
+  video: 20 * 1024 * 1024, // 20MB
+  file: 20 * 1024 * 1024, // 20MB
+};
+
+/**
+ * Upload media file to DingTalk and get media_id
+ * Uses DingTalk's media upload API: https://oapi.dingtalk.com/media/upload
+ *
+ * Note: Media files are stored temporarily by DingTalk (not in permanent storage).
+ * The media_id can be used in subsequent message sends.
+ *
+ * @param config DingTalk configuration
+ * @param mediaPath Local path to the media file
+ * @param mediaType Type of media: 'image' | 'voice' | 'video' | 'file'
+ * @param getAccessToken Function to get DingTalk access token
+ * @param log Optional logger
+ * @returns media_id on success, null on failure
+ */
+export async function uploadMedia(
+  config: DingTalkConfig,
+  mediaPath: string,
+  mediaType: DingTalkMediaType,
+  getAccessToken: (config: DingTalkConfig, log?: Logger) => Promise<string>,
+  log?: Logger
+): Promise<string | null> {
+  let fileStream: fs.ReadStream | null = null;
+
+  try {
+    const token = await getAccessToken(config, log);
+
+    // Check file size (stat will throw if file doesn't exist)
+    const stats = await fsPromises.stat(mediaPath);
+    const sizeLimit = FILE_SIZE_LIMITS[mediaType];
+    if (stats.size > sizeLimit) {
+      const sizeMB = (stats.size / (1024 * 1024)).toFixed(2);
+      const limitMB = (sizeLimit / (1024 * 1024)).toFixed(2);
+      log?.error?.(`[DingTalk] Media file too large: ${sizeMB}MB exceeds ${limitMB}MB limit for ${mediaType}`);
+      return null;
+    }
+
+    // Read file as a stream for better memory efficiency
+    fileStream = fs.createReadStream(mediaPath);
+    const filename = path.basename(mediaPath);
+
+    // Upload to DingTalk's media server using form-data
+    const form = new FormData();
+    form.append('media', fileStream, { filename });
+
+    const uploadUrl = `https://oapi.dingtalk.com/media/upload?access_token=${token}&type=${mediaType}`;
+
+    log?.debug?.(`[DingTalk] Uploading media: ${filename} (${stats.size} bytes) as ${mediaType}`);
+
+    const response = await axios.post(uploadUrl, form, {
+      headers: form.getHeaders(),
+      maxBodyLength: Infinity,
+      maxContentLength: Infinity,
+    });
+
+    if (response.data?.errcode === 0 && response.data?.media_id) {
+      log?.debug?.(`[DingTalk] Media uploaded successfully: ${response.data.media_id} (${stats.size} bytes)`);
+      return response.data.media_id;
+    } else {
+      log?.error?.(`[DingTalk] Media upload failed: ${JSON.stringify(response.data)}`);
+      return null;
+    }
+  } catch (err: any) {
+    // Handle file system errors (e.g., file not found, permission denied)
+    if (err.code === 'ENOENT') {
+      log?.error?.(`[DingTalk] Media file not found: ${mediaPath}`);
+    } else if (err.code === 'EACCES') {
+      log?.error?.(`[DingTalk] Permission denied accessing media file: ${mediaPath}`);
+    } else {
+      log?.error?.(`[DingTalk] Failed to upload media: ${err.message}`);
+      if (axios.isAxiosError(err) && err.response) {
+        log?.error?.(`[DingTalk] Upload response: ${JSON.stringify(err.response.data)}`);
+      }
+    }
+    return null;
+  } finally {
+    // Ensure file stream is closed even on error
+    if (fileStream) {
+      fileStream.destroy();
+    }
+  }
+}