honocord 1.2.0 → 1.2.1

package/README.md

@@ -1,401 +1,433 @@
-# HonoCord
+# Features
 
-A Discord interaction handler library for [Hono](https://hono.dev/), designed to work seamlessly with Cloudflare Workers and other edge runtimes.
+Honocord brings together the power of Discord's Interaction API and Hono's lightweight framework with a focus on developer experience and edge computing.
 
-## Features
+_Yes, AI helped me build this - with the focus on **helped**._
 
-- 🔥 Built on top of Hono for maximum performance
-- ⚡ Perfect for Cloudflare Workers and edge runtimes
-- 🎯 Type-safe interaction handlers
-- 🔐 Built-in request verification
-- 🎨 Support for all Discord interaction types:
-  - Slash commands with autocomplete
-  - User and Message context menu commands
-  - Message components (buttons, select menus)
-  - Modal submissions
-- 🗂️ Prefix-based routing for components and modals
-- 📦 Minimal dependencies using `@discordjs/core` and `@discordjs/builders`
+## 🚀 Core Features
 
-<small>Yes, AI helped me build this. With the focus on **helped**.</small>
+---
 
-## Installation
+### Type-Safe Development
 
-```bash
-pnpm add honocord@latest
+Full TypeScript support throughout the entire stack:
+
+- **End-to-End Types** - From handlers to Discord API responses
+- **Autocomplete & IntelliSense** - IDE support for all methods and properties
+- **Type Guards** - Runtime type checking with TypeScript inference
+- **Custom Environment Types** - Extend with your own bindings and variables
+
+```typescript
+// TypeScript knows the exact type
+const name = interaction.options.getString("name", true); // string
+const count = interaction.options.getInteger("count"); // number | null
+
+if (interaction.inGuild()) {
+  const guildId = interaction.guildId; // TypeScript knows this exists
+}
 ```
 
-The most important stuff from the dependencies is already exported through honocord itselfy but if you need more from `discord-api-types` for example, you should install it yourself as well.
+---
+
+### Handler-Based Architecture
 
-## Quick Start
+Clean, modular code organization:
 
 ```typescript
-import { Honocord, SlashCommandHandler } from "honocord";
+// Define handlers separately
+const pingCommand = new SlashCommandHandler()
+  .setName("ping")
+  .setDescription("Pong!")
+  .addHandler(async (interaction) => {
+    await interaction.reply("🏓 Pong!");
+  });
 
-const bot = new Honocord();
+// Load them together
+bot.loadHandlers(pingCommand, greetCommand, buttonHandler);
+```
 
-// Define a slash command
-const pingCommand = new SlashCommandHandler().setName("ping").setDescription("Replies with Pong!");
+**Benefits:**
 
-// Add handler to the command
-pingCommand.addHandler(async (interaction) => {
-  await interaction.reply("Pong! 🏓");
-});
+- **Separation of Concerns** - Each handler is self-contained
+- **Easy Testing** - Test handlers in isolation
+- **Reusability** - Share handlers across projects
+- **Hot Reloading** - Change handlers without restarting (in dev mode)
 
-// Register handlers
-bot.loadHandlers(pingCommand);
+---
 
-// Export the app
-export default bot.getApp();
+## 💬 Interaction Support
 
-// Or use with your own Hono app
-import { Hono } from "hono";
+### Slash Commands
 
-const app = new Hono();
+Full-featured slash command support:
+
+- **Options & Validation** - String, integer, boolean, user, role, channel, and more
+- **Subcommands & Groups** - Organize complex command structures
+- **Required & Optional** - Fine-grained control over user input
+- **Autocomplete** - Real-time suggestions as users type
+
+```typescript
+const searchCommand = new SlashCommandHandler()
+  .setName("search")
+  .setDescription("Search for items")
+  .addStringOption((option) =>
+    option.setName("query").setDescription("What to search for").setAutocomplete(true).setRequired(true)
+  )
+  .addHandler(handleSearch)
+  .addAutocompleteHandler(handleAutocomplete);
 ```
 
-## Usage with and without Cloudflare Workers
+---
 
-Hono, well rather CF Workers, have a small issue with responding to interactions.
+### Context Menus
 
-When using HonoCord in a Cloudflare Worker environment, you should ensure that your environment variable `IS_CF_WORKER` is set to `"true"` **or** you pass this information to HonoCord in the constructor:
+Right-click context menu commands:
+
+- **User Commands** - Actions on users (ban, view profile, etc.)
+- **Message Commands** - Actions on messages (report, translate, etc.)
 
 ```typescript
-const bot = new Honocord({ isCFWorker: true }); // true indicates CF Worker environment
+const reportUser = new ContextCommandHandler()
+  .setName("Report User")
+  .setType(ApplicationCommandType.User)
+  .addHandler(async (interaction) => {
+    const user = interaction.targetUser;
+    // Handle report...
+  });
 ```
 
-<details>
-    <summary>Why that is needed?</summary>
+---
 
-On Cloudflare Workers, we need to make use of `c.executionContext.waitUntil()` to handle asynchronous tasks properly without blocking the response. By checking for the `IS_CF_WORKER` environment variable, HonoCord can determine if it's running in a Cloudflare Worker environment and adjust its behavior accordingly.
+### Message Components
 
-This approach allows HonoCord to maintain compatibility with both Cloudflare Workers and other environments, ensuring that interactions are handled correctly regardless of where the code is executed.
+Interactive buttons and select menus:
 
-</details>
+- **Buttons** - Primary, secondary, success, danger, link styles
+- **Select Menus** - String, user, role, channel, mentionable options
+- **Prefix Matching** - One handler for multiple related components
+- **Parameter Passing** - Pass data through custom IDs
 
-> [!IMPORTANT]
-> This readme assumes you are using Cloudflare Workers.
-> Most stuff is the same for other environments, but keep in mind the `IS_CF_WORKER` variable and the way you export and use your Hono app.
+```typescript
+// Create a button
+new ButtonBuilder().setCustomId("confirm/action?1234567890").setLabel("Confirm").setStyle(ButtonStyle.Success);
+
+// Handle with prefix matching
+const confirmHandler = new ComponentHandler("confirm").addHandler(async (interaction) => {
+  const { firstParam } = parseCustomId(interaction.custom_id);
+  // Use param...
+});
+```
+
+---
+
+### Modals (Forms)
 
-## Philosophy - How It Works
+Full modal/form support:
 
-HonoCord leverages Hono's lightweight and fast request handling capabilities to process Discord interactions efficiently. It verifies incoming requests using Discord's public key, ensuring security and authenticity.
+- **Text Inputs** - Short and paragraph styles
+- **Validation** - Min/max length, required fields
+- **Field Access** - Type-safe field resolution
+- **Flexible Triggers** - Show from commands or components
 
-To handle interactions, you define various handler types (slash commands, context commands, components, modals) and register them with the `Honocord` instance. Each handler processes its respective interaction type.
+```typescript
+await interaction.showModal(
+  new ModalBuilder({
+    custom_id: "feedback",
+    title: "Send Feedback",
+  }).addLabelComponents(
+    new LabelBuilder()
+      .setLabel("Your Feedback")
+      .setTextInputComponent((input) => input.setCustomId("message").setStyle(TextInputStyle.Paragraph).setRequired(true))
+  )
+);
+```
 
-### Custom IDs
+---
 
-Custom IDs for components and modals use a **prefix-based routing system**, allowing you to easily manage multiple interactions with shared logic.
+## 🔧 Developer Experience
 
-Custom IDs follow the pattern: `prefix/component/path?param1/param2`
+### Minimal Boilerplate
 
-As you can see, it is basically split into two parts: a **path** and **parameters**.
-Both parts are separated by a `?`, and each part is further divided by `/` (every path-segment and param). However, the `prefix` defines which handler will process the interaction.
+_Well, I tried at least..._
 
-Use the `parseCustomId` utility to parse custom IDs:
+Get started in seconds:
 
 ```typescript
-import { parseCustomId } from "honocord";
+import { Honocord, SlashCommandHandler } from "honocord";
 
-// Example: "approve/user/request?user123/action456"
-const parsed = parseCustomId("approve/user/request?user123/action456");
+const bot = new Honocord();
 
-console.log(parsed.prefix); // "approve"
-console.log(parsed.component); // "user"
-console.log(parsed.lastPathItem); // "request"
-console.log(parsed.compPath); // ["approve", "user", "request"]
-console.log(parsed.params); // ["user123", "action456"]
-console.log(parsed.firstParam); // "user123"
-console.log(parsed.lastParam); // "action456"
+bot.loadHandlers(
+  new SlashCommandHandler()
+    .setName("ping")
+    .setDescription("Pong!")
+    .addHandler(async (i) => await i.reply("Pong!"))
+);
 
-// Get only the prefix
-const prefix = parseCustomId("approve/user/request?user123", true); // "approve"
+export default bot.getApp();
 ```
 
-## Handlers
+---
 
-### 1. Slash Command Handler
+### Built-in Utilities
 
-Slash commands are the primary way users interact with your bot. They support autocomplete for option values.
+Helpful utilities included:
+
+**Custom ID Parser:**
 
 ```typescript
-import { SlashCommandHandler } from "honocord";
+const { prefix, component, params } = parseCustomId("action/button?user123");
+```
 
-const searchCommand = new SlashCommandHandler()
-  .setName("search")
-  .setDescription("Search for something")
-  .addStringOption((option) =>
-    option.setName("query").setDescription("What to search for").setRequired(true).setAutocomplete(true)
-  )
-  .addHandler(async (interaction) => {
-    const query = interaction.options.getString("query", true);
-    await interaction.reply(`Searching for: ${query}`);
-  })
-  .addAutocompleteHandler(async (interaction) => {
-    const focusedValue = interaction.options.getFocused();
-    const choices = ["apple", "banana", "cherry", "dragon fruit", "elderberry"]
-      .filter((choice) => choice.startsWith(focusedValue.toLowerCase()))
-      .slice(0, 25); // Discord limits to 25 choices
-
-    await interaction.respond(choices.map((choice) => ({ name: choice, value: choice })));
-  });
+**Autocomplete Helper:**
 
-bot.loadHandlers(searchCommand);
+```typescript
+const autocompleteResponse = new AutocompleteHelper("query", interaction.user)
+  .addChoices({ name: "Option 1", value: "opt1" })
+  .response(); // Automatically filters
+await interaction.respond(autocompleteResponse); // Sends filtered choices
 ```
 
-### 2. Context Command Handler
+**Color Constants:**
+
+```typescript
+import { Colors } from "honocord";
+
+const embed = new EmbedBuilder().setColor(Colors.Blue);
+```
 
-Context commands appear in the right-click menu for users or messages.
+**Command Registration:**
 
 ```typescript
-import { ContextCommandHandler } from "honocord";
-import { ApplicationCommandType } from "discord-api-types/v10";
+await registerCommands(token, appId, ...handlers);
+// You can also pass a single array
+await registerCommands(token, appId, handlers);
+```
 
-// User context command
-const userInfoCommand = new ContextCommandHandler().setName("User Info").setType(ApplicationCommandType.User);
+---
 
-userInfoCommand.addHandler(async (interaction) => {
-  const user = interaction.targetUser;
-  await interaction.reply(`User: ${user.username} (${user.id})`);
-});
+### Flexible Integration
 
-// Message context command
-const translateCommand = new ContextCommandHandler().setName("Translate").setType(ApplicationCommandType.Message);
+Use Honocord your way:
 
-translateCommand.addHandler(async (interaction) => {
-  const message = interaction.targetMessage;
-  await interaction.reply(`Translating: "${message.content}"`);
-});
+**Standalone App:**
 
-bot.loadHandlers(userInfoCommand, translateCommand);
+```typescript
+const bot = new Honocord();
+export default bot.getApp();
 ```
 
-### 3. Component Handler
-
-Component handlers handle interactions from buttons, select menus, and other message components. They use a **prefix-based routing system**.
+**Custom Hono Integration:**
 
 ```typescript
-import { ComponentHandler } from "honocord";
-import { ButtonBuilder, ButtonStyle, ActionRowBuilder } from "@discordjs/builders";
-
-// Create a button with a custom_id using a prefix
-const button = new ButtonBuilder()
-  .setCustomId("approve/user123") // prefix: "approve"
-  .setLabel("Approve")
-  .setStyle(ButtonStyle.Success);
-
-// Handler for all components with the "approve" prefix
-const approveHandler = new ComponentHandler("approve", async (interaction) => {
-  // Parse the custom_id to get parameters
-  const { params } = parseCustomId(interaction.customId);
-  const userId = params[0]; // "user123"
-
-  await interaction.reply(`Approved user: ${userId}`);
-});
+const app = new Hono();
+app.get("/", (c) => c.text("Hello"));
+app.post("/interactions", bot.handle);
+```
+
+**With Middleware:**
 
-bot.loadHandlers(approveHandler);
+```typescript
+app.use("*", logger());
+app.use("*", cors());
+app.post("/interactions", bot.handle);
 ```
 
-### 4. Modal Handler
+---
 
-Modal handlers process form submissions. Like components, they use prefix-based routing.
+## 🔐 Security
 
-```typescript
-import { ModalHandler } from "honocord";
-import { ModalBuilder, TextInputBuilder, TextInputStyle, ActionRowBuilder } from "@discordjs/builders";
-
-// Create a modal
-const modal = new ModalBuilder()
-  .setCustomId("feedback/feature") // prefix: "feedback"
-  .setTitle("Feature Feedback");
-
-// ActionRows in modals are deprecated and should not be used because Honocord doesn't process them!
-const input = new LabelBuilder()
-  .setLabel("What would you like to see?")
-  .setTextInputComponent(
-    new TextInputBuilder()
-    .setCustomId("feedback_text")
-    .setStyle(TextInputStyle.Paragraph)
-    .setRequired(true)
-  );
-
-modal.addLabelComponents(input);
-
-// Handler for all modals with the "feedback" prefix
-const feedbackHandler = new ModalHandler("feedback", async (interaction) => {
-  const { component } = parseCustomId(interaction.customId);
-  const feedbackText = interaction.fields.getTextInputValue("feedback_text");
-
-  await interaction.reply({
-    content: `Thanks for your ${component} feedback: "${feedbackText}"`,
-    ephemeral: true,
-  });
-});
+### Automatic Signature Verification
 
-bot.loadHandlers(feedbackHandler);
-```
+Every request is automatically verified by the same logic [discord-interactions](https://github.com/discord/discord-interactions-js) has (without the extra dependency).
+
+---
 
-## Complete Example
+### Environment-Based Configuration
 
-Please refer to the [Examples](https://github.com/The-LukeZ/honocord-examples) repository for complete working examples, including deployment to Cloudflare Workers.
+Keep secrets secure:
 
-## Environment Variables
+```typescript
+// Access through context
+const token = interaction.context.env.DISCORD_TOKEN;
 
-```env
-DISCORD_APPLICATION_ID=your_application_id_here # only required for command registration
-DISCORD_TOKEN=your_bot_token_here # always required
-DISCORD_PUBLIC_KEY=your_public_key_here # always required
-IS_CF_WORKER=true # only required if using Cloudflare Workers
+// Never hardcoded
+const bot = new Honocord(); // Uses env vars automatically
 ```
 
-The `DISCORD_PUBLIC_KEY` is required for request verification and should be available in your environment (e.g., `c.env.DISCORD_PUBLIC_KEY` in Cloudflare Workers).
+---
 
-## TypeScript Support
+## ⚡ Performance
 
-HonoCord is written in TypeScript and provides full type safety.
+### Efficient Routing
 
-### Custom Environment Types
+Optimized handler lookup:
 
-```typescript
-// src/types.ts
-import type { BaseHonocordEnv, BaseInteractionContext } from "honocord";
-
-type MyEnv = {
-  MY_VARIABLE: string;
-};
-
-export type HonoEnv = BaseHonocordEnv<MyEnv>;
-export type MyContext = BaseInteractionContext<MyEnv>;
-
-// src/index.ts
-import type { BaseHonocordEnv, BaseInteractionContext } from "honocord";
-import type { HonoEnv, MyContext } from "./types";
-
-// Use in your handlers
-const command = new SlashCommandHandler()
-  .setName("data")
-  .setDescription("Fetch data")
-  .addHandler(async (interaction: MyContext) => {
-    const myVariable = interaction.env.MY_VARIABLE; // Fully typed!
-    // ...
-  });
-```
+- **Commands, Components and Modals**: O(1) hash map lookup by name/custom_id-prefix
+- **Minimal Overhead**: Direct API access, no unnecessary layers (except the discordjs API wrapper and REST client)
 
-## Registering Commands
+---
 
-You can register your commands using the `registerCommands()` utility function.
+### Deferred Responses
+
+Handle long-running operations:
 
 ```typescript
-// src/handlers/index.ts
-export * from "./pingCommand";
-export * from "./approveHandler";
-// ...export other handlers
+await interaction.deferReply();
 
-// src/register.ts
-import { registerCommands } from "honocord";
-import * as handlers from "./handlers/index";
+// Do expensive work
+await processLargeDataset();
 
-await registerCommands(process.env.DISCORD_TOKEN!, process.env.DISCORD_APPLICATION_ID!, ...Object.values(handlers));
+// Update when ready
+await interaction.editReply("Complete!");
 ```
 
-You should add the script to your package.json:
+---
 
-```json
-{
-  "scripts": {
-    // tsx is recommended for running TypeScript files directly, but you can use any method you prefer, even node itself if you use a JS file.
-    "register": "tsx --env-file=.env src/register.ts"
-  }
-}
+### Ephemeral Messages
+
+Reduce server clutter:
+
+```typescript
+// Only visible to user
+await interaction.reply("Secret info", true);
 ```
 
-## API Reference
+---
+
+## 🎨 Rich Content
 
-### `Honocord`
+### Discord.js Builders
 
-Main class for handling Discord interactions.
+Re-exports most important builders like EmbedBuilder and Components V2 Builders.
 
-**Constructor:**
+```typescript
+import { EmbedBuilder, ActionRowBuilder, ButtonBuilder } from "honocord";
+
+const embed = new EmbedBuilder().setTitle("Hello!").setColor(Colors.Blue).setDescription("Welcome to the server");
 
-- `new Honocord(options?: HonocordOptions)` - Creates a new instance
+const row = new ActionRowBuilder<ButtonBuilder>().addComponents(
+  new ButtonBuilder().setCustomId("welcome").setLabel("Get Started").setStyle(1) // Primary Style
+);
 
-**Methods:**
+await interaction.reply({
+  embeds: [embed],
+  components: [row],
+});
 
-- `loadHandlers(handlers: Handler[])` - Registers interaction handlers
-- `handle(c: Context)` - Hono handler for processing interactions
-- `getApp()` - Returns a pre-configured Hono app instance
-  - Route: `POST /interactions` - Handles Discord interaction requests
-  - Route: `GET *` - Displays a generic "Is Running" text.
+// Or with Components V2
+import { ContainerBuilder, TextDisplayBuilder, Colors } from "honocord";
 
-### `SlashCommandHandler`
+const container = new ContainerBuilder().setAccentColor(Colors.Green).addTextDisplayComponents(
+  new TextDisplayBuilder().setContent("# Hello, world!");
+)
 
-Extends `SlashCommandBuilder` from `@discordjs/builders`.
+await interaction.reply({
+  components: [container],
+});
+```
 
-**Methods:**
+You don't need to call `.toJSON()` manually - Honocord does it for you. Discord.js inspired.
 
-- `addHandler(handler: (interaction: ChatInputCommandInteraction) => Promise<void> | void)` - Adds the command execution handler
-- `addAutocompleteHandler(handler: (interaction: AutocompleteInteraction) => Promise<void> | void)` - Adds an optional autocomplete handler
+---
 
-### `ContextCommandHandler`
+## 🌍 Deployment Options
 
-Extends `ContextMenuCommandBuilder` from `@discordjs/builders`.
+### Cloudflare Workers
 
-**Constructor:**
+Deploy globally in seconds:
 
-```ts
-new ContextCommandHandler<
-  T extends ContextCommandType = ContextCommandType,
-  InteractionData = T extends ContextCommandType.User ? UserContextInteraction : MessageContextInteraction,
-  > ()
+```bash
+wrangler deploy
 ```
 
-`ContextCommandType` is an enum with values `User` and `Message`; Derived from ApplicationCommandType, but narrowed down to the two context command types.
+Cloudflare Workers has some unique configurations that Honocord needs to function. See the [Cloudflare Workers Deployment Guide](/wiki/Deployment-Guide#cloudflare-workers) for details.
+
+---
+
+### Traditional Servers
+
+Works anywhere Node.js runs:
 
-**Methods:**
+```bash
+node index.js
+# or
+bun run index.ts
+```
 
-- `addHandler(handler: (interaction: InteractionData) => Promise<void> | void)` - Adds the command execution handler
+---
 
-### `ComponentHandler`
+### Docker
 
-Handler for message components.
+Containerize your bot:
 
-**Constructor:**
+```dockerfile
+FROM oven/bun:1
+COPY . .
+RUN bun install
+CMD ["bun", "run", "index.ts"]
+```
 
-- `new ComponentHandler<T extends MessageComponentType = MessageComponentType>(prefix: string, handler?: Function)` - Creates a handler for components with the given prefix
+---
 
-`MessageComponentType` is a union of `ComponentType` values that represent message components (e.g., Button, StringSelectMenu).
+## 📦 Lightweight
 
-**Methods:**
+### Minimal Dependencies
 
-- `addHandler(handler: (interaction: MessageComponentInteraction<T>) => Promise<void> | void)` - Adds or replaces the component handler function
+Honocord only requires:
 
-### `ModalHandler`
+- `hono` - Web framework
+- `discord-api-types` - Type definitions
+- `@discordjs/core` - API wrapper
+- `@discordjs/rest` - HTTP REST client
+- `@discordjs/builders` - Builders
 
-Handler for modal submissions.
+---
 
-**Constructor:**
+### TypeScript First
 
-- `new ModalHandler(prefix: string, handler?: Function)` - Creates a handler for modals with the given prefix
+Written in TypeScript, designed for TypeScript:
 
-**Methods:**
+- Source maps included
+- Full type inference
+- JSDoc comments
+- Declaration files
 
-- `addHandler(handler: (interaction: ModalInteraction) => Promise<void> | void)` - Adds or replaces the modal submit handler function
+---
 
-### `parseCustomId`
+### Extensible
 
-Utility function for parsing custom IDs.
+Extend with custom types:
 
 ```typescript
-// Get full parsing details
-parseCustomId(customId: string): ParsedCustomId
+interface MyEnv {
+  DATABASE: D1Database;
+  CACHE: KVNamespace;
+}
+
+type MyContext = BaseInteractionContext<MyEnv>;
 
-// Get only the prefix
-parseCustomId(customId: string, onlyPrefix: true): string
+// Now fully typed in handlers
+new SlashCommandHandler<MyContext>().addHandler(async (interaction) => {
+  const db = interaction.context.env.DATABASE;
+  const cache = interaction.context.env.CACHE;
+});
 ```
 
-## License
+---
 
-MIT
+### Rate Limit Handling
 
-## Contributing
+Respects Discord rate limits automatically via `@discordjs/rest`.
 
-Contributions are welcome! Please feel free to submit a Pull Request.
+---
+
+### Monitoring
+
+Built-in debug logging:
+
+```typescript
+const bot = new Honocord({
+  debugRest: true, // Log all REST requests
+});
+```