@linmi/meegle-sdk-typescript

企业级 TypeScript SDK for 飞书项目（Meegle）API - 类型安全、开发友好、功能完整

✨ 特性

🎯 类型安全优先 - 完整的 TypeScript 类型定义，编译时错误检查
🛠️ 智能构建器 - 链式 API，IDE 智能提示，告别手写 JSON
🚀 现代化架构 - 支持 CommonJS 和 ES Modules，Node.js 18+ 和现代浏览器
📦 批量操作 - 高性能批量更新、删除、状态变更
🔍 强大搜索 - 类型安全的搜索构建器，支持复杂查询条件
⚡ 开箱即用 - 零配置，30 秒上手

📦 安装

npm install @linmi/meegle-sdk-typescript

🚀 5分钟快速开始

1. 创建客户端

import { NewClient, WithBaseUrl, WithUserKey } from '@linmi/meegle-sdk-typescript';

const client = NewClient(
  'your-app-id',           // 在飞书项目开放平台获取
  'your-app-secret',       // 在飞书项目开放平台获取
  WithBaseUrl('https://project.feishu.cn')  // 官方API地址
);

2. 创建工作项

import { NewCreateWorkItemReqBuilder } from '@linmi/meegle-sdk-typescript';

const req = NewCreateWorkItemReqBuilder()
  .ProjectKey('my-project')
  .WorkItemTypeKey('task')
  .Name('Meegle SDK集成测试')
  .FieldValuePairs([
    { field_key: 'priority', field_value: { value: '1' } }, // 高优先级
    { field_key: 'description', field_value: '测试新版本SDK功能' }
  ])
  .build();

const result = await client.WorkItem.Create(req, WithUserKey('your-user-key'));

if (result.err_code === 0) {
  console.log('✅ 创建成功！工作项ID:', result.data);
} else {
  console.error('❌ 创建失败:', result.err_msg);
}

3. 智能搜索工作项

import { NewTypedSearchBuilder, NewAdvancedSearchBuilder } from '@linmi/meegle-sdk-typescript';

// 使用类型安全的搜索构建器
const searchCondition = NewTypedSearchBuilder()
  .text('name').contains('SDK')
  .newGroup('AND')
    .select('priority').hasAnyOf(['1', '2'])  // 高优先级和中优先级
    .user('assignee').equals('your-user-key')
  .build();

const searchReq = NewAdvancedSearchBuilder()
  .searchGroup(searchCondition)
  .page(1, 20)
  .sort('created_at', 'desc')
  .needWorkflow()
  .build();

// 执行搜索
const searchResult = await client.WorkItem.SearchByParams(searchReq);
console.log('找到', searchResult.data.length, '个工作项');

🎯 核心功能

🔒 类型安全的字段操作

import { FieldType, SelectOption, TypedFieldValuePair } from '@linmi/meegle-sdk-typescript';

// 类型安全的字段值
const priorityField: TypedFieldValuePair<FieldType.SELECT> = {
  field_key: 'priority',
  field_value: { label: '高', value: 'high' },  // IDE会提示正确格式
  field_type: FieldType.SELECT
};

// 错误的类型会在编译时被发现
const wrongField: TypedFieldValuePair<FieldType.SELECT> = {
  field_key: 'priority',
  field_value: 'wrong_format',  // ❌ 编译错误！
  field_type: FieldType.SELECT
};

📦 强大的批量操作

import { NewBatchUpdateReqBuilder } from '@linmi/meegle-sdk-typescript';

// 批量更新多个工作项的优先级
const batchReq = NewBatchUpdateReqBuilder()
  .BatchUpdateSingleField(
    'my-project',
    'task',
    [1001, 1002, 1003],  // 工作项ID列表
    'priority',
    { label: '紧急', value: 'urgent' }
  )
  .build();

const result = await client.WorkItem.BatchUpdate(batchReq, WithUserKey('your-user-key'));

🔍 智能搜索构建器

// 构建复杂的搜索条件
const complexSearch = NewTypedSearchBuilder()
  .text('name').contains('重要')
  .newGroup('OR')
    .select('status').equals('in_progress')
    .date('due_date').between(startTime, endTime)
  .newGroup('AND')
    .number('estimate_hours').greaterThan(8)
    .user('assignee').hasAnyOf(['user1', 'user2'])
  .build();

🛠️ 完整功能

空间管理

• ✅ 空间详情和列表
• ✅ 团队成员管理
• ✅ 业务线和工作项类型

工作项管理

• ✅ CRUD 操作（创建、查询、更新、删除）
• ✅ 批量操作（批量更新、删除、状态变更）
• ✅ 搜索和筛选（智能搜索构建器）
• ✅ 工作流管理（状态流转、节点操作）
• ✅ 附件管理（上传、下载）
• ✅ 评论管理

用户和权限

• ✅ 用户搜索和详情
• ✅ 用户组管理
• ✅ 角色配置

视图和报表

• ✅ 固定视图和条件视图
• ✅ 全景视图
• ✅ 数据度量和图表

