$ show love-apples/maxapi
maxapi is an async Python SDK and bot framework for the MAX messenger platform. It provides a high-level client (`Bot`) for all MAX Bot API endpoints, an event-driven dispatcher with router hierarchy (`Dispatcher`/`Router`), composable filters (magic filter `F`, `Command`, `StateFilter`, etc.), middleware chains, a finite state machine (FSM) with multiple backends (memory, Redis), and webhook integrations for aiohttp, FastAPI, and Litestar. The library is heavily inspired by aiogram but adapted to MAX API specifics such as attachment types, callback payloads, and deep linking. It includes extensive utility code for formatting (HTML/Markdown), inline keyboard building, VCF parsing, and time helpers. The codebase is well-structured with Pydantic v2 models for all API entities, rigorous retry logic, and a comprehensive test suite covering unit, integration, and webhook scenarios. While not a standalone application, it serves as a foundational component for building production-ready MAX bots.
The LLM identified 7 files worth highlighting for reuse:
Provides `as_html()` and `as_markdown()` functions that build formatted message trees from plain text, supporting bold, italic, code, links, mentions, etc. These are reusable across any messenger text formatting scenario and have no framework dependencies.
Implements `State` and `StatesGroup` classes for a finite state machine with support for nested groups and state inheritance. This is a generic FSM implementation that can be extracted and used in any async context needing stateful conversation flows.
Provides `BaseEventIsolation`, `SimpleEventIsolation` (in-process lock), and `RedisEventIsolation` (distributed lock) to serialize event processing per `(chat_id, user_id)` key. This pattern is reusable for any async application requiring ordered, per-user event handling.
Defines `CallbackPayload` base model with classmethod `pack()` and `unpack()` that serialize/deserialize a Pydantic model instance to/from a string using a prefix and separator. This provides a clean, type-safe way to handle callback data and can be extracted for any callback-based system.
Implements `create_start_link()`, `encode_payload()`, and `decode_payload()` for generating and parsing deep link URLs with Base64-encoded payloads. This is a standalone utility applicable to any bot or application that needs start links with payload.
Provides `VcfInfo` dataclass and `parse_vcf_info()` to parse VCF (vCard) strings into structured contact data. This is a self-contained, reusable utility for handling vCard contact information in any Python project.
Defines `BaseMaxWebhook` abstract class with `process()` method that validates secret tokens and dispatches events. This pattern provides a clear template for adding webhook support to any async web framework and can be adapted beyond MAX bots.