飞书自用 n8n 节点包

这是一个自用的 n8n 自定义节点包，用于与飞书API交互。当前支持邮件联系人功能，未来将扩展更多功能。

🚀 功能特性

✅ 当前功能

• 📧 邮件联系人管理
  • ✅ 创建邮件联系人 - 在指定邮箱中创建新的邮件联系人
  • ✅ 删除邮件联系人 - 删除指定的邮件联系人
  • ✅ 更新邮件联系人 - 更新现有邮件联系人的信息
  • ✅ 列出邮件联系人 - 获取邮箱中的所有邮件联系人列表

🔮 未来规划功能

• 📋 飞书表格操作
• 📅 日历管理
• 📝 文档操作
• 💬 消息发送
• 👥 用户管理
• 🏢 组织架构管理

🔐 认证机制

支持两种认证方式：

1. 应用凭证认证 - 使用 App ID 和 App Secret
2. OAuth2 认证 - 使用用户授权令牌

📁 项目结构

n8n-nodes-feishu-self/
├── 📄 package.json                      # 项目配置文件
├── 📄 tsconfig.json                    # TypeScript 配置
├── 📄 index.ts                         # 主入口文件
├── 📄 README.md                        # 项目文档
├── 📄 .eslintrc.js                     # 代码检查配置
├── 📄 .prettierrc.js                   # 代码格式化配置
├── 📁 credentials/                     # 认证配置目录
│   ├── 📄 LarkTokenApi.credentials.ts  # 应用凭证认证
│   ├── 📄 LarkOAuth2Api.credentials.ts # OAuth2 认证
│   └── 🖼️ lark_icon.svg               # 飞书图标
└── 📁 nodes/                          # 节点目录
    └── 📁 FeishuSelf/                 # 飞书自用节点
        ├── 📄 FeishuSelf.node.ts      # 主节点文件
        ├── 📄 GenericFunctions.ts     # 通用函数
        ├── 📁 help/                   # 辅助工具
        │   ├── 📁 type/
        │   │   └── 📄 enums.ts        # 枚举类型定义
        │   └── 📁 utils/
        │       └── 📄 RequestUtils.ts # 请求工具类
        └── 📁 resource/               # 资源操作
            ├── 📄 MailContact.resource.ts # 邮件联系人资源描述
            └── 📁 mail/
                ├── 📄 CreateMailContact.operation.ts    # 创建邮件联系人
                ├── 📄 DeleteMailContact.operation.ts    # 删除邮件联系人
                ├── 📄 UpdateMailContact.operation.ts    # 更新邮件联系人
                └── 📄 ListMailContacts.operation.ts     # 列出邮件联系人

🛠 安装配置

1. 安装节点包

cd /path/to/n8n
npm install n8n-nodes-feishu-self

2. 重启 n8n 服务

# 重启 n8n 服务使新节点生效

3. 配置飞书应用凭证

方法一：应用凭证认证

1. 访问 飞书开放平台
2. 创建应用或选择现有应用
3. 获取 App ID 和 App Secret
4. 在 n8n 中创建凭证：
   • 选择 "飞书应用凭证 API"
   • 填入 App ID 和 App Secret
   • 选择合适的 Base URL

方法二：OAuth2 认证

1. 在飞书开放平台配置 OAuth2 应用
2. 设置重定向 URI
3. 配置权限范围
4. 在 n8n 中创建 OAuth2 凭证并完成授权流程

📖 使用方法

创建邮件联系人

操作参数：

• 邮箱ID - 目标邮箱的唯一标识
• 联系人姓名 - 联系人姓名（必填）
• 邮箱地址 - 联系人邮箱（必填）
• 电话号码 - 联系人电话（可选）
• 公司 - 联系人所在公司（可选）
• 职位 - 联系人职位（可选）

示例输入：

{
  "operation": "createMailContact",
  "mailboxId": "your_mailbox_id",
  "name": "张三",
  "email": "[email protected]",
  "phone": "13800138000",
  "company": "示例公司",
  "title": "产品经理"
}

删除邮件联系人

操作参数：

• 邮箱ID - 目标邮箱的唯一标识
• 邮件联系人ID - 要删除的联系人ID

更新邮件联系人

操作参数：

• 邮箱ID - 目标邮箱的唯一标识
• 邮件联系人ID - 要更新的联系人ID
• 更新字段 - 选择要更新的字段和值

支持的字段：

• 姓名
• 邮箱地址
• 电话号码
• 公司
• 职位

列出邮件联系人

操作参数：

• 邮箱ID - 目标邮箱的唯一标识
• 分页大小 - 每页返回的数量（1-100）
• 分页标记 - 分页令牌（可选）
• 返回全部 - 是否返回所有结果
• 最大项目数 - 最大返回数量

🔧 API 参考

支持的 API 端点

• POST /open-apis/mail/v1/user_mailboxes/{mailbox_id}/mail_contacts - 创建邮件联系人
• DELETE /open-apis/mail/v1/user_mailboxes/{mailbox_id}/mail_contacts/{mail_contact_id} - 删除邮件联系人
• PATCH /open-apis/mail/v1/user_mailboxes/{mailbox_id}/mail_contacts/{mail_contact_id} - 更新邮件联系人
• GET /open-apis/mail/v1/user_mailboxes/{mailbox_id}/mail_contacts - 列出邮件联系人

错误处理

• 完善的错误处理机制
• 支持 "Continue on Fail" 选项
• 自动处理认证令牌过期和重新获取
• 详细的错误信息返回

🚀 开发指南

构建项目

npm run build

开发模式

npm run dev

运行测试

npm test

代码格式化

npm run format

代码检查

npm run lint
npm run lintfix

🎯 扩展指南

本项目采用模块化设计，便于添加新功能：

添加新资源类型

1. 在 nodes/FeishuSelf/help/type/enums.ts 中添加新的操作类型
2. 在 nodes/FeishuSelf/resource/ 中创建新的资源文件
3. 在主节点文件中添加新的资源选项
4. 实现相应的操作文件

示例：添加新功能

// 1. 在 enums.ts 中添加
export declare const enum NewFeatureOperationType {
  CreateNewItem = 'createNewItem',
  // ... 其他操作
}

// 2. 在主节点中添加资源选项
{
  name: '新功能',
  value: 'newFeature',
  description: '新的飞书功能',
}

// 3. 创建相应的操作文件
// nodes/FeishuSelf/resource/newFeature/CreateNewItem.operation.ts

📄 许可证

MIT License

🤝 贡献

欢迎提交 Issue 和 Pull Request！

🔗 相关链接

• 飞书开放平台文档
• n8n 官方文档
• n8n 节点开发指南
• 飞书邮件联系人 API

📝 更新日志

v1.0.0 (2024-11-05)

• ✨ 初始版本发布
• ✅ 支持邮件联系人管理功能
• 🔐 支持应用凭证和 OAuth2 认证
• 📧 包含创建、删除、更新、列出邮件联系人操作
• 🛠 完整的错误处理和参数验证
• 📚 完善的文档和使用指南

注意： 这是一个自用节点包，当前专注于邮件联系人功能。未来将根据需要逐步扩展更多飞书API功能。