etoneya-api 0.1.0

Python client library for Etoneya Subscription Management API

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

pip install etoneya-api

Or install from source:

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

Quick Start

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

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

# 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

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

Ban/Unban User

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

# Unban user
unbanned_user = client.unban_user(1)

Delete User

client.delete_user(1)

Device Management

Get Devices

# 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

client.delete_device(1)

IP Ban Management

Create IP Ban

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

Check IP Ban

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

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

Delete IP Ban

# By ID
client.delete_ip_ban(1)

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

System Operations

Health Check

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

Update Subscriptions (Webhook)

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

Error Handling

The library provides specific exceptions for different error cases:

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

@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

@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

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

Configuration

Timeout

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

Development

Install development dependencies

pip install -e ".[dev]"

Run tests

pytest

Format code

black etoneya/

Type checking

mypy etoneya/

License

MIT License - see LICENSE file for details.

Author

nloverx

• Telegram: t.me/nloverx
• Email: [e-mail]

Contributing

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