Metadata-Version: 2.1
Name: cybertron-spark
Version: 0.3.3
Summary: Automação do Zendesk com Selenium, Zenpy e integração Cybertron
Home-page: UNKNOWN
Author: Gustavo Sartorio
Author-email: strov3rl@gmail.com
License: MIT
Keywords: zendesk selenium transformers cybertron
Platform: UNKNOWN
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENCE

Kit de Ferramentas para Automação Zendesk

## Runtime Cybertron V2

Para uma automação nova, cadastre primeiro o bot e o seu time no Cybertron.
O Infisical injeta `CYBERTRON_V2_API_URL`, `CYBERTRON_V2_API_TOKEN`,
`CYBERTRON_AUTOMATION_ID`. A área é resolvida pelo catálogo no backend. A biblioteca não contém
domínios nem rotas da API: ela descobre o contrato no servidor.

```python
from cybertron_spark import AutomationRuntime

runtime = AutomationRuntime.from_env()
runtime.start(metadata={"environment": "production"})
runtime.update_queue(12, external_id="12345")
runtime.waiting()

# ao iniciar e concluir um caso
runtime.running()
runtime.record_processed(
    "15110987",
    source_type="zendesk",
    processed_type="ticket",
    input_snapshot={"status": "open"},
    decision_data={"action": "enrich"},
    output_data={"result": "updated"},
)
runtime.checkpoint()
```

Um segredo obrigatório ausente interrompe o boot e informa seu nome. Use
`runtime.fail_critical(exc)` para registrar a falha fatal antes de o processo
encerrar e o Kubernetes assumir a recuperação.

Uma biblioteca Python projetada para acelerar o desenvolvimento de robôs de automação de processos (RPA) que interagem com a plataforma Zendesk. Ela combina a automação de interface de usuário (UI) com o Selenium e a interação via API com o Zenpy, além de fornecer componentes integrados para monitoramento (Heartbeat) e logging estruturado (BotsLogger).

Principais Funcionalidades 🚀
Gerenciamento de Driver: Crie e gerencie drivers do Selenium (Chrome, Firefox) de forma simplificada, com suporte para execução local e remota (Selenoid).

Automação UI Zendesk: Um conjunto de métodos de alto nível para interagir com a interface do Zendesk, como fazer login, preencher campos, submeter tickets, aplicar macros e muito mais.

Integração API Zendesk: Um wrapper conveniente para a biblioteca Zenpy que facilita a autenticação e a extração de dados da API do Zendesk, como buscar tickets em uma visualização.

Monitoramento e Alertas: Para novas automações, `AutomationRuntime` registra
execução, progresso, filas, itens processados e falhas críticas exclusivamente
na API Cybertron V2. `Heartbeat` permanece disponível somente para compatibilidade
dos bots ainda não migrados.

Logging Estruturado: A classe BotsLogger gera eventos JSON no stdout, com identificação do bot, execução, ambiente e contexto por ticket. Dados enviados nos atributos com chaves sensíveis são mascarados automaticamente.

Runtime para RPAs: `AutomationRuntime` é o runtime padrão para RPAs e DAGs
migrados. `BotRuntime` é apenas um alias temporário de compatibilidade para o
mesmo runtime V2; ele não envia chamadas para a API legada.

Instalação
Instale a biblioteca usando o pip:

Bash

pip install cybertron-spark==0.3.3
Como Usar
A biblioteca é dividida em componentes modulares que podem ser usados em conjunto para construir um robô robusto.

1. Configurando o Driver do Selenium (Driver_Selenium)
   Esta classe abstrai a configuração do WebDriver.

Python

from cybertron_spark import Driver_Selenium

# Configura um driver remoto (Selenoid) para o Chrome em modo headless

config_driver = Driver_Selenium(
    ipselenoid='http://seu-ip-selenoid:4444/wd/hub',
    browser='chrome',
    headless=True
)

# Cria a instância do driver

driver = config_driver.criar_driver()

print("Driver criado com sucesso!")

# ... seu código de automação aqui ...

driver.quit()

2. Monitorando o Robô (Heartbeat)
   Envie o status do seu robô para um painel de acompanhamento.

from cybertron_spark import Heartbeat

# Instancia o Heartbeat com as credenciais da sua API de monitoramento

heartbeat = Heartbeat(
    bot_id='MEU_BOT_ZENDESK_01',
    endpoint='https://api.meupainel.com/status',
    token='SEU_TOKEN_SECRETO'
)

# Envia um status

heartbeat.alertas(status=execucao)
print("Status 'EM EXECUÇÃO' enviado.")

# Envia o ID de um ticket processado para contagem

heartbeat.alertas(ticket_id='12345')
print("Registro do ticket 12345 enviado.")

# Ao final, informa que o bot está ocioso

