Metadata-Version: 2.4
Name: ihela-sdk
Version: 0.3.0
Summary: Python SDK for the iHela financial services API
Project-URL: Homepage, https://github.com/UbuhingaVizion/ihela-sdk
Project-URL: Repository, https://github.com/UbuhingaVizion/ihela-sdk
Project-URL: Documentation, https://UbuhingaVizion.github.io/ihela-sdk/
Project-URL: Issue Tracker, https://github.com/UbuhingaVizion/ihela-sdk/issues
Project-URL: Changelog, https://github.com/UbuhingaVizion/ihela-sdk/releases
Author-email: UbuViz <info@ubuviz.com>
License: MIT License
License-File: LICENSE
Keywords: api-client,banking,burundi,financial-services,ihela,mobile-money,oauth2,payments
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Requires-Python: >=3.10
Requires-Dist: httpx>=0.25.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5.0; extra == 'docs'
Requires-Dist: mkdocs>=1.5.0; extra == 'docs'
Description-Content-Type: text/markdown

# iHela SDK

[![PyPI version](https://img.shields.io/pypi/v/ihela-sdk)](https://pypi.org/project/ihela-sdk/)
[![Python versions](https://img.shields.io/pypi/pyversions/ihela-sdk)](https://pypi.org/project/ihela-sdk/)
[![License](https://img.shields.io/pypi/l/ihela-sdk)](https://github.com/UbuhingaVizion/ihela-sdk/blob/develop/LICENSE)
[![Docs](https://img.shields.io/badge/docs-mkdocs-blue)](https://UbuhingaVizion.github.io/ihela-sdk/)

Python SDK for the iHela Credit Union API for financial services in Burundi.
Framework-agnostic — works with Django, Flask, FastAPI, or any Python application.

## Installation

```bash
pip install ihela-sdk
```

Or with `uv`:

```bash
uv add ihela-sdk
```

## Quick Start

```python
from ihela_sdk import MerchantClient

client = MerchantClient("your_client_id", "your_client_secret", prod=False)
```

For async applications (FastAPI, asyncio):

```python
from ihela_sdk import AsyncMerchantClient

client = AsyncMerchantClient("your_client_id", "your_client_secret", prod=False)
```

## OAuth2 SSO

```python
from ihela_sdk import MerchantAuthorizationClient

auth = MerchantAuthorizationClient("client_id", "client_secret", prod=False)
login_url = auth.get_authorization_url(redirect_uri="https://app.com/callback/")
# Redirect user to login_url, handle callback with auth.authenticate(code, redirect_uri)
```

See the **[Authentication](https://UbuhingaVizion.github.io/ihela-sdk/authentication/)** guide for Django, Flask, and FastAPI examples.

## Exception Handling

```python
from ihela_sdk import iHelaError, iHelaAPIError, iHelaAuthenticationError

try:
    bill = client.init_bill(2000, "client@example.com", "Payment", "ref-001")
except iHelaAuthenticationError:
    print("Authentication failed. Check your credentials.")
except iHelaAPIError as e:
    print(f"API error (HTTP {e.status_code})")
except iHelaError:
    print("A client error occurred.")
```

## Features

- **Merchant Services**: Bill init/verify, cash-in, bank lists, customer lookup
- **Banking Services**: Deposits, withdrawals, account lookup/balance, statements, transaction fees
- **Agent Services**: Operations, withdrawal validation
- **OAuth2**: Client credentials and authorization code flows
- **Framework-Agnostic**: No web framework dependency — OAuth2 primitives work everywhere
- **Async Support**: Full async client variants using httpx

## Documentation

Full documentation at [UbuhingaVizion.github.io/ihela-sdk](https://UbuhingaVizion.github.io/ihela-sdk/).

## License

MIT — see [LICENSE](LICENSE).
