@stonyx/discord 0.1.1-beta.143 → 0.1.1-beta.145

package/README.md

@@ -23,7 +23,7 @@ pnpm install @stonyx/discord
 
 ## Quick Start
 
-The examples below are complete files: each one imports only from `@stonyx/discord` subpaths, so it runs in an app that depends on nothing but `@stonyx/discord`. The repo's `test/sample/` directory holds a command and an event handler written the same way ([source](https://github.com/abofs/stonyx-discord/tree/dev/test/sample)), and the test suite loads them on every run.
+The examples below are complete files: each one imports only from `@stonyx/discord` subpaths, so it runs in an app that depends on nothing but `@stonyx/discord`. The repo's `test/sample/` directory holds samples written the same way ([source](https://github.com/abofs/stonyx-discord/tree/dev/test/sample)), and the test suite loads and exercises them on every run. See [Samples](#samples) for the list.
 
 ### 1. Create handler directories
 
@@ -87,7 +87,7 @@ stonyx serve
 | `@stonyx/discord/command` | `Command` (default) — base class for slash commands |
 | `@stonyx/discord/event-handler` | `EventHandler` (default) — base class for gateway event handlers |
 | `@stonyx/discord/message` | `chunkMessage` — message chunking helper |
-| `@stonyx/discord/base` | Re-exports of common discord.js classes (`SlashCommandBuilder`, `Client`, `GatewayIntentBits`, `Partials`, ...) |
+| `@stonyx/discord/base` | Re-exports of discord.js: `SlashCommandBuilder`, `EmbedBuilder`, `ActionRowBuilder`, `ButtonBuilder`, `ButtonStyle`, `MessageFlags`, `PermissionFlagsBits`, `AttachmentBuilder`, `REST`, `Routes`, `Client`, `GatewayIntentBits`, `Partials` |
 
 ## Command Architecture
 
@@ -120,6 +120,22 @@ The framework wraps `execute()` in a try/catch. On 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
 
+### Registering commands with Discord
+
+The bot loads your command classes at boot, but it never registers them with Discord. Registration is a separate script you run whenever a command's `data` changes. [`test/sample/scripts/deploy-commands.js`](https://github.com/abofs/stonyx-discord/blob/dev/test/sample/scripts/deploy-commands.js) is a complete one. It loads the command directory and PUTs each command's `data.toJSON()` to `Routes.applicationGuildCommands(applicationId, guildId)` using `REST` from `@stonyx/discord/base`. Guild-scoped commands update immediately, which is what you want in development.
+
+```bash
+DISCORD_TOKEN=... DISCORD_BOT_USER_ID=... DISCORD_SERVER_ID=... node scripts/deploy-commands.js ./discord-commands
+```
+
+### Buttons, autocomplete and other interactions
+
+The bot's own `interactionCreate` listener dispatches only chat-input (slash) commands. Buttons, autocomplete, select menus and modals belong to your app: write an event handler with `static event = 'interactionCreate'`. [`test/sample/discord-events/interaction-create.js`](https://github.com/abofs/stonyx-discord/blob/dev/test/sample/discord-events/interaction-create.js) routes autocomplete to the command's `autocomplete(interaction)` and buttons, by `customId`, to the command's `button(interaction, action, argument)`. It leaves chat-input interactions alone so commands do not run twice.
+
+### Embeds
+
+Build embeds and button rows with `EmbedBuilder`, `ActionRowBuilder`, `ButtonBuilder` and `ButtonStyle` from `@stonyx/discord/base`. [`test/sample/discord-commands/color.js`](https://github.com/abofs/stonyx-discord/blob/dev/test/sample/discord-commands/color.js) replies with an embed and a button, and implements the `autocomplete()` and `button()` methods the router above calls.
+
 ## Event Handler Architecture
 
 ### How handlers are discovered
@@ -341,6 +357,18 @@ Configuration is read from `stonyx/config` under `discord`:
 | `handle(...args)` | Handle the event — define in subclass |
 | `this._bot` | Reference to `DiscordBot` (set during discovery) |
 
+## Samples
+
+Each sample imports only from `@stonyx/discord` subpaths and `node:` builtins, so it can be copied into an app as is. [`test/unit/sample-patterns-test.ts`](https://github.com/abofs/stonyx-discord/blob/dev/test/unit/sample-patterns-test.ts) exercises them with a fake REST client and fake interactions.
+
+| Sample | Shows |
+|--------|-------|
+| [`discord-commands/ping.js`](https://github.com/abofs/stonyx-discord/blob/dev/test/sample/discord-commands/ping.js) | A minimal slash command |
+| [`discord-commands/color.js`](https://github.com/abofs/stonyx-discord/blob/dev/test/sample/discord-commands/color.js) | A command with an embed, a button row, `autocomplete()` and `button()` |
+| [`discord-events/log-message.js`](https://github.com/abofs/stonyx-discord/blob/dev/test/sample/discord-events/log-message.js) | A `messageCreate` handler |
+| [`discord-events/interaction-create.js`](https://github.com/abofs/stonyx-discord/blob/dev/test/sample/discord-events/interaction-create.js) | Routing buttons and autocomplete from `interactionCreate` |
+| [`scripts/deploy-commands.js`](https://github.com/abofs/stonyx-discord/blob/dev/test/sample/scripts/deploy-commands.js) | Registering slash commands, guild-scoped, with `REST` and `Routes` |
+
 ## Example Project Structure
 
 ```
@@ -353,6 +381,8 @@ my-app/
 ├── discord-events/
 │   ├── message-create.js
 │   └── guild-member-add.js
+├── scripts/
+│   └── deploy-commands.js
 ├── package.json
 └── app.js
 ```

package/dist/base.d.ts

@@ -1 +1 @@
-export { SlashCommandBuilder, MessageFlags, PermissionFlagsBits, GatewayIntentBits, AttachmentBuilder, Client, Partials, REST, Routes } from 'discord.js';
+export { SlashCommandBuilder, MessageFlags, PermissionFlagsBits, GatewayIntentBits, AttachmentBuilder, Client, Partials, REST, Routes, EmbedBuilder, ActionRowBuilder, ButtonBuilder, ButtonStyle, } from 'discord.js';

package/dist/base.js

@@ -1 +1 @@
-export { SlashCommandBuilder, MessageFlags, PermissionFlagsBits, GatewayIntentBits, AttachmentBuilder, Client, Partials, REST, Routes } from 'discord.js';
+export { SlashCommandBuilder, MessageFlags, PermissionFlagsBits, GatewayIntentBits, AttachmentBuilder, Client, Partials, REST, Routes, EmbedBuilder, ActionRowBuilder, ButtonBuilder, ButtonStyle, } from 'discord.js';

package/package.json

@@ -4,7 +4,7 @@
     "stonyx-async",
     "stonyx-module"
   ],
-  "version": "0.1.1-beta.143",
+  "version": "0.1.1-beta.145",
   "description": "Discord bot module for the Stonyx framework",
   "main": "dist/main.js",
   "types": "dist/main.d.ts",
@@ -70,7 +70,7 @@
     "@types/sinon": "^21.0.1",
     "qunit": "^2.24.1",
     "sinon": "^21.0.0",
-    "stonyx": "0.2.3-beta.101",
+    "stonyx": "0.2.3-beta.102",
     "tsx": "^4.21.0",
     "typescript": "^5.8.3"
   },