stoatx 0.2.0 → 0.3.0

package/dist/index.d.mts

@@ -0,0 +1,545 @@
+import { Client as Client$1, Message } from 'stoat.js';
+
+/**
+ * Permission types for commands
+ */
+type Permission = "SendMessages" | "ManageMessages" | "ManageChannels" | "ManageServer" | "KickMembers" | "BanMembers" | "Administrator" | (string & {});
+/**
+ * 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$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;
+    /** 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;
+}
+/**
+ * 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>;
+    /** Optional: Called when a cooldown is active */
+    onCooldown?(ctx: CommandContext, remaining: number): 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()]) */
+    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;
+    }) => 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;
+}
+
+/**
+ * @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;
+}
+/**
+ * @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
+ */
+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;
+};
+
+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();
+ * ```
+ */
+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[]);
+    /**
+     * Get the number of registered commands
+     */
+    get size(): number;
+    /**
+     * Load commands from a directory using glob pattern matching
+     */
+    loadFromDirectory(directory: string): Promise<void>;
+    /**
+     * Auto-discover command files across one or more roots.
+     */
+    autoDiscover(options?: AutoDiscoveryOptions): Promise<void>;
+    private getDefaultAutoDiscoveryPatterns;
+    private isLikelyCommandModule;
+    /**
+     * Register a command instance
+     */
+    register(instance: 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 all registered events
+     */
+    getEvents(): RegisteredEvent[];
+    /**
+     * 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;
+    /**
+     * Load commands from a single file
+     */
+    private loadFile;
+    private registerStoatClassCommands;
+    /**
+     * Derive category from file path relative to base directory
+     */
+    private getCategoryFromPath;
+}
+
+/**
+ * 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
+ *
+ * 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: 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
+     */
+    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 { 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 };