Metadata-Version: 2.4
Name: nezahub
Version: 0.2.1
Summary: Official Python SDK for the NezaHub API
Author: NezaHub
License: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: httpx<1,>=0.28
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-httpx>=0.35; extra == "dev"
Requires-Dist: httpx>=0.28; extra == "dev"

# NezaHub Python SDK

Official Python client for the NezaHub REST API (`/api/v1/`).

- **Quick recipes:** [`../quick-usage.md`](../quick-usage.md)
- **Full reference:** [`../usage.md`](../usage.md)
- **All SDKs:** [`../README.md`](../README.md)

## Install

```bash
pip install nezahub
```

Local development (monorepo):

```bash
cd sdks/python
pip install -e ".[dev]"
# or from repo root:
make sdk-python
```

Requires **Python 3.10+**.

## Environments

| Environment | `base_url` |
|-------------|------------|
| Local dev | `http://localhost:8000` (default) |
| Sandbox | `https://sandbox-api.nezahub.com` |
| Live | `https://api.nezahub.com` |

```bash
export NEZAHUB_BASE_URL=https://api.nezahub.com
export NEZAHUB_API_KEY=nz_live_...
```

## Server client (API key)

```python
from nezahub import NezaHubClient, nezahub_setup

nezahub_setup(api_key="nz_test_xxx", on_error=print)

with NezaHubClient() as client:
    print(client.health())
    for product in client.products.list_auto():
        print(product["name"])
```

## Server client (JWT login)

```python
from nezahub import NezaHubClient

bootstrap = NezaHubClient(base_url="http://localhost:8000")

# Phone + password
session = bootstrap.auth.login(phone="+254700000099", password="demo12345")

client = NezaHubClient(access_token=session["tokens"]["access"])
print(client.auth.me())
```

Email + password login is supported by the API (`POST /auth/login/` with `email`) but not yet on `auth.login` — use `client._http.request("POST", "/api/v1/auth/login/", json={...})` or REST directly.

Phone OTP login uses `POST /auth/otp/send/` and `POST /auth/otp/verify/` — call via HTTP until dedicated SDK methods ship.

## Browser-safe checkout

No API key — public checkout endpoints only:

```python
from nezahub.checkout import NezaHubCheckoutClient

with NezaHubCheckoutClient(environment="test") as checkout:
    session = checkout.start_from_link("your-link-slug", customer_phone="+254700000099")
    checkout.confirm_stk(session["id"], otp_code="123456")
```

For hosted sandbox, set `base_url="https://sandbox-api.nezahub.com"`.

## Resources

| Namespace | Examples |
|-----------|----------|
| `client.auth` | `login`, `me`, `refresh_token`, `verify_2fa` |
| `client.products` | `list`, `create`, `update`, `delete` |
| `client.prices` | `create`, `update`, charge distribution |
| `client.checkout` | `create_session`, `confirm` |
| `client.transactions` | `list`, `get` |
| `client.agents` | CRUD, assignments |
| `client.payouts` | balance, create (2FA) |
| `client.wallets` | FX quote, transfer (2FA) |

## Webhooks

```python
from nezahub.webhooks import construct_event

event = construct_event(payload, signature, secret)
```

## Integration tests

```bash
make dev && make migrate
# seed demo seller (see ../flows/README.md)

cd sdks/python
NEZAHUB_INTEGRATION=1 NEZAHUB_2FA_CODE=123456 pytest tests/test_integration_flow.py -v
```

## Tests (unit)

```bash
pytest
```
