bling-jwt-auth 0.1.0__tar.gz

bling_jwt_auth-0.1.0/.gitignore

@@ -0,0 +1,20 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Testing / tooling
+.pytest_cache/
+.ruff_cache/
+
+# Local secrets and token files
+.env
+.env.*
+*.db
+token.json

bling_jwt_auth-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mercanatu contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

bling_jwt_auth-0.1.0/PKG-INFO

@@ -0,0 +1,176 @@
+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).

bling_jwt_auth-0.1.0/README.md

@@ -0,0 +1,144 @@
+# 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).

bling_jwt_auth-0.1.0/examples/__init__.py

@@ -0,0 +1 @@
+"""Example scripts."""

bling_jwt_auth-0.1.0/examples/authenticated_request.py

@@ -0,0 +1,91 @@
+"""Call the Bling homologation endpoint to verify OAuth + stored tokens.
+
+Loads secrets from `./.env` (see `env_file` on `BlingAuthSettings`) and/or exported
+`BLING_*` environment variables — run from the repo root next to `.env`.
+
+Uses the same token store as `oauth_flow.py` (see `BLING_TOKEN_STORE` and
+`BLING_TOKEN_STORE_PATH`).
+
+Example:
+    uv sync
+    uv run python examples/oauth_flow.py
+    uv run python examples/authenticated_request.py
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any, cast
+
+import httpx
+
+from bling_jwt_auth import (
+    BlingAuthSettings,
+    OAuthClient,
+    TokenManager,
+    TokenNotFoundError,
+    bling_api_headers,
+    create_token_store,
+)
+
+HOMOLOGACAO_PRODUTOS_URL = "https://api.bling.com.br/Api/v3/homologacao/produtos"
+
+
+def _summarize_body(text: str, *, max_len: int = 800) -> str:
+    if len(text) <= max_len:
+        return text
+    return text[: max_len - 3] + "..."
+
+
+def main() -> None:
+    """GET homologação produtos using the access token from the configured store."""
+    settings = BlingAuthSettings.load()
+    store = create_token_store(settings)
+    print(f"Token store: {settings.token_store.value} at {store.path}")
+
+    with OAuthClient(settings) as oauth:
+        manager = TokenManager(oauth, store, settings)
+        try:
+            access_token = manager.get_access_token()
+        except TokenNotFoundError:
+            print(
+                "No token found. Run `uv run python examples/oauth_flow.py` first "
+                f"using the same BLING_TOKEN_STORE ({settings.token_store.value}).",
+                file=sys.stderr,
+            )
+            sys.exit(1)
+
+    headers = bling_api_headers(access_token)
+    with httpx.Client(timeout=30.0) as client:
+        response = client.get(HOMOLOGACAO_PRODUTOS_URL, headers=headers)
+
+    if not response.is_success:
+        print(
+            f"Request failed: HTTP {response.status_code}\n"
+            f"{_summarize_body(response.text)}",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    try:
+        parsed: Any = response.json()
+    except json.JSONDecodeError:
+        print("Unexpected response: not JSON", file=sys.stderr)
+        print(_summarize_body(response.text), file=sys.stderr)
+        sys.exit(1)
+
+    if not isinstance(parsed, dict):
+        print("Unexpected response: JSON must be an object", file=sys.stderr)
+        sys.exit(1)
+    body: dict[str, Any] = cast("dict[str, Any]", parsed)
+    data: Any | None = body.get("data")
+    preview_payload: Any = body if data is None else data
+    preview = json.dumps(preview_payload, indent=2, ensure_ascii=False)
+    print(f"HTTP {response.status_code} OK")
+    print(preview)
+    print("Token from store is valid for the Bling API (homologação GET).")
+
+
+if __name__ == "__main__":
+    main()

bling_jwt_auth-0.1.0/examples/oauth_flow.py

@@ -0,0 +1,43 @@
+"""Minimal manual OAuth walkthrough.
+
+Loads secrets from `./.env` (see `env_file` on `BlingAuthSettings`) and/or exported
+`BLING_*` environment variables — run from the repo root next to `.env`.
+
+Example:
+    uv sync
+    uv run python examples/oauth_flow.py
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+import webbrowser
+
+from bling_jwt_auth import BlingAuthSettings, OAuthClient, TokenManager, create_token_store
+
+
+def main() -> None:
+    """Prompt for OAuth code interactively after printing the authorize URL."""
+    settings = BlingAuthSettings.load()
+    store = create_token_store(settings)
+    with OAuthClient(settings) as oauth:
+        manager = TokenManager(oauth, store, settings)
+
+        auth_url = oauth.build_authorization_url(state=os.urandom(16).hex())
+        print("Open this URL in a browser, approve access, then copy the `code` query param:")
+        print(auth_url)
+        if "--open" in sys.argv:
+            webbrowser.open(auth_url)
+
+        code = input("Paste authorization code: ").strip()
+        manager.save_from_code(code)
+        token = manager.get_access_token()
+        print("Access token acquired (truncated):", token[:24], "...")
+        print("Use HTTP headers:")
+        print("  Authorization: Bearer", "<token>")
+        print("  enable-jwt: 1")
+
+
+if __name__ == "__main__":
+    main()

