**Migrated from GitHub issue icub3d/decentcom#76** **Original Author:** @icub3d **Original Date:** 2026-04-17T21:42:08Z --- # Feature: Bot SDK ## Overview Provide a minimal Rust crate that wraps the decentcom gateway WebSocket and REST API with typed event handlers, so first-party and third-party bot authors can build bots quickly without reimplementing the protocol. ## Background The research in #68 and the bot-framework discussion concluded that bots are the right tool for moderation, welcome flows, and utility tasks that don't belong on the auth/permissions critical path. A thin SDK keeps bot implementations from going brittle or diverging from protocol changes, and it gives reference bots (separate issue) a worked-examples role rather than a reference-implementations-of-the-protocol role. ## Requirements - [x] New Rust crate at `tools/bot-sdk/` published as `decentcom-bot` (in-tree for now; crates.io later). - [x] Async event loop driven by the gateway WebSocket. - [x] Typed event handlers: `on_message`, `on_member_join`, `on_member_leave`, moderation events, etc. - [x] REST action helpers covering the actions a bot might take (send, edit, delete, kick, ban). - [x] Automatic reconnect with exponential backoff. - [x] Config loading from a TOML file and env vars (12-factor). - [x] Structured logging via `tracing`. - [x] README with a working minimal example. ## Design ### Component Changes - New workspace member at `tools/bot-sdk/`. - Reuses types from `shared/` where possible. ### API Sketch ```rust use decentcom_bot::{Bot, Context, MessageEvent}; #[tokio::main] async fn main() -> anyhow::Result<()> { Bot::from_env()? .on_message(handle_message) .run() .await } async fn handle_message(ctx: Context, evt: MessageEvent) -> anyhow::Result<()> { if evt.content.starts_with("!ping") { ctx.reply(&evt, "pong").await?; } Ok(()) } ``` ## Task List ### Phase 1: Core - [x] Scaffold `tools/bot-sdk/` workspace crate. - [x] Gateway WebSocket client with auto-reconnect + exponential backoff. - [x] Typed event deserialization against `shared/` types. - [x] Handler registration and dispatch. - [x] REST action helpers (send, edit, delete, kick, ban). ### Phase 2: Polish - [x] Config loading (env vars + TOML). - [x] `tracing`-based logging. - [x] Error types. - [x] README with minimal example. ## Test List - [x] Unit tests for event deserialization. - [ ] Integration test: SDK-based bot connects to a running dev server, receives a test message, responds. ## Open Questions - Publish to crates.io from the start or keep in-tree only for v1? (Recommendation: in-tree until stable.) - Python / TypeScript equivalents later, or keep bots Rust-only for v1? (Recommendation: Rust-only for v1 — revisit based on contributor demand.) ## Dependencies - Blocked by #75, #85 (Bot Account Type — SDK uses the same Ed25519 challenge-response flow with an `is_bot` claim). - Related: #68 (velocity / timeout primitives used by bots). - Blocks: #77 (Reference Bots).

icub3d commented

2026-04-26 16:46:11 +00:00

Owner

Migrated from GitHub issue icub3d/decentcom#76
Original Author: @icub3d
Original Date: 2026-04-17T21:42:08Z

Feature: Bot SDK

Overview

Provide a minimal Rust crate that wraps the decentcom gateway WebSocket and REST API with typed event handlers, so first-party and third-party bot authors can build bots quickly without reimplementing the protocol.

Background

The research in #68 and the bot-framework discussion concluded that bots are the right tool for moderation, welcome flows, and utility tasks that don't belong on the auth/permissions critical path. A thin SDK keeps bot implementations from going brittle or diverging from protocol changes, and it gives reference bots (separate issue) a worked-examples role rather than a reference-implementations-of-the-protocol role.

Requirements

New Rust crate at tools/bot-sdk/ published as decentcom-bot (in-tree for now; crates.io later).
Async event loop driven by the gateway WebSocket.
Typed event handlers: on_message, on_member_join, on_member_leave, moderation events, etc.
REST action helpers covering the actions a bot might take (send, edit, delete, kick, ban).
Automatic reconnect with exponential backoff.
Config loading from a TOML file and env vars (12-factor).
Structured logging via tracing.
README with a working minimal example.

Design

Component Changes

New workspace member at tools/bot-sdk/.
Reuses types from shared/ where possible.

API Sketch

use decentcom_bot::{Bot, Context, MessageEvent};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    Bot::from_env()?
        .on_message(handle_message)
        .run()
        .await
}

async fn handle_message(ctx: Context, evt: MessageEvent) -> anyhow::Result<()> {
    if evt.content.starts_with("!ping") {
        ctx.reply(&evt, "pong").await?;
    }
    Ok(())
}

Task List

Phase 1: Core

Scaffold tools/bot-sdk/ workspace crate.
Gateway WebSocket client with auto-reconnect + exponential backoff.
Typed event deserialization against shared/ types.
Handler registration and dispatch.
REST action helpers (send, edit, delete, kick, ban).

Phase 2: Polish

Config loading (env vars + TOML).
tracing-based logging.
Error types.
README with minimal example.

Test List

Unit tests for event deserialization.
Integration test: SDK-based bot connects to a running dev server, receives a test message, responds.

Open Questions

Publish to crates.io from the start or keep in-tree only for v1? (Recommendation: in-tree until stable.)
Python / TypeScript equivalents later, or keep bots Rust-only for v1? (Recommendation: Rust-only for v1 — revisit based on contributor demand.)

Dependencies

Blocked by #75, #85 (Bot Account Type — SDK uses the same Ed25519 challenge-response flow with an is_bot claim).
Related: #68 (velocity / timeout primitives used by bots).
Blocks: #77 (Reference Bots).

icub3d

closed this issue
added the
area:infra

type:feature

area:core

status:complete
labels

Rows
Columns

Feature: Bot SDK #54