Metadata-Version: 2.4
Name: foolscap-sdk
Version: 0.1.0
Summary: SDK Python oficial do Foolscap — geração de documentos: template + JSON → PDF
Project-URL: Homepage, https://foolscap.app.br
Project-URL: Documentation, https://api.foolscap.app.br/docs
Author: Foolscap
License-Expression: MIT
License-File: LICENSE
Keywords: api,contratos,documentos,foolscap,pdf,template
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: Portuguese (Brazilian)
Classifier: Programming Language :: Python :: 3
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: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx2>=2.9
Description-Content-Type: text/markdown

# foolscap-sdk

SDK Python oficial do [Foolscap](https://foolscap.app.br) — geração de documentos:
**template + JSON → PDF**, direto da sua aplicação.

```bash
pip install foolscap-sdk
```

```python
from foolscap_sdk import Foolscap

client = Foolscap(api_key="fsk_...")  # crie a key no painel, seção API Keys

doc = client.render(
    template_id="tpl_...",
    data={"contratante": {"nome": "Maria Silva"}},
    document_name="Contrato — Maria Silva",
)
print(doc.pdf_url)  # PDF pronto, URL assinada
```

`render()` cuida do ciclo assíncrono inteiro (a API responde `202` e o SDK acompanha
até o documento ficar pronto — segundos). Retry de rede é seguro por padrão: todo
render envia uma chave de idempotência, então reenvio nunca duplica documento.

## Controle fino

```python
accepted = client.render_nowait(template_id="tpl_...", data={...})
# ... sua fila, seu ritmo ...
doc = client.wait_for_document(accepted.document_id)  # ou get_document(), 1 consulta seca
pdf_bytes = client.download_pdf(doc.id)
```

## Descoberta e histórico

```python
for template in client.list_templates():
    print(template.id, template.name, template.sample_data)  # sample_data = contrato do `data`

for doc in client.iter_documents():  # paginação automática
    print(doc.created_at, doc.name, doc.status)

conta = client.account()
print(conta.plan, conta.usage.documents, "/", conta.usage.limit)
```

## Erros

Tudo herda de `FoolscapError`:

```python
from foolscap_sdk import FoolscapError, QuotaExceededError, TemplateRenderError

try:
    doc = client.render(template_id="tpl_...", data=dados)
except TemplateRenderError as e:
    print("variável faltando ou template inválido:", e.detail)
except QuotaExceededError:
    print("cota do mês esgotada — hora do upgrade :)")
except FoolscapError as e:
    print("qualquer outra falha do SDK/API:", e)
```

## Referências

- Guia de integração: https://foolscap.app.br/guia
- Referência completa da API: https://api.foolscap.app.br/docs

Python ≥ 3.10 · tipagem completa · dependência única (`httpx2`) · MIT
