Metadata-Version: 2.4
Name: etoneya-api
Version: 0.1.0
Summary: Python client library for Etoneya Subscription Management API
Author-email: nloverx <owner@nloverx.best>
License: MIT
Project-URL: Homepage, https://github.com/etoneya/etoneya-api
Project-URL: Documentation, https://github.com/etoneya/etoneya-api#readme
Project-URL: Repository, https://github.com/etoneya/etoneya-api
Project-URL: Issues, https://github.com/etoneya/etoneya-api/issues
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: pytest-mock>=3.10.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: types-requests>=2.28.0; extra == "dev"
Dynamic: license-file

# Etoneya API Client

Python client library for interacting with the Etoneya Subscription Management API.

## Features

- 🔐 Full authentication support
- 👥 User management (CRUD operations)
- 📱 Device management
- 🚫 IP ban management
- 🔄 Subscription updates via webhook
- ⚡ Type-safe with dataclasses
- 🛡️ Comprehensive error handling
- 📦 Zero dependencies (except `requests`)

## Installation

```bash
pip install etoneya-api
```

Or install from source:

```bash
git clone https://github.com/etoneya/etoneya-api.git
cd etoneya-api
pip install -e .
```

## Quick Start

```python
from etoneya import EtoneyaClient

# Initialize client
client = EtoneyaClient(
    base_url="https://api.example.com",
    auth_token="your_auth_token_here"
)

# Create a new user
user = client.create_user(
    tg_id=123456789,
    type_sub="premium",
    udid="unique-device-id",
    limit_devices=3,
    status="user"
)

print(f"Created user: {user.id}")

# Get user by Telegram ID
user = client.get_user_by_telegram(123456789)
print(f"User status: {user.status}")

# Ban a user
banned_user = client.ban_user(user.id, reason="Violation of terms")

# Get all user devices
devices = client.get_user_devices(user.udid)
print(f"User has {len(devices)} devices")

# Ban an IP address
ip_ban = client.create_ip_ban("192.168.1.1", reason="Suspicious activity")

# Check if IP is banned
ban_status = client.check_ip_ban("192.168.1.1")
print(f"IP banned: {ban_status['is_banned']}")
```

## User Management

### Create User

```python
user = client.create_user(
    tg_id=123456789,
    type_sub="premium",
    udid="unique-device-id",
    limit_devices=3,
    reason="",
    is_banned=False,
    is_active=True,
    allowed_useragents=["volunteer-agent-1"],
    status="volunteer"  # "user" or "volunteer"
)
```

### Get Users

```python
# Get by ID
user = client.get_user(1)

# Get by Telegram ID
user = client.get_user_by_telegram(123456789)

# Get all users
all_users = client.get_all_users()

# Get active users
active_users = client.get_active_users()

# Get banned users
banned_users = client.get_banned_users()
```

### Update User

```python
updated_user = client.update_user(
    user_id=1,
    limit_devices=5,
    is_active=True
)
```

### Ban/Unban User

```python
# Ban user
banned_user = client.ban_user(1, reason="Spam")

# Unban user
unbanned_user = client.unban_user(1)
```

### Delete User

```python
client.delete_user(1)
```

## Device Management

### Get Devices

```python
# Get device by ID
device = client.get_device(1)

# Get device by hardware ID
device = client.get_device_by_hwid("hwid-123")

# Get all devices for a user
devices = client.get_user_devices("unique-device-id")
```

### Delete Device

```python
client.delete_device(1)
```

## IP Ban Management

### Create IP Ban

```python
ban = client.create_ip_ban("192.168.1.1", reason="Malicious activity")
```

### Check IP Ban

```python
status = client.check_ip_ban("192.168.1.1")
print(status["is_banned"])  # True/False
print(status["ban_info"])   # Ban details if banned
```

### Get All Bans

```python
bans = client.get_all_bans()
for ban in bans:
    print(f"{ban.ip}: {ban.reason}")
```

### Delete IP Ban

```python
# By ID
client.delete_ip_ban(1)

# By IP address
client.delete_ip_ban_by_address("192.168.1.1")
```

## System Operations

### Health Check

```python
health = client.health_check()
print(health["status"])  # "healthy"
```

### Update Subscriptions (Webhook)

```python
result = client.update_subscriptions(webhook_token="your_webhook_token")
```

## Error Handling

The library provides specific exceptions for different error cases:

```python
from etoneya import (
    EtoneyaAPIError,
    AuthenticationError,
    NotFoundError,
    ValidationError,
    RateLimitError
)

try:
    user = client.get_user(999)
except NotFoundError as e:
    print(f"User not found: {e.message}")
    print(f"Status code: {e.status_code}")
except AuthenticationError as e:
    print(f"Authentication failed: {e.message}")
except ValidationError as e:
    print(f"Validation error: {e.response}")
except RateLimitError as e:
    print("Rate limit exceeded, please retry later")
except EtoneyaAPIError as e:
    print(f"API error: {e.message}")
```

## Models

### User

```python
@dataclass
class User:
    id: int
    tg_id: int
    type_sub: str
    udid: str
    limit_devices: int
    reason: str
    is_banned: bool
    is_active: bool
    allowed_useragents: List[str]
    status: str  # "user" or "volunteer"
```

### Device

```python
@dataclass
class Device:
    id: int
    hwid: str
    udid: str
    useragent: str
    os_type: str
    os_ver: int
    model: str
    app_version: str
    ip: str
```

### BannedIP

```python
@dataclass
class BannedIP:
    id: int
    ip: str
    reason: str
```

## Configuration

### Timeout

```python
client = EtoneyaClient(
    base_url="https://api.example.com",
    auth_token="token",
    timeout=60  # seconds
)
```

## Development

### Install development dependencies

```bash
pip install -e ".[dev]"
```

### Run tests

```bash
pytest
```

### Format code

```bash
black etoneya/
```

### Type checking

```bash
mypy etoneya/
```

## License

MIT License - see LICENSE file for details.

## Author

**nloverx**
- Telegram: [t.me/nloverx](https://t.me/nloverx)
- Email: owner@nloverx.best

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.
