Metadata-Version: 2.4
Name: csc_cia_stne
Version: 0.1.77
Summary: Biblioteca do time CSC-CIA utilizada no desenvolvimento de RPAs
License: MIT
Keywords: karavela,csc,cia,stone,rpa,botcity,stne
Description-Content-Type: text/markdown
License-File: LICENCE
Requires-Dist: setuptools
Requires-Dist: tzdata
Requires-Dist: python-json-logger
Requires-Dist: rich
Requires-Dist: requests
Requires-Dist: pydantic
Requires-Dist: pydantic_settings
Requires-Dist: zeep
Requires-Dist: google-cloud-bigquery
Requires-Dist: google-cloud-storage
Requires-Dist: google-cloud-bigquery-storage
Requires-Dist: google-auth
Requires-Dist: google-auth-oauthlib
Requires-Dist: google-auth-httplib2
Requires-Dist: google-api-python-client
Requires-Dist: google-cloud-documentai
Requires-Dist: pyjwt
Requires-Dist: PyYAML
Requires-Dist: python-dotenv
Requires-Dist: slack_sdk
Requires-Dist: webdriver-manager
Requires-Dist: botcity-framework-core
Requires-Dist: botcity-framework-web
Requires-Dist: email-validator
Requires-Dist: botcity-maestro-sdk
Requires-Dist: psutil
Requires-Dist: cryptography
Requires-Dist: PyPDF2
Requires-Dist: pypdf
Requires-Dist: pycryptodome
Requires-Dist: openai
Requires-Dist: tenacity
Requires-Dist: pycurl
Dynamic: license-file

# csc-cia-stne

[![PyPI version](https://img.shields.io/pypi/v/csc-cia-stne.svg)](https://pypi.org/project/csc-cia-stne/)
[![Python versions](https://img.shields.io/pypi/pyversions/csc-cia-stne.svg)](https://pypi.org/project/csc-cia-stne/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

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`](https://docs.astral.sh/uv/):

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

Para adicionar a uma rotina já existente:

```bash
uv add csc-cia-stne
```

Também é possível instalar via `pip`:

```bash
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

```python
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="roberto.lins@stone.com.br",
)

log.info("rotina iniciada")
```

### Lendo um segredo com fallback automático

```python
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

```python
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

```python
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

```python
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)](https://github.com/stone-payments/cia-libs)

---

## Suporte

- **Time mantenedor**: CSC-CIA / Stone
- **Contato**: [cia@stone.com.br](mailto:cia@stone.com.br)
- **Licença**: MIT
