# achek — Python SDK

Official Python SDK for [Achek](https://achek.com.ng) — WhatsApp OTP, automated alerts, transaction notifications, broadcasts, and support ticket tracking for Nigeria and Africa.

[![PyPI](https://img.shields.io/pypi/v/achek-sdk)](https://pypi.org/project/achek-sdk/)
[![Python](https://img.shields.io/pypi/pyversions/achek-sdk)](https://pypi.org/project/achek-sdk/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

## Install

```bash
pip install achek-sdk
```

## Quick Start

```python
from achekverify import AchekConnect

client = AchekConnect(api_key="your_api_key")

# Send WhatsApp OTP
result = client.otp.send("+2348012345678")
request_id = result["requestId"]

# Verify the code the user entered
verification = client.otp.verify(request_id, user_code)
if verification["valid"]:
    login_user()  # ✅
```

> Get your API key from the [Achek dashboard](https://achek.com.ng/dashboard/api-keys).

---

## OTP Verification

```python
# Simple send
result = client.otp.send("+2348012345678")
request_id = result["requestId"]

# With custom template (Growth+ plans)
result = client.otp.send(
    "+2348012345678",
    template="Hi {{name}}, your {{company}} code is {{code}}. Valid 10 mins.",
    recipient_name="Emeka",
    company_name="MyApp",
)

# Verify
result = client.otp.verify(request_id, "847293")
# {"valid": True, "message": "OTP verified successfully"}

# Fetch OTP logs
logs = client.otp.logs(limit=20, status="verified")
```

---

## Transaction Alerts

Send formatted debit/credit/transfer alerts directly to a customer's WhatsApp:

```python
client.alerts.transaction(
    "+2348012345678",
    type="debit",
    amount=15000,
    reference="TXN-20240519-001",
    account_name="Emeka Okafor",
    balance=240000,
    description="Transfer to Kuda",
)
```

This automatically sends a clean WhatsApp message:
```
💸 Debit Alert

Amount: ₦15,000.00
Account: Emeka Okafor
Ref: `TXN-20240519-001`
Narration: Transfer to Kuda
Balance: ₦240,000.00

_Powered by Achek_
```

### Custom Alerts

```python
client.alerts.send(
    "+2348012345678",
    "*Your account has been credited with ₦5,000* 🎉",
    category="notification",
)
```

---

## Broadcasts

Send a single WhatsApp message to up to 1,000 recipients at once:

```python
result = client.broadcasts.send(
    name="Black Friday Promo",
    message="🔥 *50% OFF* today only! Code: *FRIDAY50*",
    recipients=["+2348012345678", "+2349087654321"],  # up to 1000
)

# Check delivery status
status = client.broadcasts.status(result["id"])
```

---

## Support Ticket Tracking

Create support tickets and keep customers updated on WhatsApp automatically:

```python
# Create a ticket — customer gets a WhatsApp notification
ticket = client.tickets.create(
    "+2348012345678",
    "Payment not reflecting",
    description="Paid ₦5,000 but order not updated",
    priority="high",
    notify_customer=True,
)
ticket_id = ticket["ticketId"]

# Update — customer gets a WhatsApp update
client.tickets.update(
    ticket_id,
    status="in_progress",
    notify_customer=True,
    notification_message="We're investigating — expected resolution: 2 hours.",
)

# Resolve
client.tickets.resolve(ticket_id, "Your issue has been fixed! Check your account.")

# List open tickets
open_tickets = client.tickets.list(status="open")
```

---

## Error Handling

```python
from achekverify import AchekConnect, AchekConnectError

try:
    client.otp.send("+2348012345678")
except AchekConnectError as e:
    print(e.args[0])     # "No active subscription"
    print(e.status_code) # 402
    print(e.code)        # "SUBSCRIPTION_REQUIRED"
```

---

## Configuration

```python
client = AchekConnect(
    api_key="your_api_key",
    base_url="https://api.achek.com.ng",  # override if self-hosted
    timeout=15,                            # seconds (default: 15)
)
```

---

## API Reference

| Module | Method | Description |
|---|---|---|
| `otp` | `send(phone, **kwargs)` | Send WhatsApp OTP |
| `otp` | `verify(request_id, code)` | Verify OTP code |
| `otp` | `logs(**kwargs)` | Fetch OTP delivery logs |
| `alerts` | `send(phone, message, **kwargs)` | Send custom WhatsApp alert |
| `alerts` | `transaction(phone, **kwargs)` | Send formatted transaction alert |
| `broadcasts` | `send(name, message, recipients)` | Send broadcast to up to 1,000 numbers |
| `broadcasts` | `list()` | List recent broadcasts |
| `broadcasts` | `status(broadcast_id)` | Get broadcast delivery status |
| `tickets` | `create(phone, subject, **kwargs)` | Create support ticket |
| `tickets` | `list(**kwargs)` | List tickets |
| `tickets` | `get(ticket_id)` | Get ticket by ID |
| `tickets` | `update(ticket_id, **kwargs)` | Update status/priority |
| `tickets` | `resolve(ticket_id, message?)` | Resolve and notify customer |

---

## Links

- Website: [achek.com.ng](https://achek.com.ng)
- Dashboard: [achek.com.ng/dashboard](https://achek.com.ng/dashboard)
- Docs: [achek.com.ng/docs](https://achek.com.ng/docs)
- Issues: [github.com/CalebDevX/achek-python/issues](https://github.com/CalebDevX/achek-python/issues)

## License

MIT — see [LICENSE](LICENSE)
