# HS Mail Python SDK

[![PyPI version](https://img.shields.io/pypi/v/hsmail-sdk)](https://pypi.org/project/hsmail-sdk)
[![Python](https://img.shields.io/badge/Python-%3E%3D3.8-blue)](https://www.python.org)
[![License: MIT](https://img.shields.io/badge/License-MIT-green)](LICENSE)

Official Python SDK for the **HS Mail API**. Manage orders, read mailboxes, check live accounts, and generate 2FA codes.

---

## Installation

```bash
pip install hsmail-sdk
```

---

## Quick Start

```python
from hsmail import HsMailClient

client = HsMailClient(api_key="YOUR_API_KEY")

# Ping
status = client.ping()
print("IP:", status["ip"])

# Profile
profile = client.get_profile()
print(f"Balance: {profile['balance']} BDT")

# Products
categories = client.products.list()

# Order
order = client.orders.create("product-uuid", quantity=1)
print("Order ID:", order["orderId"])

# 2FA
result = client.tools.generate_2fa("BASE32_SECRET")
print(f"Code: {result['code']}  ({result['timeRemaining']}s)")
```

---

## Authentication

Get your API key from the [HS Mail Dashboard](https://hsmail.shop/dashboard/settings).

```python
client = HsMailClient(
    api_key="hs_live_xxxxxxxxxxxxxxx",
    base_url="https://api.hsmail.shop",  # optional
    timeout=30,                           # seconds, optional
)
```

---

## API Reference

### Profile & Status

```python
client.ping()         # { status, message, ip, timestamp }
client.get_profile()  # { id, name, email, balance, rankLevel, ... }
```

### Products

```python
client.products.list()            # All categories + products
client.products.get("uuid")       # Single product by UUID
```

### Orders

```python
client.orders.create("uuid", quantity=1)
client.orders.get("ORDER_ID")
client.orders.messages("ORDER_ID")
client.orders.send_message("ORDER_ID", message="Hello")
client.orders.reopen("ORDER_ID")
```

**Order statuses:** `PENDING` · `PROCESSING` · `COMPLETED` · `DELIVERED` · `REFUNDED`

### Mailbox

```python
# Outlook
client.mailbox.read_outlook(email, refresh_token, client_id)
client.mailbox.refresh_outlook_token(client_id, refresh_token)
client.mailbox.check_outlook(email, refresh_token, client_id)

# Gmail (requires GMAIL subscription)
client.mailbox.read_gmail(email, order_id)
client.mailbox.check_gmail(email)

# Facebook (requires FB subscription)
client.mailbox.check_facebook_bulk(["email:pass", ...])
client.mailbox.check_facebook("FB_USER_ID")

# Instagram (requires IG subscription)
client.mailbox.check_instagram("username")

# Hotmail Creator
client.mailbox.create_hotmail_order(["a@hotmail.com", ...], "USER_ONLY")
```

### Tools

```python
result = client.tools.generate_2fa("JBSWY3DPEHPK3PXP")
# { code: "123456", timeRemaining: 17 }
```

---

## Error Handling

```python
from hsmail import (
    HsMailError,
    InsufficientBalanceError,
    RateLimitError,
    AuthenticationError,
    NotFoundError,
    ValidationError,
)

try:
    order = client.orders.create("product-uuid")
except InsufficientBalanceError:
    print("Top up at https://hsmail.shop")
except RateLimitError:
    import time; time.sleep(60)  # Retry after 1 minute
except AuthenticationError as e:
    print(f"Auth problem: {e.code}")
except HsMailError as e:
    print(f"[{e.code}] {e} (HTTP {e.http_status})")
```

| Exception | When raised |
|---|---|
| `AuthenticationError` | Invalid/expired API key, banned account |
| `RateLimitError` | >100 requests/minute |
| `NotFoundError` | Resource not found |
| `InsufficientBalanceError` | Not enough BDT balance |
| `ValidationError` | Bad input, out of stock, closed order |
| `HsMailError` | All other errors |

---

## Publishing to PyPI

```bash
# Install build tools
pip install build twine

# Build
python -m build

# Upload to PyPI
twine upload dist/*
```

---

## License

MIT © [HS Mail Team](https://hsmail.shop)
