racket-cord: Racket discord library

7.1

top ← prev up next →

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

(on-event
  'message-create myclient
  (lambda (client message)
    (unless (string=? (user-id (message-author message))
                      (user-id (client-user client)))
      (cond
        [(string-prefix? (message-content message) "!echo ")
         (http:create-message client (message-channel-id message)
                              (string-trim (message-content message) "!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
[ #:token-type token-type
#:auto-shard auto-shard
#:shard-count shard-count]) → client?
  token : string?
  token-type : symbol? = 'bot
  auto-shard : boolean? = #f
  shard-count : integer? = 1

Makes a discord client with the passed token.

token: The token to use.

#:token-type: The type of token, either 'bot, 'bearer or 'client.

#:auto-shard: Whether to request the number of shards from discord, only usable for bot clients.

#:shard-count: If auto-shard is not passed, the number of shards to connect will be such.

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

Start a client. WS is connected and the client begins handling events.

This function blocks until the client is disconnected through stop-client.

procedure
(strart-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
guild-id
[ #:since since
#:game game
#:status status
#:afk afk]) → void?
  client : client?
  guild-id : integer?
  since : integer? = null
  game : game? = null
  status : string? = "online"
  afk : boolean? = #f

Updates the status of a client.

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

evt: A symbol of the event name, for example 'message-create

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.

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 : (listof 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?

3 Events

User the procedure on-event to register an event.

Example:

(on-event 'message-create
(lambda (client message)
(println (message-content message))))

Event callbacks and their types are described here:

procedure
(channel-create client channel) → void?
  client : client?
  channel : (or/c dm-channel? guild-channel?)
procedure
(channel-delete client channel) → void?
  client : client?
  channel : (or/c dm-channel? guild-channel?)
procedure
(channel-update client
old-channel
new-channel) → void?
  client : client?
  old-channel : (or/c dm-channel? guild-channel?)
  new-channel : (or/c dm-channel? guild-channel?)
procedure
(guild-create client guild) → void?
  client : client?
  guild : guild?
procedure
(guild-delete client guild) → void?
  client : client?
  guild : guild?
procedure
(guild-update client old-guild new-guild) → void?
  client : client?
  old-guild : guild?
  new-guild : guild?
procedure
(guild-ban-add client user guild) → void?
  client : client?
  user : user?
  guild : guild?
procedure
(guild-ban-remove client user guild) → void?
  client : client?
  user : user?
  guild : guild?
procedure
(guild-emojis-update client guild emojis) → void?
  client : client?
  guild : guild?
  emojis : (listof emoji?)
procedure
(guild-member-add client member) → void?
  client : client?
  member : member?
procedure
(guild-member-remove client member) → void?
  client : client?
  member : member?
procedure
(guild-member-update client
old-member
new-member) → void?
  client : client?
  old-member : member?
  new-member : member?
procedure
(presence-update client
old-member
new-member) → void?
  client : client?
  old-member : member?
  new-member : member?
procedure
(message-create client message) → void?
  client : client?
  message : message?
procedure
(message-delete client message-id) → void?
  client : client?
  message-id : string?
procedure
(message-reaction-add client
user-id
channel-id
message-id
emoji) → void?
  client : client?
  user-id : string?
  channel-id : string?
  message-id : string?
  emoji : emoji?
procedure
(message-reaction-remove client
user-id
channel-id
message-id
emoji) → void?
  client : client?
  user-id : string?
  channel-id : string?
  message-id : string?
  emoji : emoji?
procedure
(message-reaction-remove-all client
channel-id
message-id) → void?
  client : client?
  channel-id : string?
  message-id : string?
procedure
(typing-start client channel-id user-id) → void?
  client : client?
  channel-id : string?
  user-id : string?

Each event has a raw counterpart, for example 'raw-message-create. All raw events have the form:

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

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

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

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

Request a channel.

procedure
(http:modify-channel client channel-id data)
→ (or/c dm-channel? guid-channel?)
  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 ...) → (listof message?)
  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) → message?
  client : client?
  channel-id : string?
  message-id : string?

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

procedure
(http:edit-message client
channel-id
message-id
[ #:content content
#:embed embed]) → message?
  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 ...) → (listof user?)
  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]) → invite?
  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) → (listof message?)
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) → (listof emoji?)
client : client?
guild-id : string?

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

procedure
(http:create-guild-emoji client
guild-id
name
image
image-type
roles) → emoji?
  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) → emoji?
  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) → guild?
client : client?
guild-id : string?

procedure
(http:modify-guild client guild-id data) → guild?
  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)
→ (listof guild-channel?)
client : client?
guild-id : string?

procedure
(http:create-guild-channel client
guild-id
data) → guild-channel?
  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) → member?
  client : client?
  guild-id : string?
  user-id : string?

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

procedure
(http:add-guild-member client
guild-id
user-id
data) → member?
  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) → (listof role?)
client : client?
guild-id : string?

procedure
(http:create-guild-role client
guild-id
data) → role?
  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) → (listof role?)
  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) → role?
  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) → integer?
  client : client?
  guild-id : string?
  days : integer?

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

procedure
(http:get-guild-invites client guild-id) → (listof invite?)
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) → user?
client : client

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

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

procedure
(http:get-current-user-guilds client
[ #:before before
#:after after
#:limit limit])
→ (listof guild?)
  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) → (listof dm-channel?)
client : client?

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

procedure
(http:create-group-dm client data) → dm-channel?
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.

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

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

top ← prev up next →

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