Discord Action — v1 Concept

Integration of Discord into the Hercules automation platform, built on
discord.js. This document defines the scope for the
first version: which triggers/events and which functions should be implemented.

Architecture

Unlike the Shopware/Shopify actions, Discord does not push events via plain
HTTP webhooks. Events arrive over the Discord Gateway (a persistent
WebSocket connection) that discord.js manages through its Client.

This maps onto Hercules as follows:

• The action process runs a single discord.js Client (one bot) next to the
  Aquila connection.
• Event classes are registered as runtime events (like the existing actions),
  but instead of extending the Rest flow type, the action listens to
  discord.js client events and pushes them into flows via
  action.fire(eventClass, projectId, payload).
• Functions call the Discord REST API through the same discord.js client
  (client.channels, guild.members, etc.), so no separate HTTP layer is
  needed.

Discord Gateway ──ws──> discord.js Client ──action.fire()──> Aquila ──> Flows
Flows ──function call──> discord.js Client ──REST──> Discord API

Client lifecycle

• Log in on action start (client.login(token)), reuse the connected client
  for all function calls.
• discord.js handles gateway reconnects itself; on fatal auth errors, surface
  them via CodeZeroEvent.error like the reconnect loop in the existing
  actions.

Gateway intents

Discord requires intents to be declared for the events a bot receives. v1
needs:

The README of the action must document how to enable the two privileged
intents in the developer portal.

Configuration

Defined as ConfigurationDefinitions on the Action (like client_id /
client_secret in the GLS action):

Events (Triggers) — v1

Deliberately not in v1: messageUpdate/messageDelete (partials handling),
buttons/select menus (interactionCreate component types), voice events,
scheduled events, bans. See Out of scope.

Event settings

Where useful, events get optional settings to filter at the source instead of
in the flow:

• channelId (optional) on DiscordMessageCreated / DiscordReactionAdded —
  only fire for a specific channel.
• commandName (+ commandDescription, parameter definitions later) on
  DiscordSlashCommandInvoked.

Functions — v1

Grouped like the GLS action (functions/, functions/utils/).

Messaging

Members & roles (moderation basics)

Lookups

Utils (data type builders)

Like the GLS create* util functions — pure builders so flows can assemble
nested payloads:

All functions wrap discord.js errors in RuntimeError with stable error codes
(e.g. DISCORD_UNKNOWN_CHANNEL, DISCORD_MISSING_PERMISSIONS,
DISCORD_MISSING_ACCESS), mapped from DiscordAPIError.code.

Data types — v1

One class per file in src/data_types/, zod schema + @Schema decorator,
following the existing actions:

• DiscordUser — id, username, globalName, avatar URL, bot flag
• DiscordGuildMember — user, nickname, role ids, joinedAt, guild id
• DiscordMessage — id, channelId, guildId, author (DiscordUser), content,
  embeds, attachments, mentions, referenced message id, createdAt
• DiscordChannel — id, guildId, name, type (DiscordChannelType), topic,
  parent id
• DiscordChannelType — enum registered as its own data type (text, voice,
  category, announcement, thread, forum, dm)
• DiscordGuild — id, name, icon URL, ownerId, memberCount
• DiscordRole — id, guildId, name, color, position
• DiscordEmbed, DiscordEmbedField, DiscordEmbedFooter,
  DiscordEmbedAuthor
• DiscordAttachment — id, filename, contentType, size, url
• DiscordReaction — emoji (name/id), messageId, channelId, user
  (DiscordUser)
• DiscordCommandInteraction — id, commandName, options (name/value pairs),
  user, channelId, guildId

Known pitfalls from the other actions apply here:

• @Signature values are capped at 500 characters — register enums/unions as
  data types instead of inlining them.
• Optional parameters need optional: true on @Parameter; ?: in the
  signature alone is not enough.
• DiscordMessage references itself (replied-to message) — keep cyclic
  references as plain id fields in v1 to avoid recursive schema handling, or
  register each cyclic schema as its own data type with a deferred getter if
  the full object is needed.

Out of scope — v2 candidates

• Components: buttons, select menus, modals (interactionCreate component
  events + a discordSendMessageWithComponents function)
• Message events: messageUpdate, messageDelete (require partials
  handling and cache tuning)
• Channel management: create/delete/rename channels, threads
• Moderation events: guildBanAdd, guildAuditLogEntryCreate, timeouts
  (discordTimeoutMember)
• Voice: voice state events
• Scheduled events, webhooks management, polls
• Multi-bot support (one client per config scope) — v1 assumes a single
  bot token per action instance

Suggested project layout

actions/discord-action/
├── src/
│   ├── index.ts               # Action setup, discord.js client, event wiring
│   ├── client.ts              # discord.js client factory + login/reconnect
│   ├── helpers.ts             # error mapping (DiscordAPIError -> RuntimeError)
│   ├── data_types/            # one data type class per file
│   ├── events/                # one event class per file
│   └── functions/
│       ├── messaging/
│       ├── members/
│       ├── lookups/
│       └── utils/
├── module.json
├── package.json               # deps: @code0-tech/hercules, discord.js, zod
└── README.md                  # bot setup, privileged intents, invite URL