handsbot-maestro-sdk 0.1.0__tar.gz

handsbot_maestro_sdk-0.1.0/LICENSE

@@ -0,0 +1,5 @@
+Copyright © 2026 4HandsBot. Todos os direitos reservados.
+
+O uso deste SDK é permitido exclusivamente por clientes autorizados,
+em conjunto com os serviços da plataforma. É proibida a redistribuição,
+publicação, sublicenciamento ou utilização fora dessa finalidade.

handsbot_maestro_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,118 @@
+Metadata-Version: 2.4
+Name: handsbot-maestro-sdk
+Version: 0.1.0
+Summary: SDK Python para criação de tarefas no Maestro (4HandsBot)
+Project-URL: Homepage, https://github.com/fourhandsbot/maestro
+Project-URL: Bug Tracker, https://github.com/fourhandsbot/maestro/issues
+Keywords: maestro,handsbot,automation,rpa,sdk
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: Other/Proprietary License
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.31.0
+Dynamic: license-file
+
+# handsbot-maestro-sdk
+
+SDK Python para criar e enfileirar tarefas de automação no **Maestro** (4HandsBot).
+
+## Instalação
+
+```bash
+pip install handsbot-maestro-sdk
+```
+
+## Uso rápido
+
+```python
+from maestro import MaestroSDK
+
+sdk = MaestroSDK(
+    api_url="https://empresa.com.br/api/v1",
+    workspace="",
+    login="",
+    keypass="",
+)
+
+task = sdk.create_task(
+    label="minha_automacao",
+    parameters=[
+        {"label": "destinatario", "value": "admin@empresa.com"},
+    ],
+)
+
+print(task.uuid, task.status)
+```
+
+## Configuração
+
+As credenciais podem ser passadas de duas formas (argumentos têm precedência):
+
+### Via variáveis de ambiente
+
+```bash
+export MAESTRO_API_URL=http://localhost:3001/api/v1
+export MAESTRO_WORKSPACE=dev
+export MAESTRO_LOGIN=empresa
+export MAESTRO_KEYPASS=pass
+```
+
+```python
+sdk = MaestroSDK()  # lê as variáveis automaticamente
+```
+
+### Via argumentos do construtor
+
+```python
+sdk = MaestroSDK(
+    api_url="https://empresa.com.br/api/v1",
+    workspace="dev",
+    login="empresa",
+    keypass="pass",
+)
+```
+
+## `create_task`
+
+```python
+task = sdk.create_task(
+    label="nome_da_automacao",       # obrigatório — label cadastrado no Maestro
+    parameters=[                      # opcional
+        {"label": "param1", "value": "valor1"},
+    ],
+    priority=1,                       # opcional, padrão 1
+    min_execution_date=datetime(...), # opcional — executa somente após esse momento
+)
+```
+
+| Parâmetro            | Tipo         | Descrição                                         |
+| -------------------- | ------------ | ------------------------------------------------- |
+| `label`              | `str`        | Label da automação cadastrada no Maestro          |
+| `parameters`         | `list[dict]` | Lista de `{"label": ..., "value": ...}`           |
+| `priority`           | `int`        | Prioridade da tarefa (padrão: `1`)                |
+| `min_execution_date` | `datetime`   | Data/hora mínima para o runner iniciar a execução |
+
+## Exceções
+
+| Exceção                  | Quando                                             |
+| ------------------------ | -------------------------------------------------- |
+| `MaestroConfigError`     | Credenciais ausentes na inicialização              |
+| `MaestroAuthError`       | Credenciais inválidas ou token expirado            |
+| `MaestroConnectionError` | Falha de rede ou `requests` não instalado          |
+| `MaestroError`           | Automação não encontrada, parâmetro inválido, etc. |
+
+## Licença
+
+Copyright © 2026 4HandsBot. Todos os direitos reservados.
+
+O uso deste SDK é permitido exclusivamente por clientes autorizados,
+em conjunto com os serviços da plataforma. É proibida a redistribuição,
+publicação, sublicenciamento ou utilização fora dessa finalidade.

handsbot_maestro_sdk-0.1.0/README.md

