@things-factory/integration-headless 8.0.0-beta.6 → 8.0.0-beta.8

package/helps/integration/connector/headless-connector.ja.md

@@ -1,57 +1,172 @@
-### ヘッドレスプールコネクタ (Headless Pool Connector)
+### 🏆 ヘッドレスコネクター (Headless Connector)
 
-**ヘッドレスプールコネクタ**は、ヘッドレスブラウザインスタンスのプールを管理するために設計されています。このコネクタは、PDFの生成やウェブスクレイピングのように、複数のヘッドレスブラウザセッションを同時に実行する必要がある作業に便利です。このコネクタは、これらのヘッドレスブラウザインスタンスの作成、使用、および破棄を効率的に管理します。
+**ヘッドレスコネクター**は、ヘッドレスブラウザを使用して **自動ログイン**、**ウェブスクレイピング**、**PDF生成**、**フォーム送信** などのタスクを実行する強力なツールです。  
+複数のブラウザセッションを管理し、セッションの維持、クッキーの処理、APIベースのログインなどに対応しています。
 
-#### エンドポイント
+---
 
-`ヘッドレスプールコネクタ`は特定のエンドポイントを要求しませんが、接続設定の一環としてURIを提供できます。このURIは通常プレースホルダーとして使用され、プールが内部的に実際の接続を処理します。つまり、エンドポイントには任意の文字列を入力することができます。
+## 🚀 1. エンドポイント (Endpoint)
 
-#### パラメータ
+**ヘッドレスコネクター**のエンドポイントは、**対象となるウェブサイトのURL** を入力します。  
+例えば、`https://example.com` を入力すると、そのウェブサイトのコンテンツを取得できます。  
+内部コンテンツからPDFを生成する場合は、`localhost` も使用できます。
 
-- **min** (数字):
-  - プール内で維持する最小のヘッドレスブラウザインスタンスの数を指定します。
-  - デフォルト値: `2`
-- **max** (数字):
-  - プールが処理できる最大のヘッドレスブラウザインスタンスの数を指定します。
-  - デフォルト値: `10`
+---
 
-これらのパラメータは、予想される作業負荷に応じてプールのサイズを調整できるようにします。例えば、アプリケーションが同時に複数のブラウザインスタンスを頻繁に必要とする場合、`max`値を増やすことができます。
+## 🔧 2. パラメーター (Parameters)
 
-#### 設定例
+### ✅ ログイン関連設定
+
+| パラメーター         | タイプ   | 説明                                            | デフォルト値  |
+| -------------------- | -------- | ----------------------------------------------- | ------------- |
+| `username`           | `string` | ログインID (ユーザー名)                         | `""`          |
+| `password`           | `string` | ログイン用パスワード                            | `""`          |
+| `loginPagePath`      | `string` | ログインページのパス (例: `/login`)             | `"/login"`    |
+| `loginApiUrl`        | `string` | ログインAPIのエンドポイント (必要な場合のみ)    | `null`        |
+| `usernameSelector`   | `string` | ユーザー名入力欄のCSSセレクター                 | `"#username"` |
+| `passwordSelector`   | `string` | パスワード入力欄のCSSセレクター                 | `"#password"` |
+| `submitSelector`     | `string` | ログインボタンのCSSセレクター                   | `"#submit"`   |
+| `successSelector`    | `string` | ログイン成功を確認するための要素のCSSセレクター | `null`        |
+| `shadowDomSelectors` | `string` | Shadow DOM 内の要素を指定 (カンマ区切り)        | `""`          |
+| `timeout`            | `number` | ログインやページ読み込みのタイムアウト時間 (ms) | `15000`       |
+| `retries`            | `number` | ログインの試行回数                              | `3`           |
+
+---
+
+## 🔍 3. `loginApiUrl` の詳細説明
+
+### 🔹 `loginApiUrl`とは？
+
+`loginApiUrl` は、ウェブサイトが **APIベースのログイン** を使用する場合に設定するパラメーターです。  
+サイトによっては、ログインページでフォーム送信する代わりに、バックエンドのAPIを直接呼び出してログインする仕組みを持っています。
+
+---
+
+### ✅ `loginApiUrl` を **設定しない場合 (`null`)**
+
+この場合、**HTMLフォームを使用したログイン方式** を採用します。  
+ヘッドレスブラウザが自動的にユーザー名とパスワードを入力し、フォームを送信します。
+
+#### 📌 例 (HTMLフォームログイン)
+
+```json
+{
+  "endpoint": "https://example.com",
+  "params": {
+    "username": "user123",
+    "password": "securepassword",
+    "loginPagePath": "/login",
+    "usernameSelector": "#username",
+    "passwordSelector": "#password",
+    "submitSelector": "#submit-button",
+    "successSelector": ".dashboard"
+  }
+}
+```
+
+#### 🛠 動作の流れ:
+
+1. `https://example.com/login` に移動
+2. `#username` と `#password` にログイン情報を入力
+3. `#submit-button` をクリックしてフォーム送信
+4. `.dashboard` 要素の有無でログイン成功を判断
+
+---
+
+### ✅ `loginApiUrl` を **設定する場合**
+
+この場合、サイトが **APIベースの認証** を使用しているため、`loginApiUrl` を明示的に設定する必要があります。  
+例えば、ログインAPIが `/api/auth/login` の場合、このURLを指定します。
+
+#### 📌 例 (APIベースのログイン)
+
+```json
+{
+  "endpoint": "https://example.com",
+  "params": {
+    "username": "user123",
+    "password": "securepassword",
+    "loginPagePath": "/login",
+    "loginApiUrl": "/api/auth/login",
+    "usernameSelector": "#username",
+    "passwordSelector": "#password",
+    "submitSelector": "#submit-button",
+    "successSelector": ".dashboard"
+  }
+}
+```
+
+#### 🛠 動作の流れ:
+
+1. `https://example.com/api/auth/login` に **POSTリクエスト** を送信
+2. サーバーからレスポンスを受け取り、セッションのクッキーを保存
+3. メインページへ移動し、`.dashboard` の存在を確認
+
+---
+
+## 🏗 4. 設定例
 
 ```json
 {
-  "name": "headless-browser-pool",
+  "name": "headless-browser-connector",
   "connector": "headless-connector",
-  "endpoint": "1",
+  "endpoint": "https://example.com",
   "params": {
-    "min": 5,
-    "max": 20
+    "username": "user123",
+    "password": "securepassword",
+    "loginPagePath": "/login",
+    "loginApiUrl": "/api/auth/login",
+    "usernameSelector": "#username",
+    "passwordSelector": "#password",
+    "submitSelector": "#submit",
+    "successSelector": ".dashboard",
+    "timeout": 20000,
+    "retries": 5
   }
 }
 ```
 
-上記の例では、プールは少なくとも5つのヘッドレスブラウザインスタンスを維持し、必要に応じて最大20インスタンスまで拡張することができます。
+---
+
+## 🔄 5. 接続のライフサイクル (Connection Lifecycle)
 
-#### 接続ライフサイクル
+- **connect**
 
