Metadata-Version: 2.4
Name: handsbot-maestro-sdk
Version: 0.3.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.