heartbeat.alertas(status=aguardando)
print("Status 'AGUARDANDO CASOS' enviado.")

3. Usando a API do Zendesk (Zendesk_Zenpy)
   Busque tickets de uma visualização específica antes de iniciar a automação da UI.

from cybertron_spark import Zendesk_Zenpy

# Autentica na API do Zendesk

zen_api = Zendesk_Zenpy(
    zlogin='seu_email@empresa.com/token',
    zpass='SEU_TOKEN_DA_API_ZENDESK',
    instancia='sua-instancia-zendesk'
)

# Pega todos os tickets da visualização com ID 9000

ID_DA_FILA = 9000
tickets_para_processar = zen_api.pegar_tickets(fila=ID_DA_FILA)

if tickets_para_processar:
    print(f"Encontrados {len(tickets_para_processar)} tickets: {tickets_para_processar}")
else:
    print("Nenhum ticket encontrado na fila.")
4. Automatizando a Interface (Zendesk_Selenium)
Após obter um ticket, use o Selenium para interagir com ele.

Python

from cybertron_spark import Zendesk_Selenium, Driver_Selenium

# (Supondo que você já tenha um 'driver' criado)

# driver = Driver_Selenium(...).criar_driver()

# Instancia o controlador da UI do Zendesk

zen_ui = Zendesk_Selenium(
    driver=driver,
    usuario='seu_usuario_zendesk',
    senha='sua_senha_zendesk',
    instancia='sua-instancia-zendesk'
)

# Realiza o login

zen_ui.login()
print("Login realizado com sucesso.")

# Navega até um ticket e realiza ações

ticket_id = '12345'
driver.get(f"https://sua-instancia-zendesk.zendesk.com/agent/tickets/{ticket_id}")

zen_ui.esperar_carregamento()

# Aplica uma macro

zen_ui.aplicar_macro("Nome da Macro::Opção")

# Adiciona uma observação interna

zen_ui.enviar_mensagem("Este ticket foi processado pelo robô.")

# Submete o ticket como resolvido

zen_ui.enviar_ticket('resolvido')
print(f"Ticket {ticket_id} resolvido.")

driver.quit()

5. Logging Estruturado (BotsLogger)
   Emita eventos JSON para o coletor de logs da plataforma. O logger não depende do Heartbeat: cada mecanismo permanece responsável por sua própria finalidade.

Python

from cybertron_spark import BotsLogger

logs = BotsLogger(bot_id='meu_bot', environment='production')
logger = logs.get_logger(__name__)

ticket_id = '12345'

try:
    # Simula um erro
    raise ValueError("Ocorreu um problema inesperado.")
except Exception as e:
    logger.exception(
        'Falha ao processar ticket',
        extra={
            'event': 'ticket.processing_failed',
            'ticket_id': ticket_id,
        },
    )

logger.info('Ticket iniciado', extra={'event': 'ticket.started', 'ticket_id': ticket_id})

6. Runtime para RPAs Contínuos (AutomationRuntime)

### Facilitadores V2 (0.3.3)

```python
from cybertron_spark import AutomationRuntime, require_env

with AutomationRuntime(require_env('BOT_ID')) as runtime:
    # Cadastro prévio obrigatório; área/time obtidos somente do backend.
    logger = runtime.logger  # run_id real já vinculado; não alterar logs.context.
    driver = runtime.browser(playwright)  # configuração local/Selenwright validada.
    runtime.update_queue(len(tickets), external_id=fila)
    for ticket in tickets:
        with runtime.ticket(ticket, queue_id=fila) as caso:
            caso.input_snapshot = entrada_observada
            caso.decision_data = criterios
            caso.checkpoint('validated_before_submit')
            # Operação de negócio e confirmação no sistema de destino.
            caso.output_data = resultado_confirmado
            caso.success()  # ou caso.reject('codigo', 'motivo')
    runtime.waiting()
```

O context manager abre/finaliza o run, envia heartbeat em background e reporta
falhas críticas. Exceções no contexto do ticket auditam FAILED e propagam;
encerrar sem resultado explícito também não conta como sucesso. Falha de entrega
da auditoria é crítica: não repetir a operação de negócio automaticamente.
Checkpoint é telemetria de progresso, não persistência transacional/retomada.
Logs JSON vão para stdout/SigNoz; casos e eventos críticos são persistidos na V2.

`runtime.browser` usa `SELENWRIGHT_LOCAL=true` para Playwright local. No modo
remoto exige `SELENWRIGHT_URL` e `SELENWRIGHT_TOKEN`, sem URLs de fallback. O
helper é opt-in: construtores Playwright e interfaces Heartbeat/Selenium/Zenpy
legadas não são alterados. Faltas de secrets mostram seu nome no erro.
`from_env()` continua priorizando `CYBERTRON_AUTOMATION_ID` quando presente,
com fallback para `BOT_ID`; usar o construtor com BOT_ID evita identidades
herdadas incorretas quando esse valor é o identificador oficial do cadastro.

