@things-factory/integration-base 9.0.6 → 9.0.13

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

@@ -0,0 +1,55 @@
+# pyrun-connector
+
+Python Runner（pyrun）REST APIと連携するためのコネクタです。
+pyrunサーバーのREST API（例：`/api/run/{module}`）を呼び出して、Pythonモジュールの実行結果を取得できます。
+
+## パラメータ
+
+- **endpoint**: pyrunサーバーのURL（例：`http://runner.hatiolab.com:8000`）
+- **username**: （任意）pyrunサーバーにログインするユーザー名（認証が必要な場合）
+- **password**: （任意）pyrunサーバーにログインするパスワード（認証が必要な場合）
+- **token**: （任意）Bearer認証トークン。直接入力するか、username/passwordでログイン時に自動発行されます。
+
+> pyrunサーバーが認証を要求しない場合は、endpointのみ入力してください。  
+> 認証が必要な場合は、username/passwordを入力すると、コネクタが`/auth/login` APIを通じてトークンを自動取得して使用します。  
+> すでにトークンを持っている場合は、tokenのみ入力してください。
+
+## 動作仕様
+
+- usernameとpasswordが両方入力されている場合、`/auth/login`エンドポイントにログインリクエストを送り、レスポンスから`access_token`を抽出して使用します。
+- tokenが入力されている場合は、AuthorizationヘッダーのBearerトークンとしてそのまま使用します。
+- 認証情報がない場合は、認証なしでpyrun APIを呼び出します。
+- 認証に失敗した場合はエラーメッセージが返されます。
+
+## 使用例
+
+```json
+{
+  "type": "pyrun-connector",
+  "endpoint": "http://runner.hatiolab.com:8000",
+  "params": {
+    "username": "your username",
+    "password": "your password"
+  }
+}
+```
+
+または
+
+```json
+{
+  "type": "pyrun-connector",
+  "endpoint": "http://runner.hatiolab.com:8000",
+  "params": {
+    "token": "your-access-token"
+  }
+}
+```
+
+## 注意事項
+
+- Basic認証（Authorization: Basic ...）はサポートされていません。
+- username/passwordを入力すると、自動的にトークンが発行されて使用されます。
+- tokenのみ入力した場合は、そのままBearer認証として使用されます。
+- pyrunサーバーの認証ポリシーに従って、必要なパラメータを入力してください。
+- 認証に失敗した場合、`"pyrun-connector 認証失敗: [ステータスコード] [エラーメッセージ]"`のようなエラーが発生することがあります。

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

@@ -0,0 +1,55 @@
+# pyrun-connector
+
+Python Runner(pyrun) REST API와 연동하기 위한 커넥터입니다.  
+pyrun 서버의 REST API(예: `/api/run/{module}`)를 호출하여 파이썬 모듈 실행 결과를 받아올 수 있습니다.
+
+## 파라미터
+
+- **endpoint**: pyrun 서버의 URL (예: `http://runner.hatiolab.com:8000`)
+- **username**: (선택) pyrun 서버에 로그인할 사용자명. (인증이 필요한 경우)
+- **password**: (선택) pyrun 서버에 로그인할 비밀번호. (인증이 필요한 경우)
+- **token**: (선택) Bearer 인증 토큰. 직접 입력하거나, username/password로 로그인 시 자동 발급받아 사용합니다.
+
+> pyrun 서버가 인증을 요구하지 않는 경우, endpoint만 입력하면 됩니다.  
+> 인증이 필요한 경우, username/password를 입력하면 `/auth/login` API를 통해 토큰을 자동으로 발급받아 사용합니다.  
+> 이미 발급받은 토큰이 있다면 token만 입력해도 됩니다.
+
+## 동작 방식
+
+- username/password가 모두 입력되면 `/auth/login` 엔드포인트로 로그인 요청을 보내고, 응답에서 `access_token`을 추출하여 사용합니다.
+- token이 입력된 경우, 바로 Authorization 헤더(`Bearer {token}`)로 pyrun API를 호출합니다.
+- 인증 정보가 모두 없으면 인증 없이 pyrun API를 호출합니다.
+- 인증 실패 시 에러 메시지가 반환됩니다.
+
+## 사용 예시
+
+```json
+{
+  "type": "pyrun-connector",
+  "endpoint": "http://runner.hatiolab.com:8000",
+  "params": {
+    "username": "your username",
+    "password": "your password"
+  }
+}
+```
+
+또는
+
+```json
+{
+  "type": "pyrun-connector",
+  "endpoint": "http://runner.hatiolab.com:8000",
+  "params": {
+    "token": "your-access-token"
+  }
+}
+```
+
+## 참고
+
+- Basic 인증(Authorization: Basic ...)은 지원하지 않습니다.
+- username/password를 입력하면 자동으로 토큰을 발급받아 사용합니다.
+- token만 입력하면 바로 Bearer 인증으로 사용합니다.
+- pyrun 서버의 인증 정책에 따라 파라미터를 선택적으로 입력하세요.
+- 인증 실패 시 `"pyrun-connector 인증 실패: [상태코드] [에러메시지]"` 형태의 에러가 발생할 수 있습니다.

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

