Skip to content

Release 0.1.0

Pre-release
Pre-release

Choose a tag to compare

View all tags
@batarelkin batarelkin released this 27 Mar 09:14
· 42 commits to master since this release
v0.1.0
62d7155

MAX Bot API Java Client — v0.1.0

Initial release of the Java 21 client library for the MAX Messenger Bot API.

Group ID: ru.etsft.max
Java: 21+
License: Apache 2.0

Modules

Module Artifact ID Description
Core max-bot-api-core Models, sealed interfaces, enums — zero external dependencies
Client max-bot-api-client HTTP transport via java.net.http.HttpClient, query builders, rate limiter
Jackson max-bot-api-jackson Jackson serialization adapter with custom polymorphic deserializers
Gson max-bot-api-gson Gson serialization adapter (placeholder)
Webhook max-bot-api-webhook Webhook HTTPS server for receiving updates
Long Polling max-bot-api-longpolling Long polling consumer with virtual threads
Spring Boot max-bot-api-spring-boot Spring Boot auto-configuration for webhook and long polling
Test Support max-bot-api-test-support WireMock stubs and JSON fixtures for testing
Examples max-bot-api-examples Echo bot, keyboard bot, file upload bot (not published)

Installation

Gradle

dependencies {
    implementation("ru.etsft.max:max-bot-api-client:0.1.0")
    implementation("ru.etsft.max:max-bot-api-jackson:0.1.0")
    implementation("ru.etsft.max:max-bot-api-longpolling:0.1.0")

    // Optional: Spring Boot auto-configuration
    // implementation("ru.etsft.max:max-bot-api-spring-boot:0.1.0")
}

Maven

<dependency>
    <groupId>ru.etsft.max</groupId>
    <artifactId>max-bot-api-client</artifactId>
    <version>0.1.0</version>
</dependency>

Highlights

Java 21 Idiomatic Design

  • 83 record types for all DTOs — fully immutable, no getters/setters
  • 4 sealed interface hierarchies with exhaustive pattern matching:
    • Attachment (9 types + UnknownAttachment)
    • AttachmentRequest (9 types + UnknownAttachmentRequest)
    • Button (7 types + UnknownButton)
    • Update (14 types + UnknownUpdate)
  • 8 enums for API constants (chat type, chat status, sender action, etc.)
  • Virtual threads for HTTP transport and long polling

Full API Coverage

All 31 API methods implemented as type-safe query builders:

Category Methods
Bot getMyInfo, editMyInfo
Chats getChats, getChat, getChatByLink, editChat, deleteChat, sendAction
Members getMembers, addMembers, removeMember, getMembership, leaveChat
Admins getAdmins, postAdmins, deleteAdmins
Messages getMessages, getMessageById, sendMessage, editMessage, deleteMessage
Pins getPinnedMessage, pinMessage, unpinMessage
Callbacks answerOnCallback
Subscriptions getSubscriptions, subscribe, unsubscribe
Updates getUpdates
Uploads getUploadUrl
Video getVideoAttachmentDetails

Update Delivery

  • Long Polling — runs on virtual threads with configurable poll timeout, automatic marker tracking, exponential backoff on errors, graceful shutdown
  • Webhook Server — built-in HTTPS server with secret header validation, configurable port, automatic update deserialization
  • Spring Boot Auto-Configuration — single max.bot.mode property selects between webhook and longpolling; includes lifecycle management, auto-registration, and health monitoring

Serialization

  • Jackson adapter — custom StdDeserializer implementations for all polymorphic hierarchies; zero Jackson annotations in core models
  • snake_case ↔ camelCase property naming handled transparently
  • Forward-compatible — unknown update types, attachment types, button types, and extra JSON fields are tolerated without exceptions

Error Handling

  • Structured exception hierarchy: MaxApiException, MaxClientException, MaxRateLimitException, MaxMethodNotAllowedException, AttachmentNotReadyException
  • Automatic retry on 429 (rate limit) and 503 (service unavailable) with exponential backoff
  • Token-bucket rate limiter (30 rps) applied before every request
  • Configurable timeouts for connection and request

Spring Boot Integration

max:
  bot:
    mode: longpolling       # or "webhook"
    longpolling:
      token: "your-bot-token"
      poll-timeout: 30
  • max.bot.mode enum property — mutually exclusive mode selection
  • Startup warning when mode is not configured
  • Auto-creates MaxBotAPI bean from token
  • Lifecycle-managed consumer/webhook with Spring context start/stop
  • Auto-registers/unregisters webhook subscription on startup/shutdown

Quality

  • 549 tests (unit, serialization round-trip, WireMock integration)
  • JaCoCo coverage gates: ≥85% line, ≥80% branch
  • Checkstyle enforced: 120-char lines, no wildcard imports
  • SpotBugs static analysis on all production code
  • Javadoc on all public API classes and methods
  • Apache 2.0 license headers on all source files

Requirements

  • Java 21 or later
  • Jackson 2.21+ (if using max-bot-api-jackson)
  • Spring Boot 3.5+ (if using max-bot-api-spring-boot)

Links

Assets 2
Loading