Metadata-Version: 2.4
Name: maxapi-sdk
Version: 0.13.0
Summary: Production-ready Python SDK for MAX Messenger Bot API
Author: maxapi-sdk contributors
Maintainer: Maxim Strekolovskiy
License-Expression: MIT
Project-URL: Homepage, https://github.com/Maxi-online/maxapi-sdk
Project-URL: Repository, https://github.com/Maxi-online/maxapi-sdk
Project-URL: Issues, https://github.com/Maxi-online/maxapi-sdk/issues
Keywords: max,messenger,bot,sdk,python
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aiofiles>=24.1.0
Requires-Dist: aiohttp>=3.9.0
Requires-Dist: pydantic>=2.8.0
Provides-Extra: webhook
Requires-Dist: fastapi>=0.111.0; extra == "webhook"
Requires-Dist: uvicorn>=0.30.0; extra == "webhook"
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Requires-Dist: httpx>=0.27.0; extra == "dev"
Requires-Dist: build>=1.2.0; extra == "dev"
Requires-Dist: twine>=5.0.0; extra == "dev"
Dynamic: license-file

# maxapi-sdk 0.13.0

`maxapi-sdk` is a production-ready Python SDK for the MAX Messenger Bot API.

The package is designed for teams that need a reliable foundation for bot development and operations: typed API access, resilient transport, polling and webhook runtimes, routing, middleware, FSM, plugin support, callback handling, and first-class media workflows.

## Highlights

- typed Bot API client for core MAX endpoints;
- resilient transport with retries, backoff, and `Retry-After` support;
- dedicated polling and webhook runtimes;
- routing, middleware, composable filters, and dependency injection;
- FSM primitives with in-memory storage;
- plugin API for modular bot extensions;
- structured callback payload parsing;
- first-class media support for images, audio, voice, video, and files;
- typed attachment helpers for outbound and inbound media handling;
- GitHub Actions for test, build, and release automation.

## Installation

```bash
pip install maxapi-sdk
pip install maxapi-sdk[webhook]
pip install maxapi-sdk[dev]
```

## Quick start

```python
import asyncio
import os

from maxapi import Bot, Command, Dispatcher


bot = Bot(token=os.environ["MAX_BOT_TOKEN"])
dispatcher = Dispatcher()


@dispatcher.message_created(Command("start"))
async def handle_start(event):
    await event.message.answer("Bot is running")


async def main() -> None:
    await dispatcher.start_polling(bot)


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

## Media workflows

```python
from maxapi import Bot


async def send_media(bot: Bot) -> None:
    await bot.send_image("./assets/banner.png", chat_id=1001, text="Preview")
    await bot.send_voice(
        chat_id=1001,
        filename="voice.ogg",
        buffer=b"binary-audio-data",
        text="Voice update",
    )
    await bot.send_file("./reports/report.pdf", chat_id=1001, text="Report")
```

The SDK supports file path, bytes buffer, and stream-based uploads. Incoming attachments are exposed through typed accessors such as `message.images`, `message.audios`, `message.voices`, `message.videos`, and `message.files`.

## Webhook runtime

```python
import asyncio
import os

from maxapi import Bot, Dispatcher


bot = Bot(token=os.environ["MAX_BOT_TOKEN"])
dispatcher = Dispatcher()


async def main() -> None:
    await dispatcher.handle_webhook(
        bot=bot,
        host="0.0.0.0",
        port=8080,
        path="/webhook",
        secret=os.environ["MAX_BOT_WEBHOOK_SECRET"],
    )


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

## FSM example

```python
from maxapi import Dispatcher, MemoryStorage, State, StateFilter, StatesGroup


class Registration(StatesGroup):
    name = State()
    confirm = State()


dispatcher = Dispatcher(storage=MemoryStorage())


@dispatcher.message_created(StateFilter(Registration.name))
async def handle_name(message, state):
    await state.update_data(name=message.body.text)
    await state.set_state(Registration.confirm)
    await message.answer("Please confirm the entered name")
```

## Packaging and release

The repository includes CI workflows for tests, package build validation, GitHub Releases, and PyPI publication via Trusted Publishing.

## Compatibility

The public import path remains `maxapi`, while the distribution package name is `maxapi-sdk`.