@@ -0,0 +1,55 @@
+# pyrun-connector
+
+This connector is for integrating with the Python Runner (pyrun) REST API.
+You can use it to call the pyrun server's REST API (e.g., `/api/run/{module}`) and receive the result of running a Python module.
+
+## Parameters
+
+- **endpoint**: The URL of the pyrun server (e.g., `http://runner.hatiolab.com:8000`)
+- **username**: (Optional) Username for logging in to the pyrun server (if authentication is required)
+- **password**: (Optional) Password for logging in to the pyrun server (if authentication is required)
+- **token**: (Optional) Bearer authentication token. You can enter it directly, or it will be automatically issued and used if you log in with username/password.
+
+> If the pyrun server does not require authentication, just enter the endpoint.  
+> If authentication is required, enter username/password and the connector will automatically obtain a token via the `/auth/login` API.  
+> If you already have a token, you can enter only the token.
+
+## How it works
+
+- If both username and password are provided, the connector sends a login request to the `/auth/login` endpoint and extracts the `access_token` from the response.
+- If a token is provided, it is used directly as a Bearer token in the Authorization header for pyrun API calls.
+- If no authentication information is provided, the pyrun API is called without authentication.
+- If authentication fails, an error message is returned.
+
+## Example
+
+```json
+{
+  "type": "pyrun-connector",
+  "endpoint": "http://runner.hatiolab.com:8000",
+  "params": {
+    "username": "your username",
+    "password": "your password"
+  }
+}
+```
+
+Or
+
+```json
+{
+  "type": "pyrun-connector",
+  "endpoint": "http://runner.hatiolab.com:8000",
+  "params": {
+    "token": "your-access-token"
+  }
+}
+```
+
+## Notes
+
+- Basic authentication (Authorization: Basic ...) is not supported.
+- If you enter username/password, a token is automatically issued and used.
+- If you enter only a token, it is used directly as Bearer authentication.
+- Enter parameters as needed according to the pyrun server's authentication policy.
+- If authentication fails, you may see an error like: `"pyrun-connector authentication failed: [status code] [error message]"`.

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

@@ -0,0 +1,55 @@
+# pyrun-connector
+
+Penyambung ini digunakan untuk integrasi dengan Python Runner (pyrun) REST API.
+Anda boleh memanggil REST API pelayan pyrun (cth: `/api/run/{module}`) dan menerima hasil pelaksanaan modul Python.
+
+## Parameter
+
+- **endpoint**: URL pelayan pyrun (cth: `http://runner.hatiolab.com:8000`)
+- **username**: (Pilihan) Nama pengguna untuk log masuk ke pelayan pyrun (jika perlu pengesahan)
+- **password**: (Pilihan) Kata laluan untuk log masuk ke pelayan pyrun (jika perlu pengesahan)
+- **token**: (Pilihan) Token pengesahan Bearer. Anda boleh masukkan secara langsung, atau ia akan dijana dan digunakan secara automatik jika anda log masuk dengan username/password.
+
+> Jika pelayan pyrun tidak memerlukan pengesahan, hanya masukkan endpoint.  
+> Jika perlu pengesahan, masukkan username/password dan penyambung akan mendapatkan token secara automatik melalui API `/auth/login`.  
+> Jika anda sudah mempunyai token, hanya masukkan token sahaja.
+
+## Cara Kerja
+
+- Jika kedua-dua username dan password diberikan, penyambung akan menghantar permintaan log masuk ke endpoint `/auth/login` dan mengekstrak `access_token` dari respons.
+- Jika token diberikan, ia akan digunakan secara langsung sebagai Bearer token dalam header Authorization untuk panggilan API pyrun.
+- Jika tiada maklumat pengesahan diberikan, API pyrun akan dipanggil tanpa pengesahan.
+- Jika pengesahan gagal, mesej ralat akan dipaparkan.
+
+## Contoh Penggunaan
+
+```json
+{
+  "type": "pyrun-connector",
+  "endpoint": "http://runner.hatiolab.com:8000",
+  "params": {
+    "username": "your username",
+    "password": "your password"
+  }
+}
+```
+
+Atau
+
+```json
+{
+  "type": "pyrun-connector",
+  "endpoint": "http://runner.hatiolab.com:8000",
+  "params": {
+    "token": "your-access-token"
+  }
+}
+```
+
+## Nota
+
+- Pengesahan Basic (Authorization: Basic ...) tidak disokong.
+- Jika anda masukkan username/password, token akan dijana dan digunakan secara automatik.
+- Jika anda hanya masukkan token, ia akan digunakan terus sebagai pengesahan Bearer.
+- Masukkan parameter mengikut keperluan dasar pengesahan pelayan pyrun.
+- Jika pengesahan gagal, anda mungkin akan menerima ralat seperti: `"pyrun-connector pengesahan gagal: [kod status] [mesej ralat]"`.

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