Nesta versão, BotRuntime é alias exclusivamente V2; as interfaces antigas do
BotRuntime não são mantidas. Bots legados que usam Heartbeat permanecem iguais.

```python
from cybertron_spark import AutomationRuntime

runtime = AutomationRuntime.from_env()
runtime.start(metadata={'execution_type': 'deployment', 'brands': ['magalu']})

try:
    # Fluxo de negócio do bot.
    runtime.record_processed('12345', source_type='zendesk', processed_type='ticket')
finally:
    runtime.finish()
```

O runtime abre a execução, envia heartbeat automático e registra progresso
somente na V2. As variáveis obrigatórias são fornecidas por Infisical ou `.env`;
se qualquer uma estiver ausente, o boot falha indicando o nome exato do segredo.

### 7. Consultas BigQuery auditáveis

Para bots que tomam decisões com dados do BigQuery, use o helper do runtime. Ele
captura automaticamente o identificador do job, projeto, localização, datas,
volume processado, uso de cache e o hash da SQL. A SQL integral não é enviada a
logs nem ao payload.

```python
from google.cloud import bigquery
from cybertron_spark import consultar_bigquery

consulta = consultar_bigquery(
    bigquery.Client(),
    "SELECT protocolo, status FROM operacao.protocolos",
    query_name="protocolos_pendentes_v1",
)

for linha in consulta.to_records(include_fields=["protocolo", "status"]):
    # Execute a regra de negócio e, ao publicar na API Cybertron V2, envie:
    payload = consulta.payload_do_item(linha)
    # payload["source_metadata"] identifica a consulta/job.
    # payload["input_snapshot"] preserva o retrato lido pelo bot.
```

Use `include_fields` para definir, por automação, quais colunas compõem a prova
operacional. Isso evita persistir colunas que não contribuem para a auditoria.
O helper é opcional: bots que não usam BigQuery não precisam instalar nem
configurar nada adicional.

### 8. API Cybertron V2 e ambientes pelo Infisical

O endereço da V2 é definido pelo ambiente no Infisical, e não pelo código do
bot. Configure a mesma chave nos dois ambientes, com valores distintos:

| Ambiente | `CYBERTRON_V2_API_URL` |
| --- | --- |
| Development / Staging | `https://cybertron-stg.resolveluiza.com.br/api/v2/` |
| Production | `https://cybertron.resolveluiza.com.br/api/v2/` |

Configure `CYBERTRON_V2_API_TOKEN` no mesmo caminho de secrets. A biblioteca
recebe as variáveis já injetadas pelo Infisical; ela não executa login no cofre,
não grava `.env` e não possui URL fixa de ambiente.

```python
O cadastro do time e da automação é feito pela interface Cybertron V2. Isso
centraliza propriedade, permissões, workload Kubernetes e política de saúde;
o script só recebe `CYBERTRON_AUTOMATION_ID` do
Infisical.
```

`CYBERTRON_API_URL` continua reservado ao `Heartbeat` dos bots ainda legados.
`AutomationRuntime` nunca o lê nem envia telemetria para a V1.

Exemplo Completo: Estrutura de um Robô
Juntando todos os componentes para criar um fluxo de automação robusto.

Python

from rpa_zendesk_toolkit import (
    Heartbeat, BotsLogger, Driver_Selenium, Zendesk_Zenpy, Zendesk_Selenium,
    execucao, aguardando, erro
)
import time

# --- 1. CONFIGURAÇÃO INICIAL ---

HEARTBEAT_CONFIG = {
    'bot_id': 'ZENDESK_PROCESSOR_01',
    'endpoint': 'https://api.meupainel.com/status',
    'token': 'SEU_TOKEN_SECRETO'
}

ZENDESK_API_CREDS = {
    'zlogin': 'seu_email@empresa.com/token',
    'zpass': 'SEU_TOKEN_DA_API_ZENDESK',
    'instancia': 'sua-instancia'
}

ZENDESK_UI_CREDS = {
    'usuario': 'seu_usuario_zendesk',
    'senha': 'sua_senha_zendesk',
    'instancia': 'sua-instancia'
}

SELENOID_IP = 'http://seu-ip-selenoid:4444/wd/hub'

ID_FILA_ZENDESK = 9000

# --- 2. INICIALIZAÇÃO DOS COMPONENTES ---

heartbeat = Heartbeat(**HEARTBEAT_CONFIG)

logger = BotsLogger(heartbeat_instancia=heartbeat)

zen_api = Zendesk_Zenpy(**ZENDESK_API_CREDS)

# --- 3. LOOP PRINCIPAL DO ROBÔ ---

