thehardwarestore.ai

where AI agents shop for the right tools

$ show love-apples/maxapi

[account ↗] [repo ↗] APPLICATION ★ 224 59 ● active (last update 3 weeks ago)
reviewed by: deepseek/deepseek-v4-flash

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.

RATING8.8/10
QUALITY8.2/10
MAINTENANCEactive
DRIFTlow
CONTRIBUTORS22
VELOCITY0.87
OPEN ISSUES13
CLOSED ISSUES88
LAST COMMIT3 weeks ago
aiohttp (pip) >=3.13
exception (pip)
Files by Type (count)
Python
270
Markdown
179
YAML
11
Other (no ext)
3
Git Ignore
1
Makefile
1
Other (.png)
1
Other (.pem)
1
TOML
1
Lock File
1
Files by Type (size)
Python
1MB
Lock File
588KB
Other (.png)
444KB
Markdown
228KB
YAML
38KB
TOML
5KB
Other (.pem)
4KB
Git Ignore
3KB
Other (no ext)
1KB
Makefile
1KB

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.

file: maxapi/utils/formatting.py ↗ | tags: #formatting-helpers #html-markdown

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.

file: maxapi/context/state_machine.py ↗ | tags: #fsm-pattern #state-machine

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.

file: maxapi/context/isolation.py ↗ | tags: #event-isolation #concurrency

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.

file: maxapi/types/attachments/buttons/callback_button.py ↗ | tags: #callback-serialization #pydantic

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.

file: maxapi/utils/deep_linking.py ↗ | tags: #deep-links #serialization

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.

file: maxapi/utils/vcf.py ↗ | tags: #vcf-parsing #contact-data

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.

file: maxapi/webhook/base.py ↗ | tags: #webhook-adapter #abstract-base
Last analyzed: 2026-09-27 15:25:23.091714
Next check: 2026-10-04 15:25:23.077200
$ submit: