Metadata-Version: 2.4
Name: telemaster-lib
Version: 1.0.2
Summary: Professional Telegram account management library built on Telethon — structured API with Result objects.
Author-email: RoQ9 <contact@telemaster.dev>
License: MIT
Project-URL: Homepage, https://github.com/OmarMoh12/telemaster
Project-URL: Repository, https://github.com/OmarMoh12/telemaster
Project-URL: Issues, https://github.com/OmarMoh12/telemaster/issues
Keywords: telegram,tّelethon,telegram-api,telegram-client,account-manager,async,telegram-library
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Framework :: AsyncIO
Classifier: Typing :: Typed
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: telethon>=1.43.1
Requires-Dist: cryptg>=0.4.0
Provides-Extra: fast
Requires-Dist: cryptg>=0.4.0; extra == "fast"
Requires-Dist: uvloop>=0.19.0; sys_platform != "win32" and extra == "fast"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-asyncio; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Dynamic: license-file

<p align="center">
  <img src="https://img.shields.io/badge/python-3.10%2B-blue?style=for-the-badge&logo=python&logoColor=white" alt="Python 3.10+">
  <img src="https://img.shields.io/badge/license-MIT-green?style=for-the-badge" alt="MIT License">
  <img src="https://img.shields.io/badge/telethon-powered-blue?style=for-the-badge&logo=telegram&logoColor=white" alt="Telethon">
  <img src="https://img.shields.io/badge/async-await-purple?style=for-the-badge" alt="Async/Await">
</p>

<h1 align="center">📡 TeleMaster</h1>

<p align="center">
  <strong>Professional Telegram account management library — 67 methods, zero print(), zero input()</strong>
</p>

<p align="center">
  <a href="#-installation">Installation</a> •
  <a href="#-quick-start">Quick Start</a> •
  <a href="#-features">Features</a> •
  <a href="#-api-reference">API</a> •
  <a href="#-examples">Examples</a> •
  <a href="#العربية">العربية</a>
</p>

---

## ✨ Why TeleMaster?

| Feature | Raw Telethon | **TeleMaster** |
|---------|-------------|---------------------|
| Error handling | Manual try/except everywhere | ✅ Built-in, returns `Result` |
| Login flow | Monolithic, requires `input()` | ✅ Step-by-step, UI-agnostic |
| Output | `print()` mixed with logic | ✅ Zero prints, pure data |
| API surface | Low-level RPC calls | ✅ 67 high-level methods |
| Speed | Standard crypto | ✅ `cryptg` accelerated |
| Type hints | Partial | ✅ Full typing, PEP 561 |

## 📦 Installation

```bash
# From PyPI (when published)
pip install telemaster

# From GitHub
pip install git+https://github.com/OmarMoh12/telemaster.git

# From source
git clone https://github.com/OmarMoh12/telemaster.git
cd telemaster
pip install -e .

# With speed optimizations
pip install -e ".[fast]"
```

## 🚀 Quick Start

```python
import asyncio
from telemaster import TeleMaster

async def main():
    tm = TeleMaster(
        phone="+1234567890",
        api_id=12345,
        api_hash="your_api_hash",
    )

    # Connect
    await tm.connect()

    # Login (step-by-step — no input() needed!)
    result = await tm.send_code()
    code = "12345"  # Get this from your UI, bot, webhook, etc.
    result = await tm.verify_code(code)

    if result.error_type == "2FA_REQUIRED":
        result = await tm.verify_2fa("your_password")

    # Send a message
    result = await tm.send_message("me", "Hello! 🚀")
    if result:
        print(f"Sent! Message ID: {result.data.id}")
    else:
        print(f"Error: {result.error}")

    await tm.disconnect()

asyncio.run(main())
```

## 🔑 The `Result` Pattern

Every method returns a `Result` object — **never raises exceptions**:

```python
from telemaster import Result

result = await tm.send_message("me", "Hello!")

if result:                          # bool check
    msg = result.data               # The actual data
    print(msg.id, msg.text)
else:
    print(result.error)             # Human-readable error
    print(result.error_type)        # Error class name
    print(result.wait_seconds)      # For flood/slowmode errors
```

## 📋 Features

### 🔐 Authentication
```python
await tm.connect()                         # Connect to servers
await tm.is_authorized()                   # Check session
await tm.send_code()                       # Send SMS code
await tm.verify_code("12345")              # Verify code
await tm.verify_2fa("password")            # 2FA password
await tm.logout()                          # Invalidate session
await tm.disconnect()                      # Close connection
```

### 💬 Messages
```python
await tm.send_message(target, "Hello!")    # Send text
await tm.send_private("@user", "Hi!")      # Send private
await tm.edit_message(target, msg_id, "New text")
await tm.delete_messages(target, [1, 2, 3])
await tm.read_messages(target, limit=20)
await tm.read_private_messages("@user")
await tm.read_group_messages("@group")
await tm.read_channel_messages("@channel")
await tm.forward_message(from_chat, msg_id, to_chat)
await tm.get_dialogs(limit=50)
await tm.search_messages(target, "query")
await tm.mark_as_read(target)
```

