@marshmallow-stoat/mally 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,549 @@
+import { Client, Message } from 'stoat.js';
+
+/**
+ * Permission types for commands
+ */
+type Permission = "SendMessages" | "ManageMessages" | "ManageChannels" | "ManageServer" | "KickMembers" | "BanMembers" | "Administrator" | (string & {});
+/**
+ * Command metadata options passed to @Command decorator
+ */
+interface CommandOptions {
+    /** Command name (defaults to class name without 'Command' suffix) */
+    name?: string;
+    /** Command description */
+    description?: string;
+    /** Command aliases */
+    aliases?: string[];
+    /** Required permissions to run the command */
+    permissions?: Permission[];
+    /** Command category (auto-detected from directory if not provided) */
+    category?: string;
+    /** Cooldown in milliseconds */
+    cooldown?: number;
+    /** Whether the command is NSFW only */
+    nsfw?: boolean;
+    /** Whether the command is owner only */
+    ownerOnly?: boolean;
+}
+/**
+ * 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?: Permission[];
+    /** Command category (auto-detected from directory if not provided) */
+    category?: string;
+    /** Cooldown in milliseconds */
+    cooldown?: number;
+    /** 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: Permission[];
+    category: string;
+    cooldown: number;
+    nsfw: boolean;
+    ownerOnly: boolean;
+}
+/**
+ * Command execution context
+ */
+interface CommandContext {
+    /** The client instance */
+    client: Client;
+    /** The raw message content */
+    content: string;
+    /** The author ID */
+    authorId: string;
+    /** The channel ID */
+    channelId: string;
+    /** The server/guild ID (if applicable) */
+    serverId?: string;
+    /** 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<void>;
+    /** The original message object (platform-specific) */
+    message: Message;
+}
+/**
+ * Interface that all command classes must implement
+ */
+interface MallyCommand {
+    /** Command metadata (injected by registry) */
+    metadata: CommandMetadata;
+    /**
+     * Execute the command
+     */
+    run(ctx: CommandContext): Promise<void>;
+    /**
+     * Optional: Called when an error occurs during command execution
+     */
+    onError?(ctx: CommandContext, error: Error): Promise<void>;
+    guardFail?(ctx: CommandContext): Promise<void>;
+    onCooldown?(ctx: CommandContext, remaining: number): Promise<void>;
+}
+interface MallyGuard {
+    run(ctx: CommandContext): Promise<boolean> | boolean;
+    guardFail?(ctx: CommandContext): Promise<void> | void;
+}
+/**
+ * Abstract base class for commands.
+ * Extend this class to create commands without boilerplate.
+ *
+ * @example
+ * ```ts
+ * @Command({ name: 'ping', description: 'Replies with Pong!' })
+ * export class PingCommand extends BaseCommand {
+ *   async run(ctx) {
+ *     await ctx.reply('Pong!');
+ *   }
+ * }
+ * ```
+ */
+declare abstract class BaseCommand implements MallyCommand {
+    /** Command metadata (injected by registry) */
+    metadata: CommandMetadata;
+    /** Typed context for use in subclasses */
+    protected ctx: CommandContext;
+    /**
+     * Execute the command - must be implemented by subclasses
+     */
+    abstract run(ctx: CommandContext): Promise<void>;
+    /**
+     * Optional: Called when an error occurs during command execution.
+     * Override this method to provide custom error handling.
+     */
+    onError(ctx: CommandContext, error: Error): Promise<void>;
+}
+/**
+ * Constructor type for command classes
+ */
+type CommandConstructor = new () => MallyCommand;
+/**
+ * Handler options
+ */
+interface MallyHandlerOptions {
+    /** The client instance */
+    client: Client;
+    /** Directory to scan for commands (absolute path) */
+    commandsDir: string;
+    /** Command prefix or prefix resolver function */
+    prefix: string | ((ctx: {
+        serverId?: string;
+    }) => string | Promise<string>);
+    /** Owner IDs for owner-only commands */
+    owners?: string[];
+    /** File extensions to load (default: ['.js', '.ts']) */
+    extensions?: string[];
+    /** Disable mention prefix support (default: false) */
+    disableMentionPrefix?: boolean;
+}
+
+/**
+ * @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 '@marshmallow/mally';
+ *
+ * @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;
+}
+/**
+ * @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[];
+
+/**
+ * @Command
+ * Marks a class as a command and attaches metadata.
+ * This is the legacy/class-based approach where each command is a separate class.
+ *
+ * @example
+ * ```ts
+ * import { Command, MallyCommand, CommandContext } from '@marshmallow/mally';
+ *
+ * @Command({
+ *   description: 'Ban a user from the server',
+ *   aliases: ['b'],
+ *   permissions: ['BanMembers']
+ * })
+ * export class BanCommand implements MallyCommand {
+ *   metadata!: CommandMetadata;
+ *
+ *   async run(ctx: CommandContext) {
+ *     const userId = ctx.args[0];
+ *     await ctx.reply(`Banned user ${userId}`);
+ *   }
+ * }
+ * ```
+ */
+declare function Command(options?: CommandOptions): ClassDecorator;
+/**
+ * Check if a class is decorated with @Command
+ */
+declare function isCommand(target: Function): boolean;
+/**
+ * Get command options from a decorated class
+ */
+declare function getCommandOptions(target: Function): CommandOptions | undefined;
+/**
+ * Build complete CommandMetadata from options and class name
+ */
+declare function buildCommandMetadata(target: Function, options: CommandOptions, category?: string): CommandMetadata;
+
+/**
+ * @Guard
+ * Runs before a command to check if it should execute.
+ * Should return true to allow execution, false to block.
+ * Can be applied to both @Command classes and @Stoat classes.
+ *
+ * @example
+ * ```ts
+ * import { Guard, Stoat, SimpleCommand, CommandContext } from '@marshmallow/mally';
+ *
+ * // Define a guard
+ * class NotBot implements MallyGuard {
+ *   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[];
+
+/**
+ * Build CommandMetadata from SimpleCommandOptions
+ */
+declare function buildSimpleCommandMetadata(options: SimpleCommandOptions, methodName: string, category?: string): CommandMetadata;
+
+/**
+ * Metadata keys used by decorators
+ */
+declare const METADATA_KEYS: {
+    readonly COMMAND_OPTIONS: symbol;
+    readonly IS_COMMAND: symbol;
+    readonly IS_STOAT_CLASS: symbol;
+    readonly SIMPLE_COMMANDS: symbol;
+    readonly GUARDS: "mally:command:guards";
+};
+
+/**
+ * Stored command entry (supports both class-based and method-based commands)
+ */
+interface RegisteredCommand {
+    /** Instance of the command class */
+    instance: MallyCommand | object;
+    /** Command metadata */
+    metadata: CommandMetadata;
+    /** Method name to call (for @SimpleCommand methods) */
+    methodName?: string;
+    /** The original class constructor (for guard validation) */
+    classConstructor: Function;
+}
+/**
+ * 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();
+ * ```
+ */
+declare class CommandRegistry {
+    private readonly commands;
+    private readonly aliases;
+    private readonly extensions;
+    constructor(extensions?: string[]);
+    /**
+     * Get the number of registered commands
+     */
+    get size(): number;
+    /**
+     * Load commands from a directory using glob pattern matching
+     */
+    loadFromDirectory(directory: string): Promise<void>;
+    /**
+     * Register a command instance
+     */
+    register(instance: MallyCommand | object, metadata: CommandMetadata, classConstructor: Function, methodName?: string): void;
+    /**
+     * Get a command by name or alias
+     */
+    get(name: string): RegisteredCommand | undefined;
+    /**
+     * Check if a command exists
+     */
+    has(name: string): boolean;
+    /**
+     * Get all registered commands
+     */
+    getAll(): RegisteredCommand[];
+    /**
+     * Get all command metadata
+     */
+    getAllMetadata(): CommandMetadata[];
+    /**
+     * Get commands grouped by category
+     */
+    getByCategory(): Map<string, RegisteredCommand[]>;
+    /**
+     * Clear all commands
+     */
+    clear(): void;
+    /**
+     * Iterate over commands
+     */
+    [Symbol.iterator](): IterableIterator<[string, RegisteredCommand]>;
+    /**
+     * Iterate over command values
+     */
+    values(): IterableIterator<RegisteredCommand>;
+    /**
+     * Iterate over command names
+     */
+    keys(): IterableIterator<string>;
+    /**
+     * Validate that all guards on a command implement the required methods
+     * @param commandClass
+     * @param commandName
+     * @private
+     */
+    private validateGuards;
+    /**
+     * Validate that commands with cooldowns implement the onCooldown method
+     * @param instance
+     * @param metadata
+     * @private
+     */
+    private validateCooldown;
+    /**
+     * Load commands from a single file
+     */
+    private loadFile;
+    /**
+     * Derive category from file path relative to base directory
+     */
+    private getCategoryFromPath;
+}
+
+/**
+ * MallyHandler - The execution engine for commands
+ *
+ * Handles message parsing, middleware execution, and command dispatching
+ *
+ * @example
+ * ```ts
+ * import { MallyHandler } from '@marshmallow/mally';
+ * import { Client } from 'stoat.js';
+ *
+ * const client = new Client();
+ *
+ * const handler = new MallyHandler({
+ *   client,
+ *   commandsDir: path.join(__dirname, 'commands'),
+ *   prefix: '!',
+ *   owners: ['owner-user-id'],
+ * });
+ *
+ * await handler.init();
+ *
+ * client.on('message', (message) => {
+ *   handler.handleMessage(message);
+ * });
+ * ```
+ */
+declare class MallyHandler {
+    private readonly commandsDir;
+    private readonly prefixResolver;
+    private readonly owners;
+    private readonly registry;
+    private readonly cooldowns;
+    private readonly disableMentionPrefix;
+    private readonly client;
+    constructor(options: MallyHandlerOptions);
+    /**
+     * Initialize the handler - load all commands
+     */
+    init(): Promise<void>;
+    /**
+     * Parse a raw message into command context
+     */
+    parseMessage(rawContent: string, message: Message, meta: {
+        authorId: string;
+        channelId: string;
+        serverId?: string;
+        reply: (content: string) => Promise<void>;
+    }): Promise<CommandContext | null>;
+    /**
+     * Handle a message object using the configured message adapter
+     *
+     * @example
+     * ```ts
+     * // With message adapter configured
+     * client.on('messageCreate', (message) => {
+     *   handler.handle(message);
+     * });
+     * ```
+     */
+    handle(message: any): Promise<boolean>;
+    /**
+     * Handle a raw message string with metadata
+     *
+     * @example
+     * ```ts
+     * // Manual usage without message adapter
+     * client.on('messageCreate', (message) => {
+     *   handler.handleMessage(message.content, message, {
+     *     authorId: message.author.id,
+     *     channelId: message.channel.id,
+     *     serverId: message.server?.id,
+     *     reply: (content) => message.channel.sendMessage(content),
+     *   });
+     * });
+     * ```
+     */
+    handleMessage(rawContent: string, message: Message, meta: {
+        authorId: string;
+        channelId: string;
+        serverId?: string;
+        reply: (content: string) => Promise<void>;
+    }): Promise<boolean>;
+    /**
+     * Execute a command with the given context
+     */
+    execute(ctx: CommandContext): Promise<boolean>;
+    /**
+     * Get the command registry
+     */
+    getRegistry(): CommandRegistry;
+    /**
+     * Get a command by name or alias
+     */
+    getCommand(name: string): RegisteredCommand | undefined;
+    /**
+     * Get all commands
+     */
+    getCommands(): RegisteredCommand[];
+    /**
+     * Reload all commands
+     */
+    reload(): Promise<void>;
+    /**
+     * Check if a user is an owner
+     */
+    isOwner(userId: string): boolean;
+    /**
+     * Add an owner
+     */
+    addOwner(userId: string): void;
+    /**
+     * Remove an owner
+     */
+    removeOwner(userId: string): void;
+    /**
+     * Resolve the prefix for a context
+     */
+    private resolvePrefix;
+    /**
+     * Check if user is on cooldown
+     */
+    private checkCooldown;
+    /**
+     * Get remaining cooldown time in ms
+     */
+    private getRemainingCooldown;
+    /**
+     * Set cooldown for a user
+     */
+    private setCooldown;
+}
+
+export { BaseCommand, Command, type CommandConstructor, type CommandContext, type CommandMetadata, type CommandOptions, CommandRegistry, type CommandContext as Context, Guard, METADATA_KEYS, type MallyCommand, type MallyGuard, MallyHandler, type MallyHandlerOptions, type Permission, type RegisteredCommand, SimpleCommand, type SimpleCommandDefinition, type SimpleCommandOptions, Stoat, buildCommandMetadata, buildSimpleCommandMetadata, getCommandOptions, getGuards, getSimpleCommands, isCommand, isStoatClass };