#discord.mbt

Status: experimental. Minor releases may contain breaking changes; see the changelog for migration notes.

#Prerequisites

#Install

moon update
moon add gaato/discord

#Quickstart

///|
struct QuickstartEchoArgs {
  text : String
  times : Int
}

///|
async fn run_echo_bot(token : String) -> Unit {
  let args : @discord.Args[QuickstartEchoArgs] = @discord.Args::map2(
    @discord.arg_string(name="text", description="What to echo"),
    @discord.arg_int32(
      name="times",
      description="How many times (1-5)",
      min=1,
      max=5,
    ).with_default(1),
    (text, times) => { text, times, },
  )
  let echo = @discord.slash(
    name="echo",
    description="Echo your text back",
    args~,
    handler=Immediate((_ctx, value) => {
      @discord.CommandReply::message(
        content=Array::make(value.times, value.text).join("\n"),
      )
    }),
  )
  let app = @discord.App()
  app.command(echo)
  let bot = @discord.Bot(app, token~, sync=Global)
  bot.on(@discord.Events::ready(), (_ctx, ready) => {
    println("ready as \{ready.user.username}")
  })
  bot.run()
}

#Packages

#Wasm runtime and permissions

moon build --target wasm --release src/examples/interactions_http
moonrun --policy discord-policy.json _build/wasm/release/build/examples/interactions_http/interactions_http.wasm

{
  "env": {
    "required_from_host": ["DISCORD_TOKEN", "PUBLIC_KEY"],
    "from_host": ["GUILD_ID"],
    "set": {"PORT": "8080"}
  },
  "net": {
    "connect": ["discord.com:443"],
    "bind": ["0.0.0.0:8080"]
  }
}

• REST-only tool: http (brings model).
• Serverless HTTP interactions (Cloudflare Workers, Deno, Bun, and Node.js Functions, JS): app and verify.
• Native HTTP interactions server: endpoint_http.
• Gateway bot: bot, or the gaato/discord facade for everything.

#Examples

• slash_echo: minimal typed Gateway bot.
• kitchen_sink: subcommands, autocomplete, context menus, components, and modals.
• ping_gateway: low-level Gateway and REST use.
• low_level: manual Framework and Shard wiring.
• workers_echo: Cloudflare Workers adapter.
• deno_echo: Deno adapter for the same MoonBit interaction App.
• bun_echo: Bun HTTP server adapter for the same interaction App.
• vercel_echo: Vercel Node.js Function adapter for the same interaction App.
• fastly_echo: Fastly FetchEvent entry point experiment.
• lambda_url_echo: Lambda Function URL payload v2 adapter experiment.
• workers_gateway: Cloudflare Durable Object running a gateway bot (no voice).
• interactions_http: native signed-interactions HTTP server.
• experiments/spin_interactions: WASIp2 Spin component for signed PING and immediate echo; this experiment sits outside src/examples/.
• plugin_demo: a stateful feedback feature installed as a separate package.
• gate_probe: live probe for error-policy recovery and user-restricted component waits (needs a Discord client; guild commands only).
• voice_player: join a voice channel and play an Ogg/Opus file.
• voice_recorder: record a user's voice to an Ogg/Opus file.

#App core and executors

• Bot(app, token~) connects to the gateway and routes InteractionCreate events through the App.
• app.serve(group, token~) creates an InteractionEndpoint for an HTTP adapter.

#Gateway executor

bot.on(@discord.Events::message_create(), (ctx, event) => {
  let message = event.message
  println("\{message.author.username}: \{message.content}")
})

///|
let bot = @discord.Bot(app, token~, shards=Auto)

#Voice (experimental)

#Synchronization and failures

///|
async test "sync preserves entry points and skips an unchanged catalog" {
  let spec = @interaction.CommandSpec::slash("ping", "Ping")
  let (payload, report) = @framework.plan_command_sync(
    [spec],
    [spec.to_json(), { "id": "10", "type": 4, "name": "Launch", "handler": 2 }],
    unowned=Delete,
  )
  assert_true(payload is None)
  assert_false(report.overwritten)
  assert_eq(report.preserved, ["4:Launch"])
}

#HTTP interactions (experimental)

///|
async fn handle_http_interaction(
  app : @discord.App,
  group : @async.TaskGroup[Unit],
  token : String,
  body : Json,
) -> Json? {
  app.serve(group, token~).handle(body)
}

#Cloudflare Workers gateway

///|
fn restored_bot(
  app : @discord.App,
  token : String,
  saved : Map[Int, @discord.BotSession],
) -> @discord.Bot {
  @discord.Bot(app, token~, resume=saved)
}

///|
fn current_bot_sessions(bot : @discord.Bot) -> Map[Int, @discord.BotSession] {
  bot.sessions()
}

#Typed models

let id : @model.MessageId = @model.Id::parse("175928847299117063")
println(id.timestamp_ms()) // 1462015105796

#REST without the gateway

let client = @dhttp.Client(token)
let message = client.create_message(channel_id, content="hello")
client.create_message(channel_id, content="with reply", reply_to=message.id)
|> ignore

client.guild_ref(guild_id).emoji_ref(emoji_id).edit(name="renamed") |> ignore

• an opt-in, gateway-driven in-memory cache — events and intents;
• pure helpers for permissions, mentions, timestamps, and CDN URLs — models and utilities;
• structured REST, gateway, and dispatch telemetry — middleware;
• a feature-installer convention for structuring larger bots — structuring bots;
• the interaction router, response gates, and no-network handler testing under App — the framework layer.

#Development

moon check --target native --deny-warn
moon check --target js --deny-warn
moon check --target wasm --deny-warn
moon test --target native --release   # debug native builds need a working tcc setup
moon test --target js --release
moon test --target wasm --release
moon fmt
moon -C template fmt --check
moon info --target native             # regenerate pkg.generated.mbti (API review signal)
scripts/gen_extends.py                # regenerate extends.mbt after adding or removing a ToJson type

moon ide doc "@discord"
moon ide doc "@http.Client::create_message"
moon ide doc "@model.Message"
moon ide doc "@util.channel_permissions"

#License