Metadata-Version: 2.4
Name: ampere-core-sdk
Version: 0.1.1
Summary: SDK Python para Ampere Core (hexagonal: domain/application/infrastructure).
Author: Ampere Consultoria Empresarial LTDA
License: Proprietary
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.7
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Requires-Dist: types-requests>=2.32.0.20240712; extra == "dev"

# ampere-core-sdk
[![pipeline status](https://git.ampereconsultoria.com.br/public-repo/ampere-core/python-sdk/badges/main/pipeline.svg)](https://git.ampereconsultoria.com.br/public-repo/ampere-core/python-sdk/-/pipelines)
[![coverage report](https://git.ampereconsultoria.com.br/public-repo/ampere-core/python-sdk/badges/main/coverage.svg?job=pytest)](https://git.ampereconsultoria.com.br/public-repo/ampere-core/python-sdk/-/pipelines)
[![latest release](https://git.ampereconsultoria.com.br/public-repo/ampere-core/python-sdk/-/badges/release.svg)](https://git.ampereconsultoria.com.br/public-repo/ampere-core/python-sdk/-/releases)



SDK Python (3.12+) para consumir a API Ampere Core.

---
# DEVs
Sempre que iniciar o desenvolvimento rode
```bash
uv sync --dev
uv run pre-commit install
uv run pre-commit install --hook-type pre-push
uv run pre-commit install --hook-type pre-commit

# Teste inicial
uv run pre-commit run --all-files
```
---
# Uso

## 1) Instalação

### Via pip

```bash
pip install ampere-core-sdk
```

### Via uv

```bash
uv add ampere-core-sdk
```

---

## 2) Conceitos

* A API usa **tokens** (access_token + refresh_token) com expiração.
* No login, o campo `password` deve ser enviado **codificado** (SHA-256 + base64url sem padding).
* O SDK tem:

  * `AuthHttpAdapter` / `AsyncAuthHttpAdapter` → faz `login` e `refresh`.
  * `TokenManager` → garante token válido (login/refresh sob demanda) e usa uma **TokenStore** (memória/arquivo/sua implementação).
  * Config HTTP com suporte a **proxy** e **debug detalhado**.

---

## 3) Configuração mínima (variáveis de ambiente)

Os exemplos e este README usam estas env vars:

* `AMPERE_BASE_URL` - A URL sempre será https://core.ampereconsultoria.com.br, apenas em casos de debug e testes que a URL pode ser alterada sob orientação da equipe de TI da Ampere Consultoria.
* `AMPERE_USERNAME`
* `AMPERE_PASSWORD` (senha crua; o exemplo transforma para o formato exigido)

Linux/macOS:

```bash
export AMPERE_BASE_URL="https://core.ampereconsultoria.com.br"
export AMPERE_USERNAME="seu-user"
export AMPERE_PASSWORD="sua-senha"
```

Windows (PowerShell):

```powershell
$env:AMPERE_BASE_URL = "https://core.ampereconsultoria.com.br"
$env:AMPERE_USERNAME = "seu-user"
$env:AMPERE_PASSWORD = "sua-senha"
```

---

## 4) Uso

### 4.1 Login + Refresh (sync)

```python
from ampere_core.config import AmpereCoreConfig
from ampere_core.infrastructure.iam.http import AuthHttpAdapter
from ampere_core.domain.iam.security.password_encoding import sha256_base64url

cfg = AmpereCoreConfig(base_url="https://core.ampereconsultoria.com.br")
auth = AuthHttpAdapter(config=cfg)

pair = auth.login(username="users", password=sha256_base64url("senha-crua"))
print(pair.expires_at)

pair2 = auth.refresh(refresh_token=pair.refresh_token)
print(pair2.expires_at)
```

### 4.2 TokenManager (refresh automático sob demanda)

O `TokenManager` é o modo recomendado: ele chama `login`/`refresh` quando precisa.

```python
from ampere_core.application.iam.services import Credentials, TokenManager
from ampere_core.config import AmpereCoreConfig
from ampere_core.infrastructure.iam.http import AuthHttpAdapter
from ampere_core.infrastructure.iam.mock.in_memory_token_store import InMemoryTokenStore
from ampere_core.domain.iam.security.password_encoding import sha256_base64url

cfg = AmpereCoreConfig(base_url="https://core.ampereconsultoria.com.br")
auth_api = AuthHttpAdapter(config=cfg)
store = InMemoryTokenStore()

creds = Credentials(username="users", password=sha256_base64url("senha-crua"))
manager = TokenManager(auth_api=auth_api, store=store, credentials=creds)

headers = manager.auth_header()  # {"Authorization": "Bearer ..."}
print(headers)
```

---

## 5) Proxy corporativo

### 5.1 Via variáveis de ambiente (mais comum em empresas)

```bash
export HTTPS_PROXY="http://usuario:senha@proxy.empresa:3128"
export HTTP_PROXY="http://usuario:senha@proxy.empresa:3128"
export NO_PROXY="localhost,127.0.0.1,.empresa"
```

Por padrão `trust_env=True`, então funciona sem mudar código.

### 5.2 Proxy explícito no config

```python
from ampere_core.config import AmpereCoreConfig, HttpClientOptions

cfg = AmpereCoreConfig(
    base_url="https://core.ampereconsultoria.com.br",
    http=HttpClientOptions(proxy="http://proxy.empresa:3128", trust_env=False),
)
```

---

## 6) Debug detalhado (sem vazar tokens)

O SDK tem logs HTTP no logger `ampere_core.http` com redaction de headers sensíveis.

```python
import logging

from ampere_core.config import AmpereCoreConfig, HttpClientOptions, HttpDebugOptions
from ampere_core.infrastructure.iam.http import AuthHttpAdapter

logging.basicConfig(level=logging.DEBUG)
logging.getLogger("ampere_core.http").setLevel(logging.DEBUG)

cfg = AmpereCoreConfig(
    base_url="https://core.ampereconsultoria.com.br",
    http=HttpClientOptions(
        debug=HttpDebugOptions(
            enabled=True,
            log_request_headers=True,
            log_request_body=False,
            log_response_headers=True,
            log_response_body=True,
            max_body_chars=2000,
        )
    ),
)

auth = AuthHttpAdapter(config=cfg)
```

---

## 7) Cliente httpx customizado (quando a empresa exige algo especial)

Se você precisa de CA corporativa, mTLS, proxy diferente, timeouts, transport custom, etc:

```python
import httpx

from ampere_core.config import AmpereCoreConfig
from ampere_core.infrastructure.iam.http import AuthHttpAdapter

cfg = AmpereCoreConfig(base_url="https://core.ampereconsultoria.com.br")

with httpx.Client(
    base_url=cfg.base_url,
    timeout=cfg.timeout_seconds,
    trust_env=True,
    # verify="/path/ca_bundle.pem",
    # proxy="http://proxy.empresa:3128",
) as client:
    auth = AuthHttpAdapter(config=cfg, client=client)
```

---

## 8) Rodando os exemplos do repositório

```bash
uv run python examples/_01_auth_sync_basic.py
uv run python examples/_04_auth_sync_debug.py
uv run python examples/_06_token_manager_memory.py
uv run python examples/_08_auth_async_basic.py
```

### 8.1 Exemplos de Módulos (Nuvem, DI, etc)

```bash
# Cloud Manager
uv run python examples/cloud/_01_list_authentications.py

# Data Ingestion (DI)
uv run python examples/di/_00_create_json.py

# Dimensions
uv run python examples/dimensions/_01_list_dimensions.py
```

---

## 9) Documentação adicional

 [Autenticação e Tokens](./docs/authentication.md)
* [Cloud Manager](./docs/cloud/readme.md)
* [Data Ingestion (DI)](./docs/di/readme.md)
* [Dimensions](./docs/dimensions/readme.md)
* [FSARH (Recursos Hídricos)](./docs/fsarh/readme.md)
* [IAM (Identity & Access Management)](./docs/iam/readme.md)
* [Products (IPDO)](./docs/products/readme.md)
* [Usinas](./docs/usinas/readme.md)
