stoatx 0.7.7 → 1.0.1

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]