-- **connect**:
+  - 設定に従ってログインを試みます。
+  - セッションを維持し、クッキーを保存して後続のリクエストで再利用します。
 
-  - 接続を初期化し、設定されたパラメータ(`min`および`max`)に従ってヘッドレスブラウザインスタンスのプールを作成します。
-  - プールはこれらのインスタンスのライフサイクルを自動的に管理し、必要に応じて新しいインスタンスを作成し、既存のインスタンスを再利用します。
+- **disconnect**
+  - ヘッドレスブラウザのセッションを終了し、クッキーをクリアします。
 
-- **disconnect**:
-  - ヘッドレスブラウザプールを破棄し、すべてのインスタンスが適切に終了し、リソースが解放されるようにします。
+---
 
-#### 使用シナリオ
+## ⚡ 6. 対応するタスク (Supported Tasks)
 
-`ヘッドレスプールコネクタ`は、ヘッドレスブラウザ環境で作業を実行する必要があるシナリオで主に使用されます。例えば、HTMLコンテンツからPDFを生成したり、ウェブページのスクリーンショットをキャプチャしたり、ウェブサイトからデータをスクレイピングする際に便利です。
+| タスクタイプ           | 説明                                   |
+| ---------------------- | -------------------------------------- |
+| `headless-pdf-capture` | HTMLをPDFに変換する                    |
+| `headless-scrap`       | ウェブページから特定データを抽出する   |
+| `headless-post`        | フォーム入力を自動化し、送信を実行する |
 
-#### サポートするタスク
+#### 📌 タスク例
 
-`ヘッドレスプールコネクタ`は `headless-pdf` プレフィックスの付いたタスクをサポートします。これらのタスクは、このコネクタが管理するヘッドレスブラウザインスタンスを使用します。
+### 1️⃣ ウェブスクレイピング (`headless-scrap`)
+
+```json
+{
+  "name": "scrape-data",
+  "taskType": "headless-scrap",
+  "params": {
+    "path": "/products",
+    "selectors": [
+      { "text": "商品名", "value": ".product-title" },
+      { "text": "価格", "value": ".product-price" }
+    ]
+  }
+}
+```
 
-#### タスクでの使用例
+### 2️⃣ PDF生成 (`headless-pdf-capture`)
 
 ```json
 {
@@ -66,6 +181,43 @@
 }
 ```
 
-#### 説明
+### 3️⃣ フォーム送信 (`headless-post`)
+
+```json
+{
+  "name": "submit-form",
+  "taskType": "headless-post",
+  "params": {
+    "formPath": "/contact",
+    "fields": {
+      "#name": "田中 太郎",
+      "#email": "tanaka@example.com",
+      "#message": "こんにちは、これはテストメッセージです！"
+    },
+    "submitSelector": "#submit-button"
+  }
+}
+```
+
+---
+
+## 📢 7. 説明 (Description)
+
+**ヘッドレスコネクター** は **ウェブスクレイピング、自動ログイン、PDF生成、フォーム送信** などを  
+効率的に実行するための強力なツールです。  
+**HTMLベースのログイン** と **APIベースのログイン** の両方に対応し、さまざまなサイトでの認証処理が可能です。
+
+---
+
+### 📌 まとめ
+
+| 機能                     | 説明                                   |
+| ------------------------ | -------------------------------------- |
+| **HTMLフォームログイン** | ユーザー操作をシミュレートしてログイン |
+| **APIログイン**          | APIリクエストで直接ログイン (高速)     |
+| **セッション管理**       | クッキーを保存し、セッションを維持     |
+| **ウェブスクレイピング** | 指定したコンテンツを抽出して取得       |
+| **PDF変換**              | HTMLページをPDFに変換                  |
+| **フォーム送信**         | 自動的にフォーム入力＆送信を実行       |
 
-**ヘッドレスプールコネクタ**は、PDF生成やウェブスクレイピングなどの作業を効率的に実行するために、ヘッドレスブラウザインスタンスのプールを管理し、高負荷なシナリオでのリソース利用の最適化と拡張性を保証します。
+📌 **ヘッドレスコネクターを使えば、さまざまなウェブサイトのタスクを自動化できます！** 🚀

package/helps/integration/connector/headless-connector.ko.md

@@ -1,58 +1,166 @@
-### 헤드리스 풀 커넥터 (Headless Pool Connector)
+### 🏆 헤드리스 커넥터 (Headless Connector)
 
-**헤드리스 풀 커넥터**는 헤드리스 브라우저 인스턴스의 풀(pool)을 관리하기 위해 설계되었습니다. 이 커넥터는 PDF 생성이나 웹 스크래핑과 같이 여러 개의 헤드리스 브라우저 세션이 동시에 필요한 작업을 수행할 때 유용합니다. 이 커넥터는 이 헤드리스 브라우저 인스턴스의 생성, 사용 및 파기를 효율적으로 관리합니다.
+**헤드리스 커넥터**는 헤드리스 브라우저를 활용하여 **로그인 자동화**, **웹 스크래핑**, **PDF 생성**, **폼 제출** 등의 작업을 수행하는 강력한 커넥터입니다.  
+여러 개의 브라우저 세션을 관리하며, 세션 유지, 쿠키 활용, API 기반 로그인 등 다양한 기능을 제공합니다.
 
-#### 엔드포인트
+---
 
-`헤드리스 풀 커넥터`는 특정 엔드포인트를 요구하지 않지만, 연결 설정의 일환으로 URI를 제공할 수 있습니다. 이 URI는 일반적으로 플레이스홀더로 사용되며, 풀은 내부적으로 실제 연결을 처리합니다.
-즉, 엔트포인트는 임의의 문자열을 입력하시면 됩니다.
+## 🚀 1. 엔드포인트 (Endpoint)
 
-#### 매개변수
+헤드리스 커넥터의 엔드포인트는 **스크래핑 대상 웹사이트의 URL**을 입력합니다.  
+예를 들어, `https://example.com`과 같은 웹사이트의 내용을 가져오거나 내부 컨텐츠로 PDF 파일을 생성하려면 `localhost`를 사용할 수도 있습니다.
 
-- **min** (숫자):
-  - 풀에서 유지할 최소 헤드리스 브라우저 인스턴스 수를 지정합니다.
-  - 기본값: `2`
-- **max** (숫자):
-  - 풀이 처리할 수 있는 최대 헤드리스 브라우저 인스턴스 수를 지정합니다.
-  - 기본값: `10`
+---
 
-이 매개변수들은 예상되는 작업 부하에 맞춰 풀 크기를 조정할 수 있게 해줍니다. 예를 들어, 애플리케이션에서 여러 브라우저 인스턴스를 자주 동시에 필요로 하는 경우 `max` 값을 늘릴 수 있습니다.
+## 🔧 2. 매개변수 (Parameters)
 
