@kody/discord

@kody/discord

Intent

Provide reusable, account-agnostic Discord helpers for Kody agents: bot token for reading and posting in servers (messages, reactions, threads), and user OAuth for identity plus the authorizing user's guild list. This is not a personal notify package, not a gateway/chat bot, and not official-server admin.

What it does

• Verify Discord credentials (bot token or user OAuth)
• Read identity (users/@me) and list the authorizing user's guilds (OAuth)
• Fetch channels and recent messages; create threads; add reactions (bot)
• Post or edit bot messages with dryRun preview or confirm for live writes

Prerequisites / setup

There is no built-in Discord OAuth app. Both lanes are bring-your-own. Never paste tokens into chat. Agents: see AGENTS.md for import paths and smoke checks.

Auth lanes

OAuth scopes such as identify and guilds never grant channel content. Reading message text needs the privileged Message Content intent on the bot.

Multi-account: pass integration (OAuth, default discord) or secretName (bot, default discordBotToken). Additional connections use names like discord-work / discordBotTokenWork — do not hard-code personal aliases.

Lane A — user OAuth (identity and guilds)

1. Create an application at discord.com/developers/applications.
2. On OAuth2, copy the client id and client secret.
3. Add redirect URI exactly: https://kody.codes/connect/oauth.
4. Open this prefilled connect URL while signed in to Kody:

https://kody.codes/connect/oauth?provider=discord&authorizeUrl=https%3A%2F%2Fdiscord.com%2Foauth2%2Fauthorize&tokenUrl=https%3A%2F%2Fdiscord.com%2Fapi%2Foauth2%2Ftoken&flow=confidential&scopes=identify%20guilds

Decoded: authorize https://discord.com/oauth2/authorize, token https://discord.com/api/oauth2/token, flow=confidential, scopes identify guilds. Discord's token host discord.com is also the API host, so no extra allowedHosts is required. Access tokens expire after 7 days; Kody refreshes them.

For a second Discord user account, change provider= to a new name such as discord-work and pass integration: 'discord-work' on OAuth exports.

Lane B — bot token (read and post in servers)

1. On the same application's Bot tab, create the bot and copy the token. Never paste it into chat.
2. If the bot must read message text, enable the privileged Message Content intent.
3. Install the bot into the target server (Manage Server required):

https://discord.com/oauth2/authorize?client_id=YOUR_CLIENT_ID&scope=bot&permissions=68672

68672 = view channel + send messages + read history + add reactions. Add Create Public Threads / Send Messages in Threads in the developer portal if you use thread helpers.

4. Save the token:

https://kody.codes/account/secrets/new?name=discordBotToken&description=Discord%20bot%20token&allowedHosts=discord.com&scope=user

Approve host discord.com after saving. Additional bots: a different name= (for example discordBotTokenWork) and pass secretName on bot exports.

Hosts and scopes

• Required host: discord.com (API https://discord.com/api/v10).
• OAuth scopes (Lane A): identify, guilds. Optional: email, connections, guilds.members.read. None of these read channel messages.
• Bot capabilities (Lane B): install permissions integer, bot roles, and privileged intents — not OAuth scopes.

Done when

• Bot secret discordBotToken is saved with host discord.com approved, and/or OAuth integration discord is connected
• Identity smoke checks succeed for the lane(s) you use
• Mutations refuse to call Discord unless dryRun: true or confirm: true