stoatx 0.7.6 → 0.7.7

package/dist/index.d.ts

@@ -1,335 +1,43 @@
-import { Client as Client$1, Message, PermissionResolvable } from '@stoatx/client';
+import { Message, Client as Client$1, PermissionResolvable } from '@stoatx/client';
 export * from '@stoatx/client';
 
-/**
- * Simple command options passed to @SimpleCommand decorator
- * Used with @Stoat() decorated classes for method-based commands
- */
-interface SimpleCommandOptions {
-    /** Command name (defaults to method name) */
-    name?: string;
-    /** Command description */
-    description?: string;
-    /** Command aliases */
-    aliases?: string[];
-    /** Required permissions to run the command */
-    permissions?: PermissionResolvable[];
-    /** Command category (auto-detected from directory if not provided) */
-    category?: string;
-    /** Cooldown in milliseconds */
-    cooldown?: number;
-    /** Storage strategy or identifier for cooldowns (e.g. "memory", "database") */
-    cooldownStorage?: string;
-    /** Whether the command is NSFW only */
-    nsfw?: boolean;
-    /** Whether the command is owner only */
-    ownerOnly?: boolean;
-}
-/**
- * Resolved command metadata with required fields
- */
-interface CommandMetadata {
-    name: string;
-    description: string;
-    aliases: string[];
-    permissions: PermissionResolvable[];
-    category: string;
-    cooldown: number;
-    cooldownStorage?: string;
-    nsfw: boolean;
-    ownerOnly: boolean;
-}
-/**
- * Command execution context
- */
-interface CommandContext {
-    /** The client instance */
-    client: Client$1;
-    /** The raw message content */
-    content: string;
-    /** The author ID */
-    authorId: string;
-    /** The channel ID */
-    channelId: string;
-    /** The server/guild ID (if applicable) */
-    serverId?: string | undefined;
-    /** Parsed command arguments */
-    args: string[];
-    /** The prefix used */
-    prefix: string;
-    /** The command name used (could be an alias) */
-    commandName: string;
-    /** Reply to the message */
-    reply: (content: string) => Promise<Message>;
-    /** The original message object (platform-specific) */
-    message: Message;
-}
-/**
- * Optional lifecycle hooks for @Stoat() class instances
- */
-interface StoatLifecycle {
-    /** Optional: Called when an error occurs during command execution */
-    onError?(ctx: CommandContext, error: Error): Promise<void> | void;
-    /** Optional: Called when a cooldown is active */
-    onCooldown?(ctx: CommandContext, remaining: number): Promise<void> | void;
-    /** Optional: Called when user doesn't have the permissions needed */
-    onMissingPermissions?(ctx: CommandContext, missing: PermissionResolvable[]): Promise<void> | void;
-    /** Allows the class to contain other methods (such as your commands) */
-    [method: string]: any;
-}
-/**
- * Cooldown manager interface for custom cooldown storage (e.g., database)
- */
-interface CooldownManager {
-    check(ctx: CommandContext, metadata: CommandMetadata): boolean | Promise<boolean>;
-    getRemaining(ctx: CommandContext, metadata: CommandMetadata): number | Promise<number>;
-    set(ctx: CommandContext, metadata: CommandMetadata): void | Promise<void>;
-    clear?(): void | Promise<void>;
-}
-interface StoatxGuard {
-    run(ctx: CommandContext): Promise<boolean> | boolean;
-    guardFail?(ctx: CommandContext): Promise<void> | void;
-}
-/**
- * Discovery options for automatic command module loading
- */
-interface StoatxDiscoveryOptions {
-    /** Root directories to scan (default: [process.cwd()]) */
+interface AutoDiscoveryOptions {
     roots?: string[];
-    /** Glob patterns relative to each root */
     include?: string[];
-    /** Additional ignore patterns */
     ignore?: string[];
 }
 /**
- * Handler options
- */
-interface StoatxHandlerOptions {
-    /** The client instance */
-    client: Client$1;
-    /** Directory to scan for command modules (absolute path) */
-    commandsDir?: string;
-    /** Auto-discovery options used when commandsDir is not provided */
-    discovery?: StoatxDiscoveryOptions;
-    /** Command prefix or prefix resolver function */
-    prefix: string | ((ctx: {
-        serverId?: string | undefined;
-    }) => string | Promise<string>);
-    /** Owner IDs for owner-only commands */
-    owners?: string[];
-    /** File extensions to load (default: ['.js', '.mjs', '.cjs']) */
-    extensions?: string[];
-    /** Disable mention prefix support (default: false) */
-    disableMentionPrefix?: boolean;
-    /** Custom cooldown manager */
-    cooldownManager?: CooldownManager;
-}
-
-/**
- * @Stoat
- * Marks a class as a Stoat command container.
- * Use this decorator on classes that contain @SimpleCommand methods.
- *
- * @example
- * ```ts
- * import { Stoat, SimpleCommand, CommandContext } from 'stoatx';
- *
- * @Stoat()
- * class ModerationCommands {
- *   @SimpleCommand({ name: 'ban', description: 'Ban a user' })
- *   async ban(ctx: CommandContext) {
- *     await ctx.reply('User banned!');
- *   }
- *
- *   @SimpleCommand({ name: 'kick', description: 'Kick a user' })
- *   async kick(ctx: CommandContext) {
- *     await ctx.reply('User kicked!');
- *   }
- * }
- * ```
- */
-declare function Stoat(): ClassDecorator;
-/**
- * Check if a class is decorated with @Stoat
- */
-declare function isStoatClass(target: Function): boolean;
-
-/**
- * Stored simple command metadata from method decorator
+ * Stored command entry from @Stoat/@SimpleCommand registration.
  */
-interface SimpleCommandDefinition {
+interface RegisteredCommand {
+    /** Instance of the @Stoat class */
+    instance: object;
+    /** Command metadata */
+    metadata: CommandMetadata;
+    /** Method name to call */
     methodName: string;
-    options: SimpleCommandOptions;
+    /** The original class constructor (for guard validation) */
+    classConstructor: Function;
 }
 /**
- * @SimpleCommand
- * Marks a method as a simple command within a @Stoat() decorated class.
- *
- * @example
- * ```ts
- * @Stoat()
- * class Example {
- *   @SimpleCommand({ name: 'ping', description: 'Replies with Pong!' })
- *   async ping(ctx: CommandContext) {
- *     await ctx.reply('Pong!');
- *   }
- *
- *   @SimpleCommand({ aliases: ['perm'], name: 'permission' })
- *   async permission(ctx: CommandContext) {
- *     await ctx.reply('Access granted');
- *   }
- * }
- * ```
- */
-declare function SimpleCommand(options?: SimpleCommandOptions): MethodDecorator;
-/**
- * Get all simple command definitions from a @Stoat class
- */
-declare function getSimpleCommands(target: Function): SimpleCommandDefinition[];
-
-/**
- * @Guard
- * Runs before a command to check if it should execute.
- * Should return true to allow execution, false to block.
- * Applied on @Stoat classes to guard all contained @SimpleCommand methods.
- *
- * @example
- * ```ts
- * import { Guard, Stoat, SimpleCommand, CommandContext } from 'stoatx';
- *
- * // Define a guard
- * class NotBot implements StoatxGuard {
- *   run(ctx: CommandContext): boolean {
- *     return !ctx.message.author.bot;
- *   }
- *
- *   guardFail(ctx: CommandContext): void {
- *     ctx.reply("Bots cannot use this command!");
- *   }
- * }
- *
- * @Stoat()
- * @Guard(NotBot)
- * class AdminCommands {
- *   @SimpleCommand({ name: 'admin', description: 'Admin only command' })
- *   async admin(ctx: CommandContext) {
- *     ctx.reply("You passed the guard check!");
- *   }
- * }
- * ```
- */
-declare function Guard(guardClass: Function): ClassDecorator;
-/**
- * Get all guards from a decorated class
+ * Stored event entry from @On/@Once registration.
  */
-declare function getGuards(target: Function): Function[];
-
-interface EventDefinition {
+interface RegisteredEvent {
+    instance: object;
     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.
+ * CommandRegistry - Scans directories and stores commands in a Map
  *
  * @example
  * ```ts
- * import { Stoat, Once } from 'stoatx';
- * import { Client } from 'stoat.js';
+ * const registry = new CommandRegistry();
+ * await registry.loadFromDirectory('./src/commands');
  *
- * @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
- */
-declare function buildSimpleCommandMetadata(options: SimpleCommandOptions, methodName: string, category?: string): CommandMetadata;
-
-/**
- * Metadata keys used by decorators
- */
-declare const METADATA_KEYS: {
-    readonly IS_STOAT_CLASS: symbol;
-    readonly SIMPLE_COMMANDS: symbol;
-    readonly GUARDS: "stoatx:command:guards";
-    readonly EVENTS: symbol;
-};
-
-interface AutoDiscoveryOptions {
-    roots?: string[];
-    include?: string[];
-    ignore?: string[];
-}
-/**
- * Stored command entry from @Stoat/@SimpleCommand registration.
- */
-interface RegisteredCommand {
-    /** Instance of the @Stoat class */
-    instance: object;
-    /** Command metadata */
-    metadata: CommandMetadata;
-    /** Method name to call */
-    methodName: string;
-    /** 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
- *
- * @example
- * ```ts
- * const registry = new CommandRegistry();
- * await registry.loadFromDirectory('./src/commands');
- *
- * const ping = registry.get('ping');
- * const allCommands = registry.getAll();
+ * const ping = registry.get('ping');
+ * const allCommands = registry.getAll();
  * ```
  */
 declare class CommandRegistry {
@@ -426,29 +134,6 @@ declare class DefaultCooldownManager implements CooldownManager {
     set(ctx: CommandContext, metadata: CommandMetadata): void;
     clear(): void;
 }
-/**
- * Client - An extended Client that integrates StoatxHandler directly
- *
- * @example
- * ```ts
- * import { Client } from 'stoatx';
- *
- * const client = new Client({
- *   prefix: '!',
- *   owners: ['owner-user-id'],
- * });
- *
- * await client.initCommands();
- * ```
- */
-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
  *
@@ -482,7 +167,7 @@ declare class StoatxHandler {
         channelId: string;
         serverId?: string | undefined;
         reply: (content: string) => Promise<Message>;
-    }): Promise<CommandContext | null>;
+    }): Promise<CommandContext<Client> | null>;
     /**
      * Handle a message object using the configured message adapter
      *
@@ -520,7 +205,7 @@ declare class StoatxHandler {
     /**
      * Execute a command with the given context
      */
-    execute(ctx: CommandContext): Promise<boolean>;
+    execute(ctx: CommandContext<Client>): Promise<boolean>;
     /**
      * Get the command registry
      */
@@ -555,4 +240,318 @@ declare class StoatxHandler {
     private resolvePrefix;
 }
 
+/**
+ * Client - An extended Client that integrates StoatxHandler directly
+ *
+ * @example
+ * ```ts
+ * import { Client } from 'stoatx';
+ *
+ * const client = new Client({
+ *   prefix: '!',
+ *   owners: ['owner-user-id'],
+ * });
+ *
+ * await client.initCommands();
+ * ```
+ */
+declare class Client extends Client$1 {
+    readonly handler: StoatxHandler;
+    constructor(options: Omit<StoatxHandlerOptions, "client">);
+    initCommands(): Promise<void>;
+}
+
+/**
+ * Simple command options passed to @SimpleCommand decorator
+ * Used with @Stoat() decorated classes for method-based commands
+ */
+interface SimpleCommandOptions {
+    /** Command name (defaults to method name) */
+    name?: string;
+    /** Command description */
+    description?: string;
+    /** Command aliases */
+    aliases?: string[];
+    /** Required permissions to run the command */
+    permissions?: PermissionResolvable[];
+    /** Command category (auto-detected from directory if not provided) */
+    category?: string;
+    /** Cooldown in milliseconds */
+    cooldown?: number;
+    /** Storage strategy or identifier for cooldowns (e.g. "memory", "database") */
+    cooldownStorage?: string;
+    /** Whether the command is NSFW only */
+    nsfw?: boolean;
+    /** Whether the command is owner only */
+    ownerOnly?: boolean;
+}
+/**
+ * Resolved command metadata with required fields
+ */
+interface CommandMetadata {
+    name: string;
+    description: string;
+    aliases: string[];
+    permissions: PermissionResolvable[];
+    category: string;
+    cooldown: number;
+    cooldownStorage?: string;
+    nsfw: boolean;
+    ownerOnly: boolean;
+}
+/**
+ * Command execution context
+ */
+interface CommandContext<TClient extends Client$1 = Client> {
+    /** The client instance */
+    client: TClient;
+    /** The raw message content */
+    content: string;
+    /** The author ID */
+    authorId: string;
+    /** The channel ID */
+    channelId: string;
+    /** The server/guild ID (if applicable) */
+    serverId?: string | undefined;
+    /** Parsed command arguments */
+    args: string[];
+    /** The prefix used */
+    prefix: string;
+    /** The command name used (could be an alias) */
+    commandName: string;
+    /** Reply to the message */
+    reply: (content: string) => Promise<Message>;
+    /** The original message object (platform-specific) */
+    message: Message;
+}
+/**
+ * Optional lifecycle hooks for @Stoat() class instances
+ */
+interface StoatLifecycle {
+    /** Optional: Called when an error occurs during command execution */
+    onError?(ctx: CommandContext<Client>, error: Error): Promise<void> | void;
+    /** Optional: Called when a cooldown is active */
+    onCooldown?(ctx: CommandContext<Client>, remaining: number): Promise<void> | void;
+    /** Optional: Called when user doesn't have the permissions needed */
+    onMissingPermissions?(ctx: CommandContext<Client>, missing: PermissionResolvable[]): Promise<void> | void;
+    /** Allows the class to contain other methods (such as your commands) */
+    [method: string]: any;
+}
+/**
+ * Cooldown manager interface for custom cooldown storage (e.g., database)
+ */
+interface CooldownManager {
+    check(ctx: CommandContext<any>, metadata: CommandMetadata): boolean | Promise<boolean>;
+    getRemaining(ctx: CommandContext<any>, metadata: CommandMetadata): number | Promise<number>;
+    set(ctx: CommandContext<any>, metadata: CommandMetadata): void | Promise<void>;
+    clear?(): void | Promise<void>;
+}
+interface StoatxGuard {
+    run(ctx: CommandContext<Client>): Promise<boolean> | boolean;
+    guardFail?(ctx: CommandContext<Client>): Promise<void> | void;
+}
+/**
+ * Discovery options for automatic command module loading
+ */
+interface StoatxDiscoveryOptions {
+    /** Root directories to scan (default: [process.cwd()]) */
+    roots?: string[];
+    /** Glob patterns relative to each root */
+    include?: string[];
+    /** Additional ignore patterns */
+    ignore?: string[];
+}
+/**
+ * Handler options
+ */
+interface StoatxHandlerOptions {
+    /** The client instance */
+    client: Client;
+    /** Directory to scan for command modules (absolute path) */
+    commandsDir?: string;
+    /** Auto-discovery options used when commandsDir is not provided */
+    discovery?: StoatxDiscoveryOptions;
+    /** Command prefix or prefix resolver function */
+    prefix: string | ((ctx: {
+        serverId?: string | undefined;
+    }) => string | Promise<string>);
+    /** Owner IDs for owner-only commands */
+    owners?: string[];
+    /** File extensions to load (default: ['.js', '.mjs', '.cjs']) */
+    extensions?: string[];
+    /** Disable mention prefix support (default: false) */
+    disableMentionPrefix?: boolean;
+    /** Custom cooldown manager */
+    cooldownManager?: CooldownManager;
+}
+
+/**
+ * @Stoat
+ * Marks a class as a Stoat command container.
+ * Use this decorator on classes that contain @SimpleCommand methods.
+ *
+ * @example
+ * ```ts
+ * import { Stoat, SimpleCommand, CommandContext } from 'stoatx';
+ *
+ * @Stoat()
+ * class ModerationCommands {
+ *   @SimpleCommand({ name: 'ban', description: 'Ban a user' })
+ *   async ban(ctx: CommandContext) {
+ *     await ctx.reply('User banned!');
+ *   }
+ *
+ *   @SimpleCommand({ name: 'kick', description: 'Kick a user' })
+ *   async kick(ctx: CommandContext) {
+ *     await ctx.reply('User kicked!');
+ *   }
+ * }
+ * ```
+ */
+declare function Stoat(): ClassDecorator;
+/**
+ * Check if a class is decorated with @Stoat
+ */
+declare function isStoatClass(target: Function): boolean;
+
+/**
+ * Stored simple command metadata from method decorator
+ */
+interface SimpleCommandDefinition {
+    methodName: string;
+    options: SimpleCommandOptions;
+}
+type CommandMethod = (ctx: CommandContext<Client>) => Promise<void>;
+/**
+ * @SimpleCommand
+ * Marks a method as a simple command within a @Stoat() decorated class.
+ *
+ * @example
+ * ```ts
+ * @Stoat()
+ * class Example {
+ *   @SimpleCommand({ name: 'ping', description: 'Replies with Pong!' })
+ *   async ping(ctx: CommandContext) {
+ *     await ctx.reply('Pong!');
+ *   }
+ *
+ *   @SimpleCommand({ aliases: ['perm'], name: 'permission' })
+ *   async permission(ctx: CommandContext) {
+ *     await ctx.reply('Access granted');
+ *   }
+ * }
+ * ```
+ */
+declare function SimpleCommand(options?: SimpleCommandOptions): <T extends CommandMethod>(target: Object, propertyKey: string | symbol, descriptor: TypedPropertyDescriptor<T>) => TypedPropertyDescriptor<T>;
+/**
+ * Get all simple command definitions from a @Stoat class
+ */
+declare function getSimpleCommands(target: Function): SimpleCommandDefinition[];
+
+/**
+ * @Guard
+ * Runs before a command to check if it should execute.
+ * Should return true to allow execution, false to block.
+ * Applied on @Stoat classes to guard all contained @SimpleCommand methods.
+ *
+ * @example
+ * ```ts
+ * import { Guard, Stoat, SimpleCommand, CommandContext } from 'stoatx';
+ *
+ * // Define a guard
+ * class NotBot implements StoatxGuard {
+ *   run(ctx: CommandContext): boolean {
+ *     return !ctx.message.author.bot;
+ *   }
+ *
+ *   guardFail(ctx: CommandContext): void {
+ *     ctx.reply("Bots cannot use this command!");
+ *   }
+ * }
+ *
+ * @Stoat()
+ * @Guard(NotBot)
+ * class AdminCommands {
+ *   @SimpleCommand({ name: 'admin', description: 'Admin only command' })
+ *   async admin(ctx: CommandContext) {
+ *     ctx.reply("You passed the guard check!");
+ *   }
+ * }
+ * ```
+ */
+declare function Guard(guardClass: Function): ClassDecorator;
+/**
+ * Get all guards from a decorated class
+ */
+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
+ */
+declare function buildSimpleCommandMetadata(options: SimpleCommandOptions, methodName: string, category?: string): CommandMetadata;
+
+/**
+ * Metadata keys used by decorators
+ */
+declare const METADATA_KEYS: {
+    readonly IS_STOAT_CLASS: symbol;
+    readonly SIMPLE_COMMANDS: symbol;
+    readonly GUARDS: "stoatx:command:guards";
+    readonly EVENTS: symbol;
+};
+
 export { Client, type CommandContext, type CommandMetadata, CommandRegistry, type CooldownManager, DefaultCooldownManager, type EventDefinition, Guard, METADATA_KEYS, On, Once, type RegisteredCommand, type RegisteredEvent, SimpleCommand, type SimpleCommandDefinition, type SimpleCommandOptions, Stoat, type StoatLifecycle, type StoatxDiscoveryOptions, type StoatxGuard, StoatxHandler, type StoatxHandlerOptions, buildSimpleCommandMetadata, getEventsMetadata, getGuards, getSimpleCommands, isStoatClass };