n8n-nodes-larkbase-v3/README.md

n8n community node for Larkbase API

# n8n-nodes-larkbase

Node để tương tác với Larkbase API cho n8n.

## Yêu cầu hệ thống

- Node.js >= 16.0.0
- npm >= 7.0.0
- n8n >= 0.187.0

## Cài đặt

### Cài đặt qua n8n (Khuyến nghị)

1. Mở **Settings** > **Community Nodes**
2. Chọn **Install**
3. Nhập `n8n-nodes-larkbase-v3` vào ô package name
4. Chấp nhận rủi ro và chọn **Install**

### Cài đặt thủ công

```bash
# Truy cập thư mục nodes của n8n
cd ~/.n8n/nodes

# Gỡ cài đặt phiên bản cũ nếu có
npm uninstall n8n-nodes-larkbase-v3

# Xóa cache
rm -rf ~/.n8n/.cache

# Cài đặt package
npm install n8n-nodes-larkbase-v3

# Khởi động lại n8n
pm2 restart n8n
```

## Cấu trúc thư mục

```
n8n-nodes-larkbase/
├── credentials/                  # Cấu hình xác thực
│   └── LarkbaseApi.credentials.ts
├── nodes/                       # Các node
│   ├── Larkbase/               # Thư mục chứa các node
│   │   ├── Larkbase.node.ts    # Node chính
│   │   ├── LarkbaseAuth.node.ts # Node xác thực
│   │   └── LarkbasePrepareUpsert.node.ts # Node chuẩn bị upsert
│   └── modules/                 # Các module hỗ trợ
│       ├── auth.ts             # Xử lý xác thực
│       ├── batchSearch.ts      # Tìm kiếm hàng loạt
│       ├── cleanLarkbaseData.ts # Làm sạch dữ liệu
│       ├── dataUtils.ts        # Tiện ích xử lý dữ liệu
│       ├── fields.ts           # Xử lý trường dữ liệu
│       ├── larkbaseApi.ts      # Gọi API Larkbase
│       ├── prepareUpsert.ts    # Chuẩn bị dữ liệu upsert
│       └── utils.ts            # Các hàm tiện ích
├── dist/                       # Mã đã biên dịch
├── package.json               # Cấu hình package
└── tsconfig.json             # Cấu hình TypeScript
```

## Lịch sử phiên bản

### 0.6.0 (2025-04-06)
- Cải thiện cấu trúc thư mục:
  - Di chuyển các node vào thư mục `dist/nodes/Larkbase`
  - Cập nhật đường dẫn trong `package.json`
  - Sửa lỗi không tìm thấy module
- Cập nhật hướng dẫn cài đặt và cấu trúc thư mục
- Thêm hướng dẫn xử lý sự cố khi cài đặt

### 0.5.10 (2025-04-06)
- Cập nhật cấu trúc thư mục để đảm bảo các module được tìm thấy đúng cách
- Di chuyển các file node vào thư mục `dist/nodes/Larkbase`
- Cập nhật đường dẫn trong `package.json`

### 0.5.9 (2025-04-06)
- Cải thiện module Batch Search:
  - Tách logic thành các module riêng biệt
  - Thêm xử lý làm sạch dữ liệu từ Larkbase
  - Cải thiện xử lý lỗi và retry logic
  - Thêm tùy chọn delay giữa các lần gọi API
  - Sửa lỗi xử lý page_token khi lấy tất cả records

### 0.5.4 (2025-04-05)
- Cải thiện module Prepare Upsert:
  - Đổi tên input property từ `input1`, `input2` thành `new_data`, `existing_data`
  - Thêm thống kê chi tiết về dữ liệu đầu vào
  - Tự động chia nhỏ dữ liệu khi vượt quá 500 records
  - Cải thiện thông báo thống kê

### 0.5.3 (2025-04-04)
- Thêm module Prepare Upsert
- Cải thiện xử lý lỗi
- Thêm thống kê chi tiết

### 0.5.2 (2025-04-03)
- Thêm module Batch Search
- Hỗ trợ filter, sort, date filter
- Hỗ trợ lấy tất cả records

## Xử lý sự cố

### Lỗi không tìm thấy module
Nếu gặp lỗi "Cannot find module", hãy thử các bước sau:
1. Gỡ cài đặt package cũ:
```bash
npm uninstall n8n-nodes-larkbase-v3
```

