Metadata-Version: 2.4
Name: voip-client-sdk
Version: 0.2.0
Summary: Cliente Python para o painel VoIP (Laravel Nova)
Author-email: Tulio Amancio <root@tsuriu.com>
License: MIT
Project-URL: Homepage, https://gitlab.com/libandpackages/voip-client-sdk
Project-URL: Repository, https://gitlab.com/libandpackages/voip-client-sdk
Project-URL: Issues, https://gitlab.com/libandpackages/voip-client-sdk/-/issues
Keywords: voip,laravel-nova,pabx,telephony,sdk
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Communications :: Telephony
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.25.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: python-dotenv>=1.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: flake8>=6.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: build>=1.0.0; extra == "dev"
Requires-Dist: twine>=4.0.0; extra == "dev"

# VoIP Client SDK

Cliente Python para a API interna (Laravel Nova) de painéis VoIP. Permite realizar automações de CRUD de usuários, ramais (subscribers), busca de DIDs, e extração de dados do dashboard.

## Estrutura do Projeto

O repositório está organizado de forma a separar o código da biblioteca dos artefatos de apoio e desenvolvimento:

```
voip_client/
├── voip_client/                  ← O pacote Python (código-fonte da biblioteca)
│   ├── __init__.py
│   ├── __main__.py
│   ├── client.py
│   ├── auth.py
│   ├── transport.py
│   ├── resources.py
│   ├── users.py
│   ├── subscribers.py
│   ├── dids.py
│   ├── dashboard.py
│   ├── exceptions.py
│   ├── py.typed
│   └── cli.py
│
├── tests/                        ← Testes automatizados e smoke test
│   ├── test_voip_client.py
│   └── smoke_test.py
│
├── examples/                     ← Scripts de exemplo de uso
│   └── basic_usage.py
│
├── pyproject.toml                ← Metadados e dependências do pacote
├── requirements.txt               ← Alternativa simples de dependências
├── INSTRUCOES_ATUALIZACAO.md      ← Guia de manutenção, testes e release
├── README.md                     ← Esta documentação
├── .gitlab-ci.yml                 ← Pipeline CI/CD GitLab
├── .gitignore                     ← Arquivos ignorados pelo Git
└── .env.example                    ← Modelo de variáveis de ambiente
```

## Instalação

### Instalação via PyPI

```bash
pip install voip-client-sdk
```

### Instalação de Desenvolvimento

Para instalar o pacote em modo editável junto com as dependências de teste e desenvolvimento:

```bash
pip install -e ".[dev]"
```

### Instalação Simples

Para instalar apenas as dependências de execução básicas:

```bash
pip install -r requirements.txt
```

## Configuração

Copie o arquivo `.env.example` para `.env` e preencha as variáveis de ambiente necessárias:

```bash
cp .env.example .env
```

Edite o arquivo `.env`:
```env
VOIP_BASE_URL=https://voip.suaempresa.com.br
VOIP_EMAIL=seu_email@empresa.com.br
VOIP_PASSWORD=sua_senha_secreta
```

## Como Usar

### Biblioteca Python

Você pode importar e utilizar o cliente em seus scripts Python. Veja o exemplo em `examples/basic_usage.py` para uma demonstração completa:

```python
import os
from voip_client import VoipClient

# Conectar e autenticar (lê automaticamente VOIP_EMAIL e VOIP_PASSWORD das env vars)
with VoipClient(base_url="https://voip.suaempresa.com.br") as client:
    # Buscar dados do dashboard
    dados = client.get_dashboard(range_days=30)
    print(dados)
```

#### Manipulação de Cookies (Ex.: Banco de Dados)

Se você preferir persistir a sessão em um banco de dados em vez do arquivo `cookies.txt`, o cliente expõe a propriedade `cookies` e aceita o parâmetro `initial_cookies`:

```python
from voip_client import VoipClient

# Carrega cookies previamente salvos do seu banco de dados
cookies_salvos = obter_cookies_do_banco()  # Deve retornar um Dict[str, str] ou None

with VoipClient(
    base_url="https://voip.suaempresa.com.br",
    initial_cookies=cookies_salvos,
) as client:
    # O cliente usará os cookies informados. Se forem válidos, não realizará login de novo.
    dados = client.get_dashboard()
    
    # Ao final da execução, armazene os cookies atualizados no banco
    cookies_atualizados = client.cookies
    salvar_cookies_no_banco(cookies_atualizados)
```

### Interface de Linha de Comando (CLI)

O pacote também pode ser executado diretamente via terminal:

```bash
# Ajuda geral
voip-client --help

# Efetuar login e gerar/atualizar cookies.txt
voip-client --base-url "https://voip.suaempresa.com.br" login

# Consultar o dashboard
voip-client --base-url "https://voip.suaempresa.com.br" dashboard --range 30

# Rodar um teste CRUD completo (Smoke Test) contra o painel
voip-client --base-url "https://voip.suaempresa.com.br" crud-test --did-mask "0113"
```

## Executando os Testes

Os testes unitários utilizam mocks para evitar chamadas de rede reais, rodando instantaneamente:

```bash
pytest tests/
```

## ⚠️ Aviso de Segurança

### `verify_ssl`

O parâmetro `verify_ssl` controla se o certificado TLS do servidor é validado.
**O padrão é `True` (seguro)**. Use `verify_ssl=False` **somente** em ambientes
de homologação com certificado autoassinado e nunca em produção — desabilitar a
validação expõe credenciais de login e cookies de sessão a ataques MITM.

```python
# ✅ Produção (padrão seguro)
client = VoipClient(base_url="https://voip.empresa.com.br")

# ⚠️  Homologação com certificado autoassinado
client = VoipClient(base_url="https://homolog.empresa.com.br", verify_ssl=False)
```

### Senhas de ramais no dashboard

O método `get_dashboard()` **não inclui senhas de ramais por padrão**. Para
obter as senhas, passe `include_passwords=True` explicitamente:

```python
# Padrão: sem senhas (recomendado para uso geral / logging)
dados = client.get_dashboard()

# Com senhas: use somente quando necessário e nunca logue o resultado
dados_com_senhas = client.get_dashboard(include_passwords=True)
```

### Dados sensíveis em logs

Campos como `password` e `cpf` são automaticamente mascarados (`***`) nas
mensagens de erro geradas pelo cliente. Ainda assim, evite logar em nível
`DEBUG` em produção, pois outros dados de resposta (como tokens) podem aparecer.
