@stonyx/discord 0.1.0

package/README.md

@@ -0,0 +1,343 @@
+# @stonyx/discord
+
+Discord bot module for the [Stonyx framework](https://github.com/abofs/stonyx), providing plug-and-play command and event handler discovery, intent auto-derivation, and utility methods for channels, messages, and roles.
+
+## Highlights
+
+* **Command auto-discovery:** Drop command files into a directory and the framework registers them automatically.
+* **Event handler auto-discovery:** Same pattern for Discord gateway events.
+* **Intent auto-derivation:** Required intents computed from discovered event handlers.
+* **Lazy initialization:** Bot only starts if a token is configured and commands/events exist.
+* **Singleton pattern:** Matches conventions of `@stonyx/sockets` and `@stonyx/events`.
+* **Utility methods:** sendMessage, reply with auto-chunking, role management, and more.
+
+## Installation
+
+```bash
+pnpm install @stonyx/discord
+```
+
+## Quick Start
+
+### 1. Create handler directories
+
+```
+discord-commands/       # default directory (configurable)
+  ping.js
+discord-events/         # default directory (configurable)
+  message-create.js
+```
+
+### 2. Write a command
+
+```javascript
+// discord-commands/ping.js
+import { SlashCommandBuilder } from 'discord.js';
+import { Command } from '@stonyx/discord';
+
+export default class PingCommand extends Command {
+  data = new SlashCommandBuilder()
+    .setName('ping')
+    .setDescription('Replies with Pong!');
+
+  async execute(interaction) {
+    await interaction.reply('Pong!');
+  }
+}
+```
+
+### 3. Write an event handler
+
+```javascript
+// discord-events/message-create.js
+import { EventHandler } from '@stonyx/discord';
+
+export default class MessageCreateHandler extends EventHandler {
+  static event = 'messageCreate';
+
+  handle(message) {
+    if (message.author.bot) return;
+    console.log(`${message.author.username}: ${message.content}`);
+  }
+}
+```
+
+### 4. Start the bot
+
+With Stonyx auto-initialization (recommended):
+
+```bash
+stonyx serve
+```
+
+Or manually:
+
+```javascript
+import { DiscordBot } from '@stonyx/discord';
+
+const bot = new DiscordBot();
+await bot.init();
+```
+
+## Command Architecture
+
+### How commands are discovered
+
+On `init()`, `DiscordBot` scans the command directory using `forEachFileImport`. Each file's default export is instantiated and validated:
+
+- Must have a `data` property (a `SlashCommandBuilder` instance)
+- Must have an `execute(interaction)` method
+- Missing either → logged warning, command skipped
+
+Commands are registered by `instance.data.name` (the name set on the `SlashCommandBuilder`).
+
+Handler filenames follow the kebab-to-camelCase convention: `ping-stats.js` → `pingStats`.
+
+### Command class
+
+Each command extends `Command` and provides:
+
+- **`data`** — a `SlashCommandBuilder` defining the command name, description, and options
+- **`execute(interaction)`** — receives the Discord.js `ChatInputCommandInteraction`
+- **`this._bot`** — reference to the `DiscordBot` instance (set automatically during discovery)
+- **`static skipAuth`** — reserved for future auth gating (default: `false`)
+
+### Interaction error handling
+
+The framework wraps `execute()` in a try/catch. On error:
+
+1. Logs the error via `log.error()`
+2. Sends an ephemeral "There was an error executing this command!" reply
+3. Uses `followUp` if the interaction was already replied to or deferred
+
+## Event Handler Architecture
+
+### How handlers are discovered
+
+On `init()`, `DiscordBot` scans the event directory using `forEachFileImport`. Each file's default export is validated:
+
+- Must have a `static event` property (the Discord.js event name)
+- Missing → logged warning, handler skipped
+
+After discovery, each handler is wired to the Discord.js client:
+
+```javascript
+client.on(handler.constructor.event, (...args) => handler.handle(...args));
+```
+
+### EventHandler class
+
+Each handler extends `EventHandler` and provides:
+
+- **`static event`** — the Discord.js gateway event name (e.g., `'messageCreate'`, `'guildMemberAdd'`)
+- **`handle(...args)`** — receives the event arguments from Discord.js
+- **`this._bot`** — reference to the `DiscordBot` instance (set automatically during discovery)
+
+## Intent Auto-Derivation
+
+The framework automatically computes the required intents from your registered event handlers. No manual intent configuration needed.
+
+### Event-to-Intent Mapping
+
+| Event | Intents |
+|-------|---------|
+| `messageCreate` | `GuildMessages`, `DirectMessages`, `MessageContent` |
+| `messageDelete` | `GuildMessages` |
+| `messageUpdate` | `GuildMessages` |
+| `guildMemberAdd` | `GuildMembers` |
+| `guildMemberRemove` | `GuildMembers` |
+| `inviteCreate` | `GuildInvites` |
+| `inviteDelete` | `GuildInvites` |
+| `voiceStateUpdate` | `GuildVoiceStates` |
+| `interactionCreate` | *(none — handled by default)* |
+
+**`Guilds` is always included** when commands are registered.
+
+### Intent-to-Partial Mapping
+
+| Intent | Partials |
+|--------|----------|
+| `DirectMessages` | `Channel` |
+
+### Config overrides
+
+Use `additionalIntents` and `additionalPartials` in config to add intents/partials that aren't covered by auto-derivation:
+
+```javascript
+// config/environment.js (consumer app)
+export default {
+  discord: {
+    additionalIntents: ['GuildPresences'],
+    additionalPartials: ['Message', 'Reaction'],
+  }
+}
+```
+
+Values are resolved against `GatewayIntentBits` and `Partials` enums from discord.js.
+
+## Utility Methods
+
+All methods are on the `DiscordBot` instance (accessible via `this._bot` in commands/handlers or `new DiscordBot()`).
+
+### sendMessage(content, channelId, imagePath?)
+
+Send a text message to a channel. Optionally attach an image file.
+
+```javascript
+await bot.sendMessage('Hello world', '123456789');
+await bot.sendMessage('Check this out', '123456789', './screenshot.png');
+```
+
+### sendFile(file, messageObject)
+
+Edit an existing message to replace its content with a file attachment.
+
+```javascript
+const msg = await bot.sendMessage('Processing...', channelId);
+await bot.sendFile('/path/to/output.csv', msg);
+```
+
+### reply(interaction, content)
+
+Reply to a slash command interaction with auto-chunking. Messages over 2000 characters are split at newline/space boundaries and sent as follow-ups.
+
+```javascript
+await bot.reply(interaction, longContent);
+```
+
+Handles both fresh replies and deferred/already-replied interactions automatically.
+
+### updateStatus(name, type?)
+
+Set the bot's presence/activity status.
+
+```javascript
+await bot.updateStatus('with fire', 0);  // "Playing with fire"
+```
+
+Type values: `0` = Playing, `1` = Streaming, `2` = Listening, `3` = Watching, `5` = Competing.
+
+### getChannelMessages(channelId, options?)
+
+Fetch messages from a channel. Uses `maxMessagesPerRequest` as the default limit.
+
+```javascript
+const messages = await bot.getChannelMessages('123456789');
+const older = await bot.getChannelMessages('123456789', { before: '999999' });
+```
+
+### getChannelMessage(channelId, messageId)
+
+Fetch a single message by ID.
+
+```javascript
+const msg = await bot.getChannelMessage('123456789', '987654321');
+```
+
+### getGuild(guildId?)
+
+Fetch a guild. Defaults to `config.discord.serverId`.
+
+```javascript
+const guild = await bot.getGuild();
+```
+
+### clearChannelMessages(channelId)
+
+Delete all fetched messages in a channel (up to `maxMessagesPerRequest`).
+
+```javascript
+await bot.clearChannelMessages('123456789');
+```
+
+### giveRole(memberId, roleId)
+
+Add a role to a guild member in the default server.
+
+```javascript
+await bot.giveRole('111222333', '444555666');
+```
+
+## Configuration
+
+Configuration is read from `stonyx/config` under `discord`:
+
+| Option | Env Var | Default | Description |
+|--------|---------|---------|-------------|
+| `token` | `DISCORD_TOKEN` | `''` | Discord bot token |
+| `botUserId` | `DISCORD_BOT_USER_ID` | `''` | Bot's user ID |
+| `serverId` | `DISCORD_SERVER_ID` | `''` | Default guild/server ID |
+| `commandDir` | `DISCORD_COMMAND_DIR` | `'./discord-commands'` | Command files directory |
+| `eventDir` | `DISCORD_EVENT_DIR` | `'./discord-events'` | Event handler files directory |
+| `maxMessagesPerRequest` | `DISCORD_MAX_MESSAGES_PER_REQUEST` | `100` | Max messages fetched per request |
+| `additionalIntents` | — | `[]` | Extra intent names to include |
+| `additionalPartials` | — | `[]` | Extra partial names to include |
+
+### Logging config (framework-internal)
+
+| Key | Value | Purpose |
+|-----|-------|---------|
+| `log` | `DISCORD_LOG` / `false` | Enable verbose logging |
+| `logColor` | `'#7289da'` | Chronicle log color for `log.discord()` |
+| `logMethod` | `'discord'` | Creates `log.discord()` method |
+
+## API Reference
+
+### DiscordBot
+
+| Method / Property | Description |
+|-------------------|-------------|
+| `new DiscordBot()` | Singleton constructor |
+| `async init()` | Discover commands/events, derive intents, connect to Discord |
+| `commands` | `Object` — registered command instances keyed by name |
+| `eventHandlers` | `Array` — registered event handler instances |
+| `client` | Discord.js `Client` instance (after init) |
+| `ready` | `Promise` — resolves when the bot is connected and ready |
+| `sendMessage(content, channelId, imagePath?)` | Send a message to a channel |
+| `sendFile(file, messageObject)` | Replace a message with a file attachment |
+| `reply(interaction, content)` | Reply with auto-chunking |
+| `updateStatus(name, type?)` | Set bot presence |
+| `getChannelMessages(channelId, options?)` | Fetch channel messages |
+| `getChannelMessage(channelId, messageId)` | Fetch a single message |
+| `getGuild(guildId?)` | Fetch a guild |
+| `clearChannelMessages(channelId)` | Delete messages in a channel |
+| `giveRole(memberId, roleId)` | Add a role to a member |
+| `close()` | Destroy the Discord client and clear singleton |
+| `reset()` | Close + clear all commands and handlers |
+
+### Command
+
+| Property / Method | Description |
+|-------------------|-------------|
+| `static skipAuth = false` | Reserved for future auth gating |
+| `data` | `SlashCommandBuilder` — define in subclass |
+| `execute(interaction)` | Handle the slash command — define in subclass |
+| `this._bot` | Reference to `DiscordBot` (set during discovery) |
+
+### EventHandler
+
+| Property / Method | Description |
+|-------------------|-------------|
+| `static event = null` | Discord.js event name — set in subclass |
+| `handle(...args)` | Handle the event — define in subclass |
+| `this._bot` | Reference to `DiscordBot` (set during discovery) |
+
+## Example Project Structure
+
+```
+my-app/
+├── config/
+│   └── environment.js
+├── discord-commands/
+│   ├── ping.js
+│   └── stats.js
+├── discord-events/
+│   ├── message-create.js
+│   └── guild-member-add.js
+├── package.json
+└── app.js
+```
+
+## License
+
+Apache — do what you want, just keep attribution.

package/config/environment.js

@@ -0,0 +1,23 @@
+const {
+  DISCORD_TOKEN,
+  DISCORD_BOT_USER_ID,
+  DISCORD_SERVER_ID,
+  DISCORD_COMMAND_DIR,
+  DISCORD_EVENT_DIR,
+  DISCORD_MAX_MESSAGES_PER_REQUEST,
+  DISCORD_LOG,
+} = process.env;
+
+export default {
+  token: DISCORD_TOKEN ?? '',
+  botUserId: DISCORD_BOT_USER_ID ?? '',
+  serverId: DISCORD_SERVER_ID ?? '',
+  commandDir: DISCORD_COMMAND_DIR ?? './discord-commands',
+  eventDir: DISCORD_EVENT_DIR ?? './discord-events',
+  maxMessagesPerRequest: DISCORD_MAX_MESSAGES_PER_REQUEST ?? 100,
+  additionalIntents: [],
+  additionalPartials: [],
+  log: DISCORD_LOG ?? false,
+  logColor: '#7289da',
+  logMethod: 'discord',
+};

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@stonyx/discord",
+  "keywords": [
+    "stonyx-async",
+    "stonyx-module"
+  ],
+  "version": "0.1.0",
+  "description": "Discord bot module for the Stonyx framework",
+  "main": "src/main.js",
+  "type": "module",
+  "files": [
+    "*"
+  ],
+  "exports": {
+    ".": "./src/main.js",
+    "./bot": "./src/bot.js",
+    "./command": "./src/command.js",
+    "./event-handler": "./src/event-handler.js",
+    "./message": "./src/message.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/abofs/stonyx-discord.git"
+  },
+  "author": "Stone Costa",
+  "license": "Apache-2.0",
+  "contributors": [
+    "Stone Costa <stone.costa@synamicd.com>"
+  ],
+  "bugs": {
+    "url": "https://github.com/abofs/stonyx-discord/issues"
+  },
+  "homepage": "https://github.com/abofs/stonyx-discord#readme",
+  "dependencies": {
+    "stonyx": "0.2.3-beta.6",
+    "discord.js": "^14.18.0"
+  },
+  "devDependencies": {
+    "@stonyx/utils": "0.2.3-beta.5",
+    "qunit": "^2.24.1",
+    "sinon": "^21.0.0"
+  },
+  "scripts": {
+    "test": "stonyx test"
+  }
+}

