@lixiongwei/n8n-nodes-feishu 1.0.1 → 2.0.0

package/README.md

@@ -1,72 +1,138 @@
-# n8n-nodes-feishu
+# @lixiongwei/n8n-nodes-feishu
 
-> 飞书/Lark 集成节点，免费功能 + Pro License。附带 5 个即用工作流模板。
+> **Feishu / Lark** integration nodes for n8n — messaging, Bitable CRUD, approvals, calendar & contacts.
+> Free tier + Pro License. Includes workflow templates.
 
 ---
 
-## 安装
+## 📦 Install
 
 ```bash
 npm install @lixiongwei/n8n-nodes-feishu
 ```
 
-n8n 自托管版直接在 n8n 所在目录执行。云版不支持社区节点。
+Requires: n8n self-hosted. (n8n Cloud does not support community nodes.)
 
 ---
 
-## 免费功能 🆓
+## 🎮 Capabilities
 
-| 功能 | 说明 |
-|------|------|
-| **发送文本消息** | 给用户/群发文本消息 |
-| **消息触发器** | 接收飞书事件回调 |
+### 🆓 Free
+
+| Category | Operation | Description |
+|----------|-----------|-------------|
+| **Messaging** | Send Text Message | Send plain text to users or groups |
+| **Trigger** | Message Received | Webhook — fires when the bot receives a message |
+
+### ⭐ Pro — $49 one-time ([get a key](https://1717465779306.gumroad.com/l/feishu-pro))
+
+| Category | Operations |
+|----------|------------|
+| **Messaging** | Send Card Message (with Markdown & color), Send Image, Send File, Batch Send to multiple recipients |
+| **Bitable** | Read Records, Create Record, Update Record, Delete Record, Search Records, List Tables |
+| **Approvals** | List Pending, Get Detail, Approve, Reject |
+| **Calendar** | List Events, Create Event |
+| **Contacts** | Get User Info (by Open ID / Email / Mobile), Search Users |
 
 ---
 
