tadpole/rest/endpoints

The first REST endpoint bindings: things every bot does in its first hour — read itself, post a message, reply. Each function builds the request, runs it through tadpole/rest/execute, and decodes the typed model. Transport injection is inherited from execute; the plain functions use the real httpc transport, the _with variants accept any transport (tests, proxies, a future JS target).

Every call runs in a fresh execute session, so rate-limit state learned here does not carry between calls: single-call bots are fine, sustained-fire callers should use execute.send_in_session directly.

When you reach for this

• get_current_user — smoke-test a token before starting a bot, or fetch the bot’s own identity.
• send_message / reply — every text post. reply adds a message_reference, so Discord’s client shows the original above the reply and pings its author; the returned message’s message_type is 19 (REPLY).

Any other route: drop to tadpole/rest/execute with rest.post/rest.get and decode the payload yourself.

Routes

The _with variants take the same routes over an injected transport; see each function’s doc.

Failure modes

Errors arrive already mapped by execute:

• 401 — the token is wrong or was reset in the portal.
• 403 — the bot lacks permission there (for messages: usually Send Messages), or cannot view the channel.
• 404 — the id is wrong, or the resource is gone (for reply, the replied-to message was already deleted).
• 429 — rate limited; retried while the client allows, then error.RateLimited with the wait.
• status 0 — no HTTP response happened at all: network down, timeout. The status-0 convention, tadpole/rest/execute’s module doc explains why.
• DecodeFailed — Discord’s payload stopped matching the model.

Discord truncates content past 2000 characters, silently: the message posts, the tail is gone, no error returns. Check string.length yourself if the length matters.

Concurrency

Each call is independent and blocks its process for the round trip plus any sleeps. The fresh-session caveat above is the one that bites: a tight loop leans on 429 retries rather than learned waits. Sustained fire on one route belongs in execute.send_in_session.

See also

• tadpole/bot — wraps send_message/reply with a ready client
• tadpole/rest/execute — the layer below, and the session API
• tadpole/model/message — what comes back

pub fn get_current_user(
  client: rest.RestClient,
) -> Result(user.User, error.TadpoleError)

pub fn get_current_user_with(
  client: rest.RestClient,
  transport: fn(request.Request(String)) -> Result(
    response.Response(String),
    execute.TransportError,
  ),
) -> Result(user.User, error.TadpoleError)

pub fn reply(
  client: rest.RestClient,
  channel_id: ids.ChannelId,
  message_id: ids.MessageId,
  content: String,
) -> Result(message.Message, error.TadpoleError)

pub fn reply_with(
  client: rest.RestClient,
  transport: fn(request.Request(String)) -> Result(
    response.Response(String),
    execute.TransportError,
  ),
  channel_id: ids.ChannelId,
  message_id: ids.MessageId,
  content: String,
) -> Result(message.Message, error.TadpoleError)

pub fn send_message(
  client: rest.RestClient,
  channel_id: ids.ChannelId,
  content: String,
) -> Result(message.Message, error.TadpoleError)

pub fn send_message_with(
  client: rest.RestClient,
  transport: fn(request.Request(String)) -> Result(
    response.Response(String),
    execute.TransportError,
  ),
  channel_id: ids.ChannelId,
  content: String,
) -> Result(message.Message, error.TadpoleError)