Metadata-Version: 2.4
Name: janbad
Version: 0.1.0
Summary: مكتبة بايثون لإرسال وإدارة الإيموجيات المميزة (Custom Emoji) عبر Telegram Bot API
Author: ت
License: MIT
Project-URL: Homepage, https://github.com/yourusername/janbad
Project-URL: Repository, https://github.com/yourusername/janbad
Keywords: telegram,bot,custom-emoji,premium-emoji,aiogram,pyrogram,telethon
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Communications :: Chat
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28
Requires-Dist: aiohttp>=3.8
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
Dynamic: license-file

# JanBad

مكتبة بايثون بسيطة للتعامل مع **الإيموجيات المميزة (Custom Emoji)** في تيليجرام عن طريق `custom_emoji_id`، مبنية مباشرة فوق Telegram Bot API، ومستقلة عن أي فريمورك بوت معيّن.

```python
from janbad import JanBad

jan = JanBad("BOT_TOKEN")

jan.send_message(
    chat_id,
    "هذا إيموجي مميز 🙂",
    custom_emoji_id="5368324170671202286",
)
```

## التثبيت

```bash
pip install janbad
```

## إنشاء Client

المكتبة توفر نسختين:

- `JanBad` — واجهة متزامنة (sync)، تستخدم `requests`.
- `AsyncJanBad` — واجهة غير متزامنة (async)، تستخدم `aiohttp`.

```python
from janbad import JanBad, AsyncJanBad

jan = JanBad("BOT_TOKEN")
jan_async = AsyncJanBad("BOT_TOKEN")
```

عند استخدام `AsyncJanBad` يفضّل إغلاق الجلسة عند الانتهاء:

```python
await jan_async.close()
```

## إرسال إيموجي مميز واحد

```python
jan.send_custom_emoji(
    chat_id=123456789,
    custom_emoji_id="5368324170671202286",
)
```

هذا يرسل رسالة نصها placeholder افتراضي (🙂) مع entity من نوع `custom_emoji` تشير إلى الـ ID المطلوب. تقدر تغيّر الـ placeholder:

```python
jan.send_custom_emoji(
    chat_id=123456789,
    custom_emoji_id="5368324170671202286",
    placeholder="🔥",
)
```

## دمج إيموجي مميز داخل نص عادي

```python
jan.send_message(
    chat_id=123456789,
    text="مرحبا 🔥 بالجميع",
    custom_emoji_id="5368324170671202286",
    placeholder="🔥",
)
```

المكتبة تبحث عن `placeholder` داخل `text`، وتحسب `offset` و`length` بصيغة UTF-16 كما يتطلب Telegram Bot API، وتبني `MessageEntity` تلقائيًا.

## أكثر من إيموجي مميز في نفس الرسالة

```python
jan.send_message(
    chat_id=123456789,
    text="🔥 مرحبا ❤️",
    custom_emojis={
        "🔥": "5368324170671202286",
        "❤️": "5368324170671202287",
    },
)
```

كل مفتاح في `custom_emojis` هو النص/الرمز اللي يمثّل الإيموجي داخل الرسالة، والقيمة هي الـ `custom_emoji_id` المقابل له. تقدر تستخدم نفس الرمز أكثر من مرة وبتنطبق كل الحالات.

## القنوات والمجموعات والخاص

الدوال نفسها تشتغل بأي نوع chat (خاص، مجموعة، سوبر مجموعة، قناة) طالما البوت عضو فيها وعنده صلاحية الإرسال:

```python
jan.send_message(chat_id=123456789, text="🙂", custom_emoji_id="...")       # خاص
jan.send_message(chat_id=-1001234567890, text="🙂", custom_emoji_id="...")  # مجموعة/قناة
jan.send_message(chat_id="@my_channel", text="🙂", custom_emoji_id="...")   # يوزرنيم قناة
```

## الكابتشن (صور وفيديوهات)

```python
jan.send_photo(
    chat_id=123456789,
    photo="https://example.com/image.jpg",
    caption="صورة 🔥 حلوة",
    custom_emoji_id="5368324170671202286",
    placeholder="🔥",
)

jan.send_video(
    chat_id=123456789,
    video="https://example.com/video.mp4",
    caption="فيديو 🔥",
    custom_emoji_id="5368324170671202286",
    placeholder="🔥",
)
```

## التحقق من صلاحية الـ Custom Emoji ID