-#### 설정 예시
+### ✅ 로그인 관련 설정
+
+| 매개변수             | 타입     | 설명                                                            | 기본값        |
+| -------------------- | -------- | --------------------------------------------------------------- | ------------- |
+| `username`           | `string` | 로그인할 사용자 이름 (아이디)                                   | `""`          |
+| `password`           | `string` | 로그인 비밀번호                                                 | `""`          |
+| `loginPagePath`      | `string` | 로그인 페이지의 경로 (예: `/login`)                             | `"/login"`    |
+| `loginApiUrl`        | `string` | 로그인 API 엔드포인트 (없으면 `null`)                           | `null`        |
+| `usernameSelector`   | `string` | 로그인 폼의 사용자명 입력 필드 CSS 선택자                       | `"#username"` |
+| `passwordSelector`   | `string` | 로그인 폼의 비밀번호 입력 필드 CSS 선택자                       | `"#password"` |
+| `submitSelector`     | `string` | 로그인 버튼의 CSS 선택자                                        | `"#submit"`   |
+| `successSelector`    | `string` | 로그인 성공을 판별할 수 있는 요소의 CSS 선택자                  | `null`        |
+| `shadowDomSelectors` | `string` | Shadow DOM 내부 요소를 찾을 때 사용 (쉼표로 구분된 선택자 목록) | `""`          |
+| `timeout`            | `number` | 로그인 및 페이지 로딩 대기 시간 (ms)                            | `15000`       |
+| `retries`            | `number` | 로그인 시도 횟수                                                | `3`           |
+
+---
+
+## 🔍 3. `loginApiUrl` 매개변수에 대한 상세 설명
+
+### 🔹 `loginApiUrl`란?
+
+`loginApiUrl`은 웹사이트에서 구현한 로그인 방식에 따라 로그인 시도 결과를 확인하기 위해 참고하는 설정 정보입니다.
+
+### ✅ `loginApiUrl`이 **설정되지 않은 경우 (`null`)**
+
+**HTML 폼을 통한 로그인 방식**을 사용하는 웹사이트에서는 별도로 설정하지 않아도 됩니다. 이 경우는 페이지내의 form action을 직접 참조합니다.
+
+1. `loginPagePath`에 지정된 로그인 페이지로 이동합니다.
+2. 사용자명 및 비밀번호 입력 필드에 값을 입력합니다.
+3. 로그인 버튼을 클릭하여 로그인을 시도합니다.
+4. `successSelector`를 사용해 로그인 성공 여부를 판별합니다.
+
+#### 📌 예제 설정 (HTML 폼 로그인)
+
+```json
+{
+  "endpoint": "https://example.com",
+  "params": {
+    "username": "user123",
+    "password": "securepassword",
+    "loginPagePath": "/login",
+    "usernameSelector": "#username",
+    "passwordSelector": "#password",
+    "submitSelector": "#submit-button",
+    "successSelector": ".dashboard"
+  }
+}
+```
+
+#### 🛠 동작 과정
+
+1. `https://example.com/login` 페이지로 이동
+2. `#username`, `#password` 입력 필드에 값을 입력
+3. `#submit-button`을 클릭하여 로그인 요청 전송
+4. `.dashboard` 요소가 나타나면 로그인 성공으로 판단
+
+---
+
+### ✅ `loginApiUrl`을 **설정하는 경우**
+
+웹사이트가 **API 기반 로그인 방식**을 사용하는 경우입니다. 이 경우 로그인을 위해서 호출되는 `loginApiUrl`을 직접 파악해서 설정해주어야 합니다.
+Origin 서버가 아닌 별도의 SSO 서버의 API를 호출하는 경우에는 전체 API URL을 설정해주면 됩니다.
+
+#### 📌 예제 설정 (API 로그인 방식의 웹사이트)
+
+```json
+{
+  "endpoint": "https://example.com",
+  "params": {
+    "username": "user123",
+    "password": "securepassword",
+    "loginPagePath": "/login",
+    "loginApiUrl": "/api/auth/login",
+    "usernameSelector": "#username",
+    "passwordSelector": "#password",
+    "submitSelector": "#submit-button",
+    "successSelector": ".dashboard"
+  }
+}
+```
+
+---
+
+## 🏗 4. 설정 예시
 
 ```json
 {
-  "name": "headless-browser-pool",
+  "name": "headless-browser-connector",
   "connector": "headless-connector",
-  "endpoint": "1",
+  "endpoint": "https://example.com",
   "params": {
-    "min": 5,
-    "max": 20
+    "username": "user123",
+    "password": "securepassword",
+    "loginPagePath": "/login",
+    "loginApiUrl": "/api/auth/login",
+    "usernameSelector": "#username",
+    "passwordSelector": "#password",
+    "submitSelector": "#submit",
+    "successSelector": ".dashboard",
+    "timeout": 20000,
+    "retries": 5
   }
 }
 ```
 
-위 예시에서 풀은 최소 5개의 헤드리스 브라우저 인스턴스를 유지하며, 필요에 따라 최대 20개의 인스턴스로 확장할 수 있습니다.
+---
+
+## 🔄 5. 연결 생명주기 (Connection Lifecycle)
+
+- **connect**
 
-#### 연결 생명주기
+  - 설정된 매개변수에 따라 로그인 프로세스를 수행합니다.
+  - 세션이 유지되며, 쿠키를 저장하여 이후 요청에서 재사용합니다.
 
-- **connect**:
+- **disconnect**
+  - 헤드리스 브라우저 세션을 종료하고 쿠키를 정리합니다.
 
-  - 연결을 초기화하여 설정된 매개변수(`min` 및 `max`)에 따라 헤드리스 브라우저 인스턴스 풀을 생성합니다.
-  - 풀은 이러한 인스턴스들의 생명주기를 자동으로 관리하며, 필요한 경우 새로운 인스턴스를 생성하고 기존 인스턴스를 재사용합니다.
+---
 
-- **disconnect**:
-  - 헤드리스 브라우저 풀을 파기하여 모든 인스턴스가 적절히 종료되고 리소스가 해제되도록 합니다.
+## ⚡ 6. 지원하는 작업 (Supported Tasks)
 
-#### 사용 시나리오
+| 작업 유형              | 설명                                                     |
+| ---------------------- | -------------------------------------------------------- |
+| `headless-pdf-capture` | HTML을 PDF로 변환하는 작업                               |
+| `headless-scrap`       | 웹 페이지에서 특정 데이터를 추출하는 스크래핑 작업       |
+| `headless-post`        | 웹사이트에서 폼 데이터를 자동으로 입력하고 제출하는 작업 |
 
-`헤드리스 풀 커넥터`는 헤드리스 브라우저 환경에서 작업을 수행해야 하는 시나리오에서 주로 사용됩니다. 예를 들어, HTML 콘텐츠로부터 PDF를 생성하거나, 웹 페이지의 스크린샷을 캡처하거나, 웹사이트에서 데이터를 스크래핑할 때 유용합니다.
+#### 📌 작업 예시
 
-#### 지원하는 작업
+### 1️⃣ 웹 스크래핑 (`headless-scrap`)
 
