stoatx 0.2.1 → 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stoatx
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -35,41 +35,33 @@ Make sure to enable decorators in your `tsconfig.json`:
 
 ```typescript
 // index.ts
-import 'reflect-metadata';
-import { Client } from 'stoat.js';
-import { MallyHandler } from 'stoatx';
+import "reflect-metadata";
+import { Client } from "stoatx";
 
-const client = new Client();
-
-const handler = new MallyHandler({
-    client, 
-    prefix: '!', 
-    owners: ['your-user-id']
+const client = new Client({
+  prefix: "!",
+  owners: ["your-user-id"],
 });
 
-await handler.init();
-
-client.on('messageCreate', (message) => {
-  handler.handleMessage(message);
-});
+await client.initCommands();
 
-client.login('your-token');
+client.login("your-token");
 ```
 
 ### 2. Create commands
 
 ```typescript
 // commands/general.ts
-import { Stoat, SimpleCommand, Context } from 'stoatx';
+import { Stoat, SimpleCommand, Context } from "stoatx";
 
 @Stoat()
 export class GeneralCommands {
-  @SimpleCommand({ name: 'ping', description: 'Check bot latency' })
+  @SimpleCommand({ name: "ping", description: "Check bot latency" })
   async ping(ctx: Context) {
     await ctx.reply(`Pong! 🏓`);
   }
 
-  @SimpleCommand({ name: 'hello', aliases: ['hi', 'hey'] })
+  @SimpleCommand({ name: "hello", aliases: ["hi", "hey"] })
   async hello(ctx: Context) {
     await ctx.reply(`Hello, <@${ctx.authorId}>!`);
   }
@@ -115,25 +107,25 @@ async ban(ctx: Context) {
 Adds a guard check before command execution.
 
 ```typescript
-import { Stoat, SimpleCommand, Guard, MallyGuard, Context } from 'stoatx';
+import { Stoat, SimpleCommand, Guard, MallyGuard, Context } from "stoatx";
 
 // Define a guard
 class IsAdmin implements MallyGuard {
   run(ctx: Context): boolean {
-    return ctx.message.member?.hasPermission('Administrator') ?? false;
+    return ctx.message.member?.hasPermission("Administrator") ?? false;
   }
 
   guardFail(ctx: Context): void {
-    ctx.reply('You need Administrator permission!');
+    ctx.reply("You need Administrator permission!");
   }
 }
 
 @Stoat()
 @Guard(IsAdmin)
 export class AdminCommands {
-  @SimpleCommand({ name: 'shutdown' })
+  @SimpleCommand({ name: "shutdown" })
   async shutdown(ctx: Context) {
-    await ctx.reply('Shutting down...');
+    await ctx.reply("Shutting down...");
   }
 }
 ```
@@ -144,16 +136,16 @@ The `Context` object provides:
 
 ```typescript
 interface Context {
-  client: Client;          // Stoat client instance
-  message: Message;        // Original message
-  content: string;         // Raw message content
-  authorId: string;        // Author's user ID
-  channelId: string;       // Channel ID
-  serverId?: string;       // Server/Guild ID
-  args: string[];          // Parsed arguments
-  prefix: string;          // Prefix used
-  commandName: string;     // Command name used
-  
+  client: Client; // Stoat client instance
+  message: Message; // Original message
+  content: string; // Raw message content
+  authorId: string; // Author's user ID
+  channelId: string; // Channel ID
+  serverId?: string; // Server/Guild ID
+  args: string[]; // Parsed arguments
+  prefix: string; // Prefix used
+  commandName: string; // Command name used
+
   reply(content: string): Promise<void>;
 }
 ```
@@ -161,17 +153,17 @@ interface Context {
 ## Handler Options
 
 ```typescript
