Metadata-Version: 2.4
Name: bling-jwt-auth
Version: 0.1.0
Summary: OAuth 2.0 / JWT authentication helpers for the Bling API v3
Project-URL: Homepage, https://github.com/tempont/bling-jwt-auth-python
Project-URL: Documentation, https://github.com/tempont/bling-jwt-auth-python#readme
Project-URL: Repository, https://github.com/tempont/bling-jwt-auth-python
Project-URL: Issues, https://github.com/tempont/bling-jwt-auth-python/issues
Author: tempont
License-Expression: MIT
License-File: LICENSE
Keywords: api,authentication,bling,erp,jwt,oauth2
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Requires-Python: >=3.14
Requires-Dist: httpx>=0.28.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-dotenv>=1.0.0
Provides-Extra: dev
Requires-Dist: basedpyright>=1.0.0; extra == 'dev'
Requires-Dist: pre-commit>=4.0.0; extra == 'dev'
Requires-Dist: pytest-httpx>=0.30.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.8.0; extra == 'dev'
Description-Content-Type: text/markdown

# bling-jwt-auth-python

Repositório: [github.com/tempont/bling-jwt-auth-python](https://github.com/tempont/bling-jwt-auth-python) · PyPI: [`bling-jwt-auth`](https://pypi.org/project/bling-jwt-auth/)

Biblioteca Python simples para autenticar na **API v3 do Bling** usando OAuth 2.0 e tokens JWT.

Ela ajuda a:

- gerar a URL de autorização do Bling;
- trocar o `code` recebido por tokens;
- salvar os tokens em arquivo ou SQLite;
- renovar o access token automaticamente quando necessário;
- montar os headers corretos para chamar a API do Bling.

Versão em inglês: [docs/README.en.md](docs/README.en.md)

## Requisitos

- Python 3.14 ou superior
- Uma aplicação OAuth cadastrada no Bling

## Instalação

Instale pelo `pip`:

```bash
pip install bling-jwt-auth
```

Ou instale direto do GitHub:

```bash
pip install "git+https://github.com/tempont/bling-jwt-auth-python.git"
```

Para desenvolvimento local neste repositório, use:

```bash
uv sync --extra dev
```

## Configuração

Copie o arquivo de exemplo:

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

Edite o `.env` com os dados da sua aplicação no Bling:

```env
BLING_CLIENT_ID=seu_client_id
BLING_CLIENT_SECRET=seu_client_secret
BLING_REDIRECT_URI=https://seu-dominio.com/oauth/callback
```

Por padrão, os tokens são salvos em SQLite. Se quiser salvar em JSON:

```env
BLING_TOKEN_STORE=file
BLING_TOKEN_STORE_PATH=./token.json
```

## Como usar

### 1. Autorizar a conta Bling

Rode o exemplo de OAuth:

```bash
uv run python examples/oauth_flow.py
```

O script vai mostrar uma URL. Abra essa URL no navegador, autorize o acesso no Bling e cole no terminal o `code` recebido no callback.

Se quiser que o script tente abrir o navegador automaticamente:

```bash
uv run python examples/oauth_flow.py --open
```

### 2. Testar uma chamada autenticada

Depois de salvar o token, rode:

```bash
uv run python examples/authenticated_request.py
```

Esse exemplo usa o token salvo, renova se necessário e chama um endpoint de homologação do Bling.

### 3. Usar no seu código

```python
import httpx
from bling_jwt_auth import (
    BlingAuthSettings,
    OAuthClient,
    TokenManager,
    bling_api_headers,
    create_token_store,
)

settings = BlingAuthSettings()
store = create_token_store(settings)

with OAuthClient(settings) as oauth:
    manager = TokenManager(oauth, store, settings)
    access_token = manager.get_access_token()

headers = bling_api_headers(access_token)

response = httpx.get(
    "https://api.bling.com.br/Api/v3/produtos",
    headers=headers,
)
response.raise_for_status()
print(response.json())
```

## Comandos úteis para desenvolvimento

Rodar lint, checagem de tipos e testes:

```bash
make check
```

Ou:

```bash
bash scripts/check.sh
```

Rodar apenas os testes:

```bash
uv run --extra dev pytest
```

## Licença

MIT. Veja [LICENSE](LICENSE).
