csc-cia-stne 0.1.77

Biblioteca do time CSC-CIA utilizada no desenvolvimento de RPAs

csc-cia-stne

Biblioteca interna desenvolvida e mantida pelo time CSC-CIA da Stone, voltada ao desenvolvimento de RPAs e rotinas automatizadas.

Reúne integrações com sistemas internos e externos (Stone Admin, ServiceNow, Salesforce, Waccess, BC Correios, BC STA, GCP — BigQuery / Storage / Document AI / Drive, Slack, e-mail, FTP/SFTP, Provio, Jerry/IA) e utilitários comuns para bots (logging, segredos, datetime, base64, PDF, configuração por ambiente, etc.).

O objetivo é não precisar reimplementar, em cada novo robô, funcionalidades que já são usadas com frequência pelo time.

---

Instalação

Em projetos novos, recomendamos o uso do uv:

uv init meu-projeto
uv add csc-cia-stne

Para adicionar a uma rotina já existente:

uv add csc-cia-stne

Também é possível instalar via pip:

pip install csc-cia-stne

Python suportado: 3.10+ (recomendado 3.11 ou superior).

---

Recursos / Módulos

A lib é organizada em módulos por integração/funcionalidade. Os principais são:

Todas as classes abaixo são importadas diretamente do pacote raiz: from csc_cia_stne import <Classe>.

Integrações Stone / internas

Classe	Descrição
StoneAdmin	Stone Banking / Open Bank API — verificação de cliente, extratos, recibos, titularidade
ServiceNow	ServiceNow — tickets, anexos, tasks, variáveis e listagem com paginação
SalesForce	Salesforce (JWT Bearer) — Cases, feed completo (Chatter + alterações de campo + e-mails), anexos de 3 fontes, encerramento, owner
Karavela	Helpers para execução em ambiente Karavela (health-check de container)
Waccess	Waccess — usuários, fotos, grupos e cartões de acesso físico
Provio	Provio — exportação do relatório geral de provisões
JerryClient	Cliente da API Jerry (IA / OCR / chat completions Stone via Databricks)

Banco Central / órgãos externos

Classe	Descrição
BC_Correios	Automação do BC Correios
BC_STA	Automação do BC STA (Sistema de Transferência de Arquivos)

Google Cloud

Classe	Descrição
BigQuery	Consultas, inserções e utilitários para BigQuery
GCPBucket	Upload/download de arquivos em buckets GCS
GCPDocumentAIClient	OCR e extração via Google Document AI
GoogleDrive	Upload/download e organização de arquivos no Google Drive

Comunicação e arquivos

Classe	Descrição
Slack	Envio de mensagens, arquivos, threads e attachments (highlights) para canais Slack
Email	Envio de e-mails via SMTP do Gmail (com anexos, CC, CCO, máscara de remetente)
FTP	Cliente FTP/FTPS/SFTP (pycurl) com retry automático
web_screen	Factory de automação web (Selenium / BotCity)

Logging

Símbolo	Descrição
logger	Factory: log = logger("meu_modulo"). Decide automaticamente entre formato Rich (local/console) e JSON (Karavela/container) conforme a variável ambiente_de_execucao.

Utilitários (csc_cia_stne.utilitarios)

Segredos e configuração

• get_secret — resolução de segredos com fallback (env → ./secrets/ → ./.secrets/ → ./private/ → ./.private/ → /secrets/ → BotMaestro)
• get_config — leitura de settings.yaml por ambiente (dev/qa/prod)

Apresentação

• titulo — header padronizado do robô (printa em local / loga em Karavela)

Base64 e conversões

• b64encode / b64decode — utilidades base64 para strings UTF-8
• convert_bquery_result_to_json — converte RowIterator do BigQuery em list[dict]
• validate_json — valida e converte string JSON em objeto Python

Arquivos e pastas

• recriar_pasta — remove e recria uma pasta
• delete_file / delete_folder — exclusão segura com retorno padronizado

Datetime

• now_sp — datetime atual no fuso de São Paulo (America/Sao_Paulo)

PDF — extração parcial (útil antes de OCR/IA, para economizar tokens)

• extrair_x_paginas_pdf — primeiras N páginas a partir de um arquivo em disco
• extrair_paginas_intervalo_pdf — intervalo arbitrário (1-indexed)
• extrair_x_paginas_pdf_from_base64 — mesma coisa a partir de string base64