@@ -0,0 +1,55 @@
+# pyrun-connector
+
+用于与 Python Runner (pyrun) REST API 集成的连接器。
+可以调用 pyrun 服务器的 REST API（如 `/api/run/{module}`），并获取 Python 模块的执行结果。
+
+## 参数
+
+- **endpoint**: pyrun 服务器的 URL（例如：`http://runner.hatiolab.com:8000`）
+- **username**: （可选）登录 pyrun 服务器的用户名（如需认证时）
+- **password**: （可选）登录 pyrun 服务器的密码（如需认证时）
+- **token**: （可选）Bearer 认证令牌。可直接输入，或通过输入用户名/密码自动获取并使用。
+
+> 如果 pyrun 服务器不需要认证，只需输入 endpoint。  
+> 如果需要认证，输入 username/password，连接器会通过 `/auth/login` API 自动获取令牌。  
+> 如果已有令牌，只需输入 token 即可。
+
+## 工作方式
+
+- 同时输入 username 和 password 时，连接器会向 `/auth/login` 端点发送登录请求，并从响应中提取 `access_token`。
+- 输入 token 时，直接作为 Bearer 令牌用于 Authorization 头部调用 pyrun API。
+- 未输入认证信息时，将不带认证信息调用 pyrun API。
+- 认证失败时会返回错误信息。
+
+## 使用示例
+
+```json
+{
+  "type": "pyrun-connector",
+  "endpoint": "http://runner.hatiolab.com:8000",
+  "params": {
+    "username": "your username",
+    "password": "your password"
+  }
+}
+```
+
+或
+
+```json
+{
+  "type": "pyrun-connector",
+  "endpoint": "http://runner.hatiolab.com:8000",
+  "params": {
+    "token": "your-access-token"
+  }
+}
+```
+
+## 备注
+
+- 不支持 Basic 认证（Authorization: Basic ...）。
+- 输入 username/password 时会自动获取并使用令牌。
+- 仅输入 token 时直接作为 Bearer 认证使用。
+- 请根据 pyrun 服务器的认证策略选择性输入参数。
+- 认证失败时，可能会出现如下错误：`"pyrun-connector 认证失败: [状态码] [错误信息]"`。

package/helps/integration/task/pyrun-execute.ja.md

@@ -0,0 +1,36 @@
+# pyrun-execute
+
+pyrun-connector を通じて Python Runner（pyrun）サーバーの REST API（`/api/run/{module}`）を呼び出し、  
+指定した Python モジュールを実行し、その結果を返すタスクです。
+
+## パラメータ
+
+- **module**: 実行する Python モジュール名（必須）
+- **input-params**: （任意）Python モジュールに渡す入力パラメータ（キー・バリューのオブジェクト）
+
+## 使用例
+
+```json
+{
+  "task": "pyrun-execute",
+  "connection": "my-pyrun",
+  "params": {
+    "module": "hello_world",
+    "input": {
+      "name": "山田太郎",
+      "count": 3
+    }
+  }
+}
+```
+
+## 実行結果
+
+- 正常に実行されると、Python モジュールの実行結果（result）が返されます。
+- 実行中の標準出力（stdout）はログに記録され、標準エラー（stderr）が発生した場合はエラーとして処理されます。
+- exit_code が 0 でない場合、タスクは失敗とみなされエラーが発生します。
+
+## 注意事項
+
+- pyrun-connector の認証設定（token または username/password）が必要な場合があります。
+- 入力パラメータは `input` オブジェクトとして Python モジュールに渡されます。

