dingtalk-manager

钉钉工作通知 API 客户端，支持 Node.js/Bun。通过工作通知 API 向钉钉用户发送 Markdown 和文本消息。

安装

# npm
npm install dingtalk-manager

# yarn
yarn add dingtalk-manager

# bun
bun add dingtalk-manager

命令行工具

本包支持通过 bunx 或 npx 直接作为命令行工具使用，无需安装。

配置凭证

首先设置环境变量：

export DINGTALK_APP_KEY="your-app-key"
export DINGTALK_APP_SECRET="your-app-secret"
export DINGTALK_AGENT_ID="your-agent-id"
export DINGTALK_USER_ID="target-user-id"

或者使用凭证文件（--credentials-path 参数）：

bunx dingtalk-manager@latest sendMarkdown --credentials-path /path/to/credentials.json --title "标题" --content "内容"

发送 Markdown 消息

bunx dingtalk-manager@latest sendMarkdown --title "标题" --content "**加粗** 内容\n- 项目 1\n- 项目 2"

发送文本消息

bunx dingtalk-manager@latest sendText --content "纯文本消息"

输出格式

命令执行成功时输出 JSON 格式的结果：

{
  "success": true,
  "taskId": "123456789"
}

失败时：

{
  "success": false,
  "error": "错误信息"
}

帮助信息

bunx dingtalk-manager@latest --help
bunx dingtalk-manager@latest sendMarkdown --help
bunx dingtalk-manager@latest sendText --help

快速开始

方式一：直接传入凭证

import { DingTalk } from 'dingtalk-manager';

const client = new DingTalk({
  credentials: {
    appKey: 'your-app-key',
    appSecret: 'your-app-secret',
    agentId: 'your-agent-id',
    userId: 'target-user-id',
  },
});

// 发送 Markdown 消息
const result = await client.sendMarkdown('标题', '**加粗** 内容\n- 项目 1\n- 项目 2');

if (result.success) {
  console.log('消息已发送！Task ID:', result.taskId);
}

// 发送文本消息
await client.sendText('纯文本消息');

方式二：环境变量

export DINGTALK_APP_KEY="your-app-key"
export DINGTALK_APP_SECRET="your-app-secret"
export DINGTALK_AGENT_ID="your-agent-id"
export DINGTALK_USER_ID="target-user-id"

import { DingTalk } from 'dingtalk-manager';

const client = new DingTalk();
await client.sendMarkdown('标题', '内容');

方式三：凭证文件

import { DingTalk } from 'dingtalk-manager';

const client = new DingTalk({
  credentialsPath: '/path/to/credentials.json',
});

await client.sendMarkdown('标题', '内容');

凭证文件格式 (credentials.json):

{
  "appKey": "your-app-key",
  "appSecret": "your-app-secret",
  "agentId": "your-agent-id",
  "userId": "target-user-id"
}

API 参考

new DingTalk(options?)

创建 DingTalk 客户端实例。

| 参数 | 类型 | 说明 | |--------|------|-------------| | credentials | DingTalkCredentials | 直接传入凭证（优先级最高） | | credentialsPath | string | 凭证 JSON 文件路径 | | tokenCacheDir | string | access_token 缓存目录（默认：os.tmpdir()） |

client.sendMarkdown(title, content)

发送 Markdown 消息。

const result = await client.sendMarkdown('报告', `
## 每日报告

- 任务 1: 完成 ✅
- 任务 2: 待处理 ⏳

**总计**: 2 个任务
`);

console.log(result.success);    // true
console.log(result.taskId);     // '123456789'
console.log(result.error);      // undefined（成功时）

client.sendText(content)

发送纯文本消息。

const result = await client.sendText('你好，这是一条纯文本消息。');

client.getSendResult(taskId)

查询消息发送状态。

const status = await client.getSendResult('123456789');

console.log(status.success);           // true
console.log(status.readUserIdList);    // ['user1', 'user2'] 已读用户
console.log(status.unreadUserIdList);  // ['user3'] 未读用户
console.log(status.forbiddenList);     // [{ code: '143106', userid: 'user4', count: 1 }] 被限流用户

DingTalk.getForbiddenCodeInfo(code)

获取错误码的可读描述。

const info = DingTalk.getForbiddenCodeInfo('143106');
// {
//   description: '应用重复消息发送限超限（同一用户每天只能接收一条相同内容的消息）',
//   solution: '修改消息内容后重新发送，或等待明天自动重置'
// }

client.getAccessToken()

获取 access_token（带缓存）。通常不需要直接调用，但如有需要可以使用。

const token = await client.getAccessToken();

错误码

| 错误码 | 描述 | 解决方案 | |------|-------------|----------| | 143103 | 企业应用消息发送QPM超限 | 稍后重试，或优化发送频率 | | 143104 | 企业每分钟发送QPM超限 | 稍后重试，或优化发送频率 | | 143105 | 应用发送日限超限 | 已达每日上限，明天再试 | | 143106 | 重复消息发送限超限 | 修改消息内容，或等待明天 |

错误处理

import { DingTalk, DingTalkError, TokenError, MessageError, CredentialError } from 'dingtalk-manager';

try {
  const client = new DingTalk();
  const result = await client.sendMarkdown('标题', '内容');
  
  if (!result.success) {
    console.error('发送失败:', result.error);
  }
} catch (error) {
  if (error instanceof CredentialError) {
    console.error('凭证无效:', error.message);
  } else if (error instanceof TokenError) {
    console.error('Token 错误:', error.message);
  } else if (error instanceof DingTalkError) {
    console.error('钉钉错误:', error.message);
  }
}

Token 缓存

access_token 会自动缓存以减少 API 调用。Token 有效期为 2 小时，本库会提前 5 分钟刷新。

默认缓存位置：os.tmpdir()/dingtalk-token-cache.json

自定义缓存目录：

const client = new DingTalk({
  credentials: { /* ... */ },
  tokenCacheDir: '/custom/cache/directory',
});

开发

安装依赖

bun install

可用命令

| 命令 | 说明 | |------|------| | bun run build | 完整构建（清理 → 编译 JS → 生成类型声明） | | bun run build:clean | 清理 dist/ 目录 | | bun run build:js | 编译 TypeScript 到 ES Module JS（使用 Bun） | | bun run build:types | 生成 .d.ts 类型声明文件（使用 tsc） | | bun test | 运行所有测试 | | bun run test:watch | 监听模式运行测试（文件变化自动重跑） | | bun run release | 构建并发布到 npm | | bun run release:dry | 模拟发布（检查打包内容，不实际上传） |

命令详解

构建相关

# 完整构建流程
bun run build
# 等同于依次执行：
# 1. bun run build:clean  → 删除 dist/ 目录
# 2. bun run build:js     → 编译 src/index.ts 到 dist/index.js
# 3. bun run build:types  → 生成 dist/*.d.ts 类型声明

测试相关

# 运行测试
bun test

# 监听模式（开发时推荐）
bun run test:watch

发布相关

# 模拟发布（检查打包内容、文件大小等）
bun run release:dry

# 正式发布（会自动执行 prepublishOnly 钩子）
npm publish
# 或使用封装命令
bun run release

注意：npm publish 会自动触发 prepublishOnly 钩子，先执行 bun run build && bun test，确保构建和测试都通过后才发布。

环境要求

• Node.js >= 18.0.0 或 Bun >= 1.0.0

许可证

MIT