zsynctech-sdk 1.4.9__py3-none-any.whl

zsynctech_sdk-1.4.9.dist-info/METADATA

@@ -0,0 +1,208 @@
+Metadata-Version: 2.3
+Name: zsynctech-sdk
+Version: 1.4.9
+Summary: SDK Python para conectar robôs (RPA) à plataforma zsynctech-studio via Socket.IO
+Author: Rodrigo Zavan
+Author-email: Rodrigo Zavan <rodrigo.zavan@zsynctech.com.br>
+Requires-Dist: loguru>=0.7
+Requires-Dist: pydantic>=2.9
+Requires-Dist: python-socketio[client]>=5.11
+Requires-Dist: requests>=2.31
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+# zsynctech-sdk
+
+SDK Python oficial para conectar robôs de RPA à plataforma **zsynctech-studio**: handshake,
+heartbeat, ciclo de execução, consumo de fila e acesso ao cofre de credenciais, tudo via
+Socket.IO (namespace `/robot`).
+
+## Uso rápido
+
+`client.on_automation_start` registra o que rodar quando a plataforma disparar o botão
+"Iniciar" para esse robô. `client.listen()` mantém o processo vivo aguardando esse evento,
+até a conexão encerrar ou você pressionar Ctrl+C.
+
+Há duas formas de reportar trabalho, dependendo de onde a lista de tasks vem:
+
+### Consumindo a fila da plataforma
+
+Use quando as tasks vêm de uma planilha importada na plataforma - `client.queue.consume()`
+entrega uma a uma até a fila esvaziar.
+
+```python
+from zsynctech_studio_sdk import RobotClient, TaskStatus
+
+client = RobotClient.from_api_key(
+    "<sua-api-key>",
+    backend_url="http://localhost:5000",
+)
+
+@client.on_automation_start
+def handle_automation() -> None:
+    with client.execution.run(observation="Minha automação"):
+        for task in client.queue.consume():
+            with client.queue.processing(task) as outcome:
+                resultado = processar(task.payload)
+                outcome.success(result=resultado)
+
+with client:
+    client.listen()
+```
+
+### Sem fila: robô que processa a própria fonte de dados
+
+Use quando o robô lê de uma fonte própria (planilha local, API interna, scraping, banco de
+dados...) em vez de uma fila importada na plataforma - pule `client.queue` inteiramente e
+reporte cada resultado direto com `client.execution.report_tasks(...)`.
+
+```python
+from zsynctech_studio_sdk import RobotClient, TaskItem, TaskStatus
+from zsynctech_studio_sdk.utils import utc_now
+
+client = RobotClient.from_api_key(
+    "<sua-api-key>",
+    backend_url="http://localhost:5000",
+)
+
+@client.on_automation_start
+def handle_automation() -> None:
+    itens = buscar_itens_a_processar()  # a fonte de dados é sua
+
+    with client.execution.run(observation="Processamento de itens próprios"):
+        for item in itens:
+            started_at = utc_now()
+            resultado = processar(item)
+
+            client.execution.report_tasks([
+                TaskItem(
+                    external_id=item.id,
+                    status=TaskStatus.SUCCESS,
+                    result=resultado,
+                    started_at=started_at,
+                    finished_at=utc_now(),
+                )
+            ])
+
+with client:
+    client.listen()
+```
+
+Exemplos completos em [`examples/`](examples/):
+
+- [`simulate_robot.py`](examples/simulate_robot.py) - robô completo consumindo tasks de uma
+  fila da plataforma (`client.queue.consume()`); também demonstra `client.credentials.reveal()`
+  logo após conectar.
+- [`own_tasks_robot.py`](examples/own_tasks_robot.py) - robô que processa a própria fonte de
+  dados (planilha, API interna, etc.) e reporta os resultados direto na execução
+  (`client.execution.report_tasks()`), sem usar fila.
+
+### Observação da execução
+
+`observation` descreve o que está acontecendo numa execução - visível na plataforma. Dá pra
+atualizá-la quantas vezes quiser enquanto a execução está rodando, e sobrescrevê-la no
+`finish()` com o resultado final. `execution.run()` (o atalho com `with`) sempre finaliza com a
+`observation` original, então esse controle mais fino pede o par `start()`/`finish()` manual:
+
+```python
+client.execution.start(observation="Boletagem VCOM")
+try:
+    tasks = list(client.queue.consume())
+    if not tasks:
+        client.execution.finish(observation="Fila vazia, nada a processar")
+    else:
+        for i, task in enumerate(tasks, start=1):
+            client.execution.update_observation(f"Processando {i}/{len(tasks)}")
+            ...
+        client.execution.finish()
+except Exception:
+    client.execution.finish(ExecutionFinishStatus.FAILED)
+    raise
+```
+
+## Credenciais
+
+O cofre de credenciais é acessado via REST (`/robot/credentials`), sem precisar de uma conexão
+`/robot` aberta - `client.credentials` funciona mesmo antes de `client.connect()`:
+
+```python
+credencial = client.credentials.reveal("<credential-id>")
+print(credencial.value)  # str (TEXT), dict[str, str] (KEY_VALUE) ou JSON (JSON)
+
+client.credentials.rotate("<credential-id>", "novo-valor")
+
+client.credentials.expire("<credential-id>", "Login rejeitado pelo site do fornecedor")
+```
+
+Veja `log_credential()` em [`examples/simulate_robot.py`](examples/simulate_robot.py) para um
+exemplo em contexto (revela uma credencial e loga o valor assim que conecta).
+
+### Buscando por `key` em vez de `id`
+
+`id` é o identificador interno da credencial - regenerado se o banco da plataforma for
+restaurado/migrado, quebrando qualquer robô que o tenha fixo no `.env`. `key` é um identificador
+estável, definido pelo admin na plataforma (ex.: `"financeiro/senha-sap"`) e independente de
+`id`/`name`/pasta - renomear a credencial ou movê-la de pasta nunca muda a `key`. Prefira `key`
+para qualquer credencial referenciada de fora da plataforma:
+
+```python
+credencial = client.credentials.reveal_by_key("financeiro/senha-sap")
+
+client.credentials.rotate_by_key("financeiro/senha-sap", "novo-valor")
+
+client.credentials.expire_by_key("financeiro/senha-sap", "Login rejeitado pelo site do fornecedor")
+```
+
+## Arquitetura
+
+| Módulo | Responsabilidade |
+| --- | --- |
+| `client.py` | `RobotClient` - fachada única que compõe as peças abaixo |
+| `connection.py` | `SocketConnection` - handshake, heartbeat automático, reconexão, `call`/`emit` |
+| `execution.py` | `ExecutionManager` - ciclo `execution:start` / `execution:task` / `execution:finish` |
+| `queue.py` | `QueueConsumer` - `queue:next` / `queue:task-result`, iteração da fila |
+| `credentials.py` | `CredentialManager` - `reveal`/`rotate`/`expire`, por `id` ou `key`, via REST |
+| `protocol.py` | Constantes do protocolo (namespace, nomes de eventos, rotas REST) |
+| `exceptions.py` | Hierarquia de exceções do SDK (`RobotSDKError` e subclasses) |
+| `utils.py` | Funções utilitárias reutilizáveis (detecção de plataforma, hostname, timestamps) |
+| `loggers.py` | Configuração do `loguru` compartilhada pelo SDK |
+| `models/` | Modelos de dados e enums (Pydantic), espelhando os DTOs/enums do backend |
+
+Cada classe tem uma única responsabilidade (SRP): a conexão bruta não sabe o que é uma
+execução, a execução não sabe como a fila funciona, e o `RobotClient` só orquestra as três.
+Novos comportamentos (ex.: outro jeito de processar tasks) se registram via
+`on_automation_start`/`queue.processing`, sem precisar alterar essas classes.
+
+## Modelos e enums (`models/`)
+
+Todos os payloads trocados com a plataforma são validados com **Pydantic** e convertidos
+entre `snake_case` (Python) e `camelCase` (protocolo) automaticamente via `SdkBaseModel`.
+Os enums (`TaskStatus`, `RobotInstanceStatus`, `Platform`, ...) espelham exatamente os
+enums TypeScript usados por `RobotGateway` no backend.
+
+## Logs
+
+O SDK usa [`loguru`](https://loguru.readthedocs.io/) e já vem configurado com um formato
+legível por padrão. Para customizar (nível, arquivo de destino, JSON estruturado):
+
+```python
+from zsynctech_studio_sdk.loggers import configure_logging
+
+configure_logging(level="DEBUG", sink="robot.log")
+```
+
+Chame antes de criar o `RobotClient`.
+
+## Desenvolvimento
+
+```bash
+uv run pytest                          # testes
+uv run ruff check src examples tests   # lint
+uv run ruff format src examples tests  # formatação
+uv run mypy src examples tests         # checagem de tipos (modo strict)
+```
+
+`ruff` e `mypy` só olham `src`/`examples`/`tests` (não o README) - a partir do ruff 0.12+ o
+`ruff format` também reformata blocos de código Python dentro de Markdown, o que reescreveria
+os exemplos deste arquivo com as convenções de um `.py` (2 linhas em branco antes de decorators
+etc.) toda vez que rodasse. CI usa esse mesmo escopo (veja `.github/workflows/ci.yml`).

zsynctech_sdk-1.4.9.dist-info/RECORD

@@ -0,0 +1,23 @@
+zsynctech_studio_sdk/__init__.py,sha256=Lh7dG3cv8OfWcfpsDXiboxUeOgl_oaIRqlU6bdliBR0,2429
+zsynctech_studio_sdk/client.py,sha256=kng1FspB9bSPHzRKqQpQ1cd9CEOGNOuPuetuJyCfv44,4926
+zsynctech_studio_sdk/connection.py,sha256=rCDacmK7TUBm_OWShumuy8IAXxzfvFJ3BbH_GBJlB6Q,14309
+zsynctech_studio_sdk/credentials.py,sha256=dOHa1w8T-1f5gP9SPuGwsjhD1JUst1Xotyo7SDeVpDs,5828
+zsynctech_studio_sdk/exceptions.py,sha256=2GUATeFm_YRrCHL-IaLNd5V_GgjHU2nOfVVA7VOspbE,2139
+zsynctech_studio_sdk/execution.py,sha256=Ff87pp7NG8xQizMaJPBLXAp2bdbgGd_6W51VRgbkApY,5044
+zsynctech_studio_sdk/loggers.py,sha256=ndJuGUWxhIf2oeTUJ3DgMJyGsPHe0v1QiUNTBbHVRTU,1342
+zsynctech_studio_sdk/models/__init__.py,sha256=QrCiltXmPV57ksss6uNOmD1Tdjlzqf0FTRb14L23gCo,971
+zsynctech_studio_sdk/models/base.py,sha256=cpk747vvniKQtG60sKrejCo4Q9R9MRpl9sOA7gv4kLY,948
+zsynctech_studio_sdk/models/config.py,sha256=NHzh2sLocql_1sFzL4NPNlukaAfdjp-3HXusGsgNDlI,2252
+zsynctech_studio_sdk/models/credential.py,sha256=z2dKuztBWp4yNT1rYp0_f3Bk51QgZHE4B72v1MrhOBY,1363
+zsynctech_studio_sdk/models/enums.py,sha256=Y3WXvxkP6q2FfYEti38yy8gGw1HD4MSIeolFrHS2dgY,3014
+zsynctech_studio_sdk/models/execution.py,sha256=5kBYdC5bEjAYodvv688JGqh5A95UwRX7C8ku35Bs6NY,495
+zsynctech_studio_sdk/models/robot.py,sha256=whsZGifKZY8U7uq2p8gmF99zodkWXxgLnxw6mqWDlBQ,1148
+zsynctech_studio_sdk/models/task.py,sha256=qwb_jceIVpQZfSZm8CSpzKrxr93LVAVjaFzoZdRbPpo,1084
+zsynctech_studio_sdk/protocol.py,sha256=cqjUfgt4mQrjVN32i684TJzwAv5ELy_CjORrhNJIJsQ,1296
+zsynctech_studio_sdk/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+zsynctech_studio_sdk/queue.py,sha256=_nGs9eBHdPTb_bvfoaDQduDevDmZjTtHBYI3-BPKr2Y,4681
+zsynctech_studio_sdk/utils.py,sha256=PIhPhT2M2D0DK3GErFCluGJ4FM-duj1zp_j3gq7fZtI,1526
+zsynctech_sdk-1.4.9.dist-info/WHEEL,sha256=cmC5s21ojypbVslldL7IJq3hjZH-tINy4rziKePFsG0,81
+zsynctech_sdk-1.4.9.dist-info/entry_points.txt,sha256=fSTqevc1T5Xt6E8WXoe9rCIru6z0KuZhEIKwz1cVipM,61
+zsynctech_sdk-1.4.9.dist-info/METADATA,sha256=9f9JzmF4RysSUTPF8wYjXVOGC2c9Pgp6UP8iklrwiAs,8364
+zsynctech_sdk-1.4.9.dist-info/RECORD,,

zsynctech_sdk-1.4.9.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.12.23
+Root-Is-Purelib: true
+Tag: py3-none-any

zsynctech_sdk-1.4.9.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+zsynctech-sdk = zsynctech_studio_sdk:main
+

zsynctech_studio_sdk/__init__.py

@@ -0,0 +1,95 @@
+"""SDK Python para conectar robôs (RPA) à plataforma zsynctech-studio via `/robot` (Socket.IO).
+
+Uso rápido:
+
+    from zsynctech_studio_sdk import RobotClient, TaskStatus
+
+    client = RobotClient.from_api_key("<sua-api-key>", backend_url="http://localhost:5000")
+
+    @client.on_automation_start
+    def handle_automation() -> None:
+        with client.execution.run(observation="Minha automação"):
+            for task in client.queue.consume():
+                with client.queue.processing(task) as outcome:
+                    outcome.success(result={"ok": True})
+
+    with client:
+        client.listen()
+
+O cofre de credenciais é acessado à parte, via REST (não precisa de conexão aberta):
+
+    credencial = client.credentials.reveal("<credential-id>")
+    print(credencial.value)
+
+Veja `examples/simulate_robot.py` para um exemplo completo.
+"""
+
+from .client import RobotClient
+from .credentials import CredentialManager
+from .exceptions import (
+    AckTimeoutError,
+    CredentialRequestError,
+    NoActiveExecutionError,
+    NotConnectedError,
+    RobotConnectionError,
+    RobotSDKError,
+    ServerRejectedError,
+)
+from .execution import ExecutionManager
+from .models import (
+    ClaimedTask,
+    CredentialInfo,
+    CredentialStatus,
+    CredentialType,
+    ExecutionFinishResult,
+    ExecutionFinishStatus,
+    ExecutionStartResult,
+    Platform,
+    RevealedCredential,
+    RobotAvailability,
+    RobotClientConfig,
+    RobotConnection,
+    RobotInfo,
+    RobotInstanceStatus,
+    RobotStatus,
+    TaskItem,
+    TaskStatus,
+)
+from .queue import QueueConsumer, TaskOutcome
+
+__all__ = [
+    "RobotClient",
+    "RobotClientConfig",
+    "ExecutionManager",
+    "QueueConsumer",
+    "TaskOutcome",
+    "CredentialManager",
+    "RobotSDKError",
+    "RobotConnectionError",
+    "NotConnectedError",
+    "AckTimeoutError",
+    "ServerRejectedError",
+    "NoActiveExecutionError",
+    "CredentialRequestError",
+    "ClaimedTask",
+    "TaskItem",
+    "RobotInfo",
+    "RobotConnection",
+    "ExecutionStartResult",
+    "ExecutionFinishResult",
+    "CredentialInfo",
+    "RevealedCredential",
+    "Platform",
+    "RobotStatus",
+    "RobotAvailability",
+    "RobotInstanceStatus",
+    "TaskStatus",
+    "ExecutionFinishStatus",
+    "CredentialStatus",
+    "CredentialType",
+    "main",
+]
+
+
+def main() -> None:
+    print("zsynctech-studio-sdk - use RobotClient para conectar um robô à plataforma zsynctech-studio.")

zsynctech_studio_sdk/client.py

@@ -0,0 +1,122 @@
+"""`RobotClient`: the SDK's single entry point.
+
+Composes `SocketConnection` + `ExecutionManager` + `QueueConsumer` behind one high-level API,
+so a robot script only ever talks to this class:
+
+    from zsynctech_studio_sdk import RobotClient, TaskStatus
+
+    client = RobotClient.from_api_key("...", backend_url="https://minha-plataforma.com")
+
+    @client.on_automation_start
+    def handle_automation() -> None:
+        with client.execution.run(observation="Processamento diário"):
+            for task in client.queue.consume():
+                with client.queue.processing(task) as outcome:
+                    resultado = processar(task.payload)
+                    outcome.success(result=resultado)
+
+    with client:
+        client.listen()
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from types import TracebackType
+
+from .connection import SocketConnection
+from .credentials import CredentialManager
+from .execution import ExecutionManager
+from .loggers import configure_logging, logger
+from .models.config import RobotClientConfig
+from .models.enums import RobotInstanceStatus
+from .models.robot import RobotConnection, RobotInfo
+from .queue import QueueConsumer
+
+AutomationStartHandler = Callable[[], None]
+
+
+class RobotClient:
+    """High-level client for a single robot instance's connection to the platform."""
+
+    def __init__(self, config: RobotClientConfig) -> None:
+        configure_logging(level=config.log_level)
+        self._config = config
+        self._connection = SocketConnection(config)
+        self.execution = ExecutionManager(self._connection)
+        self.queue = QueueConsumer(self._connection, self.execution)
+        self.credentials = CredentialManager(config)
+
+    @classmethod
+    def from_api_key(cls, api_key: str, *, backend_url: str = "http://localhost:5000", **kwargs: object) -> RobotClient:
+        """Convenience constructor: `RobotClient.from_api_key("...", backend_url="...")`.
+
+        Any other `RobotClientConfig` field can be passed as a keyword argument (e.g.
+        `heartbeat_interval=30`).
+        """
+        config = RobotClientConfig(api_key=api_key, backend_url=backend_url, **kwargs)
+        return cls(config)
+
+    def connect(self) -> RobotConnection:
+        """Perform the handshake and block until the platform confirms the connection."""
+        logger.info("Conectando em {} como '{}'...", self._config.backend_url, self._config.hostname)
+        return self._connection.connect()
+
+    def disconnect(self) -> None:
+        self._connection.disconnect()
+
+    def on_automation_start(self, handler: AutomationStartHandler) -> AutomationStartHandler:
+        """Register `handler` to run (in a background thread) whenever the platform triggers
+        this robot's "Iniciar" action. Usable as a decorator."""
+        self._connection.on_automation_start(handler)
+        return handler
+
+    def set_status(self, status: RobotInstanceStatus) -> RobotInfo:
+        """Manually report this instance's status (ONLINE/BUSY) to the platform."""
+        return self._connection.set_status(status)
+
+    def listen(self) -> None:
+        """Block, waiting for the platform to trigger `automation:start`, until the connection
+        closes for good or the user presses Ctrl+C.
+
+        `automation:start` handlers keep firing on background threads while blocked here -
+        this just keeps the main thread (and the process) alive to host them. A dropped
+        connection (e.g. the API restarting) does not return from this call - the SDK keeps
+        reconnecting automatically in the background for as long as it's able to.
+        """
+        logger.info("Aguardando eventos da plataforma (Ctrl+C para encerrar)...")
+        try:
+            self._connection.wait()
+        except KeyboardInterrupt:
+            logger.info("Encerrando por solicitação do usuário (Ctrl+C)...")
+        finally:
+            self.disconnect()
+
+    @property
+    def connection_info(self) -> RobotConnection | None:
+        return self._connection.connection_info
+
+    @property
+    def is_connected(self) -> bool:
+        return self._connection.is_connected
+
+    @property
+    def is_stopping(self) -> bool:
+        """True once the connection is closed for good (Ctrl+C, `disconnect()`, or
+        reconnection permanently giving up) - see `SocketConnection.is_stopping`. An
+        `automation:start` handler with a loop over multiple units of work should poll this
+        between iterations and return early once it's true, instead of running to completion
+        with no connection left to report the result to."""
+        return self._connection.is_stopping
+
+    def __enter__(self) -> RobotClient:
+        self.connect()
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        self.disconnect()