npm package: @linmi/meegle-sdk-typescript
Description: TypeScript/JavaScript SDK for Meegle API - A powerful project management and work item tracking platform
Author: Linmi
Latest version: 1.1.1

# @linmi/meegle-sdk-typescript

[![npm version](https://badge.fury.io/js/@linmi%2Fmeegle-sdk-typescript.svg)](https://badge.fury.io/js/@linmi%2Fmeegle-sdk-typescript)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.8-blue.svg)](https://www.typescriptlang.org/)

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

## ✨ 特性

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

## 📦 安装

```bash
npm install @linmi/meegle-sdk-typescript
```

## 🚀 5分钟快速开始

### 1. 创建客户端

```typescript
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. 创建工作项

```typescript
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. 智能搜索工作项

```typescript
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, '个工作项');
```

## 🎯 核心功能

### 🔒 类型安全的字段操作

```typescript
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
};
```

### 📦 强大的批量操作

```typescript
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'));
```

### 🔍 智能搜索构建器

```typescript
// 构建复杂的搜索条件
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 操作（创建、查询、更新、删除）
- ✅ 批量操作（批量更新、删除、状态变更）
- ✅ 搜索和筛选（智能搜索构建器）
- ✅ 工作流管理（状态流转、节点操作）
- ✅ 附件管理（上传、下载）
- ✅ 评论管理

### 用户和权限
- ✅ 用户搜索和详情
- ✅ 用户组管理
- ✅ 角色配置

### 视图和报表
- ✅ 固定视图和条件视图
- ✅ 全景视图
- ✅ 数据度量和图表

## 📚 常用示例

### 获取项目信息

```typescript
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);
```

### 查询工作项详情

```typescript
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')
);
```

### 工作流操作

```typescript
// 查询工作流信息
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);
```

## 🔧 配置选项

### 基础配置

```typescript
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')       // 令牌类型
);
```

### 私有化部署

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

## 🆘 常见问题

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

**A:** 在 [飞书项目开放平台](https://project.feishu.cn/openapp/home) 创建应用后，在应用详情页面可以找到这些信息。

### Q: 如何获取 User Key？

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

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

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

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

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

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

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

```typescript
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 文档](https://meegle.linmi.cc)
- 🐛 [问题反馈](https://github.com/linmi/meegle-sdk-typescript/issues)
- 💬 [讨论交流](https://github.com/linmi/meegle-sdk-typescript/discussions)
- 📦 [NPM 包](https://www.npmjs.com/package/@linmi/meegle-sdk-typescript)

## 📄 许可证

Apache License 2.0 - 详见 [LICENSE](LICENSE) 文件

---