-## Pro 功能 ⭐ （需 License Key）
+## 🚀 Quick Start (3 steps)
+
+### 1. Create a Feishu/Lark app
+
+1. Go to [Feishu Dev Console](https://open.feishu.cn/) (or [Lark Dev Console](https://open.larksuite.com/))
+2. Create an **Enterprise Internal App**
+3. Enable **Bot** capability (App Capabilities → Bot → Enable)
+4. Go to **Permissions** → add at minimum:
+   - `im:message:send_as_bot` (send messages)
+   - `contact:contact.base:readonly` (for Contacts operations)
+5. Go to **Version Management** → Create version → **Publish**
+6. Copy your **App ID** and **App Secret** from Credentials & Basic Info
 
-| 功能 | 说明 |
-|------|------|
-| **发送卡片消息** | 富文本卡片模板 + Markdown |
-| **读取多维表格** | 按字段读取 Bitable 数据 |
-| **写入多维表格** | 写入新行到 Bitable |
-| **获取待审批列表** | 查询审批实例 |
+### 2. Configure n8n
+
+1. n8n → **Credentials** → New → search `Feishu` → select **Feishu / Lark API**
+2. Choose your platform (Feishu for China, Lark for International)
+3. Enter App ID + App Secret
+4. (Optional) Enter License Key for Pro features
+
+### 3. Start building
+
+Drag the **Feishu / Lark** node onto your canvas → select a Resource → select an Operation → configure → test.
 
 ---
 
-## 获取 License Key
+## 📋 Included Workflow Templates
 
-👉 **[在 Gumroad 购买](https://gumroad.com/l/feishu-pro)** — $49 一次性，永久使用。
+Import these from `node_modules/@lixiongwei/n8n-nodes-feishu/workflows/` or from the [GitHub repo](https://github.com/lixiongwei/n8n-nodes-feishu):
 
-购买后在凭证管理里填入 Key，Pro 功能即刻解锁。
+| # | File | What it does |
+|---|------|-------------|
+| 1 | `template-01-send-message.json` | External Webhook → Feishu text message (CI/CD alerts, form notifications) |
+| 2 | `template-02-cron-reminder.json` | Scheduled → Feishu reminder (daily standup, deadline alerts) |
+| 3 | `template-03-website-monitor.json` | Monitor website health → Feishu alert on downtime |
+| 4 | `template-04-form-notify.json` | Form submission → Feishu card notification |
+| 5 | `template-05-api-to-feishu.json` | Pull external API data → format → push to Feishu |
 
 ---
 
-## 附带工作流模板
+## 🔧 Common Patterns
 
-在 `workflows/` 目录下，导入即用：
+| I want to... | Use this setup |
+|-------------|---------------|
+| Get alerts when my site goes down | Template 03 — Cron + HTTP Check + If + Feishu Message |
+| Send a daily report to my team | Template 02 — Cron + Feishu Card Message |
+| Track form submissions in Bitable | Webhook → Feishu Bitable Create Record → Feishu Card to notify team |
+| Auto-approve simple requests | Feishu Trigger (Approval) → If (conditions) → Approve Instance |
+| Search users for open_ids | Contacts → Search Users → use output in subsequent Message node |
+| Build a bot that replies to messages | Feishu Trigger (Message) → AI/Logic → Feishu Send Text Message |
+
+---
 
-| 模板 | 场景 |
-|------|------|
-| `template-01-send-message.json` | Webhook → 飞书消息 |
-| `template-02-cron-reminder.json` | 定时 → 飞书提醒 |
-| `template-03-website-monitor.json` | 网站监控 → 飞书告警 |
-| `template-04-form-notify.json` | 表单提交 → 卡片通知 |
-| `template-05-api-to-feishu.json` | API 数据 → 飞书推送 |
+## ⚠️ Troubleshooting
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `Bot ability not activated (230006)` | Bot not enabled in app | App Capabilities → Enable Bot → Republish |
+| `Permission denied (99991672)` | Missing API scope | Permissions → Add required scope → Republish |
+| `Recipient ID not found (99992351)` | Wrong ID type or not in app scope | Use Contacts → Get User Info to find the correct ID |
+| `Invalid tenant access token` | Wrong App ID or Secret | Double-check from Developer Console → Credentials |
+| `This is a Pro feature` | No license key | Get one at the Gumroad link, or use a Free operation |
+| Workflow stuck spinning | Method is GET instead of POST | Check the node configuration — content-sending operations need POST |
+| Webhook URL not receiving events | App not configured for events | Add Request URL in Feishu Dev Console → Event Subscriptions |
 
 ---
 
-## 飞书应用配置
+## 🌍 Feishu vs Lark
+
+Feishu (飞书) and Lark share the same API but use **different domains**:
+
+| Platform | API Base | Used in |
+|----------|----------|---------|
+| Feishu | `open.feishu.cn` | China |
+| Lark | `open.larksuite.com` | International (Singapore, US, etc.) |
 
-1. 飞书开发者后台创建 **企业自建应用**
-2. 开启 **机器人** 能力
-3. 权限管理开通：`im:message:send_as_bot`
-4. 发布应用
-5. 在 n8n 凭证中填入 App ID + App Secret + License Key
+Choose the correct platform in your n8n credentials. If you get `99991663` errors, you likely have the wrong platform selected.
 
 ---
 
-## 版本
+## 💰 License
+
+```
+npm install → FREE features work immediately
+         ↓
+  Try Pro operation → prompted for License Key
+         ↓
+  Get Key: https://1717465779306.gumroad.com/l/feishu-pro
+         ↓
+  Enter Key in credentials → ALL features unlocked forever
+```
+
+One-time payment. No subscription. Lifetime access.
+
+---
 
-- n8n 版本要求：1.x+
-- 飞书 API 版本：v3
+- **n8n version**: 1.x+ (v2 recommended)
+- **Feishu API**: v3
+- **License**: MIT
+- **Support**: Reply on [n8n Community Forum](https://community.n8n.io/c/community-nodes/11)

package/credentials/FeishuApi.credentials.js

@@ -4,15 +4,34 @@ exports.FeishuApi = void 0;
 class FeishuApi {
     constructor() {
         this.name = 'feishuApi';
-        this.displayName = '飞书 Feishu API';
+        this.displayName = 'Feishu / Lark API';
         this.documentationUrl = 'https://open.feishu.cn/document/home/getting-started';
         this.properties = [
+            {
+                displayName: 'Platform',
+                name: 'platform',
+                type: 'options',
+                options: [
+                    {
+                        name: 'Feishu (飞书) — China',
+                        value: 'feishu',
+                        description: 'API domain: open.feishu.cn',
+                    },
+                    {
+                        name: 'Lark — International',
+                        value: 'lark',
+                        description: 'API domain: open.larksuite.com',
+                    },
+                ],
+                default: 'feishu',
+                description: 'Choose Feishu for China, Lark for international users',
+            },
             {
                 displayName: 'App ID',
                 name: 'appId',
                 type: 'string',
                 default: '',
-                description: '飞书应用的 App ID（从开发者后台-凭证与基础信息获取）',
+                description: 'From Developer Console → Credentials & Basic Info',
                 required: true,
             },
             {
@@ -21,15 +40,14 @@ class FeishuApi {
                 type: 'string',
                 typeOptions: { password: true },
                 default: '',
-                description: '飞书应用的 App Secret',
                 required: true,
             },
             {
-                displayName: 'License Key',
+                displayName: 'License Key (optional)',
                 name: 'licenseKey',
                 type: 'string',
                 default: '',
-                description: 'Pro License Key — 从 Gumroad 购买获取。留空则仅使用免费功能',
+                description: 'Pro License Key → Unlock all features. Leave empty for free features. Get one: https://1717465779306.gumroad.com/l/feishu-pro',
                 required: false,
             },
         ];