-`헤드리스 풀 커넥터`는 `headless-pdf` 접두사가 붙은 작업을 지원합니다. 이러한 작업은 이 커넥터가 관리하는 헤드리스 브라우저 인스턴스를 사용하게 됩니다.
+```json
+{
+  "name": "scrape-data",
+  "taskType": "headless-scrap",
+  "params": {
+    "path": "/products",
+    "selectors": [
+      { "text": "Product Name", "value": ".product-title" },
+      { "text": "Price", "value": ".product-price" }
+    ]
+  }
+}
+```
 
-#### 작업에서의 예시 사용
+### 2️⃣ PDF 생성 (`headless-pdf-capture`)
 
 ```json
 {
@@ -67,6 +175,43 @@
 }
 ```
 
-#### 설명
+### 3️⃣ 폼 제출 (`headless-post`)
+
+```json
+{
+  "name": "submit-form",
+  "taskType": "headless-post",
+  "params": {
+    "formPath": "/contact",
+    "fields": {
+      "#name": "John Doe",
+      "#email": "john@example.com",
+      "#message": "Hello, this is a test message!"
+    },
+    "submitSelector": "#submit-button"
+  }
+}
+```
+
+---
+
+## 📢 7. 설명 (Description)
+
+**헤드리스 커넥터**는 **웹 자동화 및 스크래핑, PDF 생성, 폼 자동 입력 및 제출** 등을 위해  
+헤드리스 브라우저 세션을 관리하는 강력한 도구입니다.  
+특히 **HTML 로그인 방식**과 **API 로그인 방식**을 모두 지원하여 다양한 웹사이트에서 안정적인 로그인을 수행할 수 있습니다.
+
+---
+
+### 📌 요약
+
+| 기능            | 설명                                  |
+| --------------- | ------------------------------------- |
+| **폼 로그인**   | UI를 직접 조작하여 로그인 (HTML 기반) |
+| **API 로그인**  | HTTP 요청을 통해 직접 로그인 (빠름)   |
+| **세션 유지**   | 쿠키를 저장하여 지속적인 세션 유지    |
+| **웹 스크래핑** | 데이터 추출 및 자동화 작업 가능       |
+| **PDF 변환**    | HTML을 PDF로 변환                     |
+| **폼 제출**     | 자동으로 데이터를 입력하고 제출       |
 
-**헤드리스 풀 커넥터**는 PDF 생성 및 웹 스크래핑과 같은 작업을 수행하기 위해 헤드리스 브라우저 인스턴스 풀을 효율적으로 관리하며, 높은 수요가 있는 시나리오에서 자원 활용의 최적화와 확장성을 보장합니다.
+**이 커넥터를 활용하면 다양한 웹사이트에서 자동 로그인 및 데이터 수집을 효율적으로 수행할 수 있습니다.** 🚀

package/helps/integration/connector/headless-connector.md

@@ -1,57 +1,168 @@
-### Headless Pool Connector
+### 🏆 Headless Connector
 
-**Headless Pool Connector** is designed to manage a pool of headless browser instances. This connector is useful when performing tasks that require multiple headless browser sessions simultaneously, such as PDF generation or web scraping. It efficiently manages the creation, use, and destruction of these headless browser instances.
+The **Headless Connector** is a powerful tool that utilizes headless browsers to perform **automated login**, **web scraping**, **PDF generation**, and **form submission** tasks.  
+It manages multiple browser sessions, maintains sessions, handles cookies, and supports API-based logins.
 
-#### Endpoint
+---
 
-`Headless Pool Connector` does not require a specific endpoint, but a URI can be provided as part of the connection setup. This URI is typically used as a placeholder, with the pool handling the actual connection internally. In other words, any string can be entered as the endpoint.
+## 🚀 1. Endpoint
 
-#### Parameters
+The endpoint for the **Headless Connector** should be the **URL of the target website** that you want to scrape or interact with.  
+For example, you can input `https://example.com` to extract content from that website. If you need to generate a PDF from internal content, you can also use `localhost`.
 
-- **min** (number):
-  - Specifies the minimum number of headless browser instances to maintain in the pool.
-  - Default value: `2`
-- **max** (number):
-  - Specifies the maximum number of headless browser instances the pool can handle.
-  - Default value: `10`
+---
 
-These parameters allow the pool size to be adjusted based on the expected workload. For example, if the application frequently requires multiple browser instances simultaneously, the `max` value can be increased.
+## 🔧 2. Parameters
 
-#### Example Configuration
+### ✅ Login Configuration
+
+| Parameter            | Type     | Description                                       | Default Value |
+| -------------------- | -------- | ------------------------------------------------- | ------------- |
+| `username`           | `string` | Username (login ID)                               | `""`          |
+| `password`           | `string` | Password for login                                | `""`          |
+| `loginPagePath`      | `string` | Path to the login page (e.g., `/login`)           | `"/login"`    |
+| `loginApiUrl`        | `string` | API endpoint for login (if applicable)            | `null`        |
+| `usernameSelector`   | `string` | CSS selector for the username input field         | `"#username"` |
+| `passwordSelector`   | `string` | CSS selector for the password input field         | `"#password"` |
+| `submitSelector`     | `string` | CSS selector for the login button                 | `"#submit"`   |
+| `successSelector`    | `string` | CSS selector to verify login success              | `null`        |
+| `shadowDomSelectors` | `string` | Comma-separated selectors for shadow DOM elements | `""`          |
+| `timeout`            | `number` | Timeout for login and page loading (ms)           | `15000`       |
+| `retries`            | `number` | Number of login retries                           | `3`           |
+
+---
+
+## 🔍 3. Detailed Explanation of `loginApiUrl`
+
+### 🔹 What is `loginApiUrl`?
+
+`loginApiUrl` is used when the website employs **API-based login** instead of traditional HTML form-based login. This parameter helps the connector determine how to handle the login process.
+
+### ✅ If `loginApiUrl` is **NOT set (`null`)**
+
+The **HTML form submission method** is used to log in.  
+The headless browser will manually enter the username and password into the login form and click the submit button.
+
+#### 📌 Example (HTML Form-Based Login)
 
 ```json
 {
-  "name": "headless-browser-pool",
+  "endpoint": "https://example.com",
+  "params": {
+    "username": "user123",
+    "password": "securepassword",
+    "loginPagePath": "/login",
+    "usernameSelector": "#username",
+    "passwordSelector": "#password",
+    "submitSelector": "#submit-button",
+    "successSelector": ".dashboard"
+  }
+}
+```
+
+#### 🛠 How it Works:
+
+1. Navigate to `https://example.com/login`
+2. Enter credentials into `#username` and `#password`
+3. Click `#submit-button` to submit the form
+4. Check if `.dashboard` exists to determine if login was successful
+
+---
+
+### ✅ If `loginApiUrl` **IS set**
+
+If the website uses **API-based authentication**, `loginApiUrl` should be explicitly set to the login API's endpoint.  
+For example, if the login API is `/api/auth/login`, this value must be configured accordingly.
+
+#### 📌 Example (API-Based Login)
+
+```json
+{
+  "endpoint": "https://example.com",
+  "params": {
+    "username": "user123",
+    "password": "securepassword",
+    "loginPagePath": "/login",
+    "loginApiUrl": "/api/auth/login",
+    "usernameSelector": "#username",
+    "passwordSelector": "#password",
+    "submitSelector": "#submit-button",
+    "successSelector": ".dashboard"
+  }
+}
+```
+
+#### 🛠 How it Works:
+
+1. Sends a **POST request** to `https://example.com/api/auth/login`
+2. Receives a response from the server and stores the session cookies
+3. Navigates to the main page and checks for `.dashboard` to verify login success
+
+---
+
+## 🏗 4. Example Configuration
+
+```json
+{
+  "name": "headless-browser-connector",
   "connector": "headless-connector",
-  "endpoint": "1",
+  "endpoint": "https://example.com",
   "params": {
-    "min": 5,
-    "max": 20
+    "username": "user123",
+    "password": "securepassword",
+    "loginPagePath": "/login",
+    "loginApiUrl": "/api/auth/login",
+    "usernameSelector": "#username",
+    "passwordSelector": "#password",
+    "submitSelector": "#submit",
+    "successSelector": ".dashboard",
+    "timeout": 20000,
+    "retries": 5
   }
 }
 ```
 
