racket-cord: Racket discord library

8.12

racket-cord: Racket discord library🔗ℹ

1 Example🔗ℹ

Example usage of the library:

(require racket-cord)

(define bot-token (getenv "BOT_TOKEN"))

(define myclient (make-client bot-token #:auto-shard #t #:intents (list intent-guilds intent-guild-messages)))

(on-event
  'raw-message-create myclient
  (lambda (ws-client client payload)
    (unless (string=? (hash-ref (hash-ref payload 'author) 'id)
                      (user-id (client-user client)))
      (cond
        [(string-prefix? (hash-ref payload 'content) "!echo ")
         (http:create-message client (hash-ref payload 'channel_id)
                              (string-trim (hash-ref  payload 'content) "!echo " #:right? #f))]))))

(define dr (make-log-receiver discord-logger 'debug))

(thread
  (thunk
    (let loop ()
      (let ([v (sync dr)])
        (printf "[~a] ~a\n" (vector-ref v 0)
                (vector-ref v 1)))
      (loop))))

(start-client myclient)

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
user
guilds
private-channels
events
http-client
token
running)
    #:mutable
    #:transparent)
  shards : list?
  user : user?
  guilds : (hash/c string? guild?)
  private-channels : (hash/c string? dm-channel?)
  events : (hash/c symbol? procedure?)
  http-client : http:http-client?
  token : string?
  running : semaphore?

Stores the state of the client.

3 Data Models🔗ℹ

Note that these have rotted significantly at the time of writing and are likely to be removed.

struct
(struct guild ( shard-id
id
name
icon
splash
owner-id
region
afk-channel-id
afk-timeout
embed-enabled
embed-channel-id
verification-level
default-message-notifications
explicit-content-filter
roles
emojis
features
mfa-level
application-id
widget-enabled
widget-channel-id
joined-at
large
member-count
voice-states
members
channels
presences))
  shard-id : integer?
  id : string?
  name : string?
  icon : string?
  splash : string?
  owner-id : string?
  region : string?
  afk-channel-id : string?
  afk-timeout : integer?
  embed-enabled : boolean?
  embed-channel-id : string?
  verification-level : integer?
  default-message-notifications : integer?
  explicit-content-filter : integer?
  roles : (hash/c string? role?)
  emojis : (hash/c string? emoji?)
  features : (listof string?)
  mfa-level : integer?
  application-id : string?
  widget-enabled : boolean?
  widget-channel-id : string?
  joined-at : string?
  large : boolean?
  member-count : integer?
  voice-states : jsexpr?
  members : (hash/c string? member?)
  channels : (hash/c string? guild-channel?)
  presences : (listof jsexpr?)

struct
(struct guild-channel ( id
type
guild-id
position
permission-overwrites
name
topic
nsfw
last-message-id
bitrate
user-limit
parent-id))
  id : string?
  type : integer?
  guild-id : string?
  position : integer?
  permission-overwrites : (listof jsexpr?)
  name : string?
  topic : string?
  nsfw : boolean?
  last-message-id : string?
  bitrate : integer?
  user-limit : integer?
  parent-id : string?

An object representing a guild text channel or a guild voice channel. Fields that only exist for voice channels will be null for a text channel, and vice-versa.

struct
(struct dm-channel ( id
type
name
last-message-id
icon
recipients
owner-id
application-id))
  id : string?
  type : integer?
  name : string?
  last-message-id : string?
  icon : string?
  recipients : string?
  owner-id : string?
  application-id : string?

struct
(struct user (id username discriminator avatar bot mfa-enabled))
  id : string?
  username : string?
  discriminator : string?
  avatar : string?
  bot : boolean?
  mfa-enabled : boolean?

struct
(struct member (user nick roles joined-at deaf mute status game))
  user : user?
  nick : (or/c string? null?)
  roles : (listof string?)
  joined-at : string?
  deaf : boolean?
  mute : boolean?
  status : (or/c string? null?)
  game : (or/c game? null?)

struct
(struct message ( id
channel-id
author
content
timestamp
edited-timestamp
tts
mention-everyone
mentions
mention-roles
attachments
embeds
reactions
pinned
type))
  id : string?
  channel-id : string?
  author : (or/c user? null?)
  content : string?
  timestamp : string?
  edited-timestamp : (or/c string? null?)
  tts : boolean?
  mention-everyone : boolean?
  mentions : (listof user?)
  mention-roles : (listof role?)
  attachments : jsexpr?
  embeds : jsexpr?
  reactions : jsexpr?
  pinned : boolean?
  type : integer?

struct
(struct role ( id
name
color
hoist
position
permissions
managed
mentionable))
  id : string?
  name : string?
  color : integer?
  hoist : boolean?
  position : integer?
  permissions : integer?
  managed : boolean?
  mentionable : boolean?

struct
(struct emoji (id name roles user require-colons managed))
  id : string?
  name : string?
  roles : (listof string?)
  user : (or/c user? null?)
  require-colons : boolean?
  managed : boolean?

struct
(struct game (name type url))
  name : string?
  type : integer?
  url : string?

struct
(struct invite (code guild-id channel-id))
  code : string?
  guild-id : string?
  channel-id : string?

struct
(struct webhook (id guild-id channel-id user name avatar token))
  id : string?
  guild-id : (or/c string? null?)
  channel-id : string?
  user : (or/c user?)
  name : (or/c string? null?)
  avatar : (or/c string? null?)
  token : string?

4 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.

5 Miscellaneous functions🔗ℹ

procedure
(get-channels client) → (listof guild-channel?)
client : client?

procedure
(get-channel client id) → (or/c guild-channel? null?)
client : client?
id : string?

Get a channel by id. Returns null on failure.

procedure
(get-guild client id) → (or/c guild? null?)
client : client?
id : string?

Get a guild by id. Returns null on failure.

procedure
(get-member client member-id guild-id) → (or/c member? null?)
  client : client?
  member-id : string?
  guild-id : string?

Get a member of a guild by id. Returns null on failure.

6 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.

7 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.

8 Additional🔗ℹ

value
discord-logger : logger?

Logger of discord events in the library.

struct
(struct http:http-client (requester global-lock ratelimits))
  requester : requester?
  global-lock : semaphore?
  ratelimits : (hash/c string? semaphore?)

Internal http client of the library, holds ratelimiting state.

1	Example
2	Client
3	Data Models
4	Events
5	Miscellaneous functions
6	HTTP
7	Exceptions
8	Additional