hudle-sdk 0.1.1

Python SDK для Dev API и Bot API Hudle

hudle-sdk

Python SDK для Dev API и Bot API Hudle.

Установка

pip install hudle-sdk

Установка из локального исходника

pip install -e /path/to/lumina/hudle-sdk

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

from hudle_sdk import HudleSDK

sdk = HudleSDK(
    base_url="https://app.hudle.ru/api",
    dev_jwt="<dev-jwt>",
    bot_token="<bot-token>",
    timeout=20,
    max_retries=4,
    backoff_factor=0.35,
    pool_connections=20,
    pool_maxsize=100,
)

# Dev API
app = sdk.dev.create_app(name="CRM Уведомления", description="Интеграция с CRM")
bot = sdk.dev.create_bot(app_id=app["id"], name="Lumos Team Bot", username="lumos_team_bot")
sdk.dev.install_bot_to_server(server_id=12, bot_id=bot["bot"]["id"])

# Bot API
sdk.bot.send_message(chat_id="channel:503", text="привет от hudle-sdk")

Производительность транспорта

SDK использует requests.Session с:

• постоянными HTTP-соединениями (pooling)
• автоматическими повторными попытками (429/5xx и сетевые ошибки)
• настраиваемыми таймаутами, retry, backoff и размером пула

Режимы авторизации для Bot API

По умолчанию SDK вызывает:

• POST /api/bot/<method> + Authorization: Bot <token>

Можно переключиться в режим токена в пути:

sdk = HudleSDK(
    base_url="https://app.hudle.ru/api",
    bot_token="<bot-token>",
    use_path_token_for_bot_api=True,
)

Тогда вызовы идут в:

• POST /api/bot/<token>/<method>

Основные компоненты

• HudleSDK: фасад с клиентами dev и bot.
• HudleDevApi: обёртки для /api/dev/* и /api/servers/*/bots.
• HudleBotApi: обёртки для /api/bot/*.
• HttpTransport: общий HTTP-слой с парсингом JSON и обработкой ошибок.

Обработка ошибок

SDK выбрасывает:

• HudleSdkError (базовая)
• HttpRequestError (сетевая/HTTP-ошибка)
• DevApiError (логические ошибки Dev API)
• BotApiError (ошибки Bot API с ok: false)

Поддерживаемые методы

Dev API

• create_app / create_application
• list_apps / list_applications
• update_app / update_application
• create_bot
• get_bot
• update_bot
• rotate_bot_token
• disable_bot
• install_bot_to_server / install_bot
• remove_bot_from_server / remove_bot
• raw_request (низкоуровневый вызов)

Bot API

• call (универсальный вызов метода)
• get_me
• log_out
• close
• get_updates
• iter_updates
• set_webhook
• get_webhook_info
• delete_webhook
• set_my_commands
• get_my_commands
• delete_my_commands
• set_event_subscriptions
• get_event_subscriptions
• delete_event_subscriptions
• get_chat
• get_chat_member
• get_chat_administrators
• get_chat_member_count
• set_chat_title
• set_chat_description
• set_chat_photo
• delete_chat_photo
• leave_chat
• export_chat_invite_link
• create_chat_invite_link
• edit_chat_invite_link
• revoke_chat_invite_link
• send_chat_action
• send_message
• forward_message
• copy_message
• send_photo
• send_video
• send_audio
• send_document
• send_voice
• send_animation
• send_video_note
• send_media_group
• send_location
• edit_message_live_location
• stop_message_live_location
• send_venue
• send_contact
• edit_message_text
• edit_message_caption
• edit_message_media
• edit_message_reply_markup
• delete_message
• get_user_profile_photos
• get_file
• ban_chat_member
• unban_chat_member
• restrict_chat_member
• promote_chat_member
• pin_chat_message
• unpin_chat_message
• unpin_all_chat_messages
• set_message_reaction

Идемпотентность

send_message поддерживает идемпотентность:

sdk.bot.send_message(
    chat_id="channel:503",
    text="событие без дублей",
    idempotency_key="ticket:9d5c...:created",
)