Metadata-Version: 2.4
Name: edahab
Version: 2.0.0
Summary: Python client for the eDahab payment API
Author: eDahab Python client contributors
License: MIT
Keywords: edahab,payment,api,somalia
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
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: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown

<p align="center">
  <img src="./eDahab.png" alt="eDahab logo" width="120" />
</p>

<h1 align="center">edahab (Python SDK)</h1>

<p align="center">
  Python client for the official <a href="https://docs.edahab.net/api-introduction">eDahab API</a>.
</p>

<p align="center">
  <a href="https://pypi.org/project/edahab/">PyPI</a> •
  <a href="./n8n-nodes-edahab/README.md">n8n Node Package</a> •
  <a href="https://docs.edahab.net/status">Status Codes</a>
</p>

---

## Product Separation

This repository contains **two separate libraries**:

- **Python SDK** (this package): `edahab`
- **n8n community node package**: `n8n-nodes-edahab/`

They are versioned and published independently.

---

## Quick Start

```bash
pip install edahab
```

```python
from edahab import configure, pay, is_invoice_paid

configure("your-api-key", "your-api-secret")

result = pay(
    customer="65",
    amount=1,
    agent="5555",
    currency="USD",  # required
)

print(result.invoice_id, is_invoice_paid(result.invoice_status))
```

> `currency` is required on all payment methods and must be `USD` or `SLSH`.

---

## Core API

### Configuration

- `configure(api_key, api_secret, ...)`
- `configure_from_env(...)`
- `get_client()`
- `clear_configuration()`

### Payment helpers

- `pay(...)` → `Issueinvoice`
- `verify_invoice(...)` → `CheckInvoiceStatus`
- `send_credit(...)` → `agentPayment`

### Utilities

- `normalize_currency("usd") -> "USD"`
- `is_invoice_paid(status)`
- `generate_request_hash(serialized_body, api_secret)`
- `serialize_body(payload)`
- `describe_status_code(code)`

---

## Interactive Reference

<details>
<summary><strong>configure / configure_from_env examples</strong></summary>

```python
from edahab import configure, configure_from_env, get_client

# Explicit:
configure("your-api-key", "your-api-secret")

# Or environment-based:
# export EDAHAB_API_KEY=...
# export EDAHAB_API_SECRET=...
configure_from_env()

client = get_client()
```

</details>

<details>
<summary><strong>pay() and verify_invoice() examples</strong></summary>

```python
from edahab import configure, pay, verify_invoice

configure("your-api-key", "your-api-secret")

invoice = pay(customer="65", amount=1, agent="5555", currency="USD")

if invoice.invoice_id:
    verified = verify_invoice(invoice_id=invoice.invoice_id)
    print(verified.invoice_status)
```

</details>

<details>
<summary><strong>send_credit() example</strong></summary>

```python
from edahab import configure, send_credit

configure("your-api-key", "your-api-secret")

credit = send_credit(
    to="252612345678",
    amount=100,
    reference="order-999",
    currency="SLSH",
)
print(credit.transaction_status, credit.transaction_message)
```

</details>

<details>
<summary><strong>Low-level EdahabClient methods</strong></summary>

```python
from edahab import EdahabClient

client = EdahabClient("your-api-key", "your-api-secret")

client.issue_invoice("65", 1, "5555", currency="USD")
client.agent_payment("252612345678", 100, "order-999", currency="SLSH")
client.check_invoice_status("INV123456789")
```

</details>

<details>
<summary><strong>Error handling pattern</strong></summary>

```python
from edahab import (
    EdahabClient,
    EdahabCredentialError,
    EdahabValidationError,
    EdahabAPIStatusError,
    EdahabHTTPError,
)

client = EdahabClient("your-api-key", "your-api-secret")

try:
    client.issue_invoice("65", 1, "5555", currency="USD")
except EdahabCredentialError:
    print("Invalid API key/secret/hash")
except EdahabValidationError as e:
    print(e.validation_errors)
except EdahabAPIStatusError as e:
    print(e.status_code, e.raw_response)
except EdahabHTTPError as e:
    print(e.status_code, e.body)
```

</details>

---

## Official Docs

- [API introduction](https://docs.edahab.net/api-introduction)
- [Purchase / Issueinvoice](https://docs.edahab.net/purchase)
- [Credit payment / agentPayment](https://docs.edahab.net/credit-invoice)
- [Verify invoice / CheckInvoiceStatus](https://docs.edahab.net/verify-invoice)
- [Status codes](https://docs.edahab.net/status)

---

## Exports

`configure`, `configure_from_env`, `get_client`, `clear_configuration`, `pay`, `verify_invoice`, `send_credit`, `is_invoice_paid`, `normalize_currency`, `generate_request_hash`, `serialize_body`, `describe_status_code`, `EdahabClient`, `DEFAULT_BASE_URL`, `StatusCode`, `STATUS_DESCRIPTIONS`, `IssueInvoiceResult`, `CheckInvoiceStatusResult`, `AgentPaymentResult`, `EdahabError`, `EdahabHTTPError`, `EdahabDecodeError`, `EdahabCredentialError`, `EdahabValidationError`, `EdahabAPIStatusError`.