package/helps/integration/task/pyrun-execute.ko.md

@@ -0,0 +1,36 @@
+# pyrun-execute
+
+pyrun-connector를 통해 Python Runner(pyrun) 서버의 REST API(`/api/run/{module}`)를 호출하여  
+지정한 파이썬 모듈을 실행하고, 실행 결과를 반환하는 태스크입니다.
+
+## parameters
+
+- **module**: 실행할 파이썬 모듈명 (필수)
+- **input-params**: (선택) 파이썬 모듈에 전달할 입력 파라미터(키-값 쌍, 오브젝트)
+
+## 사용 예시
+
+```json
+{
+  "task": "pyrun-execute",
+  "connection": "my-pyrun",
+  "params": {
+    "module": "hello_world",
+    "input": {
+      "name": "홍길동",
+      "count": 3
+    }
+  }
+}
+```
+
+## 실행 결과
+
+- 정상적으로 실행되면, 파이썬 모듈의 실행 결과(result)가 반환됩니다.
+- 실행 중 표준 출력(stdout)은 로그로 기록되며, 표준 에러(stderr) 발생 시 에러로 처리됩니다.
+- exit_code가 0이 아니면 태스크가 실패로 간주되어 에러가 발생합니다.
+
+## 참고
+
+- pyrun-connector의 인증 설정(token 또는 username/password)이 필요할 수 있습니다.
+- 입력 파라미터는 파이썬 모듈에서 `input` 오브젝트로 전달됩니다.

package/helps/integration/task/pyrun-execute.md

@@ -0,0 +1,36 @@
+# pyrun-execute
+
+This task calls the Python Runner (pyrun) server's REST API (`/api/run/{module}`) via pyrun-connector,  
+executes the specified Python module, and returns the result.
+
+## parameters
+
+- **module**: Name of the Python module to execute (required)
+- **input-params**: (Optional) Input parameters (key-value object) to pass to the Python module
+
+## Example
+
+```json
+{
+  "task": "pyrun-execute",
+  "connection": "my-pyrun",
+  "params": {
+    "module": "hello_world",
+    "input": {
+      "name": "John Doe",
+      "count": 3
+    }
+  }
+}
+```
+
+## Result
+
+- If successful, returns the result of the Python module execution.
+- Standard output (stdout) is logged, and standard error (stderr) is treated as an error.
+- If exit_code is not 0, the task is considered failed and an error is thrown.
+
+## Notes
+
+- pyrun-connector authentication (token or username/password) may be required.
+- The input parameters are passed as the `input` object to the Python module.

package/helps/integration/task/pyrun-execute.ms.md

@@ -0,0 +1,36 @@
+# pyrun-execute
+
+Tugas ini memanggil REST API pelayan Python Runner (pyrun) (`/api/run/{module}`) melalui pyrun-connector,  
+menjalankan modul Python yang ditetapkan dan memulangkan hasilnya.
+
+## Parameter
+
+- **module**: Nama modul Python yang hendak dijalankan (wajib)
+- **input-params**: (Pilihan) Parameter input (objek pasangan kunci-nilai) untuk dihantar ke modul Python
+
+## Contoh Penggunaan
+
+```json
+{
+  "task": "pyrun-execute",
+  "connection": "my-pyrun",
+  "params": {
+    "module": "hello_world",
+    "input": {
+      "name": "Ali",
+      "count": 3
+    }
+  }
+}
+```
+
+## Hasil
+
+- Jika berjaya, hasil pelaksanaan modul Python akan dipulangkan.
+- Output piawai (stdout) akan direkodkan dalam log, dan ralat piawai (stderr) akan dianggap sebagai ralat.
+- Jika exit_code bukan 0, tugas dianggap gagal dan ralat akan dibangkitkan.
+
+## Nota
+
+- Pengesahan pyrun-connector (token atau username/password) mungkin diperlukan.
+- Parameter input akan dihantar sebagai objek `input` ke modul Python.