2. Xóa cache:
```bash
rm -rf ~/.n8n/.cache
```

3. Cài đặt lại package với phiên bản mới nhất:
```bash
npm install n8n-nodes-larkbase-v3@latest
```

4. Khởi động lại n8n:
```bash
pm2 restart n8n
```

### Lỗi phiên bản không tồn tại
Nếu gặp lỗi "package version was not found", hãy:
1. Kiểm tra phiên bản mới nhất trên npm:
```bash
npm view n8n-nodes-larkbase-v3 versions
```

2. Cài đặt phiên bản cụ thể:
```bash
npm install n8n-nodes-larkbase-v3@0.6.0
```

## Liên hệ
- Email: nguyenthuongtb12@gmail.com
- GitHub: https://github.com/nguyenngothuong/node_n8n

# n8n-nodes-larkbase-v3

This is an n8n community node. It lets you use Larkbase in your n8n workflows.

Larkbase is a database service provided by Lark/Feishu.

[n8n](https://n8n.io/) is a [fair-code licensed](https://docs.n8n.io/reference/license/) workflow automation platform.

[Installation](#installation)  
[Operations](#operations)  
[Credentials](#credentials)  
[Compatibility](#compatibility)  
[Resources](#resources)  
[Version history](#version-history)  

## Installation

### Community Nodes (Recommended)

For users on n8n v0.187+, the easiest way to install this node is through the Community Nodes tab in n8n:

1. Go to **Settings** > **Community Nodes**
2. Click on **Install**
3. Enter `n8n-nodes-larkbase-v3` in the package name field
4. Accept the risks and click **Install**

### Manual Installation

To get started using the node manually:

```bash
# Install the package
cd ~/.n8n/nodes
npm install n8n-nodes-larkbase-v3

# Restart n8n
pm2 restart n8n
```

## Updating

To ensure a successful update to the latest version:

### Method 1: Through n8n UI (Recommended)

1. Go to **Settings** > **Community Nodes**
2. Find `n8n-nodes-larkbase-v3` in the list
3. Click **Update** if available

### Method 2: Manual Update (For troubleshooting)

If you experience issues with the UI update, follow these steps:

```bash
# Access n8n nodes directory
cd ~/.n8n/nodes

# Uninstall current version
npm uninstall n8n-nodes-larkbase-v3

# Clear cache
rm -rf ~/.n8n/.cache

# Install latest version
npm install n8n-nodes-larkbase-v3@0.5.4 --no-cache

# Restart n8n
pm2 restart n8n
```

## Operations

- **Batch Search**: Search for records in a Larkbase table
- **Batch Create**: Create multiple records in a Larkbase table
- **Batch Update**: Update multiple records in a Larkbase table
- **Upsert By Field**: Create or update records based on a field value
- **Prepare Upsert**: Prepare data for upsert operation with automatic data splitting

## Credentials

To use this node, you need to create an application in the [Lark/Feishu Developer Console](https://open.larksuite.com/app/) and obtain the following credentials:

- **App ID**: The ID of your Lark/Feishu application
- **App Secret**: The secret of your Lark/Feishu application

You also need to:
1. Enable the Bitable API in your application permissions
2. Add your application as a collaborator to your Larkbase tables

## Compatibility

This node has been tested with n8n version 0.187.0 and later.

## Resources

* [n8n community nodes documentation](https://docs.n8n.io/integrations/community-nodes/)
* [Lark/Feishu API documentation](https://open.larksuite.com/document/server-docs/apis/bitable/bitable-overview)

## Version history

### 0.5.4 (2025-04-06)
- Cải thiện module Prepare Upsert:
  - Loại bỏ các trường debug trong output
  - Tự động chia nhỏ dữ liệu thành các chunk khi vượt quá 500 records
  - Thêm thông tin thống kê về số lượng chunks
  - Cải thiện thông báo thống kê để hiển thị rõ ràng hơn

### 0.5.3 (2025-04-05)
- Cải thiện xử lý dữ liệu trong module Prepare Upsert
- Thêm thống kê chi tiết về dữ liệu đầu vào
- Tối ưu hóa hiệu suất khi xử lý dữ liệu lớn

### 0.5.2 (2025-04-04)
- Thêm module Prepare Upsert mới để chuẩn bị dữ liệu cho thao tác upsert
- Hỗ trợ so sánh dữ liệu dựa trên nhiều trường khóa
- Tự động phát hiện và xử lý dữ liệu trùng lặp

### 0.5.1 (2025-03-25)
- Đơn giản hóa module batch search
- Bỏ tính năng mapping mode, chỉ cho phép truyền vào input JSON
- Cải thiện hiệu suất và độ ổn định
- Sửa lỗi xử lý dữ liệu trả về từ API

### 0.4.1 (2025-03-25)
- Thêm tính năng load fields từ Larkbase để cấu hình dễ dàng hơn
- Cải thiện giao diện cấu hình fields với 3 chế độ mapping: tự động, định nghĩa thủ công, hoặc JSON
- Hỗ trợ tải danh sách fields trực tiếp từ bảng Larkbase để lựa chọn
- Thêm operation "Get Fields" để lấy thông tin về cấu trúc bảng

### 0.4.0 (2025-03-24)
- Hỗ trợ xác thực bằng token thủ công cho tất cả các operations
- Cải thiện cấu trúc mã để dễ dàng bảo trì
- Tăng cường khả năng tương thích giữa các phương thức xác thực
- Tối ưu hóa hiệu suất xử lý dữ liệu

### 0.3.1 (2025-03-23)
- Thêm tùy chọn nhập token thủ công trực tiếp vào Larkbase node
- Tăng cường độ linh hoạt với 3 phương thức xác thực: credentials, từ Auth node, và nhập thủ công
- Cải thiện trải nghiệm người dùng với nhiều tùy chọn xác thực
- Cho phép sử dụng token từ các nguồn khác ngoài Larkbase Auth node

### 0.3.0 (2025-03-23)

- Thêm node Larkbase Auth mới để lấy token xác thực
- Hỗ trợ hai phương thức xác thực: sử dụng credentials hoặc token từ node khác
- Cho phép nhập thông tin xác thực thủ công trong node Larkbase Auth
- Cải thiện tính linh hoạt trong quản lý token xác thực
- Giảm sự phụ thuộc vào credentials được lưu trữ

### 0.2.1 (2025-03-22)

- Tăng giá trị page_size mặc định từ 100 lên 500 để cải thiện hiệu suất
- Giảm số lần gọi API khi lấy dữ liệu lớn
- Tối ưu hóa tốc độ xử lý dữ liệu

### 0.2.0 (2025-03-21)

- Nâng cấp version của node từ 2 lên 3
- Đổi tên hiển thị từ "Larkbase V2" thành "Larkbase V3"
- Cải thiện khả năng tương thích với n8n
- Tăng cường trải nghiệm người dùng với giao diện mới
- Tích hợp tất cả các cải tiến từ phiên bản 0.1.5

### 0.1.5 (2025-03-20)

- Cải thiện xử lý date filter với định dạng ExactDate chuẩn của Larkbase API
- Sửa lỗi phân trang bằng cách truyền page_token và page_size dưới dạng query parameters
- Cải thiện cơ chế phát hiện vòng lặp vô hạn trong phân trang
- Tối ưu hóa hiệu suất khi lấy dữ liệu lớn
- Hỗ trợ tốt hơn cho lọc theo khoảng thời gian

### 0.1.4 (2025-03-19)

- Cải thiện xử lý dữ liệu trả về từ API Larkbase
- Thêm chuyển đổi tự động cho các loại dữ liệu khác nhau (text, number, date)
- Làm sạch cấu trúc dữ liệu phức tạp thành dạng key-value đơn giản
- Tự động chuyển đổi chuỗi ngày tháng thành timestamp
- Xử lý tốt hơn các trường hợp dữ liệu đặc biệt

### 0.1.3 (2025-03-18)

- Sửa lỗi module search khi sử dụng tùy chọn "Return All"
- Cải thiện xử lý phân trang để tránh timeout
- Thêm giới hạn số lần lặp để tránh vòng lặp vô hạn
- Loại bỏ tùy chọn limit không hoạt động đúng
- Tối ưu hóa hiệu suất khi lấy dữ liệu lớn

### 0.1.2 (2025-03-18)

- Added field type handling for batch create operations
- Improved data normalization for different field types
- Enhanced field mapping to correctly process various data types
- Fixed issues with field mappings not being applied correctly
- Added UI options to specify field types for better data handling

### 0.1.1 (2025-03-17)

- Improved filter value handling to support array values
- Fixed text field processing to convert array format to string
- Enhanced access token handling to ensure proper format
- Added support for multiple filter values in UI
- Improved error handling and debugging

### 0.1.0 (2025-03-17)

- Renamed package from n8n-nodes-larkbase-v2 to n8n-nodes-larkbase-v3
- Increased node version to improve update compatibility
- Fixed issues with node updates in n8n
- Enhanced stability and reliability
- Improved user experience

### Previous versions (n8n-nodes-larkbase-v2)

- 0.2.4: Improved update compatibility and stability
- 0.2.3: Enhanced features and performance optimizations
- 0.2.2: Added date filtering option in the UI
- 0.2.1: Added UTF-8 support for Vietnamese characters
- 0.2.0: Renamed from n8n-nodes-larkbase to n8n-nodes-larkbase-v2
- 0.1.2: Changed API endpoints
- 0.1.1: Initial release

## Tổng quan

n8n-nodes-larkbase là một community node cho phép n8n workflows tương tác với Larkbase API (Feishu/Lark Bitable). Node này cho phép người dùng thực hiện các thao tác batch search, batch create, batch update và custom upsert by field với dữ liệu trong Larkbase.

## Tính năng

- **Xác thực**: Kết nối an toàn với Larkbase API sử dụng App ID và App Secret
- **Node xác thực riêng biệt**: Lấy token xác thực từ Larkbase API với nhiều tùy chọn
- **Batch Search**: Tìm kiếm nhiều records cùng lúc với các điều kiện lọc
- **Batch Create**: Tạo nhiều records cùng lúc
- **Batch Update**: Cập nhật nhiều records cùng lúc
- **Custom Upsert by Field**: Tạo mới hoặc cập nhật records dựa trên giá trị của một trường cụ thể
- **Hỗ trợ UTF-8**: Xử lý đúng các ký tự tiếng Việt và các ngôn ngữ khác
- **Lọc theo thời gian**: Tìm kiếm records trong một khoảng thời gian cụ thể
- **Hỗ trợ giá trị lọc dạng mảng**: Cho phép tìm kiếm với nhiều giá trị cùng lúc
- **Xử lý trường text**: Tự động chuyển đổi các trường text từ dạng array về dạng string
- **Phương thức xác thực linh hoạt**: 3 tùy chọn xác thực cho tất cả các thao tác

## Cấu hình

Để sử dụng Larkbase node, bạn cần tạo credentials với các thông tin sau:

- **App ID**: App ID của ứng dụng Feishu/Lark (tìm thấy trong Feishu/Lark Developer Console)
- **App Secret**: App Secret của ứng dụng Feishu/Lark (tìm thấy trong Feishu/Lark Developer Console)

## Ví dụ sử dụng

### Lấy Access Token với Node Larkbase Auth

1. Thêm Larkbase Auth node vào workflow
2. Chọn "Get Access Token" làm operation
3. Chọn phương thức xác thực:
   - "Credentials" để sử dụng thông tin xác thực đã lưu
   - "Manual Input" để nhập thông tin xác thực thủ công
4. Nếu chọn "Manual Input", nhập App ID và App Secret
5. Thực thi node để lấy access token

### Sử dụng Access Token từ Node Larkbase Auth

1. Thêm Larkbase Auth node vào workflow để lấy token
2. Thêm Larkbase node vào workflow
3. Chọn "Access Token" làm phương thức xác thực
4. Sử dụng biểu thức để lấy token từ node trước đó:
   `{{$node["Larkbase Auth"].json["access_token"]}}`
5. Cấu hình các tham số khác và thực thi node

### Sử dụng Token thủ công

1. Thêm Larkbase node vào workflow
2. Chọn "Manual Token" làm phương thức xác thực
3. Nhập access token trực tiếp vào trường "Manual Token"
4. Cấu hình các tham số khác và thực thi node
5. Phương pháp này hữu ích khi bạn đã có sẵn token từ nguồn khác

### Batch Search Records

1. Thêm Larkbase node vào workflow
2. Chọn "Record" làm resource
3. Chọn "Batch Search" làm operation
4. Chọn phương thức xác thực phù hợp (Credentials, Access Token, hoặc Manual Token)
5. Cấu hình App Token, Table ID và các điều kiện lọc
6. Thực thi node để lấy dữ liệu

### Batch Create Records

1. Thêm Larkbase node vào workflow
2. Chọn "Record" làm resource
3. Chọn "Batch Create" làm operation
5. Cấu hình App Token, Table ID và dữ liệu cần tạo
6. Thực thi để tạo records mới

### Batch Update Records

1. Thêm Larkbase node vào workflow
2. Chọn "Record" làm resource
3. Chọn "Batch Update" làm operation
4. Chọn phương thức xác thực phù hợp (Credentials, Access Token, hoặc Manual Token)
5. Cấu hình App Token, Table ID và dữ liệu cần cập nhật
6. Thực thi để cập nhật records

### Custom Upsert by Field

1. Thêm Larkbase node vào workflow
2. Chọn "Record" làm resource
3. Chọn "Upsert by Field" làm operation
4. Chọn phương thức xác thực phù hợp (Credentials, Access Token, hoặc Manual Token)
5. Cấu hình App Token, Table ID, trường làm key và dữ liệu cần upsert
6. Thực thi để tạo mới hoặc cập nhật records

## Tài liệu API

Node được xây dựng dựa trên tài liệu Larkbase API. Các endpoint chính bao gồm:

- `/open-apis/bitable/v1/apps/{app_token}/tables/{table_id}/records/search` - Cho batch search
- `/open-apis/bitable/v1/apps/{app_token}/tables/{table_id}/records/batch_create` - Cho batch create
- `/open-apis/bitable/v1/apps/{app_token}/tables/{table_id}/records/batch_update` - Cho batch update

## Ghi chú phát triển

Node này được phát triển sử dụng n8n community node framework. Cấu trúc tuân theo các best practices cho việc phát triển n8n node:

```
n8n-nodes-larkbase/
├── credentials/                  # Cấu hình xác thực
│   └── LarkbaseApi.credentials.ts
├── nodes/                        # Triển khai node
│   ├── Larkbase.node.ts
│   ├── LarkbasePrepareUpsert.node.ts
│   ├── modules/                  # Các module hỗ trợ
│   │   ├── auth.ts              # Xử lý xác thực
│   │   ├── batchSearch.ts       # Tìm kiếm hàng loạt
│   │   ├── cleanLarkbaseData.ts # Làm sạch dữ liệu
│   │   ├── dataUtils.ts         # Tiện ích xử lý dữ liệu
│   │   ├── fields.ts            # Xử lý trường dữ liệu
│   │   ├── larkbaseApi.ts       # Gọi API Larkbase
│   │   ├── prepareUpsert.ts     # Chuẩn bị dữ liệu upsert
│   │   └── utils.ts             # Các hàm tiện ích
│   └── larkbase.svg             # Icon của node
├── dist/                         # Mã đã biên dịch
├── index.js                      # Entry point
├── index.ts                      # Export node và credentials
├── package.json                  # Cấu hình package
└── tsconfig.json                 # Cấu hình TypeScript
```

## Xử lý sự cố

Các vấn đề thường gặp và giải pháp:

1. **Lỗi xác thực**: Đảm bảo App ID và App Secret của bạn chính xác
2. **Giới hạn tốc độ**: API Larkbase có thể có giới hạn tốc độ; cân nhắc thêm độ trễ giữa các thao tác
3. **Vấn đề định dạng dữ liệu**: Kiểm tra cấu trúc dữ liệu nếu gặp lỗi phân tích
4. **Lỗi ký tự đặc biệt**: Đảm bảo dữ liệu tiếng Việt được mã hóa đúng cách
5. **Lỗi định dạng ngày tháng**: Đảm bảo định dạng ngày tháng đúng (ISO 8601) khi sử dụng lọc theo thời gian
6. **Lỗi giá trị lọc dạng mảng**: Đối với toán tử "Is One Of", nhập các giá trị phân cách bằng dấu phẩy

## Cải tiến trong tương lai

Các tính năng dự kiến cho các phiên bản tương lai:

- Hỗ trợ thêm các resource của Larkbase
- Thao tác xóa batch
- Khả năng lọc nâng cao
- Hỗ trợ webhook cho cập nhật dữ liệu real-time

## Đóng góp

Đóng góp để cải thiện node được hoan nghênh. Vui lòng làm theo các bước sau:

1. Fork repository
2. Tạo branch tính năng
3. Thực hiện các thay đổi
4. Gửi pull request

## Giấy phép

Node này được phát hành theo Giấy phép MIT.