المكتبة تفرّق بين نوعين من التحقق:

1. **تحقق شكلي (offline)**: يتم تلقائيًا في كل استدعاء — يتأكد أن الـ ID نص/رقم غير فارغ ويحتوي أرقام فقط. إذا فشل، ترمي `InvalidCustomEmojiID`.
2. **تحقق فعلي من تيليجرام (online)**: عبر `verify_custom_emoji_id`، والتي تستدعي `getCustomEmojiStickers` من Bot API للتأكد أن الـ ID موجود فعلاً:

```python
sticker = jan.verify_custom_emoji_id("5368324170671202286")
```

إذا رجع تيليجرام نتيجة فارغة، ترمي المكتبة `CustomEmojiNotFound`.

> **ملاحظة مهمة**: التحقق الشكلي وحده لا يضمن أن الـ ID فعلاً custom emoji موجود وصالح — رقم صحيح الصيغة قد لا يقابل أي إيموجي حقيقي. للتأكد الفعلي استخدم `verify_custom_emoji_id` قبل الإرسال في الحالات الحساسة.

## الأخطاء (Exceptions)

| الاستثناء | يحدث متى |
|---|---|
| `JanBadError` | الأساس لكل استثناءات المكتبة |
| `InvalidCustomEmojiID` | الـ ID فارغ أو غير رقمي أو من نوع غير مدعوم |
| `CustomEmojiNotFound` | الـ ID لا يقابل أي custom emoji فعلي عند تيليجرام |
| `InvalidChatID` | الـ chat_id فارغ أو بصيغة غير صحيحة |
| `TelegramAPIError` | تيليجرام رجّع خطأ (صلاحيات، توكن، حظر، إلخ) — يحتوي `error_code` و`description` |

```python
from janbad import JanBadError, InvalidCustomEmojiID, TelegramAPIError

try:
    jan.send_custom_emoji(chat_id, custom_emoji_id)
except InvalidCustomEmojiID as e:
    print("ID غير صالح:", e)
except TelegramAPIError as e:
    print("خطأ من تيليجرام:", e.error_code, e.description)
except JanBadError as e:
    print("خطأ عام بالمكتبة:", e)
```

## القيود المهمة (اقرأها قبل الاستخدام)

- المكتبة تبني `MessageEntity` من نوع `custom_emoji` كما هو موثّق رسميًا في Telegram Bot API، ولا تخترع أي خاصية غير موجودة.
- عرض الإيموجي المميز فعليًا للمستخدم النهائي (بدل الشكل الاحتياطي/placeholder) يعتمد على سياسات تيليجرام من جهة العميل المستقبل، وهذا خارج عن تحكم المكتبة.
- التحقق الشكلي (`InvalidCustomEmojiID`) يتأكد فقط من صيغة الـ ID، وليس دليلًا على وجوده الفعلي؛ استخدم `verify_custom_emoji_id` للتأكد الحقيقي.
- أي قيود صلاحيات (مثل الحاجة لأن يكون البوت أدمن في قناة/مجموعة، أو حظر إرسال معين) تُرجعها تيليجرام نفسها كـ `TelegramAPIError`، ولا تتحايل المكتبة عليها.
- راجع دائمًا [توثيق Telegram Bot API الرسمي](https://core.telegram.org/bots/api#messageentity) لأي تحديثات مستقبلية على هذه الخاصية.

## المتطلبات

- Python 3.9+
- `requests` (للواجهة المتزامنة)
- `aiohttp` (للواجهة غير المتزامنة)

## أمثلة مع فريموركات أخرى

### aiogram

```python
from aiogram import Bot, Dispatcher
from aiogram.filters import Command
from aiogram.types import Message
from janbad import AsyncJanBad

jan = AsyncJanBad("BOT_TOKEN")

@dp.message(Command("emoji"))
async def send_emoji(message: Message):
    await jan.send_custom_emoji(message.chat.id, "5368324170671202286")
```

### python-telegram-bot

```python
from telegram.ext import Application, CommandHandler
from janbad import JanBad

jan = JanBad("BOT_TOKEN")

async def emoji_command(update, context):
    jan.send_custom_emoji(update.effective_chat.id, "5368324170671202286")
```

أمثلة كاملة إضافية موجودة داخل مجلد `examples/` (`aiogram_example.py`, `ptb_example.py`, `basic_usage.py`).

## الترخيص

MIT
