Metadata-Version: 2.4
Name: orbitsender-sdk
Version: 1.0.0
Summary: SDK Python oficial do OrbitSender — facade ergonômica + cliente gerado do OpenAPI.
Author: OrbitSender
License: MIT
Project-URL: Homepage, https://docs.orbitsender.com/desenvolvedor
Project-URL: Source, https://github.com/OrbitSender/orbitsender-docs
Keywords: orbitsender,whatsapp,sdk,api,openapi,campaigns
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.23
Requires-Dist: attrs>=22.2.0
Requires-Dist: python-dateutil>=2.8.0

# orbitsender-sdk (Python)

SDK Python oficial do OrbitSender. Facade ergonômica (`orbitsender_sdk`) sobre o
cliente gerado do OpenAPI (`orbitsender`), num único pacote.

```bash
pip install orbitsender-sdk
```

```python
from orbitsender_sdk import create_orbit_sender, RateLimitError

os = create_orbit_sender(api_key="sk_live_...")
me = os.partner.me()                      # retorna o model; lança exceção tipada em erro
done = os.campaigns.wait_until_sent(cid)  # poll do agregado groups (webhook é só sinal)
```

## O que a facade dá (paridade com o SDK TS)

- **Auth unificada:** `api_key` (header `x-api-key`), `oauth` (OAuthConfig — PKCE +
  refresh single-flight) ou `oauth_token` (Bearer estático).
- **Erros tipados lançáveis:** `RateLimitError` (`.retry_after`), `PlanLimitError`
  (`.current`/`.max`), `ForbiddenScopeError`, `OAuthError`, ...
- **Retry** idempotente (nunca em POST de escrita) que honra `Retry-After`.
- **Waiters:** `campaigns.wait_until_sent`, `channels.wait_until_connected`.
- **Idempotência:** `idempotency_key=` nas escritas.
- **Webhooks:** `construct_event(raw_body, headers, secret)` (verificação HMAC).
- **Correlação:** cada requisição leva um `x-request-id` próprio, que o backend ecoa
  e registra no log. Passe `on_request_id=meu_log.append` em `create_orbit_sender`
  para guardá-lo e citá-lo no suporte (as exceções também trazem `.request_id`).
- **OAuth PKCE:** `OrbitSenderOAuth.begin/exchange/revoke` + `complete_oauth`.

## Regeneração (zero lock-in)

O cliente cru (`orbitsender/`) é gerado por `openapi-python-client` a partir de
`../../openapi/orbitsender-api.yaml`. A facade (`orbitsender_sdk/`) é escrita à mão
e **regen-safe** (fica fora do pacote gerado). Ver `PUBLISHING.md`.
