stoatx 0.2.1 → 0.4.0

package/dist/index.d.ts

@@ -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 };

package/dist/index.js

@@ -30,13 +30,16 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  Client: () => Client,
   CommandRegistry: () => CommandRegistry,
   Guard: () => Guard,
   METADATA_KEYS: () => METADATA_KEYS,
-  MallyHandler: () => MallyHandler,
+  On: () => On,
+  Once: () => Once,
   SimpleCommand: () => SimpleCommand,
   Stoat: () => Stoat,
   buildSimpleCommandMetadata: () => buildSimpleCommandMetadata,
+  getEventsMetadata: () => getEventsMetadata,
   getGuards: () => getGuards,
   getSimpleCommands: () => getSimpleCommands,
   isStoatClass: () => isStoatClass
@@ -48,9 +51,10 @@ var import_reflect_metadata = require("reflect-metadata");
 
 // src/decorators/keys.ts
 var METADATA_KEYS = {
-  IS_STOAT_CLASS: /* @__PURE__ */ Symbol("mally:stoat:isClass"),
-  SIMPLE_COMMANDS: /* @__PURE__ */ Symbol("mally:stoat:simpleCommands"),
-  GUARDS: "mally:command:guards"
+  IS_STOAT_CLASS: /* @__PURE__ */ Symbol("stoatx:stoat:isClass"),
+  SIMPLE_COMMANDS: /* @__PURE__ */ Symbol("stoatx:stoat:simpleCommands"),
+  GUARDS: "stoatx:command:guards",
+  EVENTS: /* @__PURE__ */ Symbol("stoatx:stoat:events")
 };
 
 // src/decorators/store.ts
@@ -161,6 +165,31 @@ function getGuards(target) {
   return Reflect.getMetadata(METADATA_KEYS.GUARDS, target) || [];
 }
 
