stoatx 0.7.7 → 0.8.0

package/README.md

@@ -6,273 +6,12 @@ A high-performance, decorator-based command handler for Stoat bots. Inspired by
 
 - **Decorator-based** - Use `@Stoat()` and `@SimpleCommand()` decorators like discordx
 - **Guards** - Built-in guard system for permissions and checks
-- **Cooldowns** - Per-command cooldown support
+- **Cooldowns** - Per-command cooldown support with custom storage support
 - **Organized** - Group multiple commands in a single class
 - **Type-safe** - Full TypeScript support
 
-## Installation
-
-```bash
-npm install stoatx reflect-metadata
-# or
-pnpm add stoatx reflect-metadata
-```
-
-Make sure to enable decorators in your `tsconfig.json`:
-
-```json
-{
-  "compilerOptions": {
-    "experimentalDecorators": true,
-    "emitDecoratorMetadata": true
-  }
-}
-```
-
-## Quick Start
-
-### 1. Create your handler
-
-```typescript
-// index.ts
-import "reflect-metadata";
-import { Client } from "stoatx";
-
-const client = new Client({
-  prefix: "!",
-  owners: ["your-user-id"],
-});
-
-await client.initCommands();
-
-client.login("your-token");
-```
-
-### 2. Create commands
-
-```typescript
-// commands/general.ts
-import { Stoat, SimpleCommand, Context } from "stoatx";
-
-@Stoat()
-export class GeneralCommands {
-  @SimpleCommand({ name: "ping", description: "Check bot latency" })
-  async ping(ctx: Context) {
-    await ctx.reply(`Pong! 🏓`);
-  }
-
-  @SimpleCommand({ name: "hello", aliases: ["hi", "hey"] })
-  async hello(ctx: Context) {
-    await ctx.reply(`Hello, <@${ctx.authorId}>!`);
-  }
-}
-```
-
-That's it! No manual imports needed - decorated command classes are auto-discovered.
-
-## Decorators
-
-### @Stoat()
-
-Marks a class as a command container. All `@SimpleCommand()` methods inside will be registered.
-
-```typescript
-@Stoat()
-export class MyCommands {
-  // commands go here
-}
-```
-
-### @SimpleCommand(options)
-
-Marks a method as a command.
-
-```typescript
-@SimpleCommand({
-  name: 'ban',           // Command name (defaults to method name)
-  description: 'Ban a user',
-  aliases: ['b'],        // Alternative names
-  permissions: ['BanMembers'], // This is currently not implemented, but will be in the future
-  cooldown: 5000,        // 5 seconds
-  cooldownStorage: "database", // A custom flag you can use in your CustomCooldownManager
-  ownerOnly: false,
-  nsfw: false,
-})
-async ban(ctx: Context) {
-  // logic
-}
-```
-
-### StoatLifecycle Interface
-
-Provides intellisense for lifecycle hooks like `onError` and `onCooldown` on your `@Stoat()` classes.
-
-```typescript
-import { Stoat, SimpleCommand, CommandContext, StoatLifecycle } from "stoatx";
-
-@Stoat()
-export class MyCommands implements StoatLifecycle {
-  @SimpleCommand({ cooldown: 5000 })
-  async ping(ctx: CommandContext) {
-    await ctx.reply(`Pong! 🏓`);
-  }
-
-  // Called when the command is placed on cooldown
-  async onCooldown(ctx: CommandContext, remaining: number) {
-    await ctx.reply(`You are in cooldown, wait ${(remaining / 1000).toFixed(1)} seconds!`);
-  }
-
-  // Called when an error occurs during execution
-  async onError(ctx: CommandContext, error: Error) {
-    console.error(error);
-    await ctx.reply("An error occurred");
-  }
-}
-```
-
-## Custom Cooldowns
-
-By default, cooldowns are stored in memory. For persistent or distributed setups, you can implement the `CooldownManager` interface to store cooldowns in a database such as Redis, PostgreSQL or MongoDB.
-
-```typescript
-import { Client, CooldownManager, CommandContext, CommandMetadata, DefaultCooldownManager } from "stoatx";
-
-class MixedCooldownManager implements CooldownManager {
-  private memory = new DefaultCooldownManager();
-
-  async check(ctx: CommandContext, metadata: CommandMetadata): Promise<boolean> {
-    if (metadata.cooldownStorage === "database") {
-      // Return true if action is allowed in DB
-      return true;
-    }
-    return this.memory.check(ctx, metadata);
-  }
-
-  async getRemaining(ctx: CommandContext, metadata: CommandMetadata): Promise<number> {
-    if (metadata.cooldownStorage === "database") {
-      // Query remaining from DB
-      return 0;
-    }
-    return this.memory.getRemaining(ctx, metadata);
-  }
-
-  async set(ctx: CommandContext, metadata: CommandMetadata): Promise<void> {
-    if (metadata.cooldownStorage === "database") {
-      // Store cooldown expiration in your database
-      return;
-    }
-    this.memory.set(ctx, metadata);
-  }
-}
-
-const client = new Client({
-  prefix: "!",
-  cooldownManager: new MixedCooldownManager(),
-});
-```
-
-## Guards
-
-### @Guard(GuardClass)
-
-Adds a guard check before command execution.
-
-```typescript
-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;
-  }
-
-  guardFail(ctx: Context): void {
-    ctx.reply("You need Administrator permission!");
-  }
-}
-
-@Stoat()
-@Guard(IsAdmin)
-export class AdminCommands {
-  @SimpleCommand({ name: "shutdown" })
-  async shutdown(ctx: Context) {
-    await ctx.reply("Shutting down...");
-  }
-}
-```
-
-## Context
-
-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
-
-  reply(content: string): Promise<void>;
-}
-```
-
-## Handler Options
-
-```typescript
-interface StoatxHandlerOptions {
-  client: Client;
-  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
-  };
-  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
-}
-
-// Default auto-discovery is discordx-like: scans broadly under process.cwd(),
-// then registers only files that look like decorated command modules.
-```
-
-## Dynamic Prefix
-
-```typescript
-const client = new Client({
-  prefix: async ({ serverId }) => {
-    // Fetch from database, etc.
-    return serverId ? await getServerPrefix(serverId) : "!";
-  },
-});
-
-// Optional: constrain auto-discovery to specific roots/patterns
-const scopedClient = new Client({
-  prefix: "!",
-  discovery: {
-    roots: [process.cwd()],
-    include: ["apps/bot/dist/commands/**/*.js"],
-  },
-});
-
-// TypeScript source discovery is opt-in and requires a TS runtime loader (tsx/ts-node)
-const tsRuntimeClient = new Client({
-  prefix: "!",
-  extensions: [".ts"],
-  discovery: {
-    include: ["apps/bot/src/commands/**/*.ts"],
-  },
-});
-```
-
-All commands are defined through `@Stoat()` classes and `@SimpleCommand()` methods.
+For installation instructions, guides, and API references, visit the **[Stoatx Documentation](https://stoatx-ts.github.io/stoatx/)**.
 
 ## License
 
-MIT © [Stoatx / Stoatx Team]
+MIT © [Stoatx / Stoatx Team]

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { Message, Client as Client$1, PermissionResolvable } from '@stoatx/client';
+import { Message, Client as Client$1, ClientOptions, PermissionResolvable } from '@stoatx/client';
 export * from '@stoatx/client';
 
 interface AutoDiscoveryOptions {
@@ -150,6 +150,7 @@ declare class StoatxHandler {
     private readonly cooldownManager;
     private readonly disableMentionPrefix;
     private readonly client;
+    private readonly flagPrefix;
     constructor(options: StoatxHandlerOptions);
     /**
      * Initialize the handler - load all commands
@@ -159,6 +160,10 @@ declare class StoatxHandler {
      * Attach registered events to the client
      */
     private attachEvents;
+    /**
+     * Parses raw string arguments into positional args and key-value options
+     */
+    private parseCommandOptions;
     /**
      * Parse a raw message into command context
      */
@@ -167,7 +172,7 @@ declare class StoatxHandler {
         channelId: string;
         serverId?: string | undefined;
         reply: (content: string) => Promise<Message>;
-    }): Promise<CommandContext<Client> | null>;
+    }): Promise<CommandContext | null>;
     /**
      * Handle a message object using the configured message adapter
      *
@@ -205,7 +210,7 @@ declare class StoatxHandler {
     /**
      * Execute a command with the given context
      */
-    execute(ctx: CommandContext<Client>): Promise<boolean>;
+    execute(ctx: CommandContext): Promise<boolean>;
     /**
      * Get the command registry
      */
@@ -257,10 +262,22 @@ declare class StoatxHandler {
  */
 declare class Client extends Client$1 {
     readonly handler: StoatxHandler;
-    constructor(options: Omit<StoatxHandlerOptions, "client">);
-    initCommands(): Promise<void>;
+    constructor(options: Omit<StoatxHandlerOptions, "client"> & ClientOptions);
+    login(token: string): Promise<string>;
+    executeCommand(message: Message): Promise<void>;
 }
 
+type OptionType = "string" | "number" | "boolean" | "user" | "channel" | "role";
+interface CommandOptionDefinition {
+    /** The name of the flag (e.g., "deleteMessages") */
+    name: string;
+    /** The expected data type */
+    type: OptionType;
+    /** Whether the user MUST provide this flag */
+    required?: boolean;
+    /** Description for help menus */
+    description?: string;
+}
 /**
  * Simple command options passed to @SimpleCommand decorator
  * Used with @Stoat() decorated classes for method-based commands
@@ -284,6 +301,10 @@ interface SimpleCommandOptions {
     nsfw?: boolean;
     /** Whether the command is owner only */
     ownerOnly?: boolean;
+    /** Command options/flags (e.g., --deleteMessages true) */
+    options?: CommandOptionDefinition[];
+    /** Command args that act like flags without passing flags */
+    args?: CommandOptionDefinition[];
 }
 /**
  * Resolved command metadata with required fields
@@ -298,11 +319,13 @@ interface CommandMetadata {
     cooldownStorage?: string;
     nsfw: boolean;
     ownerOnly: boolean;
+    options?: CommandOptionDefinition[];
+    args?: CommandOptionDefinition[];
 }
 /**
  * Command execution context
  */
-interface CommandContext<TClient extends Client$1 = Client> {
+interface CommandContext<TOptions = Record<string, string | number | boolean>, TArgs extends (string | number | boolean)[] = (string | number | boolean)[], TClient extends Client$1 = Client> {
     /** The client instance */
     client: TClient;
     /** The raw message content */
@@ -314,7 +337,8 @@ interface CommandContext<TClient extends Client$1 = Client> {
     /** The server/guild ID (if applicable) */
     serverId?: string | undefined;
     /** Parsed command arguments */
-    args: string[];
+    args: TArgs;
+    options?: TOptions;
     /** The prefix used */
     prefix: string;
     /** The command name used (could be an alias) */
@@ -383,6 +407,10 @@ interface StoatxHandlerOptions {
     disableMentionPrefix?: boolean;
     /** Custom cooldown manager */
     cooldownManager?: CooldownManager;
+    /** * The prefix used to identify flags/options (defaults to "-")
+     * @example "+" for +force, "/" for /force
+     */
+    flagPrefix?: string;
 }
 
 /**
@@ -421,7 +449,7 @@ interface SimpleCommandDefinition {
     methodName: string;
     options: SimpleCommandOptions;
 }
-type CommandMethod = (ctx: CommandContext<Client>) => Promise<void>;
+type CommandMethod = (ctx: CommandContext) => Promise<void>;
 /**
  * @SimpleCommand
  * Marks a method as a simple command within a @Stoat() decorated class.
@@ -554,4 +582,9 @@ declare const METADATA_KEYS: {
     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 };
+declare class CommandValidationError extends Error {
+    readonly optionName: string;
+    constructor(optionName: string, message: string);
+}
+
+export { Client, type CommandContext, type CommandMetadata, type CommandOptionDefinition, CommandRegistry, CommandValidationError, type CooldownManager, DefaultCooldownManager, type EventDefinition, Guard, METADATA_KEYS, On, Once, type OptionType, 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.d.ts

@@ -1,4 +1,4 @@
-import { Message, Client as Client$1, PermissionResolvable } from '@stoatx/client';
+import { Message, Client as Client$1, ClientOptions, PermissionResolvable } from '@stoatx/client';
 export * from '@stoatx/client';
 
 interface AutoDiscoveryOptions {
@@ -150,6 +150,7 @@ declare class StoatxHandler {
     private readonly cooldownManager;
     private readonly disableMentionPrefix;
     private readonly client;
+    private readonly flagPrefix;
     constructor(options: StoatxHandlerOptions);
     /**
      * Initialize the handler - load all commands
@@ -159,6 +160,10 @@ declare class StoatxHandler {
      * Attach registered events to the client
      */
     private attachEvents;
+    /**
+     * Parses raw string arguments into positional args and key-value options
+     */
+    private parseCommandOptions;
     /**
      * Parse a raw message into command context
      */
@@ -167,7 +172,7 @@ declare class StoatxHandler {
         channelId: string;
         serverId?: string | undefined;
         reply: (content: string) => Promise<Message>;
-    }): Promise<CommandContext<Client> | null>;
+    }): Promise<CommandContext | null>;
     /**
      * Handle a message object using the configured message adapter
      *
@@ -205,7 +210,7 @@ declare class StoatxHandler {
     /**
      * Execute a command with the given context
      */
-    execute(ctx: CommandContext<Client>): Promise<boolean>;
+    execute(ctx: CommandContext): Promise<boolean>;
     /**
      * Get the command registry
      */
@@ -257,10 +262,22 @@ declare class StoatxHandler {
  */
 declare class Client extends Client$1 {
     readonly handler: StoatxHandler;
-    constructor(options: Omit<StoatxHandlerOptions, "client">);
-    initCommands(): Promise<void>;
+    constructor(options: Omit<StoatxHandlerOptions, "client"> & ClientOptions);
+    login(token: string): Promise<string>;
+    executeCommand(message: Message): Promise<void>;
 }
 
+type OptionType = "string" | "number" | "boolean" | "user" | "channel" | "role";
+interface CommandOptionDefinition {
+    /** The name of the flag (e.g., "deleteMessages") */
+    name: string;
+    /** The expected data type */
+    type: OptionType;
+    /** Whether the user MUST provide this flag */
+    required?: boolean;
+    /** Description for help menus */
+    description?: string;
+}
 /**
  * Simple command options passed to @SimpleCommand decorator
  * Used with @Stoat() decorated classes for method-based commands
@@ -284,6 +301,10 @@ interface SimpleCommandOptions {
     nsfw?: boolean;
     /** Whether the command is owner only */
     ownerOnly?: boolean;
+    /** Command options/flags (e.g., --deleteMessages true) */
+    options?: CommandOptionDefinition[];
+    /** Command args that act like flags without passing flags */
+    args?: CommandOptionDefinition[];
 }
 /**
  * Resolved command metadata with required fields
@@ -298,11 +319,13 @@ interface CommandMetadata {
     cooldownStorage?: string;
     nsfw: boolean;
     ownerOnly: boolean;
+    options?: CommandOptionDefinition[];
+    args?: CommandOptionDefinition[];
 }
 /**
  * Command execution context
  */
-interface CommandContext<TClient extends Client$1 = Client> {
+interface CommandContext<TOptions = Record<string, string | number | boolean>, TArgs extends (string | number | boolean)[] = (string | number | boolean)[], TClient extends Client$1 = Client> {
     /** The client instance */
     client: TClient;
     /** The raw message content */
@@ -314,7 +337,8 @@ interface CommandContext<TClient extends Client$1 = Client> {
     /** The server/guild ID (if applicable) */
     serverId?: string | undefined;
     /** Parsed command arguments */
-    args: string[];
+    args: TArgs;
+    options?: TOptions;
     /** The prefix used */
     prefix: string;
     /** The command name used (could be an alias) */
@@ -383,6 +407,10 @@ interface StoatxHandlerOptions {
     disableMentionPrefix?: boolean;
     /** Custom cooldown manager */
     cooldownManager?: CooldownManager;
+    /** * The prefix used to identify flags/options (defaults to "-")
+     * @example "+" for +force, "/" for /force
+     */
+    flagPrefix?: string;
 }
 
 /**
@@ -421,7 +449,7 @@ interface SimpleCommandDefinition {
     methodName: string;
     options: SimpleCommandOptions;
 }
-type CommandMethod = (ctx: CommandContext<Client>) => Promise<void>;
+type CommandMethod = (ctx: CommandContext) => Promise<void>;
 /**
  * @SimpleCommand
  * Marks a method as a simple command within a @Stoat() decorated class.
@@ -554,4 +582,9 @@ declare const METADATA_KEYS: {
     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 };
+declare class CommandValidationError extends Error {
+    readonly optionName: string;
+    constructor(optionName: string, message: string);
+}
+
+export { Client, type CommandContext, type CommandMetadata, type CommandOptionDefinition, CommandRegistry, CommandValidationError, type CooldownManager, DefaultCooldownManager, type EventDefinition, Guard, METADATA_KEYS, On, Once, type OptionType, type RegisteredCommand, type RegisteredEvent, SimpleCommand, type SimpleCommandDefinition, type SimpleCommandOptions, Stoat, type StoatLifecycle, type StoatxDiscoveryOptions, type StoatxGuard, StoatxHandler, type StoatxHandlerOptions, buildSimpleCommandMetadata, getEventsMetadata, getGuards, getSimpleCommands, isStoatClass };