-In the example above, the pool maintains at least 5 headless browser instances and can scale up to 20 instances as needed.
+---
+
+## 🔄 5. Connection Lifecycle
+
+- **connect**
 
-#### Connection Lifecycle
+  - Performs the login process according to the provided parameters.
+  - Maintains the session and stores cookies for future requests.
 
-- **connect**:
+- **disconnect**
+  - Terminates the browser session and clears cookies.
 
-  - Initializes the connection and creates the pool of headless browser instances based on the configured parameters (`min` and `max`).
-  - The pool automatically manages the lifecycle of these instances, creating new ones as needed and reusing existing ones.
+---
 
-- **disconnect**:
-  - Destroys the headless browser pool, ensuring all instances are properly terminated and resources are released.
+## ⚡ 6. Supported Tasks
 
-#### Usage Scenarios
+| Task Type              | Description                            |
+| ---------------------- | -------------------------------------- |
+| `headless-pdf-capture` | Converts HTML to a PDF                 |
+| `headless-scrap`       | Extracts specific data from a web page |
+| `headless-post`        | Automates form filling and submission  |
 
-`Headless Pool Connector` is primarily used in scenarios where tasks need to be executed in a headless browser environment. For example, it is useful for generating PDFs from HTML content, capturing screenshots of web pages, or scraping data from websites.
+#### 📌 Task Examples
 
-#### Supported Tasks
+### 1️⃣ Web Scraping (`headless-scrap`)
 
-`Headless Pool Connector` supports tasks prefixed with `headless-pdf`. These tasks will utilize the headless browser instances managed by this connector.
+```json
+{
+  "name": "scrape-data",
+  "taskType": "headless-scrap",
+  "params": {
+    "path": "/products",
+    "selectors": [
+      { "text": "Product Name", "value": ".product-title" },
+      { "text": "Price", "value": ".product-price" }
+    ]
+  }
+}
+```
 
-#### Example Usage in Tasks
+### 2️⃣ PDF Generation (`headless-pdf-capture`)
 
 ```json
 {
@@ -66,6 +177,42 @@ In the example above, the pool maintains at least 5 headless browser instances a
 }
 ```
 
-#### Description
+### 3️⃣ Form Submission (`headless-post`)
+
+```json
+{
+  "name": "submit-form",
+  "taskType": "headless-post",
+  "params": {
+    "formPath": "/contact",
+    "fields": {
+      "#name": "John Doe",
+      "#email": "john@example.com",
+      "#message": "Hello, this is a test message!"
+    },
+    "submitSelector": "#submit-button"
+  }
+}
+```
+
+---
+
+## 📢 7. Description
+
+The **Headless Connector** is a powerful tool for **automated web scraping, PDF generation, and form submission** tasks.  
+It supports both **HTML-based logins** and **API-based logins**, making it suitable for a variety of website authentication methods.
+
+---
+
+### 📌 Summary
+
+| Feature                | Description                               |
+| ---------------------- | ----------------------------------------- |
+| **HTML Form Login**    | Simulates user interaction for login      |
+| **API Login**          | Sends login requests via API (faster)     |
+| **Session Management** | Stores cookies for session persistence    |
+| **Web Scraping**       | Extracts specific content from websites   |
+| **PDF Generation**     | Converts HTML pages to PDF                |
+| **Form Submission**    | Fills out and submits forms automatically |
 
-**Headless Pool Connector** efficiently manages the pool of headless browser instances to execute tasks like PDF generation and web scraping, ensuring optimization and scalability of resources in high-demand scenarios.
+📌 **With the Headless Connector, you can easily automate various tasks across different websites!** 🚀

package/helps/integration/connector/headless-connector.ms.md

@@ -1,59 +1,171 @@
-### Penyambung Kolam Tanpa Kepala (Headless Pool Connector)
+### 🏆 **Penyambung Headless (Headless Connector)**
 
-**Penyambung Kolam Tanpa Kepala** direka untuk menguruskan kolam contoh pelayar tanpa kepala. Penyambung ini berguna apabila menjalankan tugas yang memerlukan beberapa sesi pelayar tanpa kepala secara serentak seperti penjanaan PDF atau pengikisan web. Penyambung ini menguruskan penciptaan, penggunaan, dan pemusnahan contoh pelayar tanpa kepala dengan cekap.
+**Penyambung Headless** ialah alat yang kuat yang menggunakan pelayar headless untuk melaksanakan **log masuk automatik**, **pengikisan web (web scraping)**, **penjanaan PDF**, dan **penghantaran borang**.  
+Ia menguruskan berbilang sesi pelayar, mengekalkan sesi, mengendalikan kuki, serta menyokong log masuk berdasarkan API.
 
-#### Titik Akhir
+---
 
-`Penyambung Kolam Tanpa Kepala` tidak memerlukan titik akhir tertentu, tetapi URI boleh disediakan sebagai sebahagian daripada tetapan sambungan. URI ini biasanya digunakan sebagai tempat letak sementara, dan kolam akan mengendalikan sambungan sebenar secara dalaman. Dengan kata lain, sebarang rentetan boleh dimasukkan sebagai titik akhir.
+## 🚀 **1. Titik Akhir (Endpoint)**
 
-#### Parameter
+Titik akhir untuk **Penyambung Headless** ialah **URL laman web sasaran** yang ingin dikikis (scraping) atau berinteraksi dengannya.  
+Sebagai contoh, `https://example.com` boleh digunakan untuk mengekstrak data daripada laman web, atau `localhost` boleh digunakan jika anda ingin menjana fail PDF dari kandungan dalaman.
 
-- **min** (nombor):
-  - Menentukan bilangan minimum contoh pelayar tanpa kepala yang dikekalkan dalam kolam.
-  - Nilai lalai: `2`
-- **max** (nombor):
-  - Menentukan bilangan maksimum contoh pelayar tanpa kepala yang boleh diuruskan oleh kolam.
-  - Nilai lalai: `10`
+---
 