package/helps/integration/task/pyrun-execute.zh.md

@@ -0,0 +1,36 @@
+# pyrun-execute
+
+通过 pyrun-connector 调用 Python Runner (pyrun) 服务器的 REST API（`/api/run/{module}`），  
+执行指定的 Python 模块并返回执行结果的任务。
+
+## 参数
+
+- **module**: 要执行的 Python 模块名称（必填）
+- **input-params**: （可选）传递给 Python 模块的输入参数（键值对对象）
+
+## 使用示例
+
+```json
+{
+  "task": "pyrun-execute",
+  "connection": "my-pyrun",
+  "params": {
+    "module": "hello_world",
+    "input": {
+      "name": "张三",
+      "count": 3
+    }
+  }
+}
+```
+
+## 执行结果
+
+- 执行成功时，返回 Python 模块的执行结果（result）。
+- 执行过程中标准输出（stdout）会被记录为日志，标准错误（stderr）会作为错误处理。
+- exit_code 不为 0 时，任务会被视为失败并抛出错误。
+
+## 备注
+
+- 可能需要 pyrun-connector 的认证设置（token 或 username/password）。
+- 输入参数会作为 `input` 对象传递给 Python 模块。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@things-factory/integration-base",
-  "version": "9.0.6",
+  "version": "9.0.13",
   "main": "dist-server/index.js",
   "browser": "client/index.js",
   "things-factory": true,
@@ -45,5 +45,5 @@
     "readline": "^1.3.0",
     "ses": "^1.5.0"
   },
-  "gitHead": "dbefe868d95df678038075c233267a4edc64dc40"
+  "gitHead": "8629e384d819c0d232f76def3e04ed0c1030a3d0"
 }

package/translations/en.json

@@ -8,6 +8,8 @@
   "label.auth-key": "authentication key",
   "label.connectionTimeoutMillis": "Connection Timeout (milliseconds)",
   "label.idleTimeoutMillis": "Idle Timeout (milliseconds)",
+  "label.input-params": "input parameters",
+  "label.token": "token",
   "label.login-api-url": "login API URL",
   "label.login-page-path": "login page path",
   "label.maxPoolConnection": "Max Pool Connection",

package/translations/ja.json

@@ -8,6 +8,8 @@
   "label.auth-key": "認証キー",
   "label.connectionTimeoutMillis": "接続タイムアウト（ミリ秒）",
   "label.idleTimeoutMillis": "アイドルタイムアウト（ミリ秒）",
+  "label.input-params": "入力パラメータ",
+  "label.token": "トークン",
   "label.login-api-url": "ログインAPI URL",
   "label.login-page-path": "ログインページパス",
   "label.maxPoolConnection": "最大プール接続数",

package/translations/ko.json

@@ -8,6 +8,8 @@
   "label.auth-key": "인증 키",
   "label.connectionTimeoutMillis": "연결 시간 제한 (밀리초)",
   "label.idleTimeoutMillis": "유휴 시간 제한 (밀리초)",
+  "label.input-params": "입력 파라미터",
+  "label.token": "토큰",
   "label.login-api-url": "로그인 API URL",
   "label.login-page-path": "로그인 페이지 경로",
   "label.maxPoolConnection": "최대 풀 연결 수",

package/translations/ms.json

@@ -8,6 +8,8 @@
   "label.auth-key": "Kunci pengesahan",
   "label.connectionTimeoutMillis": "Had Masa Sambungan (milisaat)",
   "label.idleTimeoutMillis": "Had Masa Tanpa Aktiviti (milisaat)",
+  "label.input-params": "parameter input",
+  "label.token": "token",
   "label.login-api-url": "URL API log masuk",
   "label.login-page-path": "laluan halaman log masuk",
   "label.maxPoolConnection": "Sambungan Pool Maksimum",

package/translations/zh.json

@@ -8,6 +8,8 @@
   "label.auth-key": "认证密钥",
   "label.connectionTimeoutMillis": "连接超时时间（毫秒）",
   "label.idleTimeoutMillis": "空闲超时时间（毫秒）",
+  "label.input-params": "输入参数",
+  "label.token": "token",
   "label.login-api-url": "登录API URL",
   "label.login-page-path": "登录页面路径",
   "label.maxPoolConnection": "最大连接池连接数",