Metadata-Version: 2.4
Name: aioshad
Version: 1.0.0
Summary: Advanced asynchronous Python client/userbot library for a Shad account
Author: aioshad contributors
License: MIT
Keywords: shad,messenger,userbot,asyncio,python,account-client
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Framework :: AsyncIO
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.27.0
Requires-Dist: h2>=4.0.0
Requires-Dist: cryptography>=42.0.0
Requires-Dist: Pillow>=10.0.0
Dynamic: license-file
Dynamic: requires-python

# aioshad 1.0.0

کتابخانهٔ asynchronous برای ساخت **custom client / self account** روی شاد. این پروژه یک Bot API جداگانه نیست؛ session به حسابی تعلق دارد که با آن login شده است.

> نکتهٔ compatibility: بخش transport و payloadهای شاد بر پایهٔ ساختار موجود در پروژهٔ `shadism` ارائه‌شده و APIهای مشاهده‌شدهٔ وب شاد ساخته شده‌اند. چون endpointها و payloadهای رسمی شاد عمومی و ثابت نیستند، قابلیت‌هایی که payload دقیق‌شان مستند نیستند به‌صورت `client.invoke()` در دسترس‌اند و حدس زده نشده‌اند.

## نصب

```bash
pip install -e .
```

## ورود اکانت

```python
import asyncio
from aioshad import Client

app = Client("0937xxxxxxxx", session_directory="./sessions")

async def main():
    await app.start()

asyncio.run(main())
```

در اجرای اول کد OTP از شما درخواست می‌شود و session ذخیره می‌شود.

برای رمزنگاری session:

```bash
export AIOSHAD_SESSION_KEY="یک-راز-32-بایتی-یا-عبارت-قوی"
```

## پیام و handler

```python
from aioshad import Client, filters

app = Client("0937xxxxxxxx", session_directory="./sessions")

@app.on_message(filters.command("ping"))
async def ping(message):
    await message.reply("pong")

@app.on_message(filters.private & filters.text)
async def private_text(message):
    print(message.text)

asyncio.run(app.start())
```

handlerهای sync و async هر دو پشتیبانی می‌شوند.

## امکانات حساب

### تایم کنار نام

این قابلیت واقعاً `updateProfile` را روی **همان حساب session** اجرا می‌کند:

```python
from aioshad import Client, TimeName

app = Client("0937xxxxxxxx", session_directory="./sessions")

async def main():
    await app.connect()
    await app.presence.start_time_name(
        TimeName(
            format="⏰ {time}",
            timezone="Asia/Tehran",
            interval=60,
        )
    )
    await app.start_in_background()
    await app.run_until_disconnected()

asyncio.run(main())
```

Placeholders: `{time}`, `{time_12}`, `{date}`, `{day}`, `{timestamp}`.

### پروفایل

```python
await app.profile.set_name("AioShad")
await app.profile.set_last_name("Client")
await app.profile.set_bio("Powered by aioshad")
```

### پاسخ خودکار حساب

```python
app.autoreply.add("سلام", "سلام، در خدمتم.")
app.autoreply.set_default("پیامت دریافت شد.")
await app.autoreply.enable()
```

### زمان‌بندی داخلی

```python
async def task():
    await app.send_message("g0...", "پیام زمان‌بندی‌شده")

app.scheduler.every(60, task)
```

حداقل فاصلهٔ scheduler پنج ثانیه است.

## APIهای اصلی

- `send_message`, `edit_message`, `delete_message(s)`
- `reply`, `reply_photo`, `reply_file`
- `upload_file`, `send_photo`, `send_file`
- `get_me`, `get_user_info`
- `get_chats`, `get_chat_info`, `get_chat_info_by_username`
- `get_messages`, `get_chat_history`
- `get_chats_updates`, `get_messages_updates`
- login/session/device management
- voice chat methods موجود در پروتکل پایه
- `block_user` / `unblock_user`
- فیلترهای command/regex/private/group/channel/reply/edited/author/chat/media/text
- `&`, `|`, `~` برای ترکیب فیلترها
- host failover
- HTTP/2
- retry/backoff
- local rate limiting
- duplicate-update suppression
- encrypted session storage
- graceful shutdown

## RPC خام

برای متدهای پروتکل که هنوز payload قطعی آن‌ها مشخص نیست:

```python
result = await app.invoke(
    "METHOD_NAME",
    some_parameter="value",
)
```

این قسمت عمداً generic است تا بدون جعل payload جدید، آدرس هر API واقعی را بتوانید به کتابخانه اضافه کنید.

## معماری

```text
Client
├── Methods / RPC
├── Transport (HTTP/2 + failover + rate limit)
├── Session (optional AES-GCM storage)
├── Dispatcher / Filters
├── ProfileManager
├── PresenceManager / TimeName
├── AutoResponder
└── Scheduler
```

## وضعیت تست

قبل از release این پروژه تست‌های unit برای session encryption، filters، rate limiting و models دارد. تست زندهٔ شبکه به‌صورت پیش‌فرض اجرا نمی‌شود، چون نیازمند یک حساب شاد و endpointهای فعال است.