@@ -0,0 +1,96 @@
+# handsbot-maestro-sdk
+
+SDK Python para criar e enfileirar tarefas de automação no **Maestro** (4HandsBot).
+
+## Instalação
+
+```bash
+pip install handsbot-maestro-sdk
+```
+
+## Uso rápido
+
+```python
+from maestro import MaestroSDK
+
+sdk = MaestroSDK(
+    api_url="https://empresa.com.br/api/v1",
+    workspace="",
+    login="",
+    keypass="",
+)
+
+task = sdk.create_task(
+    label="minha_automacao",
+    parameters=[
+        {"label": "destinatario", "value": "admin@empresa.com"},
+    ],
+)
+
+print(task.uuid, task.status)
+```
+
+## Configuração
+
+As credenciais podem ser passadas de duas formas (argumentos têm precedência):
+
+### Via variáveis de ambiente
+
+```bash
+export MAESTRO_API_URL=http://localhost:3001/api/v1
+export MAESTRO_WORKSPACE=dev
+export MAESTRO_LOGIN=empresa
+export MAESTRO_KEYPASS=pass
+```
+
+```python
+sdk = MaestroSDK()  # lê as variáveis automaticamente
+```
+
+### Via argumentos do construtor
+
+```python
+sdk = MaestroSDK(
+    api_url="https://empresa.com.br/api/v1",
+    workspace="dev",
+    login="empresa",
+    keypass="pass",
+)
+```
+
+## `create_task`
+
+```python
+task = sdk.create_task(
+    label="nome_da_automacao",       # obrigatório — label cadastrado no Maestro
+    parameters=[                      # opcional
+        {"label": "param1", "value": "valor1"},
+    ],
+    priority=1,                       # opcional, padrão 1
+    min_execution_date=datetime(...), # opcional — executa somente após esse momento
+)
+```
+
+| Parâmetro            | Tipo         | Descrição                                         |
+| -------------------- | ------------ | ------------------------------------------------- |
+| `label`              | `str`        | Label da automação cadastrada no Maestro          |
+| `parameters`         | `list[dict]` | Lista de `{"label": ..., "value": ...}`           |
+| `priority`           | `int`        | Prioridade da tarefa (padrão: `1`)                |
+| `min_execution_date` | `datetime`   | Data/hora mínima para o runner iniciar a execução |
+
+## Exceções
+
+| Exceção                  | Quando                                             |
+| ------------------------ | -------------------------------------------------- |
+| `MaestroConfigError`     | Credenciais ausentes na inicialização              |
+| `MaestroAuthError`       | Credenciais inválidas ou token expirado            |
+| `MaestroConnectionError` | Falha de rede ou `requests` não instalado          |
+| `MaestroError`           | Automação não encontrada, parâmetro inválido, etc. |
+
+## Licença
+
+Copyright © 2026 4HandsBot. Todos os direitos reservados.
+
+O uso deste SDK é permitido exclusivamente por clientes autorizados,
+em conjunto com os serviços da plataforma. É proibida a redistribuição,
+publicação, sublicenciamento ou utilização fora dessa finalidade.

handsbot_maestro_sdk-0.1.0/handsbot_maestro_sdk.egg-info/PKG-INFO

