Metadata-Version: 2.4
Name: umojasdk
Version: 0.1.1
Summary: One SDK. Every African payment. Python SDK for M-Pesa, Airtel Money, and more.
Project-URL: Homepage, https://umojasdk.dev
Project-URL: Repository, https://github.com/knelso/umoja_sdk
Project-URL: Documentation, https://umojasdk.dev/docs
Author-email: Synapse Softwares <hello@synapsesoftwares.com>
License: MIT
Keywords: africa,airtel-money,daraja,kenya,m-pesa,mobile-money,mpesa,payment
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.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Requires-Dist: httpx>=0.27.0
Provides-Extra: dev
Requires-Dist: anyio[trio]>=4.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# umojasdk

**One SDK. Every African payment.**

UmojaSDK is the unified Python SDK for African mobile money integrations — M-Pesa (Safaricom Daraja 3.0), Airtel Money, and more.

Built by [Synapse Softwares](https://synapsesoftwares.com).

## Installation

```bash
pip install umojasdk
```

## Quickstart — M-Pesa STK Push

```python
from umojasdk import UmojaMpesa, MpesaConfig, STKPushRequest

mpesa = UmojaMpesa(MpesaConfig(
    consumer_key="your_key",
    consumer_secret="your_secret",
    shortcode="174379",
    passkey="your_passkey",
    callback_url="https://yourapp.com/mpesa/callback",
    env="sandbox"
))

result = mpesa.stk_push(STKPushRequest(
    phone="0712345678",   # accepts 07XX, +2547XX, 2547XX — auto-normalized
    amount=1500,
    reference="ORDER-001"
))

print(result.checkout_request_id)
```

```python
# Parse incoming Daraja callback
from umojasdk import parse_stk_callback

payment = parse_stk_callback(request_body)

if payment["success"]:
    print(payment["mpesa_receipt_number"])
    print(payment["amount"])

# CRITICAL: Always return 200 to stop Daraja retries
return {"ResultCode": 0, "ResultDesc": "Accepted"}
```

## Quickstart — Airtel Money

```python
from umojasdk import UmojaAirtel, AirtelConfig, AirtelCollectionRequest

airtel = UmojaAirtel(AirtelConfig(
    client_id="your_client_id",
    client_secret="your_client_secret",
    env="sandbox"
))

result = airtel.request_to_pay(AirtelCollectionRequest(
    phone="0733123456",
    amount=500,
    reference="ORDER-002"
))
```

## Async Support

```python
from umojasdk import AsyncUmojaMpesa, MpesaConfig, STKPushRequest

mpesa = AsyncUmojaMpesa(MpesaConfig(...))

result = await mpesa.stk_push(STKPushRequest(
    phone="0712345678",
    amount=1500,
    reference="ORDER-001"
))
```

## Features

| Feature | Status |
|---------|--------|
| STK Push (Lipa Na M-Pesa) | ✓ |
| STK Push status query | ✓ |
| C2B URL registration & callbacks | ✓ |
| B2C disbursements | ✓ |
| Transaction status query | ✓ |
| Transaction reversal | ✓ |
| SIM Swap detection (Daraja 3.0) | ✓ |
| Tax remittance to KRA (Daraja 3.0) | ✓ |
| Airtel Money collections | ✓ |
| Airtel Money disbursements | ✓ |
| Webhook parsing | ✓ |
| Phone number normalization | ✓ |
| Automatic token refresh | ✓ |
| Typed errors | ✓ |
| Async client | ✓ |

## Error Handling

```python
from umojasdk.core.errors import UmojaAuthError, UmojaValidationError, UmojaApiError

try:
    result = mpesa.stk_push(req)
except UmojaAuthError:
    pass  # bad credentials
except UmojaValidationError as e:
    pass  # bad input — str(e) is human-readable
except UmojaApiError as e:
    pass  # Daraja error — e.raw has full response
```

## Environment Variables

```bash
MPESA_CONSUMER_KEY=
MPESA_CONSUMER_SECRET=
MPESA_SHORTCODE=174379
MPESA_PASSKEY=
MPESA_CALLBACK_URL=
MPESA_ENV=sandbox         # "sandbox" | "production"

AIRTEL_CLIENT_ID=
AIRTEL_CLIENT_SECRET=
AIRTEL_ENV=sandbox
```

## Related

- **TypeScript SDK**: `npm install umojasdk`
- **CLI**: `npx @umojasdk/cli init`
- **Docs**: [umojasdk.dev](https://umojasdk.dev)

## License

MIT — [github.com/Knelso/Umoja_SDK](https://github.com/Knelso/Umoja_SDK)

*Built with precision in Nairobi, Kenya. For Africa, by Africa.*
