Metadata-Version: 2.4
Name: hudle-sdk
Version: 0.1.1
Summary: Python SDK для Dev API и Bot API Hudle
Author: Hudle Team
License-Expression: MIT
Project-URL: Homepage, https://hudle.ru
Keywords: hudle,sdk,bot-api,dev-api
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests<3.0.0,>=2.31.0
Provides-Extra: dev
Requires-Dist: build<2.0.0,>=1.2.1; extra == "dev"
Requires-Dist: twine<6.0.0,>=5.1.1; extra == "dev"
Dynamic: license-file

# hudle-sdk

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

## Установка

```bash
pip install hudle-sdk
```

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

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

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

```python
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>`

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

```python
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` поддерживает идемпотентность:

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