-Parameter ini membolehkan saiz kolam disesuaikan berdasarkan beban kerja yang dijangkakan. Sebagai contoh, jika aplikasi sering memerlukan beberapa contoh pelayar serentak, nilai `max` boleh ditingkatkan.
+## 🔧 **2. Parameter (Parameters)**
 
-#### Contoh Tetapan
+### ✅ **Tetapan Berkaitan Log Masuk**
+
+| Parameter            | Jenis    | Penerangan                                                   | Nilai Lalai   |
+| -------------------- | -------- | ------------------------------------------------------------ | ------------- |
+| `username`           | `string` | ID pengguna untuk log masuk                                  | `""`          |
+| `password`           | `string` | Kata laluan untuk log masuk                                  | `""`          |
+| `loginPagePath`      | `string` | Laluan ke halaman log masuk (contoh: `/login`)               | `"/login"`    |
+| `loginApiUrl`        | `string` | URL API untuk log masuk (jika diperlukan)                    | `null`        |
+| `usernameSelector`   | `string` | Pemilih CSS untuk medan input nama pengguna                  | `"#username"` |
+| `passwordSelector`   | `string` | Pemilih CSS untuk medan input kata laluan                    | `"#password"` |
+| `submitSelector`     | `string` | Pemilih CSS untuk butang log masuk                           | `"#submit"`   |
+| `successSelector`    | `string` | Pemilih CSS untuk elemen yang menunjukkan kejayaan log masuk | `null`        |
+| `shadowDomSelectors` | `string` | Pemilih untuk elemen dalam Shadow DOM (dipisahkan koma)      | `""`          |
+| `timeout`            | `number` | Had masa menunggu untuk log masuk dan pemuatan halaman (ms)  | `15000`       |
+| `retries`            | `number` | Bilangan percubaan untuk log masuk                           | `3`           |
+
+---
+
+## 🔍 **3. Penjelasan Terperinci Mengenai `loginApiUrl`**
+
+### 🔹 **Apa itu `loginApiUrl`?**
+
+`loginApiUrl` ialah parameter yang digunakan untuk **log masuk berdasarkan API**.  
+Sesetengah laman web tidak menggunakan borang HTML biasa untuk log masuk tetapi menggunakan API backend untuk mengesahkan pengguna.
+
+---
+
+### ✅ **Jika `loginApiUrl` Tidak Ditetapkan (`null`)**
+
+Dalam kes ini, **borang HTML biasa** digunakan untuk log masuk.  
+Pelayar headless akan mengisi nama pengguna dan kata laluan secara automatik, kemudian menghantar borang tersebut.
+
+#### 📌 **Contoh (Log Masuk Borang HTML)**
 
 ```json
 {
-  "name": "headless-browser-pool",
+  "endpoint": "https://example.com",
+  "params": {
+    "username": "user123",
+    "password": "securepassword",
+    "loginPagePath": "/login",
+    "usernameSelector": "#username",
+    "passwordSelector": "#password",
+    "submitSelector": "#submit-button",
+    "successSelector": ".dashboard"
+  }
+}
+```
+
+#### 🛠 **Proses Operasi**:
+
+1. Pergi ke `https://example.com/login`.
+2. Isi medan `#username` dan `#password`.
+3. Klik butang `#submit-button` untuk menghantar borang.
+4. Jika `.dashboard` wujud, log masuk dianggap berjaya.
+
+---
+
+### ✅ **Jika `loginApiUrl` Ditentukan**
+
+Dalam kes ini, laman web menggunakan **log masuk berdasarkan API**, jadi URL API perlu dinyatakan secara eksplisit.  
+Sebagai contoh, jika API log masuk ialah `/api/auth/login`, ia mesti dinyatakan dalam parameter.
+
+#### 📌 **Contoh (Log Masuk Berdasarkan API)**
+
+```json
+{
+  "endpoint": "https://example.com",
+  "params": {
+    "username": "user123",
+    "password": "securepassword",
+    "loginPagePath": "/login",
+    "loginApiUrl": "/api/auth/login",
+    "usernameSelector": "#username",
+    "passwordSelector": "#password",
+    "submitSelector": "#submit-button",
+    "successSelector": ".dashboard"
+  }
+}
+```
+
+#### 🛠 **Proses Operasi**:
+
+1. Hantar **permintaan POST** ke `https://example.com/api/auth/login`.
+2. Simpan kuki sesi selepas menerima respons.
+3. Navigasi ke halaman utama dan periksa `.dashboard` untuk memastikan log masuk berjaya.
+
+---
+
+## 🏗 **4. Contoh Konfigurasi**
+
+```json
+{
+  "name": "headless-browser-connector",
   "connector": "headless-connector",
-  "endpoint": "1",
+  "endpoint": "https://example.com",
   "params": {
-    "min": 5,
-    "max": 20
+    "username": "user123",
+    "password": "securepassword",
+    "loginPagePath": "/login",
+    "loginApiUrl": "/api/auth/login",
+    "usernameSelector": "#username",
+    "passwordSelector": "#password",
+    "submitSelector": "#submit",
+    "successSelector": ".dashboard",
+    "timeout": 20000,
+    "retries": 5
   }
 }
 ```
 
-Dalam contoh di atas, kolam akan mengekalkan sekurang-kurangnya 5 contoh pelayar tanpa kepala dan boleh berkembang kepada maksimum 20 contoh
+---
+
+## 🔄 **5. Kitaran Hayat Sambungan (Connection Lifecycle)**
 
-apabila diperlukan.
+- **connect**
 
-#### Kitaran Hidup Sambungan
+  - Mencuba log masuk berdasarkan parameter yang dikonfigurasi.
+  - Mengekalkan sesi dan menyimpan kuki untuk permintaan seterusnya.
 
-- **connect**:
+- **disconnect**
+  - Menamatkan sesi pelayar headless dan memadamkan kuki.
 
-  - Menginisialisasi sambungan dan mencipta kolam contoh pelayar tanpa kepala mengikut parameter yang ditetapkan (`min` dan `max`).
-  - Kolam akan menguruskan kitaran hidup contoh-contoh ini secara automatik, mencipta contoh baru jika diperlukan, dan menggunakan semula contoh sedia ada.
+---
 
-- **disconnect**:
-  - Menghancurkan kolam pelayar tanpa kepala dan memastikan semua contoh ditutup dengan betul dan sumber dilepaskan.
+## ⚡ **6. Tugas yang Disokong (Supported Tasks)**
 
-#### Senario Penggunaan
+| Jenis Tugas            | Penerangan                                     |
+| ---------------------- | ---------------------------------------------- |
+| `headless-pdf-capture` | Menukar HTML kepada PDF                        |
+| `headless-scrap`       | Mengekstrak data tertentu dari laman web       |
+| `headless-post`        | Mengisi dan menghantar borang secara automatik |
 
