Metadata-Version: 2.4
Name: notifica-govbr
Version: 0.1.1
Summary: Biblioteca para o serviço de notificações do gov.br
License-Expression: Apache-2.0
License-File: LICENSE
Requires-Dist: httpx>=0.28.1
Requires-Dist: django>=6.1.2 ; extra == 'django'
Requires-Dist: fastapi>=0.162.0 ; extra == 'fastapi'
Requires-Dist: pydantic-settings>=2.16.1 ; extra == 'fastapi'
Requires-Python: >=3.12
Provides-Extra: django
Provides-Extra: fastapi
Description-Content-Type: text/markdown

# notifica-govbr

Biblioteca Python para envio de notificações à **Caixa Postal Digital do cidadão**,
com entrega opcional por **push no aplicativo gov.br**, via API do SERPRO.

> **Público-alvo:** órgãos e entidades da Administração Pública com acesso à API
> de envio de mensagens da Caixa Postal.

## Instalação

```bash
pip install notifica-govbr
```

## Pré-requisitos

- **API key** fornecida pelo SERPRO para o seu órgão.
- **Template cadastrado** previamente no serviço. A biblioteca referencia um
  `template_id`; ela não cria templates.

## Uso básico

```python
from notifica_govbr import (
    HttpNotificationAdapter,
    NotificaClient,
    Notification,
    Recipient,
)

adapter = HttpNotificationAdapter(
    base_url="https://h-api-orgaos-cxpostal.np.estaleiro.serpro.gov.br",  # homologação
    api_key="sua-api-key",
)

client = NotificaClient(adapter)

response = client.send(
    Notification(
        subject="Olá, cidadão",
        recipients=[
            Recipient(cpf="12345678901", tags={"nome": "Maria"}),
        ],
        has_push=True,
        template_id=42,
        version=1,
        tags={"documento": "CNH"},
    )
)

print(response.cpf_successes)   # ['12345678901']
print(response.failed)          # []  ou  [FailedSend(cpfs=[...], reason='...')]
```

O adaptador HTTP gerencia o ciclo de vida da conexão e pode ser usado como
_context manager_:

```python
with HttpNotificationAdapter(base_url=..., api_key=...) as adapter:
    client = NotificaClient(adapter)
    client.send(...)
```

## Testes com a API fake

A biblioteca inclui um adaptador em memória para testar o seu código sem rede.
Ele implementa a mesma porta do adaptador HTTP e registra o que foi enviado:

```python
from notifica_govbr import FakeNotificationAdapter, NotificaClient

fake = FakeNotificationAdapter()
client = NotificaClient(fake)

client.send(...)

assert fake.sent[0].subject == "Olá, cidadão"
```

Para simular falhas por CPF:

```python
fake = FakeNotificationAdapter(
    failing_cpfs={"98765432100"},
    failure_reason="CPF não encontrado",
)
response = NotificaClient(fake).send(...)

assert response.failed[0].cpfs == ["98765432100"]
assert response.failed[0].reason == "CPF não encontrado"
```

## Integração com FastAPI

A biblioteca inclui um helper que lê as configurações via `pydantic-settings`
e monta o `NotificaClient` pronto para ser usado com `Depends`.

Instale o extra:

```bash
pip install "notifica-govbr[fastapi]"
```

Configure as variáveis de ambiente (ou um arquivo `.env`):

```bash
NOTIFICA_BASE_URL=https://h-api-orgaos-cxpostal.np.estaleiro.serpro.gov.br
NOTIFICA_API_KEY=sua-api-key
```

Use a dependency pronta:

```python
from fastapi import Depends, FastAPI
from notifica_govbr import NotificaClient
from notifica_govbr.integracao.fastapi import get_notifica_client

app = FastAPI()

@app.post("/notificar")
def notificar(client: NotificaClient = Depends(get_notifica_client)):
    return client.send(...)
```

Nos testes, sobrescreva a dependency para usar o fake:

```python
from notifica_govbr import FakeNotificationAdapter, NotificaClient

def override():
    return NotificaClient(FakeNotificationAdapter())

app.dependency_overrides[get_notifica_client] = override
```

## Integração com Django

Instale o extra:

```bash
pip install "notifica-govbr[django]"
```

Configure as settings no `settings.py` do seu projeto:

```python
NOTIFICA_BASE_URL = "https://h-api-orgaos-cxpostal.np.estaleiro.serpro.gov.br"
NOTIFICA_API_KEY = "sua-api-key"
```

Use o helper nas views ou services:

```python
from notifica_govbr.integracao.django import get_notifica_client

def minha_view(request):
    client = get_notifica_client()
    return client.send(...)
```

Assim como no FastAPI, o helper apenas monta o cliente; o gerenciamento do ciclo de vida e o tratamento de exceções ficam a cargo da sua aplicação.

## Formato da resposta

`SendResponse` reflete o contrato da API (`falhas`/`sucessos`):

- `response.cpf_successes: list[str]` — CPFs processados com sucesso.
- `response.failed: list[FailedSend]` — falhas agrupadas por motivo.
  - `FailedSend.cpfs: list[str]`
  - `FailedSend.reason: str`

Falhas **por destinatário** vêm no `SendResponse`. Falhas **de transporte**
(timeout, `401`, `5xx`) viram exceções `httpx.HTTPError` — o usuário trata
os dois casos em lugares diferentes, sem misturar.

## API pública

```python
from notifica_govbr import (
    FailedSend,
    FakeNotificationAdapter,
    HttpNotificationAdapter,
    NotificaClient,
    Notification,
    NotificationPort,
    Recipient,
    SendResponse,
)
```

`NotificationPort` é o `Protocol` que qualquer adaptador precisa cumprir. Use-o
apenas se quiser implementar um adaptador próprio (ex: cache, fila, outro
transporte). Para o uso comum, basta `HttpNotificationAdapter` ou
`FakeNotificationAdapter`.

## Status

Versão **0.1.0** — adaptador síncrono (`httpx.Client`). Versão assíncrona
(`httpx.AsyncClient`) planejada para uma versão futura, sem quebrar a API atual.

## Licença

Este projeto está licenciado sob a **Apache License 2.0**.
Veja o arquivo [LICENSE](LICENSE) para o texto completo.
