🚀 aiosubgram

PyPI - Version License

aiosubgram — это современная асинхронная Python библиотека для взаимодействия с API сервиса монетизации subgram.org.

Библиотека полностью покрывает функционал API, поддерживает строгую типизацию (Pydantic) и предоставляет готовые инструменты для легкой интеграции с aiogram 3.x.

✨ Особенности

⚡ Полностью асинхронная (на базе aiohttp).
🛡 Строгая типизация: Все ответы API валидируются через Pydantic модели.
🤖 Aiogram 3 Integration: Встроенные Middleware и клавиатуры для реализации ОП (Обязательной Подписки).
📦 Полное покрытие API: Поддержка всех методов для Рекламодателей, Владельцев ботов (Publisher) и Общей статистики.
🛠 Удобная обработка ошибок: Понятные исключения для отладки.

📥 Установка

Установите библиотеку через pip:

pip install aiosubgram

🚀 Быстрый старт

Для начала работы вам понадобятся ключи от Subgram. Их можно найти в личном кабинете.

Secret Key: Для управления заказами и ботами.
API Token: Для просмотра статистики и баланса.
API Key (Bot): Для проверки подписок конкретного бота.

Базовый пример (получение баланса)

import asyncio
from aiosubgram import SubgramClient

async def main():
    # Инициализация клиента
    client = SubgramClient(
        api_token="ВАШ_API_TOKEN"
    )

    async with client:
        balance = await client.get_balance()
        print(f"Текущий баланс: {balance.balance}$")

        for bot in balance.bots_info:
            print(f"Бот {bot.bot_username}: {bot.revenue}$")

if __name__ == "__main__":
    asyncio.run(main())

🤖 Интеграция с Aiogram 3

Библиотека предоставляет готовый Middleware, который автоматически проверяет подписку пользователя на спонсоров перед обработкой любого сообщения.

Пример бота с ОП (Обязательной Подпиской)

import asyncio
from aiogram import Bot, Dispatcher, F
from aiogram.types import Message, CallbackQuery
from aiosubgram import SubgramClient
from aiosubgram.utils.middleware import OPMiddleware

# Конфигурация
BOT_TOKEN = "YOUR_TELEGRAM_BOT_TOKEN"
SUBGRAM_API_KEY = "YOUR_SUBGRAM_BOT_API_KEY"

bot = Bot(token=BOT_TOKEN)
dp = Dispatcher()

# Инициализация клиента Subgram
subgram = SubgramClient(api_key=SUBGRAM_API_KEY)

# Подключение Middleware
dp.message.middleware(
    OPMiddleware(
        client=subgram,
        max_sponsors=3, # Максимум каналов для подписки
        sub_text="🔒 <b>Доступ закрыт!</b>\nПодпишитесь на спонсоров:",
        done_button_text="✅ Я подписался"
    )
)

@dp.message()
async def echo_handler(message: Message):
    # Этот код выполнится только если пользователь подписан
    await message.answer("🎉 Вы прошли проверку! Бот доступен.")

# Обработчик кнопки "Я подписался"
@dp.callback_query(F.data == "subgram-done")
async def check_sub(callback: CallbackQuery):
    response = await subgram.get_sponsors(
        chat_id=callback.message.chat.id,
        user_id=callback.from_user.id
    )

    if response.status == "ok":
        await callback.message.delete()
        await callback.message.answer("✅ Спасибо! Доступ открыт.")
    else:
        await callback.answer("❌ Вы подписались не на всех!", show_alert=True)

async def main():
    async with subgram:
        await dp.start_polling(bot)

if __name__ == "__main__":
    asyncio.run(main())

📚 Функционал

📢 Для Владельцев Ботов (Publisher)

Методы для монетизации вашего бота:

get_sponsors(...) — Получить список каналов для подписки (ОП).
add_bot(...) — Добавить нового бота в систему.
update(...) — Обновить настройки бота.
get_bot_info(...) — Получить информацию о боте.
get_user_info(...) — Получить демографию пользователя.

# Пример получения спонсоров вручную
sponsors = await client.get_sponsors(chat_id=123, user_id=456)
for sponsor in sponsors.sponsors:
    print(f"Нужна подписка на: {sponsor.link}")

🎯 Для Рекламодателей (Advertiser)

Управление рекламными кампаниями:

create_order(...) — Создать заказ (подписчики в канал/бот).
update_order(...) — Изменить параметры заказа (статус, цена).
get_order_info(...) — Получить статус выполнения.

# Создание заказа на подписчиков
order = await client.create_order(
    link="https://t.me/my_channel",
    ads_type="channel",
    quantity_all=1000,
    price=0.5
)
print(f"Заказ создан: ID {order.response.order_id}")

📊 Общие методы

get_balance() — Баланс аккаунта.
get_statistic(...) — Детальная статистика доходов/расходов.
toggle_exclusion(...) — Блокировка нежелательных ботов/каналов.

⚙️ Требования

Python 3.9+
aiohttp
pydantic >= 2.0
aiogram >= 3.x (опционально, для использования utils)

🤝 Contributing

Баги и предложения можно отправлять в Issues. Pull Request'ы приветствуются!

📄 Лицензия

Подробнее см. в файле LICENSE.