-interface MallyHandlerOptions {
+interface StoatxHandlerOptions {
   client: Client;
-  commandsDir?: string;          // Legacy mode: explicitly scan this directory
+  commandsDir?: string; // Legacy mode: explicitly scan this directory
   discovery?: {
-    roots?: string[];            // Default: [process.cwd()]
-    include?: string[];          // Glob patterns per root
-    ignore?: string[];           // Additional ignore globs
+    roots?: string[]; // Default: [process.cwd()]
+    include?: string[]; // Glob patterns per root
+    ignore?: string[]; // Additional ignore globs
   };
-  prefix: string | ((ctx: { serverId?: string }) => string | Promise<string>);
-  owners?: string[];             // Owner user IDs
-  extensions?: string[];         // File extensions (default: ['.js', '.mjs', '.cjs'])
+  prefix: string  ((ctx: { serverId?: string }) => string  Promise<string>);
+  owners?: string[]; // Owner user IDs
+  extensions?: string[]; // File extensions (default: ['.js', '.mjs', '.cjs'])
   disableMentionPrefix?: boolean; // Disable @bot prefix
 }
 
@@ -182,31 +174,28 @@ interface MallyHandlerOptions {
 ## Dynamic Prefix
 
 ```typescript
-const handler = new MallyHandler({
-  client,
+const client = new Client({
   prefix: async ({ serverId }) => {
     // Fetch from database, etc.
-    return serverId ? await getServerPrefix(serverId) : '!';
+    return serverId ? await getServerPrefix(serverId) : "!";
   },
 });
 
 // Optional: constrain auto-discovery to specific roots/patterns
-const scopedHandler = new MallyHandler({
-  client,
-  prefix: '!',
+const scopedClient = new Client({
+  prefix: "!",
   discovery: {
     roots: [process.cwd()],
-    include: ['apps/bot/dist/commands/**/*.js'],
+    include: ["apps/bot/dist/commands/**/*.js"],
   },
 });
 
 // TypeScript source discovery is opt-in and requires a TS runtime loader (tsx/ts-node)
-const tsRuntimeHandler = new MallyHandler({
-  client,
-  prefix: '!',
-  extensions: ['.ts'],
+const tsRuntimeClient = new Client({
+  prefix: "!",
+  extensions: [".ts"],
   discovery: {
-    include: ['apps/bot/src/commands/**/*.ts'],
+    include: ["apps/bot/src/commands/**/*.ts"],
   },
 });
 ```
@@ -216,6 +205,3 @@ All commands are defined through `@Stoat()` classes and `@SimpleCommand()` metho
 ## License
 
 AGPL-3.0-or-later
-
-
-

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { Client, Message } from 'stoat.js';
+import { Client as Client$1, Message } from 'stoat.js';
 
 /**
  * Permission types for commands
@@ -44,7 +44,7 @@ interface CommandMetadata {
  */
 interface CommandContext {
     /** The client instance */
-    client: Client;
+    client: Client$1;
     /** The raw message content */
     content: string;
     /** The author ID */
@@ -60,7 +60,7 @@ interface CommandContext {
     /** The command name used (could be an alias) */
     commandName: string;
     /** Reply to the message */
-    reply: (content: string) => Promise<void>;
+    reply: (content: string) => Promise<Message>;
     /** The original message object (platform-specific) */
     message: Message;
 }
@@ -73,14 +73,14 @@ interface StoatLifecycle {
     /** Optional: Called when a cooldown is active */
     onCooldown?(ctx: CommandContext, remaining: number): Promise<void>;
 }
-interface MallyGuard {
+interface StoatxGuard {
     run(ctx: CommandContext): Promise<boolean> | boolean;
     guardFail?(ctx: CommandContext): Promise<void> | void;
 }
 /**
  * Discovery options for automatic command module loading
  */
-interface MallyDiscoveryOptions {
+interface StoatxDiscoveryOptions {
     /** Root directories to scan (default: [process.cwd()]) */
     roots?: string[];
     /** Glob patterns relative to each root */
@@ -91,13 +91,13 @@ interface MallyDiscoveryOptions {
 /**
  * Handler options
  */
-interface MallyHandlerOptions {
+interface StoatxHandlerOptions {
     /** The client instance */
-    client: Client;
+    client: Client$1;
     /** Directory to scan for command modules (absolute path) */
     commandsDir?: string;
     /** Auto-discovery options used when commandsDir is not provided */
-    discovery?: MallyDiscoveryOptions;
+    discovery?: StoatxDiscoveryOptions;
     /** Command prefix or prefix resolver function */
     prefix: string | ((ctx: {
         serverId?: string;
@@ -183,7 +183,7 @@ declare function getSimpleCommands(target: Function): SimpleCommandDefinition[];
  * import { Guard, Stoat, SimpleCommand, CommandContext } from 'stoatx';
  *
  * // Define a guard
- * class NotBot implements MallyGuard {
+ * class NotBot implements StoatxGuard {
  *   run(ctx: CommandContext): boolean {
  *     return !ctx.message.author.bot;
  *   }
@@ -209,6 +209,60 @@ declare function Guard(guardClass: Function): ClassDecorator;
  */
 declare function getGuards(target: Function): Function[];
 
+interface EventDefinition {
+    methodName: string;
+    event: string;
+    type: "on" | "once";
+}
+/**
+ * @On
+ * Triggered on every occurrence of the event.
+ * Marks a method to be executed whenever the specified client event is emitted.
+ *
+ * @example
+ * ```ts
+ * import { Stoat, On } from 'stoatx';
+ * import { Message, Client } from 'stoat.js';
+ *
+ * @Stoat()
+ * class BotEvents {
+ *   @On('messageCreate')
+ *   async onMessage(message: Message, client: Client) {
+ *     console.log('New message received:', message.content);
+ *   }
+ * }
+ * ```
+ *
+ * @param event The name of the client event to listen to
+ */
+declare function On(event: string): MethodDecorator;
+/**
+ * @Once
+ * Triggered only fully once.
+ * Marks a method to be executed only the FIRST time the specified client event is emitted.
+ *
+ * @example
+ * ```ts
+ * import { Stoat, Once } from 'stoatx';
+ * import { Client } from 'stoat.js';
+ *
+ * @Stoat()
+ * class BotEvents {
+ *   @Once('ready')
+ *   async onReady(client: Client) {
+ *     console.log('Bot successfully started and logged in!');
+ *   }
+ * }
+ * ```
+ *
+ * @param event The name of the client event to listen to
+ */
+declare function Once(event: string): MethodDecorator;
+/**
+ * Get all event definitions from a @Stoat class
+ */
+declare function getEventsMetadata(target: Function): EventDefinition[];
+
 /**
  * Build CommandMetadata from SimpleCommandOptions
  */
@@ -220,7 +274,8 @@ declare function buildSimpleCommandMetadata(options: SimpleCommandOptions, metho
 declare const METADATA_KEYS: {
     readonly IS_STOAT_CLASS: symbol;
     readonly SIMPLE_COMMANDS: symbol;
-    readonly GUARDS: "mally:command:guards";
+    readonly GUARDS: "stoatx:command:guards";
+    readonly EVENTS: symbol;
 };
 
 interface AutoDiscoveryOptions {
@@ -241,6 +296,15 @@ interface RegisteredCommand {
     /** The original class constructor (for guard validation) */
     classConstructor: Function;
 }
+/**
+ * Stored event entry from @On/@Once registration.
+ */
+interface RegisteredEvent {
+    instance: object;
+    methodName: string;
+    event: string;
+    type: "on" | "once";
+}
 /**
  * CommandRegistry - Scans directories and stores commands in a Map
  *
@@ -257,6 +321,7 @@ declare class CommandRegistry {
     private static readonly DEFAULT_AUTO_DISCOVERY_IGNORES;
     private readonly commands;
     private readonly aliases;
+    private readonly registeredEvents;
     private readonly extensions;
     private readonly processedStoatClasses;
     constructor(extensions?: string[]);
@@ -294,6 +359,10 @@ declare class CommandRegistry {
      * Get all command metadata
      */
     getAllMetadata(): CommandMetadata[];
+    /**
+     * Get all registered events
+     */
+    getEvents(): RegisteredEvent[];
     /**
      * Get commands grouped by category
      */
@@ -333,44 +402,53 @@ declare class CommandRegistry {
 }
 
 /**
- * MallyHandler - The execution engine for commands
- *
- * Handles message parsing, middleware execution, and command dispatching
+ * Client - An extended Client that integrates StoatxHandler directly
  *
  * @example
  * ```ts
- * import { MallyHandler } from 'stoatx';
- * import { Client } from 'stoat.js';
- *
- * const client = new Client();
+ * import { Client } from 'stoatx';
  *
- * const handler = new MallyHandler({
- *   client,
+ * const client = new Client({
  *   prefix: '!',
  *   owners: ['owner-user-id'],
  * });
  *
- * await handler.init();
- *
- * client.on('message', (message) => {
- *   handler.handleMessage(message);
- * });
+ * await client.initCommands();
  * ```
  */
-declare class MallyHandler {
-    private readonly commandsDir?;
-    private readonly discoveryOptions?;
+declare class Client extends Client$1 {
+    readonly handler: StoatxHandler;
+    constructor(options: Omit<StoatxHandlerOptions, "client">);
+    /**
+     * Initialize the StoatxHandler commands
+     */
+    initCommands(): Promise<void>;
+}
+/**
+ * StoatxHandler - The execution engine for commands
+ *
+ * Handles message parsing, middleware execution, and command dispatching
+ *
+ * @internal This class is not intended to be instantiated directly. Use the `Client` from `stoatx` instead.
+ */
+declare class StoatxHandler {
+    private readonly commandsDir;
+    private readonly discoveryOptions;
     private readonly prefixResolver;
     private readonly owners;
     private readonly registry;
     private readonly cooldowns;
     private readonly disableMentionPrefix;
     private readonly client;
-    constructor(options: MallyHandlerOptions);
+    constructor(options: StoatxHandlerOptions);
     /**
      * Initialize the handler - load all commands
      */
     init(): Promise<void>;
+    /**
+     * Attach registered events to the client
+     */
+    private attachEvents;
     /**
      * Parse a raw message into command context
      */
@@ -378,7 +456,7 @@ declare class MallyHandler {
         authorId: string;
         channelId: string;
         serverId?: string;
-        reply: (content: string) => Promise<void>;
+        reply: (content: string) => Promise<Message>;
     }): Promise<CommandContext | null>;
     /**
      * Handle a message object using the configured message adapter
@@ -412,7 +490,7 @@ declare class MallyHandler {
         authorId: string;
         channelId: string;
         serverId?: string;
-        reply: (content: string) => Promise<void>;
+        reply: (content: string) => Promise<Message>;
     }): Promise<boolean>;
     /**
      * Execute a command with the given context
@@ -464,4 +542,4 @@ declare class MallyHandler {
     private setCooldown;
 }
 
-export { type CommandContext, type CommandMetadata, CommandRegistry, type CommandContext as Context, Guard, METADATA_KEYS, type MallyDiscoveryOptions, type MallyGuard, MallyHandler, type MallyHandlerOptions, type Permission, type RegisteredCommand, SimpleCommand, type SimpleCommandDefinition, type SimpleCommandOptions, Stoat, type StoatLifecycle, buildSimpleCommandMetadata, getGuards, getSimpleCommands, isStoatClass };
+export { Client, type CommandContext, type CommandMetadata, CommandRegistry, type EventDefinition, Guard, METADATA_KEYS, On, Once, type Permission, type RegisteredCommand, type RegisteredEvent, SimpleCommand, type SimpleCommandDefinition, type SimpleCommandOptions, Stoat, type StoatLifecycle, type StoatxDiscoveryOptions, type StoatxGuard, StoatxHandler, type StoatxHandlerOptions, buildSimpleCommandMetadata, getEventsMetadata, getGuards, getSimpleCommands, isStoatClass };