racket-cord: Racket discord library🔗ℹ

1 Quick Start🔗ℹ

Create a client using make-client
Register websocket event handlers using on-event
Start the client and begin receiving events using start-client
Make auxiliary HTTP calls using provided utility functions

2 Client🔗ℹ

procedure
(make-client token
[ #:intents intents
#:token-type token-type
#:auto-shard auto-shard
#:shard-count shard-count]) → client?
  token : string?
  intents : (listof integer?) = null
  token-type : (or/c 'bot 'bearer 'client) = 'bot
  auto-shard : boolean? = #f
  shard-count : integer? = 1

Constructs a client with the passed token.

#:auto-shard: If #t, ask Discord what the number of shards should be. Only applies if #:token-type is 'bot.

#:shard-count: If #:auto-shard is #f, the number of shards to use.

procedure
(start-client client) → void?
client : client?

Starts a client and begins handling events.
This function blocks until the client is stopped through stop-client.

procedure
(start-client-no-wait client) → void?
client : client?

Same as start-client but does not block the calling thread.

procedure
(stop-client client) → void?
client : client?

Stops a client

procedure
(update-status client
[ #:since since
#:activities activities
#:status status
#:afk afk]) → void?
  client : client?
  since : (or/c integer? #f) = #f
  activities : (listof hash?) = null
   status : (or/c "online" "dnd" "idle" "invisible" "offline")
= "online"
  afk : boolean? = #f

Updates the client’s status.

struct
(struct client ( shards
shard-threads
user
events
http-client
token
intents
running)
    #:mutable
    #:transparent)
  shards : list?
  shard-threads : any/c
  user : (hash/c symbol? any/c)
  events : (hash/c symbol? procedure?)
  http-client : any/c
  token : string?
  intents : any/c
  running : semaphore?

Stores the state of the client.

3 Events🔗ℹ

procedure
(on-event evt client callback) → void?
  evt : symbol?
  client : client?
  callback : procedure?

Subscribe to callbacks for the given gateway event identified by evt.

The Racket symbol name evt corresponding to a given Discord gateway event is derived as follows:

Lowercase the event name
Replace underscores with dashes
Convert to symbol
Prefix with "raw-"

For example, the Discord gateway event MESSAGE_CREATE would be identified as the Racket symbol 'raw-message-create.

The signature of "callback" should be as follows.

procedure
(raw-callback ws-client client data) → void?
  ws-client : ws-client?
  client : client?
  data : jsexpr?

where data is the raw d payload received from the Discord gateway.

4 HTTP🔗ℹ

HTTP requests are defined here. Ratelimiting is handled for you by the library. Requests that fail raise a exn:fail:network:http:discord? exception. All functions return the raw JSON as returned by the Discord REST API.

procedure
(http:get-channel client channel-id) → jsexpr?
client : client?
channel-id : string?

Request a channel.

procedure
(http:modify-channel client channel-id data) → jsexpr?
  client : client?
  channel-id : string?
  data : hash?

data should be a hashmap that conforms to Modify Channel.

procedure
(http:delete-channel client channel-id) → jsexpr?
client : client?
channel-id : string?

procedure
(http:get-channel-messages client
channel-id
params ...) → jsexpr?
  client : client?
  channel-id : string?
  params : (cons/c string? string?)

params provided should be cons cells of '(k . v) conforming to Get Channel Message.

procedure
(http:get-channel-message client
channel-id
message-id) → jsexpr?
  client : client?
  channel-id : string?
  message-id : string?

procedure
(http:create-message client
[ content
#:embed embed
#:tts tts
#:file file]) → jsexpr?
  client : client?
  content : string? = ""
  embed : jsexpr? = null
  tts : boolean? = #f
  file : attachment? = #f

procedure
(http:edit-message client
channel-id
message-id
[ #:content content
#:embed embed]) → jsexpr?
  client : client?
  channel-id : string?
  message-id : string?
  content : (or/c string? null?) = null
  embed : jsexpr? = null

procedure
(http:delete-message client
channel-id
message-id) → jsexpr?
  client : client?
  channel-id : string?
  message-id : string?

procedure
(http:create-reaction client
channel-id
message-id
emoji) → jsexpr?
  client : client?
  channel-id : string?
  message-id : string?
  emoji : string?

procedure
(http:delete-own-reaction client
channel-id
message-id
emoji) → jsexpr?
  client : client?
  channel-id : string?
  message-id : string?
  emoji : string?

procedure
(http:delete-user-reaction client
channel-id
message-id
emoji
user-id) → jsexpr?
  client : client?
  channel-id : string?
  message-id : string?
  emoji : string?
  user-id : string?

procedure
(http:get-reactions client
channel-id
message-id
emoji
params ...) → jsexpr?
  client : client?
  channel-id : string?
  message-id : string?
  emoji : string?
  params : (cons string? string?)

params provided should be cons cells of '(k . v) conforming to Get Reactions.

procedure
(http:delete-all-reactions client
channel-id
message-id) → jsexpr?
  client : client?
  channel-id : string?
  message-id : string?

procedure
(http:bulk-delete-messages client
channel-id
ids ...) → jsexpr?
  client : client?
  channel-id : string?
  ids : string?

procedure
(http:edit-channel-permissions client
channel-id
overwrite-id
allow
deny
type) → jsexpr?
  client : client?
  channel-id : string?
  overwrite-id : string?
  allow : integer?
  deny : integer?
  type : string?

procedure
(http:get-channel-invites client
channel-id) → jsexpr?
client : client?
channel-id : string?

procedure
(http:create-channel-invite client
channel-id
[ age
uses
temporary
unique]) → jsexpr?
  client : client?
  channel-id : string?
  age : integer? = 86400
  uses : integer? = 0
  temporary : boolean? = #f
  unique : boolean = #f

procedure
(http:delete-channel-permission client
channel-id
overwrite-id) → jsexpr?
  client : client?
  channel-id : string?
  overwrite-id : string?

procedure
(http:trigger-typing-indicator client
channel-id) → jsexpr?
client : client?
channel-id : string?

procedure
(http:get-pinned-messages client
channel-id) → jsexpr?
client : client?
channel-id : string?

procedure
(http:add-pinned-channel-message client
channel-id
message-id) → jsexpr?
  client : client?
  channel-id : string?
  message-id : string?

procedure
(http:delete-pinned-channel-message client
channel-id
message-id) → jsexpr?
  client : client?
  channel-id : string?
  message-id : string?

procedure
(http:group-dm-add-recipient client
channel-id
user-id
access-token
nick) → jsexpr?
  client : client?
  channel-id : string?
  user-id : string?
  access-token : string?
  nick : string?

procedure
(http:group-dm-remove-recipient client
channel-id
user-id) → jsexpr?
  client : client?
  channel-id : string?
  user-id : string?

procedure
(http:list-guild-emoji client guild-id) → jsexpr?
client : client?
guild-id : string?

procedure
(http:get-guild-emoji client
guild-id
emoji-id) → jsexpr?
  client : client?
  guild-id : string?
  emoji-id : string?

procedure
(http:create-guild-emoji client
guild-id
name
image
image-type
roles) → jsexpr?
  client : client?
  guild-id : string?
  name : string?
  image : bytes?
  image-type : string?
  roles : (listof string?)

procedure
(http:modify-guild-emoji client
guild-id
emoji-id
name
roles) → jsexpr?
  client : client?
  guild-id : string?
  emoji-id : string?
  name : string?
  roles : (listof string?)

procedure
(http:delete-guild-emoji client
guild-id
emoji-id) → jsexpr?
  client : client?
  guild-id : string?
  emoji-id : string?

procedure
(http:get-guild client guild-id) → jsexpr?
client : client?
guild-id : string?

procedure
(http:modify-guild client guild-id data) → jsexpr?
  client : client?
  guild-id : string?
  data : hash?

data should be a hashmap that conforms to Modify Guild.

procedure
(http:delete-guild client guild-id) → jsexpr?
client : client?
guild-id : string?

procedure
(http:get-guild-channels client guild-id) → jsexpr?
client : client?
guild-id : string?

procedure
(http:create-guild-channel client
guild-id
data) → jsexpr?
  client : client?
  guild-id : string?
  data : hash?

data should be a hashmap that conforms to Create Guild Channel.

procedure
(http:modify-guild-channel-permissions client
guild-id
data)
→ (racket data)
  client : client?
  guild-id : string?
  data : hash?

should be a hashmap that conforms to Modify Guild Channel Positions.

procedure
(http:get-guild-member client
guild-id
user-id) → jsexpr?
  client : client?
  guild-id : string?
  user-id : string?

procedure
(http:list-guild-members client
guild-id
[ #:limit limit
#:after after]) → jsexpr?
  client : client?
  guild-id : string?
  limit : integer? = 1
  after : integer? = 0

procedure
(http:add-guild-member client
guild-id
user-id
data) → jsexpr?
  client : client?
  guild-id : string?
  user-id : string?
  data : hash?

data should be a hashmap that conforms to Add Guild Member.

procedure
(http:modify-guild-member client
guild-id
user-id
data) → jsexpr?
  client : client?
  guild-id : string?
  user-id : string?
  data : hash?

data should be a hashmap that conforms to Modify Guild Member.

procedure
(http:modify-user-nick client guild-id nick) → jsexpr?
  client : client?
  guild-id : string?
  nick : string?

procedure
(http:add-guild-member-rols client
guild-id
user-id
role-id) → jsexpr?
  client : client?
  guild-id : string?
  user-id : string?
  role-id : string?

procedure
(http:remove-guild-member-role client
guild-id
user-id
role-id) → jsexpr?
  client : client?
  guild-id : string?
  user-id : string?
  role-id : string?

procedure
(http:remove-guild-member client
guild-id
user-id) → jsexpr?
  client : client?
  guild-id : string?
  user-id : string?

procedure
(http:get-guild-bans client guild-id) → jsexpr?
client : client?
guild-id : string?

procedure
(http:create-guild-ban client
guild-id
user-id
[ days]) → jsexpr?
  client : client?
  guild-id : string?
  user-id : string?
  days : integer? = 1

procedure
(http:remove-guild-ban client
guild-id
user-id) → jsexpr?
  client : client?
  guild-id : string?
  user-id : string?

procedure
(http:get-guild-roles client guild-id) → jsexpr?
client : client?
guild-id : string?

procedure
(http:create-guild-role client
guild-id
data) → jsexpr?
  client : client?
  guild-id : string?
  data : hash?

data should be a hashmap that conforms to Create Guild Role.

procedure
(http:modify-guild-role-positions client
guild-id
data) → jsexpr?
  client : client?
  guild-id : string?
  data : hash?

data should be a hashmap that conforms to Modify Guild Role Positions.

procedure
(http:modify-guild-role client
guild-id
role-id
data) → jsexpr?
  client : client?
  guild-id : string?
  role-id : string?
  data : hash?

data should be a hashmap that conforms to Modify Guild Role.

procedure
(http:delete-guild-role client
guild-id
role-id) → jsexpr?
  client : client?
  guild-id : string?
  role-id : string?

procedure
(http:get-guild-prune-count client
guild-id
days) → jsexpr?
  client : client?
  guild-id : string?
  days : integer?

procedure
(http:begin-guild-prune client
guild-id
days) → jsexpr?
  client : client?
  guild-id : string?
  days : integer?

procedure
(http:get-guild-invites client guild-id) → jsexpr?
client : client?
guild-id : string?

procedure
(http:get-guild-integrations client
guild-id) → jsexpr?
client : client?
guild-id : string?

procedure
(http:create-guild-integration client
guild-id
type
id) → jsexpr?
  client : client?
  guild-id : string?
  type : string?
  id : string?

procedure
(http:modify-guild-integration client
guild-id
integration-id
data) → jsexpr?
  client : client?
  guild-id : string?
  integration-id : string?
  data : hash?

data should be a hashmap that conforms to Modify Guild Integration.

procedure
(http:delete-guild-integration client
guild-id
integration-id) → jsexpr?
  client : client?
  guild-id : string?
  integration-id : string?

procedure
(http:sync-guild-integrations client
guild-id
integration-id) → jsexpr?
  client : client?
  guild-id : string?
  integration-id : string?

procedure
(http:get-guild-embed client guild-id) → jsexpr?
client : client?
guild-id : string?

procedure
(http:modify-guild-embed client
guild-id
data) → jsexpr?
  client : client?
  guild-id : string?
  data : hash?

data should be a hashmap that conforms to Modify Guild Embed.

procedure
(http:get-current-user client) → jsexpr?
client : client

procedure
(http:get-user client user-id) → jsexpr?
client : client?
user-id : string?

procedure
(http:modify-current-user client
[ #:username username
#:avatar avatar
#:avatar-type avatar-type]) → jsexpr?
  client : client?
  username : string? = null
  avatar : bytes? = null
  avatar-type : string? = ""

procedure
(http:get-current-user-guilds client
[ #:before before
#:after after
#:limit limit]) → jsexpr?
  client : client?
  before : integer? = null
  after : integer? = null
  limit : integer? = null

procedure
(http:leave-guild client guild-id) → jsexpr?
client : client?
guild-id : string?

procedure
(http:get-user-dms client) → jsexpr?
client : client?

procedure
(http:create-dm client recipient-id) → jsexpr?
client : client?
recipient-id : string?

procedure
(http:create-group-dm client data) → jsexpr?
client : client?
data : hash?

data should be a hashmap that conforms to Create Group DM.

procedure
(http:create-webhook client
channel-id
name
avatar
avatar-type) → jsexpr?
  client : client?
  channel-id : string?
  name : string?
  avatar : bytes?
  avatar-type : string?

procedure
(http:get-channel-webhooks client
channel-id) → jsexpr?
client : client?
channel-id : string?

procedure
(http:get-guild-webhooks client guild-id) → jsexpr?
client : client?
guild-id : string?

procedure
(http:get-webhook client webhook-id) → jsexpr?
client : client?
webhook-id : string?

procedure
(http:get-webhook-with-token client
webhook-id
webhook-token) → jsexpr?
  client : client?
  webhook-id : string?
  webhook-token : string?

procedure
(http:modify-webhook client
webhook-id
[ #:name name
#:avatar avatar
#:avatar-type avatar-type
#:channel-id channel-id]) → jsexpr?
  client : client?
  webhook-id : string?
  name : string? = null
  avatar : bytes? = null
  avatar-type : string? = ""
  channel-id : string? = null

procedure
(http:modify-webhook-with-token client
webhook-id
token
[ #:name name
#:avatar avatar
#:avatar-type avatar-type
#:channel-id channel-id])
→ jsexpr?
  client : client?
  webhook-id : string?
  token : string?
  name : string? = null
  avatar : bytes = null
  avatar-type : string = ""
  channel-id : string? = null

procedure
(http:delete-webhook client webhook-id) → jsexpr?
client : client?
webhook-id : string?

procedure
(http:delete-webhook-with-token client
webhook-id
webhook-token) → jsexpr?
  client : client?
  webhook-id : string?
  webhook-token : string?

procedure
(http:execute-webhook client
webhook-id
webhook-token
data
[ #:wait wait]) → jsexpr?
  client : client?
  webhook-id : string?
  webhook-token : string?
  data : hash?
  wait : boolean? = #f

data should be a hashmap that conforms to Execute Webhook.

5 Exceptions🔗ℹ

struct
(struct http:exn:fail:network:http:discord ( message
continuation-marks
http-code
discord-code
reason)
    #:transparent)
  message : string?
  continuation-marks : continuation-mark-set?
  http-code : number?
  discord-code : number?
  reason : string?

Raised when a http error code is retrieved from discord.

6 Additional🔗ℹ

value
discord-logger : logger?

Logger of discord events in the library.