@@ -0,0 +1,118 @@
+Metadata-Version: 2.4
+Name: handsbot-maestro-sdk
+Version: 0.1.0
+Summary: SDK Python para criação de tarefas no Maestro (4HandsBot)
+Project-URL: Homepage, https://github.com/fourhandsbot/maestro
+Project-URL: Bug Tracker, https://github.com/fourhandsbot/maestro/issues
+Keywords: maestro,handsbot,automation,rpa,sdk
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: Other/Proprietary License
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.31.0
+Dynamic: license-file
+
+# handsbot-maestro-sdk
+
+SDK Python para criar e enfileirar tarefas de automação no **Maestro** (4HandsBot).
+
+## Instalação
+
+```bash
+pip install handsbot-maestro-sdk
+```
+
+## Uso rápido
+
+```python
+from maestro import MaestroSDK
+
+sdk = MaestroSDK(
+    api_url="https://empresa.com.br/api/v1",
+    workspace="",
+    login="",
+    keypass="",
+)
+
+task = sdk.create_task(
+    label="minha_automacao",
+    parameters=[
+        {"label": "destinatario", "value": "admin@empresa.com"},
+    ],
+)
+
+print(task.uuid, task.status)
+```
+
+## Configuração
+
+As credenciais podem ser passadas de duas formas (argumentos têm precedência):
+
+### Via variáveis de ambiente
+
+```bash
+export MAESTRO_API_URL=http://localhost:3001/api/v1
+export MAESTRO_WORKSPACE=dev
+export MAESTRO_LOGIN=empresa
+export MAESTRO_KEYPASS=pass
+```
+
+```python
+sdk = MaestroSDK()  # lê as variáveis automaticamente
+```
+
+### Via argumentos do construtor
+
+```python
+sdk = MaestroSDK(
+    api_url="https://empresa.com.br/api/v1",
+    workspace="dev",
+    login="empresa",
+    keypass="pass",
+)
+```
+
+## `create_task`
+
+```python
+task = sdk.create_task(
+    label="nome_da_automacao",       # obrigatório — label cadastrado no Maestro
+    parameters=[                      # opcional
+        {"label": "param1", "value": "valor1"},
+    ],
+    priority=1,                       # opcional, padrão 1
+    min_execution_date=datetime(...), # opcional — executa somente após esse momento
+)
+```
+
+| Parâmetro            | Tipo         | Descrição                                         |
+| -------------------- | ------------ | ------------------------------------------------- |
+| `label`              | `str`        | Label da automação cadastrada no Maestro          |
+| `parameters`         | `list[dict]` | Lista de `{"label": ..., "value": ...}`           |
+| `priority`           | `int`        | Prioridade da tarefa (padrão: `1`)                |
+| `min_execution_date` | `datetime`   | Data/hora mínima para o runner iniciar a execução |
+
+## Exceções
+
+| Exceção                  | Quando                                             |
+| ------------------------ | -------------------------------------------------- |
+| `MaestroConfigError`     | Credenciais ausentes na inicialização              |
+| `MaestroAuthError`       | Credenciais inválidas ou token expirado            |
+| `MaestroConnectionError` | Falha de rede ou `requests` não instalado          |
+| `MaestroError`           | Automação não encontrada, parâmetro inválido, etc. |
+
+## Licença
+
+Copyright © 2026 4HandsBot. Todos os direitos reservados.
+
+O uso deste SDK é permitido exclusivamente por clientes autorizados,
+em conjunto com os serviços da plataforma. É proibida a redistribuição,
+publicação, sublicenciamento ou utilização fora dessa finalidade.

handsbot_maestro_sdk-0.1.0/handsbot_maestro_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+LICENSE
+README.md
+pyproject.toml
+handsbot_maestro_sdk.egg-info/PKG-INFO
+handsbot_maestro_sdk.egg-info/SOURCES.txt
+handsbot_maestro_sdk.egg-info/dependency_links.txt
+handsbot_maestro_sdk.egg-info/requires.txt
+handsbot_maestro_sdk.egg-info/top_level.txt
+maestro/__init__.py
+maestro/client.py
+maestro/exceptions.py

handsbot_maestro_sdk-0.1.0/handsbot_maestro_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

handsbot_maestro_sdk-0.1.0/handsbot_maestro_sdk.egg-info/requires.txt

@@ -0,0 +1 @@
+requests>=2.31.0

handsbot_maestro_sdk-0.1.0/handsbot_maestro_sdk.egg-info/top_level.txt

@@ -0,0 +1 @@
+maestro

handsbot_maestro_sdk-0.1.0/maestro/__init__.py

@@ -0,0 +1,11 @@
+from .client import MaestroSDK, Task
+from .exceptions import MaestroError, MaestroAuthError, MaestroConnectionError, MaestroConfigError
+
+__all__ = [
+    "MaestroSDK",
+    "Task",
+    "MaestroError",
+    "MaestroAuthError",
+    "MaestroConnectionError",
+    "MaestroConfigError",
+]

handsbot_maestro_sdk-0.1.0/maestro/client.py