+// src/decorators/Events.ts
+var import_reflect_metadata4 = require("reflect-metadata");
+function createEventDecorator(event, type) {
+  return (target, propertyKey, descriptor) => {
+    const constructor = target.constructor;
+    const existingEvents = Reflect.getMetadata(METADATA_KEYS.EVENTS, constructor) || [];
+    existingEvents.push({
+      methodName: String(propertyKey),
+      event,
+      type
+    });
+    Reflect.defineMetadata(METADATA_KEYS.EVENTS, existingEvents, constructor);
+    return descriptor;
+  };
+}
+function On(event) {
+  return createEventDecorator(event, "on");
+}
+function Once(event) {
+  return createEventDecorator(event, "once");
+}
+function getEventsMetadata(target) {
+  return Reflect.getMetadata(METADATA_KEYS.EVENTS, target) || [];
+}
+
 // src/decorators/utils.ts
 function buildSimpleCommandMetadata(options, methodName, category) {
   return {
@@ -184,6 +213,7 @@ var _CommandRegistry = class _CommandRegistry {
   constructor(extensions = [".js", ".mjs", ".cjs"]) {
     this.commands = /* @__PURE__ */ new Map();
     this.aliases = /* @__PURE__ */ new Map();
+    this.registeredEvents = [];
     this.processedStoatClasses = /* @__PURE__ */ new Set();
     this.extensions = extensions;
   }
@@ -207,7 +237,7 @@ var _CommandRegistry = class _CommandRegistry {
         await this.loadFile(file, directory);
       }
     }
-    console.log(`[Mally] Loaded ${this.commands.size} command(s)`);
+    console.log(`[Stoatx] Loaded ${this.commands.size} command(s) and ${this.registeredEvents.length} event(s)`);
   }
   /**
    * Auto-discover command files across one or more roots.
@@ -235,7 +265,7 @@ var _CommandRegistry = class _CommandRegistry {
       }) ?? roots[0];
       await this.loadFile(file, baseDir);
     }
-    console.log(`[Mally] Auto-discovered ${candidateFiles} candidate file(s), loaded ${this.commands.size} command(s)`);
+    console.log(`[Stoatx] Loaded ${this.commands.size} command(s) and ${this.registeredEvents.length} event(s)`);
   }
   getDefaultAutoDiscoveryPatterns() {
     return this.extensions.map((ext) => `**/*${ext}`);
@@ -243,7 +273,7 @@ var _CommandRegistry = class _CommandRegistry {
   async isLikelyCommandModule(filePath) {
     try {
       const source = await fs.readFile(filePath, "utf8");
-      return source.includes("Stoat") || source.includes("SimpleCommand") || source.includes("Command") || source.includes("mally:command");
+      return source.includes("Stoat") || source.includes("SimpleCommand") || source.includes("Command") || source.includes("stoatx:command");
     } catch {
       return true;
     }
@@ -254,7 +284,7 @@ var _CommandRegistry = class _CommandRegistry {
   register(instance, metadata, classConstructor, methodName) {
     const name = metadata.name.toLowerCase();
     if (this.commands.has(name)) {
-      console.warn(`[Mally] Duplicate command name: ${name}. Skipping...`);
+      console.warn(`[Stoatx] Duplicate command name: ${name}. Skipping...`);
       return;
     }
     this.validateGuards(classConstructor, metadata.name);
@@ -262,7 +292,7 @@ var _CommandRegistry = class _CommandRegistry {
     for (const alias of metadata.aliases) {
       const aliasLower = alias.toLowerCase();
       if (this.aliases.has(aliasLower) || this.commands.has(aliasLower)) {
-        console.warn(`[Mally] Duplicate alias: ${aliasLower}. Skipping...`);
+        console.warn(`[Stoatx] Duplicate alias: ${aliasLower}. Skipping...`);
         continue;
       }
       this.aliases.set(aliasLower, name);
@@ -295,6 +325,12 @@ var _CommandRegistry = class _CommandRegistry {
   getAllMetadata() {
     return this.getAll().map((c) => c.metadata);
   }
+  /**
+   * Get all registered events
+   */
+  getEvents() {
+    return this.registeredEvents;
+  }
   /**
    * Get commands grouped by category
    */
@@ -314,6 +350,7 @@ var _CommandRegistry = class _CommandRegistry {
   clear() {
     this.commands.clear();
     this.aliases.clear();
+    this.registeredEvents.length = 0;
     this.processedStoatClasses.clear();
   }
   /**
@@ -341,20 +378,20 @@ var _CommandRegistry = class _CommandRegistry {
    * @private
    */
   validateGuards(commandClass, commandName) {
-    const guards = Reflect.getMetadata("mally:command:guards", commandClass) || [];
+    const guards = Reflect.getMetadata("stoatx:command:guards", commandClass) || [];
     for (const GuardClass of guards) {
       const guardInstance = new GuardClass();
       if (typeof guardInstance.run !== "function") {
         console.error(
-          `[Mally] FATAL: Guard "${GuardClass.name}" on command "${commandName}" does not have a run() method.`
+          `[Stoatx] FATAL: Guard "${GuardClass.name}" on command "${commandName}" does not have a run() method.`
         );
         process.exit(1);
       }
       if (typeof guardInstance.guardFail !== "function") {
         console.error(
-          `[Mally] FATAL: Guard "${GuardClass.name}" on command "${commandName}" does not have a guardFail() method.`
+          `[Stoatx] FATAL: Guard "${GuardClass.name}" on command "${commandName}" does not have a guardFail() method.`
         );
-        console.error(`[Mally] All guards must implement guardFail() to handle failed checks.`);
+        console.error(`[Stoatx] All guards must implement guardFail() to handle failed checks.`);
         process.exit(1);
       }
     }
@@ -375,15 +412,16 @@ var _CommandRegistry = class _CommandRegistry {
         this.registerStoatClassCommands(stoatClass, stoatInstance, filePath, baseDir);
       }
     } catch (error) {
-      console.error(`[Mally] Failed to load command file: ${filePath}`, error);
+      console.error(`[Stoatx] Failed to load command file: ${filePath}`, error);
     }
   }
   registerStoatClassCommands(stoatClass, instance, filePath, baseDir) {
     const simpleCommands = getSimpleCommands(stoatClass);
+    const events = getEventsMetadata(stoatClass);
     const category = this.getCategoryFromPath(filePath, baseDir);
-    if (simpleCommands.length === 0) {
+    if (simpleCommands.length === 0 && events.length === 0) {
       console.warn(
-        `[Mally] Class ${stoatClass.name} is decorated with @Stoat but has no @SimpleCommand methods. Skipping...`
+        `[Stoatx] Class ${stoatClass.name} is decorated with @Stoat but has no @SimpleCommand, @On or @Once methods. Skipping...`
       );
       this.processedStoatClasses.add(stoatClass);
       return;
@@ -391,12 +429,25 @@ var _CommandRegistry = class _CommandRegistry {
     for (const cmdDef of simpleCommands) {
       const method = instance[cmdDef.methodName];
       if (typeof method !== "function") {
-        console.warn(`[Mally] Method ${cmdDef.methodName} not found on ${stoatClass.name}. Skipping...`);
+        console.warn(`[Stoatx] Method ${cmdDef.methodName} not found on ${stoatClass.name}. Skipping...`);
         continue;
       }
       const metadata = buildSimpleCommandMetadata(cmdDef.options, cmdDef.methodName, category);
       this.register(instance, metadata, stoatClass, cmdDef.methodName);
     }
+    for (const eventDef of events) {
+      const method = instance[eventDef.methodName];
+      if (typeof method !== "function") {
+        console.warn(`[Stoatx] Method ${eventDef.methodName} not found on ${stoatClass.name}. Skipping...`);
+        continue;
+      }
+      this.registeredEvents.push({
+        instance,
+        methodName: eventDef.methodName,
+        event: eventDef.event,
+        type: eventDef.type
+      });
+    }
     this.processedStoatClasses.add(stoatClass);
   }
   /**
@@ -421,8 +472,24 @@ _CommandRegistry.DEFAULT_AUTO_DISCOVERY_IGNORES = [
 var CommandRegistry = _CommandRegistry;
 
 // src/handler.ts
-var import_reflect_metadata4 = require("reflect-metadata");
-var MallyHandler = class {
+var import_reflect_metadata5 = require("reflect-metadata");
+var import_stoat = require("stoat.js");
+var Client = class extends import_stoat.Client {
+  constructor(options) {
+    super();
+    this.handler = new StoatxHandler({ ...options, client: this });
+    this.on("messageCreate", async (message) => {
+      await this.handler.handle(message);
+    });
+  }
+  /**
+   * Initialize the StoatxHandler commands
+   */
+  async initCommands() {
+    await this.handler.init();
+  }
+};
+var StoatxHandler = class {
   constructor(options) {
     this.cooldowns = /* @__PURE__ */ new Map();
     this.client = options.client;
@@ -439,9 +506,33 @@ var MallyHandler = class {
   async init() {
     if (this.commandsDir) {
       await this.registry.loadFromDirectory(this.commandsDir);
-      return;
+    } else {
+      await this.registry.autoDiscover(this.discoveryOptions);
+    }
+    this.attachEvents();
+  }
+  /**
+   * Attach registered events to the client
+   */
+  attachEvents() {
+    const events = this.registry.getEvents();
+    for (const eventDef of events) {
+      const handler = async (...args) => {
+        try {
+          await eventDef.instance[eventDef.methodName](...args, this.client);
+        } catch (error) {
+          console.error(
+            `[Stoatx] Event Handler Error in @${eventDef.type === "on" ? "On" : "Once"}('${eventDef.event}'):`,
+            error
+          );
+        }
+      };
+      if (eventDef.type === "once") {
+        this.client.once(eventDef.event, handler);
+      } else {
+        this.client.on(eventDef.event, handler);
+      }
     }
-    await this.registry.autoDiscover(this.discoveryOptions);
   }
   /**
    * Parse a raw message into command context
@@ -508,7 +599,7 @@ var MallyHandler = class {
     const channelId = message.channel.id;
     const serverId = message.server?.id;
     const reply = async (content) => {
-      await message.channel.sendMessage(content);
+      return await message.channel.sendMessage(content);
     };
     return this.handleMessage(rawContent, message, {
       authorId,
@@ -553,7 +644,7 @@ var MallyHandler = class {
       await ctx.reply("This command is owner-only.");
       return false;
     }
-    const guards = Reflect.getMetadata("mally:command:guards", classConstructor) || [];
+    const guards = Reflect.getMetadata("stoatx:command:guards", classConstructor) || [];
     for (const guardClass of guards) {
       const guardInstance = new guardClass();
       if (typeof guardInstance.run === "function") {
@@ -562,7 +653,7 @@ var MallyHandler = class {
           if (typeof guardInstance.guardFail === "function") {
             await guardInstance.guardFail(ctx);
           } else {
-            console.error("[Mally] Guard check failed but no guardFail method defined on", guardClass.name);
+            console.error("[Stoatx] Guard check failed but no guardFail method defined on", guardClass.name);
           }
           return false;
         }
@@ -587,7 +678,7 @@ var MallyHandler = class {
       if (typeof instance.onError === "function") {
         await instance.onError(ctx, error);
       } else {
-        console.error(`[Mally] Error in command ${metadata.name}:`, error);
+        console.error(`[Stoatx] Error in command ${metadata.name}:`, error);
         await ctx.reply(`An error occurred: ${error.message}`);
       }
       return false;
@@ -684,13 +775,16 @@ var MallyHandler = class {
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  Client,
   CommandRegistry,
   Guard,
   METADATA_KEYS,
-  MallyHandler,
+  On,
+  Once,
   SimpleCommand,
   Stoat,
   buildSimpleCommandMetadata,
+  getEventsMetadata,
   getGuards,
   getSimpleCommands,
   isStoatClass