---

Quickstart

Setup mínimo de uma rotina

from csc_cia_stne import logger
from csc_cia_stne.utilitarios import titulo

log = logger(__name__)

titulo(
    project_name="Minha rotina",
    project_version="0.1.0",
    project_dev_name="Roberto Lins",
    project_dev_mail="[e-mail]",
)

log.info("rotina iniciada")

Lendo um segredo com fallback automático

from csc_cia_stne.utilitarios import get_secret

# Resolve, nesta ordem: env var → ./secrets/MINHA_SECRET → ./.secrets/... → /secrets/... → BotMaestro
senha = get_secret(name="MINHA_SECRET")

if senha is None:
    raise RuntimeError("Segredo MINHA_SECRET não encontrado")

Consultando tickets no ServiceNow

from csc_cia_stne import ServiceNow
from csc_cia_stne.utilitarios import get_secret

svc = ServiceNow(
    username=get_secret(name="SERVICENOW_USERNAME"),
    password=get_secret(name="SERVICENOW_PASSWORD"),
    env="qa",
)

resultado = svc.listar_tickets(
    tabela="x_stps2_services_catalog_base_task",
    campos=["number", "sys_id", "state"],
    query="assignment_group=45251cd61bed42544867a68fe54bcbe3",
    limite=50,
)

for ticket in resultado["content"]["result"]:
    print(ticket["number"]["display_value"])

Karavela: secrets e health-check

from csc_cia_stne import Karavela

k = Karavela()
token = k.get_secret(name="MEU_TOKEN")

k.create_health_check_file(health_check_filename="./healthy_check/healthy")
# ... execução do robô ...
k.destroy_health_check_file()

Salesforce: listar Cases e baixar anexos

from csc_cia_stne import SalesForce
from csc_cia_stne.utilitarios import get_secret

sf = SalesForce(
    iss=get_secret(name="SF_CLIENT_ID"),
    sub=get_secret(name="SF_USERNAME"),
    version="60.0",
    private_key_content=get_secret(name="SF_PRIVATE_KEY"),
)
if not sf.is_connected:
    raise RuntimeError(sf.error)

# Listagem paginada de Cases (datas já convertidas para SP)
casos = sf.listar_casos(
    query="SELECT Id, CaseNumber, Subject FROM Case WHERE Status = 'Novo'",
    paginar=True,
)

# Anexos consolidados (Files + Attachments + EmailAttachments)
arquivos = sf.listar_arquivos_caso(caso_id=casos.data["records"][0]["Id"])

---

Variáveis de ambiente

Variável	Descrição
ambiente_de_execucao	Quando definida como karavela, o logger passa para o formato JSON e o helper titulo passa a logar (em vez de printar).
log_level	Nível mínimo do logger (DEBUG, INFO, WARNING, ERROR, CRITICAL).

Demais variáveis específicas (credenciais, URLs, etc.) são consumidas por cada módulo conforme necessidade — consulte a documentação interna.

---

Convenções importantes

Antes de usar a lib em produção, é importante conhecer alguns padrões:

• Envelope de retorno: a maioria dos métodos retorna dict no formato {success/status, data/result, error}. Em geral, não levantam exceção nas operações de negócio — sempre cheque o status do dict.
• .env no cwd: várias classes carregam um .env do diretório atual via python-dotenv no __init__. Em jobs que rodam fora do diretório do projeto, garanta que o .env seja resolvido de outra forma.
• Conexões silenciosas: alguns construtores não levantam exceção quando a conexão falha. Cheque atributos como is_connected e error antes de usar.
• Logger é factory: from csc_cia_stne import logger devolve uma função. Use log = logger("meu_modulo"). O formato (Rich x JSON) é decidido automaticamente pelo ambiente.
• Detecção de ambiente Karavela: definindo ambiente_de_execucao=karavela, o logger e o titulo mudam para o modo container/JSON sem alteração de código.

---

Documentação

A documentação completa, com exemplos por classe e receitas (padrões maduros usados em produção: logger console+arquivo, agente Jerry+LangChain com saída Pydantic, OCR + classificação por IA, pipeline GCS → Google Drive, etc.), está no repositório interno:

GitHub — stone-payments/cia-libs (acesso restrito)

---

Suporte

• Time mantenedor: CSC-CIA / Stone
• Contato: [e-mail]
• Licença: MIT