discljord.connections — org.suskalo/discljord 1.3.0-SNAPSHOT

Namespace for creating a connection to Discord, and recieving messages. Contains functionality required to create and maintain a sharded and auto-reconnecting connection object which will recieve messages from Discord, and pass them on to client code.

add-shards! clj

(add-shards! connection-ch new-shards intents & {:keys [disable-compression]})

Adds new shard connections using state fetched with get-shard-state!.

connect-bot! clj

(connect-bot! token out-ch & {:keys [intents disable-compression]})

Creates a connection process which will handle the services granted by Discord which interact over websocket.

Takes a token for the bot, and a channel on which all events from Discord will be sent back across.

Returns a channel used to communicate with the process and send packets to Discord.

Keep in mind that Discord sets a limit to how many shards can connect in a given period. This means that communication to Discord may be bounded based on which shard you use to talk to the server immediately after starting the bot.

intents is a set containing keywords representing which events will be sent to the bot by Discord. Valid values for the set are in gateway-intents. If intents is unspecified, a [[clojure.core/ex-info]] is returned with a relevant message.

connect-shards! clj

(connect-shards! token
                 out-ch
                 gateway
                 shard-ids
                 &
                 {:keys [intents identify-when disable-compression]})

Connects a specific set of shard ids to Discord.

Acts like connect-bot!, but also requires a gateway returned from get-websocket-gateway and a sequence of shard-ids to connect with, as well as a function used to determine when identify payloads are permitted to be sent.

identify must be a function from token to core.async channel which yields an item when an identify is permitted. This must be at least five seconds after the most recent identify by any shard, however any additional attempts to identify from this connection will include that wait by default, only identifies from other connections must be taken into account for this.

The recommended number of shards for your bot can be determined by the return value of get-websocket-gateway.

If Discord determines the bot must re-shard, then a :re-shard event will be emitted from the returned channel and all shards will be disconnected.

Because Discord has a limit of one shard connecting per five seconds, some amount of synchronization between calls to connect-shards! must be had. Additional calls should only be made five seconds after the :connected-all-shards event has been received.

create-activity clj

(create-activity & {:keys [name type url] :or {type :game} :as args})

Takes keyword arguments and constructs an activity to be used in status updates.

Keyword Arguments: name: a string which will display as the bot's status message, required type: keywords :game, :stream, :music, or :watch which change how the status message displays, as "Playing", "Streaming", "Listening to", or "Watching" respectively, defaults to :game. You can also pass the number of the discord status type directly if it isn't listed here. url: link to display with the :stream type, currently only urls starting with https://twitch.tv/ will work, defaults to nil

disconnect-bot! clj

(disconnect-bot! connection-ch)

Takes the channel returned by connect-bot! and stops the connection.

gateway-intents clj

get-shard-state! clj

(get-shard-state! connection-ch)

(get-shard-state! connection-ch shards)

Fetches the current shard session state.

shards is an optional set of shard state values. If it is not included, all shards will be fetched. Any shard which matches with the given keys will be included.

Returns a promise which can be derefed or taken off of like a channel.

get-websocket-gateway clj

(get-websocket-gateway token)

Gets the shard count and websocket endpoint from Discord's API.

Takes the token of the bot.

Returns a map with the keys :url, :shard-count, and :session-start limit, or nil in the case of an error.

guild-request-members! clj

(guild-request-members! connection-ch guild-id & args)

Takes the channel returned by connect-bot!, the snowflake guild id, and optional arguments about the members you want to get information about, and signals Discord to send you :guild-members-chunk events.

Keyword Arguments: query: a string that the username of the searched user starts with, or empty string for all users, defaults to empty string limit: the maximum number of members to give based on the query

remove-shards! clj

(remove-shards! connection-ch shards)

Removes shards matching any of the passed shards.

This will ignore the :seq keyword on any passed shard, but otherwise is as one of the shards returned from get-shard-state!.

status-update! clj

(status-update! connection-ch & args)

Takes the channel returned by connect-bot! and a set of keyword options, and updates Discord with a new status for your bot.

Keyword Arguments: idle-since: epoch time in milliseconds of when the bot went idle, defaults to nil activity: an activity map, from create-activity, which is used for the bot, defaults to nil status: a keyword representing the current status of the bot, can be :online, :dnd, :idle, :invisible, or :offline, defaults to :online afk: a boolean to say if the bot is afk, defaults to false shards: a set of shard ids to send this update to, or the keyword :all

voice-state-update! clj

(voice-state-update! connection-ch guild-id & args)

Takes the channel returned by connect-bot!, a guild id, and a set of keyword options and updates Discord with a new voice state.

Keyword Arguments: channel-id: the new channel id snowflake that your bot is in, disconnect if nil, defaults to nil mute: boolean which says if the bot is muted deaf: boolean which says if the bot is deafened