n8n-nodes-excel-api 1.0.0

package/README.md

@@ -0,0 +1,522 @@
+# n8n-nodes-excel-api
+
+[![npm version](https://badge.fury.io/js/n8n-nodes-excel-api.svg)](https://badge.fury.io/js/n8n-nodes-excel-api)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+n8n 社群節點，透過 API 存取 Excel 檔案，具備**並行安全保護**。完美適用於多使用者同時透過 n8n 工作流程存取相同 Excel 檔案的場景。
+
+## 🎯 為什麼需要這個節點？
+
+### 問題所在
+直接在 n8n 中使用 Excel 檔案時：
+- ❌ 多個工作流程同時存取同一檔案會導致檔案損毀
+- ❌ 並行寫入時會發生資料覆蓋與遺失
+- ❌ 缺乏檔案鎖定機制
+- ❌ 難以處理多人同時提交的 Webhook 表單
+
+### 解決方案
+本節點搭配 [Excel API Server](https://github.com/code4Copilot/excel-api-server) 提供：
+- ✅ **檔案鎖定** - 自動佇列管理並行請求
+- ✅ **資料完整性** - 無資料遺失或損毀
+- ✅ **多使用者支援** - 完美適用於多人提交的 HTML 表單
+- ✅ **類似 Google Sheets 的介面** - 在 n8n 中熟悉的操作方式
+- ✅ **批次操作** - 高效的大量更新
+
+## 📦 安裝方式
+
+### 方法 1：npm（推薦）
+
+```bash
+npm install n8n-nodes-excel-api
+```
+
+### 方法 2：手動安裝
+
+```bash
+# 1. 複製儲存庫
+git clone https://github.com/code4Copilot/n8n-nodes-excel-api.git
+cd n8n-nodes-excel-api
+
+# 2. 安裝相依套件
+npm install
+
+# 3. 建置
+npm run build
+
+# 4. 連結到 n8n
+npm link
+cd ~/.n8n
+npm link n8n-nodes-excel-api
+
+# 5. 重新啟動 n8n
+n8n start
+```
+
+### 方法 3：社群套件（發布後）
+
+在 n8n 中：
+1. 前往 **設定** → **社群節點**
+2. 點擊 **安裝**
+3. 輸入：`n8n-nodes-excel-api`
+4. 點擊 **安裝**
+
+## 🚀 前置需求
+
+**必須先執行 Excel API Server！**
+
+安裝並啟動 [Excel API Server](https://github.com/code4Copilot/excel-api-server)：
+
+```bash
+# 使用 Docker 快速啟動
+docker run -d \
+  -p 8000:8000 \
+  -v $(pwd)/data:/app/data \
+  -e API_TOKEN=your-secret-token \
+  yourusername/excel-api-server
+```
+
+詳細資訊請參閱 [Excel API Server 文件](https://github.com/code4Copilot/excel-api-server)。
+
+## 🔧 設定
+
+### 1. 設定憑證
+
+在 n8n 中：
+1. 前往 **憑證** → **新增**
+2. 搜尋「Excel API」
+3. 填寫：
+   - **API URL**：`http://localhost:8000`（您的 API 伺服器位址）
+   - **API Token**：`your-secret-token`（來自 Excel API Server）
+4. 點擊 **儲存**
+
+### 2. 將節點加入工作流程
+
+1. 建立或開啟工作流程
+2. 點擊 **新增節點**
+3. 搜尋「Excel API」
+4. 選擇節點
+5. 選擇您的憑證
+6. 設定操作
+
+## 📚 操作說明
+
+### 1. Append（附加）
+在工作表末端新增一列資料。
+
+**兩種模式：**
+
+#### Object Mode（物件模式）- 推薦
+使用欄位名稱對應，更安全且易於維護。
+
+**範例：**
+```json
+{
+  "員工編號": "{{ $json.body.employeeId }}",
+  "姓名": "{{ $json.body.name }}",
+  "部門": "{{ $json.body.department }}",
+  "職位": "{{ $json.body.position }}",
+  "薪資": "{{ $json.body.salary }}"
+}
+```
+
+**特色：**
+- ✅ 自動讀取 Excel 表頭（第一列）
+- ✅ 按照欄位名稱智能對應
+- ✅ 忽略未知欄位，並在回應中提示
+- ✅ 欄位順序可任意調整
+- ✅ 缺少的欄位會自動填入空值
+
+#### Array Mode（陣列模式）
+依照精確的欄位順序指定值。
+
+**範例：**
+```json
+["E100", "江小魚", "人資部", "經理", "70000"]
+```
+
+**注意：** 值的順序必須與 Excel 欄位順序完全對應。
+
+### 2. Read（讀取）
+從 Excel 檔案讀取資料。
+
+**參數：**
+- `file`：檔案名稱（例如：`employees.xlsx`）
+- `sheet`：工作表名稱（預設：`Sheet1`）
+- `range`：儲存格範圍（例如：`A1:D10`，留空讀取全部資料）
+
+**輸出：**
+- 若偵測到表頭，自動將第一列轉換為欄位名稱
+- 回傳物件陣列，以表頭作為鍵值
+- 若無表頭則回傳原始資料陣列
+
+### 3. Update（更新）
+更新現有列的資料。
+
+**識別方式：**
+
+#### 依列號（Row Number）
+直接指定要更新的列號（從 2 開始，第 1 列為表頭）。
+
+**範例：**
+```json
+{
+  "operation": "update",
+  "identifyBy": "rowNumber",
+  "rowNumber": 5,
+  "valuesToSet": {
+    "狀態": "已完成",
+    "更新日期": "2025-12-21"
+  }
+}
+```
+
+#### 依查找（Lookup）
+透過查找特定欄位的值來找到要更新的列。
+
+**範例：**
+```json
+{
+  "operation": "update",
+  "identifyBy": "lookup",
+  "lookupColumn": "員工編號",
+  "lookupValue": "E100",
+  "valuesToSet": {
+    "薪資": "80000",
+    "職位": "資深經理"
+  }
+}
+```
+
+### 4. Delete（刪除）
+從工作表中刪除一列。
+
+**識別方式：**
+
+#### 依列號
+```json
+{
+  "operation": "delete",
+  "identifyBy": "rowNumber",
+  "rowNumber": 5
+}
+```
+
+#### 依查找
+```json
+{
+  "operation": "delete",
+  "identifyBy": "lookup",
+  "lookupColumn": "員工編號",
+  "lookupValue": "E100"
+}
+```
+
+### 5. Batch（批次）
+一次執行多個操作（更有效率）。
+
+**範例：**
+```json
+{
+  "operations": [
+    {
+      "type": "append",
+      "values": ["E010", "Alice", "行銷部", "專員", "65000"]
+    },
+    {
+      "type": "update",
+      "row": 5,
+      "values": ["E005", "Updated Name", "IT部", "經理", "90000"]
+    },
+    {
+      "type": "delete",
+      "row": 10
+    }
+  ]
+}
+```
+
+## 🎨 使用範例
+
+## 🎨 使用範例
+
+### 範例 1：Webhook 表單寫入 Excel
+
+完美適用於多人同時提交表單的場景！
+
+```
+┌──────────────────┐
+│ Webhook          │  接收表單提交
+│ POST /submit     │
+└────────┬─────────┘
+         │
+         ▼
+┌──────────────────┐
+│ Excel API        │  操作：Append（物件模式）
+│                  │  檔案：registrations.xlsx
+│                  │  值：{
+│                  │    "姓名": "{{ $json.body.name }}",
+│                  │    "Email": "{{ $json.body.email }}",
+│                  │    "電話": "{{ $json.body.phone }}",
+│                  │    "提交時間": "{{ $now }}"
+│                  │  }
+└────────┬─────────┘
+         │
+         ▼
+┌──────────────────┐
+│ Respond Webhook  │  回傳成功訊息
+└──────────────────┘
+```
+
+**HTML 表單：**
+```html
+<form id="registrationForm">
+  <input type="text" name="name" placeholder="姓名" required>
+  <input type="email" name="email" placeholder="Email" required>
+  <input type="tel" name="phone" placeholder="電話" required>
+  <button type="submit">提交</button>
+</form>
+
+<script>
+document.getElementById('registrationForm').addEventListener('submit', async (e) => {
+  e.preventDefault();
+  const formData = new FormData(e.target);
+  await fetch('YOUR_WEBHOOK_URL', {
+    method: 'POST',
+    headers: {'Content-Type': 'application/json'},
+    body: JSON.stringify(Object.fromEntries(formData))
+  });
+  alert('提交成功！');
+});
+</script>
+```
+
+### 範例 2：每日報表產生
+
+```
+┌──────────────────┐
+│ Schedule         │  每天早上 9:00
+│ 0 9 * * *        │
+└────────┬─────────┘
+         │
+         ▼
+┌──────────────────┐
+│ Excel API        │  操作：Read
+│ (讀取)           │  檔案：sales.xlsx
+└────────┬─────────┘
+         │
+         ▼
+┌──────────────────┐
+│ Filter           │  篩選今日記錄
+└────────┬─────────┘
+         │
+         ▼
+┌──────────────────┐
+│ Send Email       │  發送每日報表
+└──────────────────┘
+```
+
+### 範例 3：批次更新
+
+```
+┌──────────────────┐
+│ Code             │  準備操作陣列
+│                  │  operations = [...]
+└────────┬─────────┘
+         │
+         ▼
+┌──────────────────┐
+│ Excel API        │  操作：Batch
+│ (批次)           │  檔案：data.xlsx
+│                  │  操作：{{ $json.operations }}
+└──────────────────┘
+```
+
+### 範例 4：透過員工編號更新薪資
+
+```
+┌──────────────────┐
+│ Webhook          │  接收更新請求
+│ POST /update     │  { "employeeId": "E100", "salary": 85000 }
+└────────┬─────────┘
+         │
+         ▼
+┌──────────────────┐
+│ Excel API        │  操作：Update
+│                  │  識別方式：Lookup
+│                  │  查找欄位：員工編號
+│                  │  查找值：{{ $json.body.employeeId }}
+│                  │  設定值：{ "薪資": "{{ $json.body.salary }}" }
+└────────┬─────────┘
+         │
+         ▼
+┌──────────────────┐
+│ Respond Webhook  │  回傳更新結果
+└──────────────────┘
+```
+
+## 🧪 並行測試
+
+測試 10 個同時提交：
+
+```javascript
+// concurrent_test.js
+const promises = [];
+for (let i = 0; i < 10; i++) {
+  promises.push(
+    fetch('YOUR_WEBHOOK_URL', {
+      method: 'POST',
+      headers: {'Content-Type': 'application/json'},
+      body: JSON.stringify({
+        員工編號: `E${String(i).padStart(3, '0')}`,
+        姓名: `測試使用者 ${i}`,
+        時間戳記: new Date().toISOString()
+      })
+    })
+  );
+}
+
+await Promise.all(promises);
+console.log('所有請求完成！');
+```
+
+**結果：** 所有 10 筆記錄都會安全地寫入 Excel，不會有資料遺失或損毀！
+
+## ⚠️ 常見問題
+
+### 問題 1：節點未顯示在 n8n 中
+
+**解決方法：**
+```bash
+# 重新啟動 n8n
+pkill -f n8n
+n8n start
+
+# 或使用 pm2
+pm2 restart n8n
+```
+
+### 問題 2：API 連線失敗
+
+**解決方法：**
+- 檢查 Excel API Server 是否正在執行：`curl http://localhost:8000/`
+- 驗證憑證中的 API URL 是否正確
+- 檢查 API Token 是否正確
+- 檢查防火牆設定
+
+### 問題 3：「找不到參數」錯誤
+
+**原因：** 參數名稱設定錯誤
+
+**解決方法：**
+- 確認選擇了正確的 Append Mode（Object 或 Array）
+- Object Mode：使用 `appendValuesObject` 參數
+- Array Mode：使用 `appendValuesArray` 參數
+- 檢查 JSON 格式是否正確
+
+### 問題 4：「檔案鎖定」錯誤
+
+**原因：** 並行請求過多或 API 伺服器問題
+
+**解決方法：**
+- 稍等片刻後重試
+- 檢查 API 伺服器狀態
+- 必要時重新啟動 Excel API Server
+
+## 🔐 安全性
+
+### 最佳實踐
+
+1. **使用強式 API Token**
+   ```bash
+   # 產生安全的 token
+   openssl rand -hex 32
+   ```
+
+2. **在正式環境使用 HTTPS**
+   - 設定反向代理（Nginx）
+   - 使用 SSL 憑證
+
+3. **限制存取**
+   - 僅允許信任的網路存取 API URL
+   - 遠端存取時使用 VPN
+
+4. **定期備份**
+   - 設定 Excel 檔案自動備份
+   - 將備份儲存在安全位置
+
+## 📊 效能優化建議
+
+### 1. 使用批次操作
+```javascript
+// ❌ 不好：多次單一操作
+for (item of items) {
+  await appendRow(item);
+}
+
+// ✅ 好：一次批次操作
+await batchOperations(items.map(item => ({
+  type: "append",
+  values: item.values
+})));
+```
+
+### 2. 讀取時指定範圍
+```javascript
+// ❌ 不好：讀取整個檔案
+range: ""
+
+// ✅ 好：只讀取需要的範圍
+range: "A1:D100"
+```
+
+### 3. 使用高效的工作流程
+- 在一個工作流程中組合相關操作
+- 減少 API 呼叫次數
+- 適當使用快取
+
+## 🆕 最新功能
+
+### Object Mode（物件模式）
+- ✅ 使用 `/api/excel/append_object` API
+- ✅ 自動讀取 Excel 表頭（第一列）
+- ✅ 按照欄位名稱智能對應
+- ✅ 忽略未知欄位，並在回應中提示
+- ✅ 不需要記住欄位順序
+
+### 進階更新與刪除
+- ✅ 支援依列號直接操作
+- ✅ 支援依查找欄位值來操作
+- ✅ 可更新特定欄位而不影響其他欄位
+
+## 🤝 貢獻
+
+歡迎貢獻！
+
+1. Fork 此儲存庫
+2. 建立您的功能分支：`git checkout -b feature/AmazingFeature`
+3. 提交您的變更：`git commit -m 'Add some AmazingFeature'`
+4. 推送到分支：`git push origin feature/AmazingFeature`
+5. 開啟 Pull Request
+
+## 📄 授權
+
+MIT 授權 - 詳見 [LICENSE](LICENSE) 檔案
+
+## 🔗 相關專案
+
+- [Excel API Server](https://github.com/code4Copilot/excel-api-server) - 後端 API 伺服器（必要）
+- [n8n](https://github.com/n8n-io/n8n) - 工作流程自動化工具
+
+## 📧 支援
+
+- GitHub Issues：[回報問題](https://github.com/code4Copilot/n8n-nodes-excel-api/issues)
+- Email：your.email@example.com
+- n8n 社群：[n8n 論壇](https://community.n8n.io)
+
+## ⭐ Star 歷史
+
+如果這個專案對您有幫助，請給它一個 ⭐！
+
+---
+
+**用 ❤️ 為 n8n 社群打造**

package/dist/credentials/ExcelApiAuth.credentials.d.ts

@@ -0,0 +1,7 @@
+import { ICredentialType, INodeProperties } from 'n8n-workflow';
+export declare class ExcelApiAuth implements ICredentialType {
+    name: string;
+    displayName: string;
+    documentationUrl: string;
+    properties: INodeProperties[];
+}

package/dist/credentials/ExcelApiAuth.credentials.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExcelApiAuth = void 0;
+class ExcelApiAuth {
+    constructor() {
+        this.name = 'excelApiAuth';
+        this.displayName = 'Excel API Auth';
+        this.documentationUrl = 'https://your-docs-url.com';
+        this.properties = [
+            {
+                displayName: 'API URL',
+                name: 'url',
+                type: 'string',
+                default: 'http://localhost:8000',
+                required: true,
+                description: 'The base URL of your Excel API server',
+                placeholder: 'http://localhost:8000',
+            },
+            {
+                displayName: 'API Token',
+                name: 'token',
+                type: 'string',
+                typeOptions: {
+                    password: true,
+                },
+                default: '',
+                required: true,
+                description: 'The API token for authentication',
+            },
+        ];
+    }
+}
+exports.ExcelApiAuth = ExcelApiAuth;

package/dist/nodes/ExcelApi/ExcelApi.node.d.ts

@@ -0,0 +1,11 @@
+import { IExecuteFunctions, ILoadOptionsFunctions, INodeExecutionData, INodePropertyOptions, INodeType, INodeTypeDescription } from 'n8n-workflow';
+export declare class ExcelApi implements INodeType {
+    description: INodeTypeDescription;
+    methods: {
+        loadOptions: {
+            getExcelFiles(this: ILoadOptionsFunctions): Promise<INodePropertyOptions[]>;
+            getExcelSheets(this: ILoadOptionsFunctions): Promise<INodePropertyOptions[]>;
+        };
+    };
+    execute(this: IExecuteFunctions): Promise<INodeExecutionData[][]>;
+}

package/dist/nodes/ExcelApi/ExcelApi.node.js

@@ -0,0 +1,505 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExcelApi = void 0;
+const n8n_workflow_1 = require("n8n-workflow");
+class ExcelApi {
+    constructor() {
+        this.description = {
+            displayName: 'Excel API',
+            name: 'excelApi',
+            icon: 'file:excelapi.svg',
+            group: ['transform'],
+            version: 1,
+            subtitle: '={{$parameter["operation"]}}',
+            description: 'Access Excel files via API with concurrent safety',
+            defaults: {
+                name: 'Excel API',
+            },
+            inputs: ['main'],
+            outputs: ['main'],
+            credentials: [
+                {
+                    name: 'excelApiAuth',
+                    required: true,
+                },
+            ],
+            properties: [
+                {
+                    displayName: 'Operation',
+                    name: 'operation',
+                    type: 'options',
+                    noDataExpression: true,
+                    options: [
+                        { name: 'Append', value: 'append', action: 'Append row to Excel file', description: 'Add a new row to the end of the sheet' },
+                        { name: 'Read', value: 'read', action: 'Read Excel file', description: 'Read data from Excel file' },
+                        { name: 'Update', value: 'update', action: 'Update row', description: 'Update an existing row' },
+                        { name: 'Delete', value: 'delete', action: 'Delete row', description: 'Delete a row' },
+                        { name: 'Batch', value: 'batch', action: 'Batch operations', description: 'Execute multiple operations at once' },
+                    ],
+                    default: 'append',
+                },
+                // File selection
+                {
+                    displayName: 'File Name',
+                    name: 'fileName',
+                    type: 'options',
+                    required: true,
+                    typeOptions: {
+                        loadOptionsMethod: 'getExcelFiles',
+                    },
+                    default: '',
+                    description: 'Select an Excel file from the server',
+                },
+                // Sheet selection
+                {
+                    displayName: 'Sheet Name',
+                    name: 'sheetName',
+                    type: 'options',
+                    typeOptions: {
+                        loadOptionsMethod: 'getExcelSheets',
+                        loadOptionsDependsOn: ['fileName'],
+                    },
+                    default: 'Sheet1',
+                    description: 'Select a worksheet from the file',
+                },
+                // Append operation - Mode selection
+                {
+                    displayName: 'Append Mode',
+                    name: 'appendMode',
+                    type: 'options',
+                    displayOptions: {
+                        show: {
+                            operation: ['append']
+                        }
+                    },
+                    options: [
+                        { name: 'Object (By Column Names)', value: 'object', description: 'Map values by column names - easier and safer' },
+                        { name: 'Array (By Position)', value: 'array', description: 'Specify values in exact column order' },
+                    ],
+                    default: 'object',
+                    description: 'How to specify values to append',
+                },
+                // Append - Object Mode
+                {
+                    displayName: 'Values to Append',
+                    name: 'appendValuesObject',
+                    type: 'json',
+                    displayOptions: {
+                        show: {
+                            operation: ['append'],
+                            appendMode: ['object']
+                        }
+                    },
+                    default: '{\n  "Column1": "{{ $json.field1 }}",\n  "Column2": "{{ $json.field2 }}"\n}',
+                    required: true,
+                    description: 'Object with column names as keys. Column names must match Excel headers exactly.',
+                    hint: 'Example: {"員工編號": "{{ $json.body.employeeId }}", "姓名": "{{ $json.body.name }}"}',
+                },
+                // Append - Array Mode
+                {
+                    displayName: 'Values to Append',
+                    name: 'appendValuesArray',
+                    type: 'json',
+                    displayOptions: {
+                        show: {
+                            operation: ['append'],
+                            appendMode: ['array']
+                        }
+                    },
+                    default: '["value1", "value2", "value3"]',
+                    required: true,
+                    description: 'Array of values to append. Can use expressions like {{ $json.fieldName }}',
+                    hint: 'Example: ["{{ $json.name }}", "{{ $json.email }}", "{{ $json.age }}"]',
+                },
+                // Read operation
+                {
+                    displayName: 'Range',
+                    name: 'range',
+                    type: 'string',
+                    displayOptions: { show: { operation: ['read'] } },
+                    default: '',
+                    description: 'Cell range to read (e.g., A1:D10). Leave empty to read all data',
+                    placeholder: 'A1:D10',
+                },
+                // Update & Delete: Row Identification Method
+                {
+                    displayName: 'Identify Row By',
+                    name: 'identifyBy',
+                    type: 'options',
+                    displayOptions: { show: { operation: ['update', 'delete'] } },
+                    options: [
+                        { name: 'Row Number', value: 'rowNumber', description: 'Specify the exact row number' },
+                        { name: 'Lookup', value: 'lookup', description: 'Find row by matching a column value' },
+                    ],
+                    default: 'rowNumber',
+                    description: 'How to identify the row to update/delete',
+                },
+                // Row Number (for direct specification)
+                {
+                    displayName: 'Row Number',
+                    name: 'rowNumber',
+                    type: 'number',
+                    displayOptions: {
+                        show: {
+                            operation: ['update', 'delete'],
+                            identifyBy: ['rowNumber']
+                        }
+                    },
+                    required: true,
+                    default: 2,
+                    description: 'Row number to update/delete (1-based, row 1 is header)',
+                    hint: '⚠️ Row 1 is protected (header row). Data rows start from row 2.',
+                },
+                // Lookup Column (for lookup method)
+                {
+                    displayName: 'Lookup Column',
+                    name: 'lookupColumn',
+                    type: 'string',
+                    displayOptions: {
+                        show: {
+                            operation: ['update', 'delete'],
+                            identifyBy: ['lookup']
+                        }
+                    },
+                    required: true,
+                    default: '',
+                    placeholder: 'e.g., 員工編號, Email, ID',
+                    description: 'Column name to search in (must match header exactly)',
+                    hint: 'The first row is treated as headers',
+                },
+                // Lookup Value (for lookup method)
+                {
+                    displayName: 'Lookup Value',
+                    name: 'lookupValue',
+                    type: 'string',
+                    displayOptions: {
+                        show: {
+                            operation: ['update', 'delete'],
+                            identifyBy: ['lookup']
+                        }
+                    },
+                    required: true,
+                    default: '',
+                    placeholder: 'e.g., E001, john@example.com',
+                    description: 'Value to search for in the lookup column',
+                    hint: 'Can use expressions like {{ $json.id }}',
+                },
+                // Update operation: Values to Set
+                {
+                    displayName: 'Values to Set',
+                    name: 'valuesToSet',
+                    type: 'json',
+                    displayOptions: { show: { operation: ['update'] } },
+                    default: '{\n  "Status": "Done",\n  "UpdatedDate": "2024-01-01"\n}',
+                    required: true,
+                    description: 'Object with column names as keys and new values',
+                    hint: 'Example: {"Status": "{{ $json.status }}", "Salary": {{ $json.salary }}}',
+                },
+                // Batch operation
+                {
+                    displayName: 'Operations',
+                    name: 'batchOperations',
+                    type: 'json',
+                    displayOptions: { show: { operation: ['batch'] } },
+                    default: `[
+  {
+    "type": "append",
+    "values": ["value1", "value2"]
+  },
+  {
+    "type": "update",
+    "row": 5,
+    "values": ["new1", "new2"]
+  }
+]`,
+                    required: true,
+                    description: 'Array of operations to execute',
+                    hint: 'Each operation should have "type" (append/update/delete) and related fields',
+                },
+            ],
+        };
+        this.methods = {
+            loadOptions: {
+                async getExcelFiles() {
+                    const credentials = await this.getCredentials('excelApiAuth');
+                    const apiUrl = credentials.url;
+                    const apiToken = credentials.token;
+                    try {
+                        const response = await this.helpers.request({
+                            method: 'GET',
+                            url: `${apiUrl}/api/excel/files`,
+                            headers: {
+                                'Authorization': `Bearer ${apiToken}`,
+                            },
+                            json: true,
+                        });
+                        if (response.success && response.files) {
+                            return response.files.map((file) => ({
+                                name: file,
+                                value: file,
+                            }));
+                        }
+                        return [];
+                    }
+                    catch (error) {
+                        return [];
+                    }
+                },
+                async getExcelSheets() {
+                    const fileName = this.getNodeParameter('fileName');
+                    if (!fileName) {
+                        return [];
+                    }
+                    const credentials = await this.getCredentials('excelApiAuth');
+                    const apiUrl = credentials.url;
+                    const apiToken = credentials.token;
+                    try {
+                        const response = await this.helpers.request({
+                            method: 'GET',
+                            url: `${apiUrl}/api/excel/sheets?file=${encodeURIComponent(fileName)}`,
+                            headers: {
+                                'Authorization': `Bearer ${apiToken}`,
+                            },
+                            json: true,
+                        });
+                        if (response.success && response.sheets) {
+                            return response.sheets.map((sheet) => ({
+                                name: sheet,
+                                value: sheet,
+                            }));
+                        }
+                        return [];
+                    }
+                    catch (error) {
+                        return [];
+                    }
+                },
+            },
+        };
+    }
+    async execute() {
+        var _a;
+        const items = this.getInputData();
+        const returnData = [];
+        const operation = this.getNodeParameter('operation', 0);
+        // Get credentials
+        const credentials = await this.getCredentials('excelApiAuth');
+        const apiUrl = credentials.url;
+        const apiToken = credentials.token;
+        // Common parameters
+        const fileName = this.getNodeParameter('fileName', 0);
+        const sheetName = this.getNodeParameter('sheetName', 0) || 'Sheet1';
+        if (!fileName) {
+            throw new n8n_workflow_1.NodeOperationError(this.getNode(), 'File Name is required. Please select an Excel file.');
+        }
+        try {
+            for (let i = 0; i < items.length; i++) {
+                let responseData;
+                if (operation === 'append') {
+                    // Get append mode to determine which parameter to use
+                    const appendMode = this.getNodeParameter('appendMode', i);
+                    const parameterName = appendMode === 'object' ? 'appendValuesObject' : 'appendValuesArray';
+                    const appendValuesRaw = this.getNodeParameter(parameterName, i);
+                    let appendValues;
+                    if (typeof appendValuesRaw === 'string') {
+                        try {
+                            appendValues = JSON.parse(appendValuesRaw);
+                        }
+                        catch {
+                            throw new n8n_workflow_1.NodeOperationError(this.getNode(), `Values to Append must be a valid JSON ${appendMode === 'object' ? 'object' : 'array'}`);
+                        }
+                    }
+                    else {
+                        appendValues = appendValuesRaw;
+                    }
+                    // Use different API endpoint based on append mode
+                    if (appendMode === 'object') {
+                        // Object Mode: Use append_object API
+                        // This API automatically reads headers and maps values by column names
+                        responseData = await this.helpers.request({
+                            method: 'POST',
+                            url: `${apiUrl}/api/excel/append_object`,
+                            headers: {
+                                'Authorization': `Bearer ${apiToken}`,
+                                'Content-Type': 'application/json',
+                            },
+                            body: {
+                                file: fileName,
+                                sheet: sheetName,
+                                values: appendValues,
+                            },
+                            json: true,
+                        });
+                    }
+                    else {
+                        // Array Mode: Use standard append API
+                        responseData = await this.helpers.request({
+                            method: 'POST',
+                            url: `${apiUrl}/api/excel/append`,
+                            headers: {
+                                'Authorization': `Bearer ${apiToken}`,
+                                'Content-Type': 'application/json',
+                            },
+                            body: {
+                                file: fileName,
+                                sheet: sheetName,
+                                values: appendValues,
+                            },
+                            json: true,
+                        });
+                    }
+                }
+                else if (operation === 'read') {
+                    const range = this.getNodeParameter('range', i);
+                    responseData = await this.helpers.request({
+                        method: 'POST',
+                        url: `${apiUrl}/api/excel/read`,
+                        headers: {
+                            'Authorization': `Bearer ${apiToken}`,
+                            'Content-Type': 'application/json',
+                        },
+                        body: {
+                            file: fileName,
+                            sheet: sheetName,
+                            range: range || undefined,
+                        },
+                        json: true,
+                    });
+                    if (responseData.success && responseData.data) {
+                        const data = responseData.data;
+                        if (data.length > 1) {
+                            const headers = data[0];
+                            const hasHeaders = headers.every((h) => typeof h === 'string' && h.length > 0);
+                            if (hasHeaders) {
+                                for (let rowIdx = 1; rowIdx < data.length; rowIdx++) {
+                                    const rowData = {};
+                                    const row = data[rowIdx];
+                                    headers.forEach((header, colIdx) => {
+                                        rowData[header] = row[colIdx];
+                                    });
+                                    returnData.push({ json: rowData });
+                                }
+                                continue;
+                            }
+                        }
+                        returnData.push({ json: responseData });
+                        continue;
+                    }
+                }
+                else if (operation === 'update') {
+                    // Get identification method
+                    const identifyBy = this.getNodeParameter('identifyBy', i);
+                    const valuesToSetRaw = this.getNodeParameter('valuesToSet', i);
+                    let valuesToSet;
+                    if (typeof valuesToSetRaw === 'string') {
+                        try {
+                            valuesToSet = JSON.parse(valuesToSetRaw);
+                        }
+                        catch {
+                            throw new n8n_workflow_1.NodeOperationError(this.getNode(), 'Values to Set must be a valid JSON object');
+                        }
+                    }
+                    else {
+                        valuesToSet = valuesToSetRaw;
+                    }
+                    // Build request body
+                    const requestBody = {
+                        file: fileName,
+                        sheet: sheetName,
+                        values_to_set: valuesToSet,
+                    };
+                    if (identifyBy === 'rowNumber') {
+                        const rowNumber = this.getNodeParameter('rowNumber', i);
+                        requestBody.row = rowNumber;
+                    }
+                    else if (identifyBy === 'lookup') {
+                        const lookupColumn = this.getNodeParameter('lookupColumn', i);
+                        const lookupValue = this.getNodeParameter('lookupValue', i);
+                        requestBody.lookup_column = lookupColumn;
+                        requestBody.lookup_value = lookupValue;
+                    }
+                    responseData = await this.helpers.request({
+                        method: 'PUT',
+                        url: `${apiUrl}/api/excel/update_advanced`,
+                        headers: {
+                            'Authorization': `Bearer ${apiToken}`,
+                            'Content-Type': 'application/json',
+                        },
+                        body: requestBody,
+                        json: true,
+                    });
+                }
+                else if (operation === 'delete') {
+                    // Get identification method
+                    const identifyBy = this.getNodeParameter('identifyBy', i);
+                    // Build request body
+                    const requestBody = {
+                        file: fileName,
+                        sheet: sheetName,
+                    };
+                    if (identifyBy === 'rowNumber') {
+                        const rowNumber = this.getNodeParameter('rowNumber', i);
+                        requestBody.row = rowNumber;
+                    }
+                    else if (identifyBy === 'lookup') {
+                        const lookupColumn = this.getNodeParameter('lookupColumn', i);
+                        const lookupValue = this.getNodeParameter('lookupValue', i);
+                        requestBody.lookup_column = lookupColumn;
+                        requestBody.lookup_value = lookupValue;
+                    }
+                    responseData = await this.helpers.request({
+                        method: 'DELETE',
+                        url: `${apiUrl}/api/excel/delete_advanced`,
+                        headers: {
+                            'Authorization': `Bearer ${apiToken}`,
+                            'Content-Type': 'application/json',
+                        },
+                        body: requestBody,
+                        json: true,
+                    });
+                }
+                else if (operation === 'batch') {
+                    const batchOperationsRaw = this.getNodeParameter('batchOperations', i);
+                    let batchOperations;
+                    if (typeof batchOperationsRaw === 'string') {
+                        try {
+                            batchOperations = JSON.parse(batchOperationsRaw);
+                        }
+                        catch {
+                            throw new n8n_workflow_1.NodeOperationError(this.getNode(), 'Batch Operations must be a valid JSON array');
+                        }
+                    }
+                    else {
+                        batchOperations = batchOperationsRaw;
+                    }
+                    responseData = await this.helpers.request({
+                        method: 'POST',
+                        url: `${apiUrl}/api/excel/batch`,
+                        headers: {
+                            'Authorization': `Bearer ${apiToken}`,
+                            'Content-Type': 'application/json',
+                        },
+                        body: {
+                            file: fileName,
+                            sheet: sheetName,
+                            operations: batchOperations,
+                        },
+                        json: true,
+                    });
+                }
+                else {
+                    throw new n8n_workflow_1.NodeOperationError(this.getNode(), `Unsupported operation: ${operation}`);
+                }
+                returnData.push({ json: responseData });
+            }
+        }
+        catch (error) {
+            if ((_a = error.response) === null || _a === void 0 ? void 0 : _a.body) {
+                throw new n8n_workflow_1.NodeOperationError(this.getNode(), `Excel API Error: ${JSON.stringify(error.response.body)}`);
+            }
+            throw new n8n_workflow_1.NodeOperationError(this.getNode(), error.message);
+        }
+        return [returnData];
+    }
+}
+exports.ExcelApi = ExcelApi;

package/dist/nodes/ExcelApi/excelapi.svg

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg width="60px" height="60px" viewBox="0 0 60 60" version="1.1" xmlns="http://www.w3.org/2000/svg">
+    <g stroke="none" stroke-width="1" fill="none" fill-rule="evenodd">
+        <rect fill="#217346" x="0" y="0" width="60" height="60" rx="8"/>
+        <text font-family="Arial-BoldMT, Arial" font-size="36" font-weight="bold" fill="#FFFFFF">
+            <tspan x="13" y="43">X</tspan>
+        </text>
+    </g>
+</svg>

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "n8n-nodes-excel-api",
+  "version": "1.0.0",
+  "description": "n8n node for accessing Excel files via API with concurrent safety",
+  "keywords": [
+    "n8n-community-node-package",
+    "n8n",
+    "excel",
+    "api",
+    "spreadsheet"
+  ],
+  "license": "MIT",
+  "homepage": "https://github.com/code4Copilot/n8n-nodes-excel-api",
+  "author": {
+    "name": "Hueyan Chen",
+    "email": "hueyan.chen@gmail.com"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/code4Copilot/n8n-nodes-excel-api.git"
+  },
+  "main": "index.js",
+  "scripts": {
+    "build": "tsc && gulp build:icons",
+    "dev": "tsc --watch",
+    "format": "prettier nodes --write",
+    "lint": "eslint -c .eslintrc.prepublish.js --ext .ts,.js nodes package.json",
+    "lintfix": "eslint -c .eslintrc.prepublish.js --ext .ts,.js nodes package.json --fix",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
+    "prepublishOnly": "npm run build && npm run lint"
+  },
+  "files": [
+    "dist"
+  ],
+  "n8n": {
+    "n8nNodesApiVersion": 1,
+    "credentials": [
+      "dist/credentials/ExcelApiAuth.credentials.js"
+    ],
+    "nodes": [
+      "dist/nodes/ExcelApi/ExcelApi.node.js"
+    ]
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.0",
+    "@types/node": "^20.0.0",
+    "@typescript-eslint/parser": "^5.0.0",
+    "eslint": "^8.57.1",
+    "eslint-plugin-n8n-nodes-base": "^1.0.0",
+    "gulp": "^4.0.2",
+    "jest": "^29.5.0",
+    "n8n-workflow": "*",
+    "prettier": "^2.7.1",
+    "ts-jest": "^29.1.0",
+    "typescript": "^5.3.3"
+  },
+  "peerDependencies": {
+    "n8n-workflow": "*"
+  }
+}