Meegle TypeScript SDK Demo

这是 @linmi/meegle-sdk-typescript 的官方示例项目，展示了如何使用 TypeScript SDK 与 Meegle API 进行交互。

🚀 快速开始

安装依赖

npm install
# 或者
pnpm install

运行示例

ES Module 版本（推荐）

npm start
# 或者
node index.js

CommonJS 版本

npm run start:cjs
# 或者
node index-commonjs.js

语法检查

npm run check

📁 文件说明

• index.js - ES Module 版本的主示例（推荐使用）
• index-commonjs.js - CommonJS 版本的示例（兼容性支持）
• index-with-priority.js - 带有优先级字段的高级示例
• package.json - 项目配置文件
• README.md - 本说明文档

🔧 重要说明

1. 字段格式要求

对于 select 类型的字段（如 priority），需要使用对象格式：

// ✅ 正确格式
{ 
  field_key: 'priority', 
  field_value: {
    value: "1"  // P1 优先级
  }
}

// ❌ 错误格式
{ field_key: 'priority', field_value: '1' }

优先级选项对照表：

• "0" - P0 最高优先级
• "1" - P1 高优先级
• "2" - P2 正常优先级
• "99" - 待定

2. 常见问题解决

问题：response.data 返回 undefined

原因分析：

• 当 API 调用失败时（err_code !== 0），服务器不会返回 data 字段
• data 为 undefined 是正常现象，需要检查错误信息

解决方案：

if (response.err_code === 0) {
  console.log('✅ 成功! 工作项ID:', response.data);
} else {
  console.log('❌ 失败:', response.err_msg);
  if (response.err) {
    console.log('详细错误:', response.err.msg);
  }
}

问题：field [priority] is illegal

原因：

• select 类型字段需要使用对象格式 {value: "选项值"}
• 选项值必须与系统预定义的选项匹配

解决方案： 参考上面的"字段格式要求"部分使用正确格式。

3. UserKey 说明

每次 API 调用都必须传入 WithUserKey 参数：

const response = await client.WorkItem.CreateWorkItem(
  request, 
  WithUserKey('你的用户Key')  // 必需参数
);

UserKey 可以在飞书项目的个人设置中获取。

🎯 示例功能

基础示例 (index.js)

• ✅ 创建工作项（带优先级）
• ✅ 字段值设置
• ✅ 错误处理
• ✅ 响应解析

高级示例 (index-with-priority.js)

• ✅ 多种优先级格式测试
• ✅ 容错处理
• ✅ 详细日志输出

📊 执行结果

成功执行后会显示：

🚀 开始创建工作项...

✅ 工作项创建成功!
📋 工作项ID: 6192741570
📊 类型: 需求 (story)
⚡ 优先级: P1
📝 描述: 已设置描述信息

🎉 SDK 测试完成，功能正常！

🔗 相关链接

• Meegle TypeScript SDK
• API 文档
• 字段类型说明

💡 开发提示

1. 调试模式：SDK 会自动输出 [DEBUG] 日志，显示请求信息
2. 错误处理：务必检查 err_code 字段判断操作是否成功
3. 字段验证：使用 GetMeta API 获取字段定义和验证规则
4. 类型安全：充分利用 TypeScript 的类型检查功能