📚 常用示例

获取项目信息

import { NewListProjectReqBuilder } from '@linmi/meegle-sdk-typescript';

// 获取用户可访问的项目列表
const projectReq = NewListProjectReqBuilder()
  .UserKey('your-user-key')
  .build();

const projects = await client.Project.ListProject(
  projectReq, 
  WithUserKey('your-user-key')
);

console.log('可访问的项目:', projects.data);

查询工作项详情

import { NewQueryWorkItemDetailReqBuilder } from '@linmi/meegle-sdk-typescript';

const detailReq = NewQueryWorkItemDetailReqBuilder()
  .ProjectKey('my-project')
  .WorkItemTypeKey('task')
  .WorkItemIds([1001, 1002])
  .Fields(['name', 'priority', 'assignee', 'status'])  // 只返回需要的字段
  .Expand({
    need_workflow: true,        // 包含工作流信息
    need_user_detail: true,     // 包含用户详情
    need_multi_text: true       // 包含富文本详情
  })
  .build();

const details = await client.WorkItem.QueryWorkItemDetail(
  detailReq, 
  WithUserKey('your-user-key')
);

工作流操作

// 查询工作流信息
const workflowReq = {
  // ... 省略配置
  Body: {
    flow_type: 0,  // 节点流
    expand: { need_workflow: true }
  }
};

const workflow = await client.WorkItem.QueryWorkflow(workflowReq);

// 状态流转
const stateChangeReq = {
  // ... 省略配置  
  Body: {
    transition_id: 12345,
    role_owners: [
      { role_key: 'reviewer', user_keys: ['reviewer_user_key'] }
    ]
  }
};

await client.WorkItem.NodeStateChange(stateChangeReq);

🔧 配置选项

基础配置

import { 
  NewClient,
  WithBaseUrl,
  WithLogLevel,
  WithReqTimeout,
  WithAccessTokenType
} from '@linmi/meegle-sdk-typescript';

const client = NewClient(
  'app-id',
  'app-secret',
  WithBaseUrl('https://project.feishu.cn'),      // 官方API地址
  WithLogLevel('info'),                          // 日志级别: debug | info | warn | error
  WithReqTimeout(30000),                         // 请求超时时间（毫秒）
  WithAccessTokenType('user_access_token')       // 令牌类型
);

私有化部署

// 私有化部署的客户端配置
const privateClient = NewClient(
  'app-id',
  'app-secret',
  WithBaseUrl('https://your-private-domain.com')  // 使用您的私有化地址
);

🆘 常见问题

Q: 如何获取 App ID 和 App Secret？

A: 在 飞书项目开放平台 创建应用后，在应用详情页面可以找到这些信息。

Q: 如何获取 User Key？

A: 在飞书项目中，双击个人头像即可看到 User Key。

Q: 字段值格式错误怎么办？

A: 使用我们提供的类型安全构建器，IDE 会自动提示正确的格式：

// ✅ 使用类型安全的方式
const search = NewTypedSearchBuilder()
  .select('priority').equals('high');  // IDE 会提示正确格式

// ❌ 避免手动构建
const search = { field_key: 'priority', operator: '=', value: 'wrong' };

Q: API 调用失败怎么排查？

A: 检查响应的错误信息：

const result = await client.WorkItem.Create(req, WithUserKey('your-user-key'));

if (result.err_code !== 0) {
  console.error('错误码:', result.err_code);
  console.error('错误信息:', result.err_msg);
  
  if (result.err) {
    console.error('详细错误:', result.err.msg);
    console.error('请求ID:', result.err.log_id);  // 用于技术支持
  }
}

Q: 如何提升性能？

A:

1. 使用批量操作API处理多个工作项
2. 指定 fields 参数只返回需要的字段
3. 合理使用 expand 参数避免多次请求

📊 性能指标

• 包大小: 77KB（gzip 压缩后）
• 类型定义: 109KB（完整的 TypeScript 支持）
• API 覆盖率: 95%（支持 90+ API 端点）
• 浏览器兼容: Chrome 80+, Firefox 80+, Safari 14+
• Node.js 兼容: 18.0.0+

🎉 v1.1.0 新特性

🔒 企业级类型安全

• 25+ 字段类型的完整定义
• 15+ 搜索操作符的类型安全
• 编译时错误检查，运行时零意外

🛠️ 智能构建器

• TypedSearchBuilder：类型安全的搜索条件构建
• AdvancedSearchBuilder：高级搜索功能
• BatchUpdateReqBuilder：批量操作构建器

📦 强大的批量操作

• 批量更新（最多100个工作项）
• 批量删除和状态变更（最多50个工作项）
• 批量操作结果追踪

🎯 开发者体验

• IDE 智能提示和自动补全
• 详细的错误类型和处理
• 丰富的使用示例和最佳实践

🔗 相关链接

• 📖 API 文档
• 🐛 问题反馈
• 💬 讨论交流
• 📦 NPM 包

📄 许可证

Apache License 2.0 - 详见 LICENSE 文件