racket-cord: Racket discord library
(require racket-cord) | package: racket-cord |
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 [ #: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
#: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?
This function blocks until the client is stopped through stop-client.
procedure
(start-client-no-wait client) → void?
client : client?
procedure
(stop-client client) → void?
client : client?
procedure
(update-status client guild-id [ #:since since #:activities activities #:status status #:afk afk]) → void? client : client? guild-id : integer? since : (or/c integer? #f) = #f activities : (listof hash?) = null
status : (or/c "online" "dnd" "idle" "invisible" "offline") = "online" afk : boolean? = #f
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?
3 Data Models
Note that these have rotted significantly at the time of writing. Please see the source for precise details. Not all data models are fully specified or working.
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?
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
id : string? name : string? roles : (listof string?) user : (or/c user? null?) require-colons : boolean? managed : boolean?
struct
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
evt : symbol? client : client? callback : procedure?
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
For example, the Discord gateway event MESSAGE_CREATE would be identified as the Racket symbol 'message-create.
The exact type for callback depends on the specific event, see Event Callback Signatures for more information.
Each event has a raw counterpart, identified by prepending raw- to the Racket symbolic name. For example, the raw event symbol for MESSAGE_CREATE would be 'raw-message-create.
Raw events contain the raw data as provided by the Discord gateway. In contrast, the regular events are unmarshalled into structural representations by the library.
As of the time of writing, the regular events have bitrotted quite a bit and will need some work to fix. If you must receive many events reliably, using raw events is recommended.
Raw events will also allow you to immediately react to new features added by Discord without having to wait for the library to update.
In contrast to regular events, all raw event callbacks have the same type:
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.1 Event Callback Signatures
Below are the expected callback signatures for event handlers.
Note that some of these are no longer accurate and the authors are working on fixing them.
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?
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?
procedure
(get-member client member-id guild-id) → (or/c member? null?)
client : client? member-id : string? guild-id : string?
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.
procedure
(http:get-channel client channel-id)
→ (or/c dm-channel? guild-channel?) client : client? channel-id : string?
procedure
(http:modify-channel client channel-id data)
→ (or/c dm-channel? guid-channel?) client : client? channel-id : string? data : hash?
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?)
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 #:file file]) → message? 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]) → 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?)
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?
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?
procedure
(http:modify-guild-channel-permissions client guild-id data) → (racket data) client : client? guild-id : string? data : hash?
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?
procedure
(http:modify-guild-member client guild-id user-id data) → jsexpr? client : client? guild-id : string? user-id : string? data : hash?
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?
procedure
(http:modify-guild-role-positions client guild-id data) → (listof role?) client : client? guild-id : string? data : hash?
procedure
(http:modify-guild-role client guild-id role-id data) → role? client : client? guild-id : string? role-id : string? data : hash?
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?
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?
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?
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
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?
8 Additional
value
struct
(struct http:http-client (requester global-lock ratelimits))
requester : requester? global-lock : semaphore? ratelimits : (hash/c string? semaphore?)