package/src/bot.js

@@ -0,0 +1,214 @@
+import config from 'stonyx/config';
+import log from 'stonyx/log';
+import { Client, GatewayIntentBits, AttachmentBuilder, MessageFlags } from 'discord.js';
+import { forEachFileImport } from '@stonyx/utils/file';
+import { deriveIntents, derivePartials } from './intents.js';
+import { chunkMessage } from './message.js';
+
+export default class DiscordBot {
+  commands = {};
+  eventHandlers = [];
+  ready = new Promise(resolve => { this.resolveReady = resolve; });
+
+  constructor() {
+    if (DiscordBot.instance) return DiscordBot.instance;
+    DiscordBot.instance = this;
+  }
+
+  async init() {
+    const { token } = config.discord;
+
+    if (!token) {
+      log.discord('No DISCORD_TOKEN configured — bot will not start');
+      this.resolveReady();
+      return;
+    }
+
+    await this.discoverCommands();
+    await this.discoverEvents();
+
+    const hasWork = Object.keys(this.commands).length > 0 || this.eventHandlers.length > 0;
+
+    if (!hasWork) {
+      log.discord('No discord commands or event handlers found — skipping bot initialization');
+      this.resolveReady();
+      return;
+    }
+
+    const intents = deriveIntents(this.eventHandlers, config.discord.additionalIntents);
+    const partials = derivePartials(intents, config.discord.additionalPartials);
+
+    if (Object.keys(this.commands).length > 0) {
+      intents.push(GatewayIntentBits.Guilds);
+    }
+
+    this.client = new Client({ intents: [...new Set(intents)], partials });
+    this.registerClientEvents();
+    this.client.login(token);
+
+    await this.ready;
+  }
+
+  registerClientEvents() {
+    const { client } = this;
+
+    client.on('clientReady', () => {
+      this.resolveReady();
+      log.discord('Discord Bot is Ready!');
+    });
+
+    client.on('interactionCreate', async interaction => {
+      if (!interaction.isChatInputCommand()) return;
+
+      const { commandName } = interaction;
+      const command = this.commands[commandName];
+
+      if (!command) {
+        return await interaction.reply({ content: `\`/${commandName}\` is not available`, flags: MessageFlags.Ephemeral });
+      }
+
+      try {
+        await command.execute(interaction);
+      } catch (error) {
+        log.error(error);
+        const reply = { content: 'There was an error executing this command!', flags: MessageFlags.Ephemeral };
+        if (interaction.replied || interaction.deferred) {
+          await interaction.followUp(reply);
+        } else {
+          await interaction.reply(reply);
+        }
+      }
+    });
+
+    for (const handler of this.eventHandlers) {
+      client.on(handler.constructor.event, (...args) => handler.handle(...args));
+    }
+  }
+
+  async discoverCommands() {
+    const { commandDir } = config.discord;
+
+    await forEachFileImport(commandDir, (CommandClass, { name }) => {
+      const instance = new CommandClass();
+
+      if (!instance.data || typeof instance.execute !== 'function') {
+        log.discord(`Command "${name}" is missing data or execute — skipping`);
+        return;
+      }
+
+      instance._bot = this;
+      this.commands[instance.data.name] = instance;
+      log.discord(`Loaded command: /${instance.data.name}`);
+    }, { ignoreAccessFailure: true });
+  }
+
+  async discoverEvents() {
+    const { eventDir } = config.discord;
+
+    await forEachFileImport(eventDir, (EventHandlerClass, { name }) => {
+      if (!EventHandlerClass.event) {
+        log.discord(`Event handler "${name}" is missing static event property — skipping`);
+        return;
+      }
+
+      const instance = new EventHandlerClass();
+      instance._bot = this;
+      this.eventHandlers.push(instance);
+      log.discord(`Loaded event handler: ${EventHandlerClass.event} (${name})`);
+    }, { ignoreAccessFailure: true });
+  }
+
+  async sendMessage(content, channelId, imagePath = null) {
+    const channel = await this.client.channels.fetch(channelId);
+    if (!channel) throw new Error('Invalid Channel ID');
+
+    const options = { content };
+    if (imagePath) {
+      options.files = [new AttachmentBuilder(imagePath)];
+    }
+    return await channel.send(options);
+  }
+
+  async sendFile(file, messageObject) {
+    return await messageObject.edit({
+      content: '',
+      files: [{
+        attachment: file,
+        name: file.split('/').pop()
+      }]
+    });
+  }
+
+  async reply(interaction, content) {
+    if (content.length <= 2000) {
+      if (interaction.deferred || interaction.replied) {
+        return await interaction.editReply({ content });
+      }
+      return await interaction.reply({ content });
+    }
+
+    const [first, ...rest] = chunkMessage('', content);
+
+    if (interaction.deferred || interaction.replied) {
+      await interaction.editReply({ content: first });
+    } else {
+      await interaction.reply({ content: first });
+    }
+
+    for (const chunk of rest) {
+      await interaction.followUp({ content: chunk });
+    }
+  }
+
+  async updateStatus(name, type = 0) {
+    await this.client.user.setPresence({
+      activities: [{ name, type }],
+      status: 'online'
+    });
+  }
+
+  async getChannelMessages(channelId, options = {}) {
+    const channel = await this.client.channels.fetch(channelId);
+    return await channel.messages.fetch({
+      limit: config.discord.maxMessagesPerRequest,
+      ...options
+    });
+  }
+
+  async getChannelMessage(channelId, messageId) {
+    const channel = await this.client.channels.fetch(channelId);
+    return await channel.messages.fetch(messageId);
+  }
+
+  async getGuild(guildId = config.discord.serverId) {
+    return await this.client.guilds.fetch(guildId);
+  }
+
+  async clearChannelMessages(channelId) {
+    const promises = [];
+    const messages = await this.getChannelMessages(channelId);
+    messages.forEach(message => promises.push(message.delete()));
+    return Promise.all(promises);
+  }
+
+  async giveRole(memberId, roleId) {
+    const guild = await this.getGuild();
+    const role = await guild.roles.fetch(roleId);
+    const member = await guild.members.fetch(memberId);
+    await member.roles.add(role);
+  }
+
+  close() {
+    if (this.client) {
+      this.client.destroy();
+      this.client = null;
+    }
+    DiscordBot.instance = null;
+  }
+
+  reset() {
+    this.close();
+    this.commands = {};
+    this.eventHandlers = [];
+  }
+}