@@ -0,0 +1,205 @@
+import os
+import sys
+import time
+from datetime import datetime
+from typing import Optional, List, Dict, Any
+
+if hasattr(sys.stdout, "reconfigure"):
+    sys.stdout.reconfigure(encoding="utf-8")
+
+try:
+    import requests as _requests
+    _HAS_REQUESTS = True
+except ImportError:
+    _HAS_REQUESTS = False
+
+from .exceptions import MaestroAuthError, MaestroConnectionError, MaestroConfigError, MaestroError
+
+_TOKEN_REFRESH_MARGIN = 300  # renova 5 min antes de expirar
+
+
+class Task:
+    """Tarefa retornada pela API após criação."""
+
+    def __init__(self, data: Dict[str, Any]):
+        self.uuid: str = data.get("uuid", "")
+        self.status: str = data.get("status", "")
+        self.priority: int = data.get("priority", 1)
+        self.min_execution_date: Optional[str] = data.get("min_execution_date")
+        self._raw = data
+
+    def __repr__(self) -> str:
+        return f"Task(uuid={self.uuid!r}, status={self.status!r})"
+
+
+class MaestroSDK:
+    """
+    SDK Python para o Maestro (4HandsBot).
+
+    Cria e enfileira tarefas de automação via API.
+
+    Configuração — duas formas (argumentos têm precedência sobre variáveis de ambiente):
+
+    1. Variáveis de ambiente:
+           MAESTRO_API_URL, MAESTRO_WORKSPACE, MAESTRO_LOGIN, MAESTRO_KEYPASS
+
+    2. Argumentos do construtor (útil para testes locais):
+           sdk = MaestroSDK(
+               api_url="http://localhost:3001/api/v1",
+               workspace="minha-empresa",
+               login="automacao@empresa.com",
+               keypass="senha",
+           )
+
+    A autenticação ocorre na inicialização — se as credenciais forem inválidas
+    ou a API estiver inacessível, uma exceção é lançada imediatamente.
+    """
+
+    def __init__(
+        self,
+        api_url: Optional[str] = None,
+        workspace: Optional[str] = None,
+        login: Optional[str] = None,
+        keypass: Optional[str] = None,
+    ):
+        self._api_url = api_url or os.environ.get("MAESTRO_API_URL")
+        self._workspace = workspace or os.environ.get("MAESTRO_WORKSPACE")
+        self._login = login or os.environ.get("MAESTRO_LOGIN")
+        self._keypass = keypass or os.environ.get("MAESTRO_KEYPASS")
+
+        self._token: Optional[str] = None
+        self._token_expires_at: Optional[float] = None
+
+        self._assert_api_config()
+        self._assert_requests()
+        self._do_authenticate()
+
+    def create_task(
+        self,
+        label: str,
+        parameters: Optional[List[Dict[str, str]]] = None,
+        priority: int = 1,
+        min_execution_date: Optional[datetime] = None,
+    ) -> Task:
+        """
+        Cria e enfileira uma tarefa pelo label da automação.
+
+        Args:
+            label:              Label da automação cadastrada no Maestro.
+            parameters:         Lista de dicionários {"label": ..., "value": ...}.
+                                Os labels devem corresponder aos parâmetros da automação.
+            priority:           Prioridade da tarefa (padrão: 1).
+            min_execution_date: Data/hora mínima para execução. Se informada, a tarefa
+                                só será iniciada pelo runner após esse momento.
+
+        Returns:
+            Task com uuid e status inicial ("pending").
+
+        Raises:
+            MaestroError:        Automação não encontrada ou parâmetro inválido.
+            MaestroAuthError:    Credenciais inválidas ou token expirado.
+            MaestroConnectionError: Falha de rede.
+        """
+        body: Dict[str, Any] = {
+            "label": label,
+            "priority": priority,
+            "parameters": parameters or [],
+        }
+        if min_execution_date is not None:
+            body["min_execution_date"] = min_execution_date.isoformat()
+
+        resp = self._request("POST", "/tasks/by-label", json=body)
+
+        if resp.status_code == 404:
+            raise MaestroError(resp.json().get("error", f"Automação '{label}' não encontrada."))
+        if resp.status_code == 400:
+            raise MaestroError(resp.json().get("error", "Parâmetros inválidos."))
+        if not resp.ok:
+            raise MaestroError(f"Erro ao criar tarefa (HTTP {resp.status_code}): {resp.text}")
+
+        return Task(resp.json())
+
+    # ------------------------------------------------------------------
+    # Autenticação (interno)
+    # ------------------------------------------------------------------
+
+    def _authenticate(self) -> str:
+        if self._token and self._token_expires_at:
+            if time.time() < self._token_expires_at - _TOKEN_REFRESH_MARGIN:
+                return self._token
+        self._do_authenticate()
+        return self._token  # type: ignore[return-value]
+
+    def _do_authenticate(self) -> None:
+        self._assert_requests()
+        self._assert_api_config()
+
+        url = f"{self._api_url}/auth/client-login"
+        body = {
+            "workspace": self._workspace,
+            "login": self._login,
+            "keypass": self._keypass,
+        }
+        headers = {"Content-Type": "application/json", "X-Client-Type": "sdk"}
+
+        try:
+            resp = _requests.post(url, json=body, headers=headers, timeout=30)
+        except _requests.RequestException as exc:
+            raise MaestroConnectionError(f"Falha ao conectar à API Maestro: {exc}") from exc
+
+        if resp.status_code == 401:
+            raise MaestroAuthError("Credenciais inválidas.")
+        if not resp.ok:
+            raise MaestroAuthError(f"Falha na autenticação (HTTP {resp.status_code}): {resp.text}")
+
+        data = resp.json()
+        self._token = data["token"]
+        expires_raw: str = data["expires_at"]
+        dt = datetime.fromisoformat(expires_raw.replace("Z", "+00:00"))
+        self._token_expires_at = dt.timestamp()
+
+    def _request(self, method: str, endpoint: str, **kwargs: Any) -> Any:
+        self._assert_api_config()
+        self._assert_requests()
+
+        url = f"{self._api_url}{endpoint}"
+        headers = {"Authorization": f"Bearer {self._authenticate()}", "X-Client-Type": "sdk"}
+        headers.update(kwargs.pop("headers", {}))
+
+        resp = _requests.request(method, url, headers=headers, timeout=30, **kwargs)
+
+        if resp.status_code == 498:
+            self._token = None
+            headers["Authorization"] = f"Bearer {self._authenticate()}"
+            resp = _requests.request(method, url, headers=headers, timeout=30, **kwargs)
+
+        return resp
+
+    # ------------------------------------------------------------------
+    # Helpers
+    # ------------------------------------------------------------------
+
+    def _assert_api_config(self) -> None:
+        missing = [
+            name
+            for name, val in [
+                ("api_url", self._api_url),
+                ("workspace", self._workspace),
+                ("login", self._login),
+                ("keypass", self._keypass),
+            ]
+            if not val
+        ]
+        if missing:
+            raise MaestroConfigError(
+                f"Configuração incompleta — campos ausentes: {', '.join(missing)}. "
+                "Passe via variáveis de ambiente (MAESTRO_API_URL, MAESTRO_WORKSPACE, "
+                "MAESTRO_LOGIN, MAESTRO_KEYPASS) ou pelos argumentos do construtor."
+            )
+
+    def _assert_requests(self) -> None:
+        if not _HAS_REQUESTS:
+            raise MaestroConnectionError(
+                "O pacote 'requests' é necessário. "
+                "Instale com: pip install handsbot-maestro-sdk"
+            )

handsbot_maestro_sdk-0.1.0/maestro/exceptions.py

@@ -0,0 +1,11 @@
+class MaestroError(Exception):
+    pass
+
+class MaestroAuthError(MaestroError):
+    pass
+
+class MaestroConnectionError(MaestroError):
+    pass
+
+class MaestroConfigError(MaestroError):
+    pass

handsbot_maestro_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "handsbot-maestro-sdk"
+version = "0.1.0"
+description = "SDK Python para criação de tarefas no Maestro (4HandsBot)"
+readme = "README.md"
+license-files = ["LICENSE"]
+requires-python = ">=3.9"
+dependencies = [
+    "requests>=2.31.0",
+]
+keywords = ["maestro", "handsbot", "automation", "rpa", "sdk"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "License :: Other/Proprietary License",
+    "Operating System :: OS Independent",
+    "Intended Audience :: Developers",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+[project.urls]
+Homepage = "https://github.com/fourhandsbot/maestro"
+"Bug Tracker" = "https://github.com/fourhandsbot/maestro/issues"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["maestro*"]
+exclude = ["example*", ".venv*"]

handsbot_maestro_sdk-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+