-`Penyambung Kolam Tanpa Kepala` terutamanya digunakan dalam senario di mana tugas perlu dijalankan dalam persekitaran pelayar tanpa kepala. Contohnya, ia berguna untuk menjana PDF daripada kandungan HTML, menangkap tangkapan skrin halaman web, atau mengikis data daripada laman web.
+#### 📌 **Contoh Penggunaan Tugas**
 
-#### Tugas yang Disokong
+### 1️⃣ **Pengikisan Web (`headless-scrap`)**
 
-`Penyambung Kolam Tanpa Kepala` menyokong tugas yang bermula dengan awalan `headless-pdf`. Tugas-tugas ini akan menggunakan contoh pelayar tanpa kepala yang diuruskan oleh penyambung ini.
+```json
+{
+  "name": "scrape-data",
+  "taskType": "headless-scrap",
+  "params": {
+    "path": "/products",
+    "selectors": [
+      { "text": "Nama Produk", "value": ".product-title" },
+      { "text": "Harga", "value": ".product-price" }
+    ]
+  }
+}
+```
 
-#### Contoh Penggunaan dalam Tugas
+### 2️⃣ **Penjanaan PDF (`headless-pdf-capture`)**
 
 ```json
 {
@@ -68,6 +180,42 @@ apabila diperlukan.
 }
 ```
 
-#### Penjelasan
+### 3️⃣ **Penghantaran Borang (`headless-post`)**
+
+```json
+{
+  "name": "submit-form",
+  "taskType": "headless-post",
+  "params": {
+    "formPath": "/contact",
+    "fields": {
+      "#name": "Ali Bin Ahmad",
+      "#email": "ali@example.com",
+      "#message": "Salam, ini adalah mesej ujian!"
+    },
+    "submitSelector": "#submit-button"
+  }
+}
+```
+
+---
+
+## 📢 **7. Penerangan (Description)**
+
+**Penyambung Headless** membolehkan **pengikisan web, log masuk automatik, penjanaan PDF, dan penghantaran borang** dilakukan secara automatik.  
+Ia menyokong kedua-dua **log masuk berdasarkan borang HTML** dan **log masuk API**, membolehkan sambungan yang stabil di pelbagai laman web.
+
+---
+
+### 📌 **Ringkasan**
+
+| Fungsi                    | Penerangan                                                |
+| ------------------------- | --------------------------------------------------------- |
+| **Log Masuk Borang HTML** | Mensimulasikan interaksi pengguna untuk log masuk         |
+| **Log Masuk API**         | Menggunakan permintaan API untuk log masuk (lebih pantas) |
+| **Penyelenggaraan Sesi**  | Menyimpan kuki untuk memastikan sesi kekal aktif          |
+| **Pengikisan Web**        | Mengekstrak data yang ditentukan secara automatik         |
+| **Penukaran PDF**         | Menukar halaman HTML kepada format PDF                    |
+| **Penghantaran Borang**   | Mengisi dan menghantar borang secara automatik            |
 
-**Penyambung Kolam Tanpa Kepala** menguruskan kolam contoh pelayar tanpa kepala secara cekap untuk melaksanakan tugas seperti penjanaan PDF dan pengikisan web, memastikan pengoptimuman dan kebolehskalaan sumber dalam senario permintaan tinggi.
+📌 **Gunakan Penyambung Headless untuk mengautomasikan pelbagai tugas web dengan lebih mudah dan cekap!** 🚀

package/helps/integration/connector/headless-connector.zh.md

@@ -1,57 +1,168 @@
-### 无头浏览器池连接器 (Headless Pool Connector)
+### 🏆 无头连接器 (Headless Connector)
 
-**无头浏览器池连接器**旨在管理无头浏览器实例的池。该连接器在执行需要多个无头浏览器会话同时运行的任务时非常有用，例如生成PDF或进行网页抓取。它能够有效地管理这些无头浏览器实例的创建、使用和销毁。
+**无头连接器** 利用无头浏览器执行 **自动登录**、**网页爬取**、**PDF 生成**、**表单提交**等任务。  
+它可以管理多个浏览器会话，支持会话保持、Cookie 处理、基于 API 的登录等功能。
 
-#### 端点
+---
 
-`无头浏览器池连接器`不要求特定的端点，但可以作为连接设置的一部分提供URI。此URI通常作为占位符使用，池在内部处理实际连接。也就是说，端点可以输入任意字符串。
+## 🚀 1. 端点（Endpoint）
 
-#### 参数
+无头连接器的端点需要填写 **目标网页的 URL**。  
+例如，可以输入 `https://example.com` 以抓取该网站的内容，或者使用 `localhost` 生成 PDF。
 
-- **min** (数字):
-  - 指定池中维持的最少无头浏览器实例数量。
-  - 默认值: `2`
-- **max** (数字):
-  - 指定池中可以处理的最大无头浏览器实例数量。
-  - 默认值: `10`
+---
 
-这些参数允许根据预期的工作负载调整池的大小。例如，如果应用程序经常同时需要多个浏览器实例，则可以增加`max`值。
+## 🔧 2. 参数（Parameters）
 