def main():
    driver = None
    try:
        heartbeat.alertas(status=aguardando)
        tickets = zen_api.pegar_tickets(fila=ID_FILA_ZENDESK)

        if not tickets:
            print("Nenhum ticket na fila. Aguardando...")
            return

        heartbeat.alertas(status=execucao)

        # Cria o driver apenas se houver tickets para processar
        driver_manager = Driver_Selenium(ipselenoid=SELENOID_IP)
        driver = driver_manager.criar_driver()

        zen_ui = Zendesk_Selenium(driver=driver, **ZENDESK_UI_CREDS)
        zen_ui.login()

        for ticket_id in tickets:
            try:
                print(f"Processando ticket: {ticket_id}")
                driver.get(f"https://{ZENDESK_UI_CREDS['instancia']}.zendesk.com/agent/tickets/{ticket_id}")
                zen_ui.esperar_carregamento()

                # --- Lógica de negócio do seu robô ---
                zen_ui.enviar_mensagem(f"Processamento automático iniciado pelo bot {HEARTBEAT_CONFIG['bot_id']}.")
                time.sleep(2) # Simula trabalho
                zen_ui.enviar_ticket('pendente')
                zen_ui.esperar_carregamento()
                # ------------------------------------

                heartbeat.alertas(ticket_id=ticket_id) # Registra sucesso

            except Exception as e:
                logger.error(
                    error=e,
                    message=f"Erro ao processar ticket {ticket_id}",
                    ticket_id=ticket_id
                )
                # Pular para o próximo ticket em caso de erro

    except Exception as e:
        acao = logger.error(
            error=e,
            message="Erro crítico na execução principal do robô",
            ticket_id="N/A",
            error_type='CRITICAL'
        )
        if acao == 'stop':
            heartbeat.alertas(status=erro)
            # Adicione lógica para parar o robô de forma segura

    finally:
        if driver:
            driver.quit()
        print("Ciclo finalizado.")

if __name__ == '__main__':
    while True:
        main()
        time.sleep(60) # Espera 1 minuto antes de verificar a fila novamente

# Integração com Playwright e Selenwright 🚀

A biblioteca agora conta com suporte nativo ao **Playwright**, oferecendo automações muito mais rápidas, estáveis e resilientes (auto-wait) em comparação com o Selenium tradicional.

Foram adicionados módulos específicos para gerenciar instâncias de navegador e interagir com sistemas estratégicos (Zendesk, Sandiego e MLAdmin).

## 1. Configurando o Driver do Playwright

A classe `Driver_Playwright` gerencia a criação de contextos e páginas, com suporte a instâncias locais e remotas (Selenwright).

```python
from playwright.sync_api import sync_playwright
from cybertron_spark.playwright_manager import Driver_Playwright

with sync_playwright() as p:
    driver_manager = Driver_Playwright(
        playwright_instance=p, 
        local=True, 
        headless=False 
    )
    browser, context, page = driver_manager.criar_browser()
  
    # ... passe o objeto 'page' para as classes de automação ...
  
    browser.close()
```

## 2. Automação Playwright: Zendesk

Realize fluxos completos na Zendesk de forma mais rápida.

```python
from cybertron_spark.playwright_manager import Zendesk_Playwright

zen = Zendesk_Playwright(page=page, instancia="sua-instancia")
zen.login()

zen.abrir_ticket("1234567")
zen.aplicar_macro("Classificação::Teste")
zen.enviar_mensagem("<p>Nota interna automática via Playwright</p>", publica=False)
zen.enviar_ticket("aberto")
zen.fechar_ticket_atual() # Limpa a aba para não sobrecarregar a memória
```

## 3. Automação Playwright: Sandiego

Gerencie cancelamentos e trocas de pedidos diretamente no sistema Sandiego.

```python
from cybertron_spark.playwright_manager import Sandiego_Playwright

sandiego = Sandiego_Playwright(page=page)
sandiego.login()

# Tenta realizar a troca e valida se o botão 'Abrir Ticket' está habilitado
sucesso = sandiego.gerar_troca(numero_pedido="1019386971")
if sucesso:
    print("Troca gerada com sucesso.")
```

## 4. Automação Playwright: MLAdmin

Gerencie fluxos para pedidos 1P (que possuem pacotes) no MLAdmin, incluindo suporte avançado a interceptação de alertas em tela (`Dialog`).

```python
from cybertron_spark.playwright_manager import MLAdmin_Playwright

mladmin = MLAdmin_Playwright(page=page)
mladmin.login()

# Tenta gerar um vale-compras e o robô já intercepta alertas nativos do sistema
sucesso = mladmin.gerar_vale(pacote="987654321")
if sucesso:
    print("Vale gerado com sucesso.")

Licença
Este projeto está licenciado sob a licença MIT. Veja o arquivo LICENSE para mais detalhes.