bling_jwt_auth-0.1.0/pyproject.toml

@@ -0,0 +1,129 @@
+[build-system]
+requires = ["hatchling>=1.24"]
+build-backend = "hatchling.build"
+
+[project]
+name = "bling-jwt-auth"
+version = "0.1.0"
+description = "OAuth 2.0 / JWT authentication helpers for the Bling API v3"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.14"
+authors = [{ name = "tempont" }]
+keywords = ["bling", "oauth2", "jwt", "authentication", "erp", "api"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.14",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.28.0",
+    "pydantic>=2.0.0",
+    "pydantic-settings>=2.0.0",
+    "python-dotenv>=1.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/tempont/bling-jwt-auth-python"
+Documentation = "https://github.com/tempont/bling-jwt-auth-python#readme"
+Repository = "https://github.com/tempont/bling-jwt-auth-python"
+Issues = "https://github.com/tempont/bling-jwt-auth-python/issues"
+
+[project.optional-dependencies]
+dev = [
+    "basedpyright>=1.0.0",
+    "pre-commit>=4.0.0",
+    "pytest>=8.0.0",
+    "pytest-httpx>=0.30.0",
+    "ruff>=0.8.0",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/bling_jwt_auth"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "/scripts",
+    "/src",
+    "/tests",
+    "/examples",
+    "/README.md",
+    "/LICENSE",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py314"
+line-length = 100
+indent-width = 4
+exclude = [".git", ".ruff_cache", ".venv"]
+show-fixes = true
+
+[tool.ruff.format]
+indent-style = "space"
+line-ending = "lf"
+quote-style = "double"
+docstring-code-format = true
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+    "YTT",
+    "CPY",
+    "FA",
+    "TD",
+    "C90",
+    "PGH",
+    "COM812",
+    "COM819",
+    "D206",
+    "D300",
+    "E111",
+    "E114",
+    "E117",
+    "E501",
+    "Q000",
+    "Q001",
+    "Q002",
+    "Q003",
+    "W191",
+]
+task-tags = ["TODO", "FIXME", "XXX", "HACK"]
+
+[tool.ruff.lint.per-file-ignores]
+"examples/**" = ["T201"]
+"tests/**" = [
+    "ANN001",
+    "ANN201",
+    "PLR2004",
+    "S101",
+    "S105",
+    "S106",
+]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.pyright]
+pythonVersion = "3.14"
+typeCheckingMode = "strict"
+failOnWarnings = true
+venvPath = "."
+venv = ".venv"
+extraPaths = ["src"]
+exclude = [
+    "**/.venv",
+    ".venv",
+]
+
+[dependency-groups]
+dev = [
+    "build>=1.5.0",
+    "twine>=6.2.0",
+]

bling_jwt_auth-0.1.0/scripts/check.sh

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+# Run the same checks as CI / pre-commit (ruff, basedpyright, pytest).
+# Usage: from repo root — make check   or   bash scripts/check.sh
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$ROOT"
+
+run_checks() {
+  python -m ruff check .
+  python -m basedpyright
+  python -m pytest
+}
+
+if command -v uv >/dev/null 2>&1; then
+  # Resolves the project env (creates .venv / syncs deps if needed).
+  uv run --extra dev python -m ruff check .
+  uv run --extra dev python -m basedpyright
+  uv run --extra dev python -m pytest
+  exit 0
+fi
+
+if [[ -d .venv ]]; then
+  # shellcheck source=/dev/null
+  source "${ROOT}/.venv/bin/activate"
+fi
+
+if ! python -c "import bling_jwt_auth" 2>/dev/null; then
+  echo "error: bling_jwt_auth not importable — run: uv sync --extra dev" >&2
+  echo "   (or: pip install -e '.[dev]')" >&2
+  exit 1
+fi
+
+run_checks

bling_jwt_auth-0.1.0/src/bling_jwt_auth/__init__.py

@@ -0,0 +1,31 @@
+"""Bling API v3 OAuth helpers (JWT-ready)."""
+
+from bling_jwt_auth.config import BlingAuthSettings, TokenStoreKind
+from bling_jwt_auth.exceptions import BlingAuthError, OAuthRequestError, TokenNotFoundError
+from bling_jwt_auth.headers import bling_api_headers
+from bling_jwt_auth.manager import TokenManager
+from bling_jwt_auth.models.token import StoredToken, TokenResponse
+from bling_jwt_auth.oauth.client import OAuthClient
+from bling_jwt_auth.storage.base import TokenStore
+from bling_jwt_auth.storage.factory import create_token_store
+from bling_jwt_auth.storage.file import FileTokenStore
+from bling_jwt_auth.storage.sqlite import SQLiteTokenStore
+
+__all__ = [
+    "BlingAuthError",
+    "BlingAuthSettings",
+    "FileTokenStore",
+    "OAuthClient",
+    "OAuthRequestError",
+    "SQLiteTokenStore",
+    "StoredToken",
+    "TokenManager",
+    "TokenNotFoundError",
+    "TokenResponse",
+    "TokenStore",
+    "TokenStoreKind",
+    "bling_api_headers",
+    "create_token_store",
+]
+
+__version__ = "0.1.0"