### 📷 Media
```python
await tm.send_photo(target, "photo.jpg", caption="📸")
await tm.send_video(target, "video.mp4", caption="🎬")
await tm.send_file(target, "doc.pdf", caption="📄")
await tm.send_voice(target, "voice.ogg")
await tm.send_album(target, ["img1.jpg", "img2.jpg"])
await tm.download_media(message)
```

### 👤 Profile
```python
await tm.get_account_info()                # Full profile info
await tm.update_first_name("John")
await tm.update_last_name("Doe")
await tm.update_bio("Hello world!")
await tm.update_username("johndoe")
await tm.set_profile_photo("photo.jpg")
await tm.delete_profile_photo()
await tm.delete_all_profile_photos()
await tm.get_profile_photos("@user")
```

### 👥 Groups & Channels
```python
await tm.join("@channel")
await tm.leave("@channel")
await tm.create_group("My Group", about="Description")
await tm.create_channel("My Channel", about="Description")
await tm.create_basic_group("Group", users=["@user1"])
await tm.update_group_title(target, "New Title")
await tm.update_group_about(target, "New Description")
await tm.update_group_photo(target, "photo.jpg")
await tm.update_group_username(target, "new_username")
await tm.get_participants(target, limit=100)
await tm.add_member(target, "@user")
await tm.kick_member(target, "@user")
await tm.get_invite_link(target)
```

### 📇 Contacts
```python
await tm.add_contact("+1234567890", "John", "Doe")
await tm.add_contact_by_username("@user", "John")
await tm.remove_contact(user_id)
await tm.get_contacts()
await tm.search_contacts("John")
```

### 🔒 Security (2FA)
```python
await tm.enable_2fa("new_password", hint="my hint")
await tm.change_2fa("old_pass", "new_pass")
await tm.disable_2fa("current_password")
await tm.get_2fa_status()
```

### 📖 Stories
```python
await tm.post_story("photo.jpg", caption="My story!")
await tm.delete_story(story_id)
```

### ❤️ Interactions
```python
await tm.send_reaction(target, msg_id, "❤")
await tm.remove_reaction(target, msg_id)
await tm.send_custom_reaction(target, msg_id, emoji_id)
await tm.click_button(target, msg_id, button_text="Click me")
await tm.get_buttons(target, msg_id)
```

### 💾 Sessions
```python
TeleMaster.list_sessions("./")        # Find .session files
TeleMaster.get_session_info("file.session")
TeleMaster.delete_session("file.session")
```

## 📂 Project Structure

```
telemaster/
├── telemaster/          # 📦 Core library
│   ├── __init__.py            # Public exports
│   ├── client.py              # TeleMaster facade (67 methods)
│   ├── models.py              # Result, AccountInfo, MessageInfo, etc.
│   ├── auth.py                # Step-by-step authentication
│   ├── messages.py            # Message operations
│   ├── media.py               # File uploads with captions
│   ├── profile.py             # Profile management
│   ├── groups.py              # Groups & channels
│   ├── contacts.py            # Contact management
│   ├── security.py            # 2FA management
│   ├── stories.py             # Stories
│   ├── interactions.py        # Reactions & buttons
│   ├── sessions.py            # Session file management
│   └── py.typed               # PEP 561 marker
├── examples/                  # 📝 Usage examples
│   ├── cli_login.py
│   ├── send_message.py
│   └── manage_profile.py
├── docs/                      # 📖 Documentation website
├── pyproject.toml             # Package configuration
├── requirements.txt
├── LICENSE                    # MIT
├── README.md
└── .gitignore
```

## ⚡ Performance

TeleMaster uses **`cryptg`** — a C-extension that accelerates Telethon's encryption by **~5x**:

```bash
pip install telemaster[fast]
```

On Linux, `uvloop` is also included for faster async I/O.

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch: `git checkout -b feature/amazing`
3. Commit changes: `git commit -m "Add amazing feature"`
4. Push: `git push origin feature/amazing`
5. Open a Pull Request

## 📄 License

MIT License — see [LICENSE](LICENSE) for details.

---

<div dir="rtl">

## العربية

### 📡 مدير تيليجرام

مكتبة بايثون احترافية لإدارة حساب تيليجرام بالكامل — **67 دالة** بدون أي `print()` أو `input()`.

### المميزات:
- 🔐 تسجيل دخول على خطوات (مناسب للبوتات والمواقع)
- 💬 إرسال/تعديل/حذف/قراءة رسائل
- 📷 رفع صور وفيديوهات وملفات مع كابشن
- 👤 إدارة الملف الشخصي (اسم، يوزر، بايو، صورة)
- 🔒 إدارة كلمة المرور الثنائية (2FA)
- 👥 إنشاء وإدارة مجموعات وقنوات
- 📖 نشر قصص
- ❤️ تفاعلات وضغط أزرار
- 💾 إدارة ملفات الجلسات

### التثبيت:
```bash
pip install git+https://github.com/OmarMoh12/telemaster.git
```

### مثال سريع:
```python
from telemaster import TeleMaster

tm = TeleMaster(phone="+970...", api_id=123, api_hash="abc")
await tm.connect()
await tm.send_code()              # إرسال كود — بدون input!
await tm.verify_code("12345")     # تحقق من الكود
await tm.send_message("me", "مرحبا! 🚀")
```

</div>

---

<p align="center">
  Made with ❤️ by <strong>RoQ9</strong>
</p>
