botcity-maestro-client 1.0.1

A lightweight Python SDK for interacting with the BotCity Maestro API v2.

🇧🇷 BotCity Maestro Client (pt-BR)

📘 Leia esse documento em outros idiomas:
🇺🇸 English Version

BotCity Maestro Client é um SDK Python leve e moderno para interação com a API BotCity Maestro (v2).
Ele fornece um ponto de entrada único, autenticação automática com cache de token e uma interface consistente para todas as rotas da API.

---

🚀 Instalação

pip install botcity-maestro-client

Dependências:

• requests >= 2.31.0

---

⚡ Exemplo rápido

from maestro_client import MaestroClient

# Inicializa o cliente
client = MaestroClient(
    login="seu_login",
    key="sua_chave",
    base_url="https://developers.botcity.dev"
)

# Autentica (executado automaticamente se necessário)
client.authenticate()

# Lista tarefas
tasks = client.tasks.list(page=1, size=50)
print(tasks.data)

# Busca uma tarefa específica
task = client.tasks.get(task_id="123456")
print(task.data)

# Cancela uma tarefa
client.tasks.cancel(task_id="123456")

---

🧩 Recursos principais

✅ Cache de token e renovação automática em caso de 401 Unauthorized
✅ Submódulos organizados (tasks, bots, logs, runners, etc.)
✅ Retorno padronizado via MaestroResponse
✅ Suporte para chamadas diretas com request_raw()
✅ Tipagem completa e docstrings para IDEs

---

🧱 Estrutura da Classe Principal

MaestroClient

Classe principal para interação com a API BotCity Maestro.

Atributo	Tipo	Descrição
base_url	str	URL base da API Maestro (padrão: https://developers.botcity.dev)
login_value	str	Credencial de login
key_value	str	Chave de autenticação
organization	str	Identificador da organização
token	str	Token de acesso com cache automático

---

🔐 Autenticação

A autenticação é realizada via:

POST /api/v2/workspace/login

Exemplo de uso:

client.authenticate()
print(client.token)         # Bearer token
print(client.organization)  # Organização cacheada

---

🌐 Requisições personalizadas

Você pode chamar qualquer rota diretamente usando request_raw():

response = client.request_raw(
    method="GET",
    path="/api/v2/task",
    params={"size": 50, "page": 0, "sort": "dateCreation"}
)

print(response.status_code)
print(response.data)

---

🧩 Submódulos disponíveis

Recurso	Endpoint	Descrição
tasks	/api/v2/task	Gerencia criação, status e controle de tarefas
logs	/api/v2/log	Cria, lista e baixa logs
automations	/api/v2/activity	Lista automações e seus metadados
bots	/api/v2/bot	Gerencia versões e repositórios de bots
runners	/api/v2/machine	Exibe informações sobre máquinas e runners
credentials	/api/v2/credential	Cria e recupera credenciais seguras
datapools	/api/v2/datapool	Gerencia pools de dados e seus itens
result_files	/api/v2/artifact	Manipula arquivos e artefatos de resultado
errors	/api/v2/error	Lista e detalha erros por automação
schedules	/api/v2/scheduling	Cria e gerencia agendamentos
workspaces	/api/v2/workspaces	Consulta informações do workspace

---

💾 Exemplo – Criando uma Credencial

client.credentials.create(
    label="MyCredential",
    values={
        "user": "user123",
        "password": "pass123"
    }
)

Payload enviado:

{
  "label": "MyCredential",
  "organizationLabel": "ORG123",
  "repositoryLabel": "DEFAULT",
  "secrets": [
    {"key": "user", "value": "user123"},
    {"key": "password", "value": "pass123"}
  ]
}

---

🔍 MaestroResponse

Cada requisição retorna um objeto padronizado MaestroResponse.

Atributo	Tipo	Descrição
ok	bool	Indica se a resposta foi 2xx
status_code	int	Código HTTP
url	str	URL final requisitada
headers	dict	Cabeçalhos de resposta
data	dict ou bytes	Dados decodificados
raw	requests.Response	Objeto original da resposta

---

🧠 Tratamento de erros

Todas as exceções são encapsuladas em MaestroClientError.

from maestro_client import MaestroClientError

try:
    client.tasks.get("invalid_id")
except MaestroClientError as e:
    print("Erro:", e)

---

📂 Estrutura mínima do projeto

src/
 └── maestro_client/
      ├── __init__.py
      ├── client.py
      ├── helpers.py
      └── ...

---

📘 Roadmap

• Adicionar suporte assíncrono (aiohttp)
• Implementar retry com backoff exponencial
• Melhorar tipagem de retorno dos submódulos

---

📜 Licença

Distribuído sob a licença MIT.
© 2025 Ausier

---

🇺🇸 BotCity Maestro Client (EN)

📘 Read this document in other languages:
🇧🇷 Versão em Português (pt-BR)

BotCity Maestro Client is a lightweight and modern Python SDK for interacting with the BotCity Maestro API (v2).
It provides a single entry point, automatic token caching, and a unified response structure for all resources.

---

🚀 Installation

pip install botcity-maestro-client

Dependencies:

• requests >= 2.31.0

---

⚡ Quick Example

from maestro_client import MaestroClient

client = MaestroClient(
    login="your_login",
    key="your_key",
    base_url="https://developers.botcity.dev"
)

# Authenticate (auto-called if needed)
client.authenticate()

# List tasks
tasks = client.tasks.list(page=1, size=50)
print(tasks.data)

---

🧱 Class Overview

MaestroClient

Main entry point for all BotCity Maestro API interactions.

Attribute	Type	Description
base_url	str	Base URL of the Maestro API
login_value	str	Login credential
key_value	str	API key credential
organization	str	Cached organization label
token	str	Cached access token

---

🔐 Authentication

Authentication is performed via:

POST /api/v2/workspace/login

Example:

client.authenticate()
print(client.token)
print(client.organization)

The client automatically refreshes tokens when expired or on 401 Unauthorized.

---

🌐 Custom Requests

Use request_raw() to call any API route directly:

resp = client.request_raw(
    method="GET",
    path="/api/v2/task",
    params={"page": 1, "size": 20}
)
print(resp.data)

---

🧩 Submodules

Resource	Endpoint	Description
tasks	/api/v2/task	Manage task creation and control
logs	/api/v2/log	Create and list logs
automations	/api/v2/activity	View automation metadata
bots	/api/v2/bot	Manage bots and versions
runners	/api/v2/machine	Get machine/runner info
credentials	/api/v2/credential	Manage credentials
datapools	/api/v2/datapool	Manage data pools
result_files	/api/v2/artifact	Handle artifacts
errors	/api/v2/error	Inspect automation errors
schedules	/api/v2/scheduling	Manage schedules
workspaces	/api/v2/workspaces	View workspace info

---

🧠 Example – Creating a Credential

client.credentials.create(
    label="MyCredential",
    values={
        "user": "user123",
        "password": "pass123"
    }
)

---

🧩 Error Handling

All errors raise a MaestroClientError.

from maestro_client import MaestroClientError

try:
    client.tasks.get("invalid_id")
except MaestroClientError as e:
    print("Error:", e)

---

📘 Roadmap

• Add async support (aiohttp)
• Implement exponential retry/backoff
• Improve type coverage

---

📜 License

Distributed under the MIT License.
© 2025 Ausier