package/src/command.js

@@ -0,0 +1,3 @@
+export default class Command {
+  static skipAuth = false;
+}

package/src/event-handler.js

@@ -0,0 +1,3 @@
+export default class EventHandler {
+  static event = null;
+}

package/src/intents.js

@@ -0,0 +1,56 @@
+import { GatewayIntentBits, Partials } from 'discord.js';
+
+const EVENT_INTENT_MAP = {
+  messageCreate:      [GatewayIntentBits.GuildMessages, GatewayIntentBits.DirectMessages, GatewayIntentBits.MessageContent],
+  messageDelete:      [GatewayIntentBits.GuildMessages],
+  messageUpdate:      [GatewayIntentBits.GuildMessages],
+  guildMemberAdd:     [GatewayIntentBits.GuildMembers],
+  guildMemberRemove:  [GatewayIntentBits.GuildMembers],
+  inviteCreate:       [GatewayIntentBits.GuildInvites],
+  inviteDelete:       [GatewayIntentBits.GuildInvites],
+  voiceStateUpdate:   [GatewayIntentBits.GuildVoiceStates],
+  interactionCreate:  [],
+};
+
+const INTENT_PARTIAL_MAP = {
+  [GatewayIntentBits.DirectMessages]: [Partials.Channel],
+};
+
+export function deriveIntents(eventHandlers, additionalIntents = []) {
+  const intents = new Set([GatewayIntentBits.Guilds]);
+
+  for (const handler of eventHandlers) {
+    const event = handler.constructor.event;
+    const required = EVENT_INTENT_MAP[event];
+    if (required) {
+      for (const intent of required) intents.add(intent);
+    }
+  }
+
+  for (const name of additionalIntents) {
+    const intent = GatewayIntentBits[name];
+    if (intent !== undefined) intents.add(intent);
+  }
+
+  return [...intents];
+}
+
+export function derivePartials(intents, additionalPartials = []) {
+  const partials = new Set();
+
+  for (const intent of intents) {
+    const required = INTENT_PARTIAL_MAP[intent];
+    if (required) {
+      for (const partial of required) partials.add(partial);
+    }
+  }
+
+  for (const name of additionalPartials) {
+    const partial = Partials[name];
+    if (partial !== undefined) partials.add(partial);
+  }
+
+  return [...partials];
+}
+
+export { EVENT_INTENT_MAP, INTENT_PARTIAL_MAP };