-#### 设置示例
+### ✅ 登录相关配置
+
+| 参数                 | 类型     | 描述                                         | 默认值        |
+| -------------------- | -------- | -------------------------------------------- | ------------- |
+| `username`           | `string` | 登录用户名（账户名）                         | `""`          |
+| `password`           | `string` | 登录密码                                     | `""`          |
+| `loginPagePath`      | `string` | 登录页面路径（如 `/login`）                  | `"/login"`    |
+| `loginApiUrl`        | `string` | 登录 API 端点（如果没有则 `null`）           | `null`        |
+| `usernameSelector`   | `string` | 登录表单的用户名输入框 CSS 选择器            | `"#username"` |
+| `passwordSelector`   | `string` | 登录表单的密码输入框 CSS 选择器              | `"#password"` |
+| `submitSelector`     | `string` | 登录按钮的 CSS 选择器                        | `"#submit"`   |
+| `successSelector`    | `string` | 用于判断登录成功的元素 CSS 选择器            | `null`        |
+| `shadowDomSelectors` | `string` | 处理 Shadow DOM 内部元素的选择器（逗号分隔） | `""`          |
+| `timeout`            | `number` | 登录及页面加载的超时时间（毫秒）             | `15000`       |
+| `retries`            | `number` | 登录重试次数                                 | `3`           |
+
+---
+
+## 🔍 3. `loginApiUrl` 参数的详细说明
+
+### 🔹 `loginApiUrl` 是什么？
+
+`loginApiUrl` 是指用于网站 **API 登录** 的接口地址。如果网站不使用 API 方式登录，则不需要设置此参数。
+
+### ✅ `loginApiUrl` 为空 (`null`)
+
+此时 **使用 HTML 表单提交的方式进行登录**。  
+无头浏览器会直接模拟用户操作，如填写用户名和密码，并点击提交按钮。
+
+#### 📌 示例（HTML 表单登录）
 
 ```json
 {
-  "name": "headless-browser-pool",
+  "endpoint": "https://example.com",
+  "params": {
+    "username": "user123",
+    "password": "securepassword",
+    "loginPagePath": "/login",
+    "usernameSelector": "#username",
+    "passwordSelector": "#password",
+    "submitSelector": "#submit-button",
+    "successSelector": ".dashboard"
+  }
+}
+```
+
+#### 🛠 处理过程：
+
+1. 访问 `https://example.com/login`
+2. 在 `#username` 和 `#password` 输入框中填入账户信息
+3. 点击 `#submit-button` 提交表单
+4. 通过 `.dashboard` 元素是否存在来判断是否登录成功
+
+---
+
+### ✅ `loginApiUrl` 设定时
+
+如果目标网站使用 **API 方式登录**，则 `loginApiUrl` 需要设置为该 API 的地址。  
+例如，如果 API 登录地址是 `/api/auth/login`，则需要手动设置该参数。
+
+#### 📌 示例（API 登录方式）
+
+```json
+{
+  "endpoint": "https://example.com",
+  "params": {
+    "username": "user123",
+    "password": "securepassword",
+    "loginPagePath": "/login",
+    "loginApiUrl": "/api/auth/login",
+    "usernameSelector": "#username",
+    "passwordSelector": "#password",
+    "submitSelector": "#submit-button",
+    "successSelector": ".dashboard"
+  }
+}
+```
+
+#### 🛠 处理过程：
+
+1. 发送 **HTTP POST 请求** 到 `https://example.com/api/auth/login`
+2. 服务器返回成功响应，浏览器存储会话 Cookie
+3. 访问主页面并检查 `.dashboard` 是否存在，以确认登录成功
+
+---
+
+## 🏗 4. 配置示例
+
+```json
+{
+  "name": "headless-browser-connector",
   "connector": "headless-connector",
-  "endpoint": "1",
+  "endpoint": "https://example.com",
   "params": {
-    "min": 5,
-    "max": 20
+    "username": "user123",
+    "password": "securepassword",
+    "loginPagePath": "/login",
+    "loginApiUrl": "/api/auth/login",
+    "usernameSelector": "#username",
+    "passwordSelector": "#password",
+    "submitSelector": "#submit",
+    "successSelector": ".dashboard",
+    "timeout": 20000,
+    "retries": 5
   }
 }
 ```
 
-在上述示例中，池至少保持5个无头浏览器实例，并且在需要时可以扩展到最多20个实例。
+---
+
+## 🔄 5. 连接生命周期（Connection Lifecycle）
+
+- **connect**
 
-#### 连接生命周期
+  - 根据参数执行登录流程，并保持会话。
+  - 存储 Cookie，以便后续请求使用。
 
-- **connect**:
+- **disconnect**
+  - 关闭浏览器会话，并清除 Cookie。
 
-  - 初始化连接，根据设定的参数(`min` 和 `max`)创建无头浏览器实例池。
-  - 池会自动管理这些实例的生命周期，必要时创建新的实例并重用现有的实例。
+---
 
-- **disconnect**:
-  - 销毁无头浏览器池，确保所有实例都被适当关闭并释放资源。
+## ⚡ 6. 支持的任务（Supported Tasks）
 
-#### 使用场景
+| 任务类型               | 描述                   |
+| ---------------------- | ---------------------- |
+| `headless-pdf-capture` | 将 HTML 转换为 PDF     |
+| `headless-scrap`       | 网页爬取，提取特定数据 |
+| `headless-post`        | 自动填写表单并提交     |
 
-`无头浏览器池连接器`主要用于需要在无头浏览器环境中执行任务的场景。例如，生成HTML内容的PDF、捕获网页截图或从网站抓取数据。
+#### 📌 任务示例
 
-#### 支持的任务
+### 1️⃣ 网页爬取（`headless-scrap`）
 
-`无头浏览器池连接器`支持以 `headless-pdf` 为前缀的任务。这些任务将使用由此连接器管理的无头浏览器实例。
+```json
+{
+  "name": "scrape-data",
+  "taskType": "headless-scrap",
+  "params": {
+    "path": "/products",
+    "selectors": [
+      { "text": "商品名称", "value": ".product-title" },
+      { "text": "价格", "value": ".product-price" }
+    ]
+  }
+}
+```
 
-#### 任务示例使用
+### 2️⃣ PDF 生成（`headless-pdf-capture`）
 
 ```json
 {
@@ -66,6 +177,42 @@
 }
 ```
 
-#### 说明
+### 3️⃣ 表单提交（`headless-post`）
+
+```json
+{
+  "name": "submit-form",
+  "taskType": "headless-post",
+  "params": {
+    "formPath": "/contact",
+    "fields": {
+      "#name": "张三",
+      "#email": "zhangsan@example.com",
+      "#message": "你好，我想咨询一下！"
+    },
+    "submitSelector": "#submit-button"
+  }
+}
+```
+
+---
+
+## 📢 7. 说明（Description）
+
+**无头连接器** 可用于 **自动化网页爬取、PDF 生成、表单提交** 等任务。  
+它支持 **HTML 登录** 和 **API 登录**，适用于各种不同的网页登录方式。
+
+---
+
+### 📌 功能总结
+
+| 功能              | 说明                                 |
+| ----------------- | ------------------------------------ |
+| **HTML 表单登录** | 直接模拟用户操作（适用于大部分网页） |
+| **API 登录**      | 通过 API 发送登录请求（更快）        |
+| **会话保持**      | 存储 Cookie 并维持登录状态           |
+| **网页爬取**      | 提取页面中的特定数据                 |
+| **PDF 生成**      | 将 HTML 页面转换为 PDF               |
+| **表单提交**      | 自动填充并提交表单                   |
 
-**无头浏览器池连接器**通过高效管理无头浏览器实例池，确保在高需求场景下执行PDF生成和网页抓取等任务时，资源利用的优化和可扩展性。
+📌 **通过无头连接器，你可以轻松地在不同网站上实现自动化操作！** 🚀

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@things-factory/integration-headless",
-  "version": "8.0.0-beta.6",
+  "version": "8.0.0-beta.8",
   "main": "dist-server/index.js",
   "things-factory": true,
   "author": "heartyoh <heartyoh@hatiolab.com>",
@@ -22,12 +22,12 @@
     "clean": "npm run clean:server"
   },
   "dependencies": {
-    "@things-factory/attachment-base": "^8.0.0-beta.5",
-    "@things-factory/board-service": "^8.0.0-beta.6",
-    "@things-factory/integration-base": "^8.0.0-beta.6",
+    "@things-factory/attachment-base": "^8.0.0-beta.8",
+    "@things-factory/board-service": "^8.0.0-beta.8",
+    "@things-factory/integration-base": "^8.0.0-beta.8",
     "@things-factory/shell": "^8.0.0-beta.5",
     "ejs": "^3.1.10",
     "pdf-lib": "^1.17.1"
   },
-  "gitHead": "4b07596c7ccb0dd903a67aa0bf1d80e608e1ed70"
+  "gitHead": "bf5206511b2d84dfb95edc3dae7f54f6cbb9bcca"
 }