stoatx 0.7.6 → 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.ts CHANGED
@@ -1,335 +1,43 @@
1
- import { Client as Client$1, Message, PermissionResolvable } from '@stoatx/client';
1
+ import { Message, Client as Client$1, ClientOptions, PermissionResolvable } from '@stoatx/client';
2
2
  export * from '@stoatx/client';
3
3
 
4
- /**
5
- * Simple command options passed to @SimpleCommand decorator
6
- * Used with @Stoat() decorated classes for method-based commands
7
- */
8
- interface SimpleCommandOptions {
9
- /** Command name (defaults to method name) */
10
- name?: string;
11
- /** Command description */
12
- description?: string;
13
- /** Command aliases */
14
- aliases?: string[];
15
- /** Required permissions to run the command */
16
- permissions?: PermissionResolvable[];
17
- /** Command category (auto-detected from directory if not provided) */
18
- category?: string;
19
- /** Cooldown in milliseconds */
20
- cooldown?: number;
21
- /** Storage strategy or identifier for cooldowns (e.g. "memory", "database") */
22
- cooldownStorage?: string;
23
- /** Whether the command is NSFW only */
24
- nsfw?: boolean;
25
- /** Whether the command is owner only */
26
- ownerOnly?: boolean;
27
- }
28
- /**
29
- * Resolved command metadata with required fields
30
- */
31
- interface CommandMetadata {
32
- name: string;
33
- description: string;
34
- aliases: string[];
35
- permissions: PermissionResolvable[];
36
- category: string;
37
- cooldown: number;
38
- cooldownStorage?: string;
39
- nsfw: boolean;
40
- ownerOnly: boolean;
41
- }
42
- /**
43
- * Command execution context
44
- */
45
- interface CommandContext {
46
- /** The client instance */
47
- client: Client$1;
48
- /** The raw message content */
49
- content: string;
50
- /** The author ID */
51
- authorId: string;
52
- /** The channel ID */
53
- channelId: string;
54
- /** The server/guild ID (if applicable) */
55
- serverId?: string | undefined;
56
- /** Parsed command arguments */
57
- args: string[];
58
- /** The prefix used */
59
- prefix: string;
60
- /** The command name used (could be an alias) */
61
- commandName: string;
62
- /** Reply to the message */
63
- reply: (content: string) => Promise<Message>;
64
- /** The original message object (platform-specific) */
65
- message: Message;
66
- }
67
- /**
68
- * Optional lifecycle hooks for @Stoat() class instances
69
- */
70
- interface StoatLifecycle {
71
- /** Optional: Called when an error occurs during command execution */
72
- onError?(ctx: CommandContext, error: Error): Promise<void> | void;
73
- /** Optional: Called when a cooldown is active */
74
- onCooldown?(ctx: CommandContext, remaining: number): Promise<void> | void;
75
- /** Optional: Called when user doesn't have the permissions needed */
76
- onMissingPermissions?(ctx: CommandContext, missing: PermissionResolvable[]): Promise<void> | void;
77
- /** Allows the class to contain other methods (such as your commands) */
78
- [method: string]: any;
79
- }
80
- /**
81
- * Cooldown manager interface for custom cooldown storage (e.g., database)
82
- */
83
- interface CooldownManager {
84
- check(ctx: CommandContext, metadata: CommandMetadata): boolean | Promise<boolean>;
85
- getRemaining(ctx: CommandContext, metadata: CommandMetadata): number | Promise<number>;
86
- set(ctx: CommandContext, metadata: CommandMetadata): void | Promise<void>;
87
- clear?(): void | Promise<void>;
88
- }
89
- interface StoatxGuard {
90
- run(ctx: CommandContext): Promise<boolean> | boolean;
91
- guardFail?(ctx: CommandContext): Promise<void> | void;
92
- }
93
- /**
94
- * Discovery options for automatic command module loading
95
- */
96
- interface StoatxDiscoveryOptions {
97
- /** Root directories to scan (default: [process.cwd()]) */
4
+ interface AutoDiscoveryOptions {
98
5
  roots?: string[];
99
- /** Glob patterns relative to each root */
100
6
  include?: string[];
101
- /** Additional ignore patterns */
102
7
  ignore?: string[];
103
8
  }
104
9
  /**
105
- * Handler options
106
- */
107
- interface StoatxHandlerOptions {
108
- /** The client instance */
109
- client: Client$1;
110
- /** Directory to scan for command modules (absolute path) */
111
- commandsDir?: string;
112
- /** Auto-discovery options used when commandsDir is not provided */
113
- discovery?: StoatxDiscoveryOptions;
114
- /** Command prefix or prefix resolver function */
115
- prefix: string | ((ctx: {
116
- serverId?: string | undefined;
117
- }) => string | Promise<string>);
118
- /** Owner IDs for owner-only commands */
119
- owners?: string[];
120
- /** File extensions to load (default: ['.js', '.mjs', '.cjs']) */
121
- extensions?: string[];
122
- /** Disable mention prefix support (default: false) */
123
- disableMentionPrefix?: boolean;
124
- /** Custom cooldown manager */
125
- cooldownManager?: CooldownManager;
126
- }
127
-
128
- /**
129
- * @Stoat
130
- * Marks a class as a Stoat command container.
131
- * Use this decorator on classes that contain @SimpleCommand methods.
132
- *
133
- * @example
134
- * ```ts
135
- * import { Stoat, SimpleCommand, CommandContext } from 'stoatx';
136
- *
137
- * @Stoat()
138
- * class ModerationCommands {
139
- * @SimpleCommand({ name: 'ban', description: 'Ban a user' })
140
- * async ban(ctx: CommandContext) {
141
- * await ctx.reply('User banned!');
142
- * }
143
- *
144
- * @SimpleCommand({ name: 'kick', description: 'Kick a user' })
145
- * async kick(ctx: CommandContext) {
146
- * await ctx.reply('User kicked!');
147
- * }
148
- * }
149
- * ```
150
- */
151
- declare function Stoat(): ClassDecorator;
152
- /**
153
- * Check if a class is decorated with @Stoat
154
- */
155
- declare function isStoatClass(target: Function): boolean;
156
-
157
- /**
158
- * Stored simple command metadata from method decorator
10
+ * Stored command entry from @Stoat/@SimpleCommand registration.
159
11
  */
160
- interface SimpleCommandDefinition {
12
+ interface RegisteredCommand {
13
+ /** Instance of the @Stoat class */
14
+ instance: object;
15
+ /** Command metadata */
16
+ metadata: CommandMetadata;
17
+ /** Method name to call */
161
18
  methodName: string;
162
- options: SimpleCommandOptions;
19
+ /** The original class constructor (for guard validation) */
20
+ classConstructor: Function;
163
21
  }
164
22
  /**
165
- * @SimpleCommand
166
- * Marks a method as a simple command within a @Stoat() decorated class.
167
- *
168
- * @example
169
- * ```ts
170
- * @Stoat()
171
- * class Example {
172
- * @SimpleCommand({ name: 'ping', description: 'Replies with Pong!' })
173
- * async ping(ctx: CommandContext) {
174
- * await ctx.reply('Pong!');
175
- * }
176
- *
177
- * @SimpleCommand({ aliases: ['perm'], name: 'permission' })
178
- * async permission(ctx: CommandContext) {
179
- * await ctx.reply('Access granted');
180
- * }
181
- * }
182
- * ```
183
- */
184
- declare function SimpleCommand(options?: SimpleCommandOptions): MethodDecorator;
185
- /**
186
- * Get all simple command definitions from a @Stoat class
187
- */
188
- declare function getSimpleCommands(target: Function): SimpleCommandDefinition[];
189
-
190
- /**
191
- * @Guard
192
- * Runs before a command to check if it should execute.
193
- * Should return true to allow execution, false to block.
194
- * Applied on @Stoat classes to guard all contained @SimpleCommand methods.
195
- *
196
- * @example
197
- * ```ts
198
- * import { Guard, Stoat, SimpleCommand, CommandContext } from 'stoatx';
199
- *
200
- * // Define a guard
201
- * class NotBot implements StoatxGuard {
202
- * run(ctx: CommandContext): boolean {
203
- * return !ctx.message.author.bot;
204
- * }
205
- *
206
- * guardFail(ctx: CommandContext): void {
207
- * ctx.reply("Bots cannot use this command!");
208
- * }
209
- * }
210
- *
211
- * @Stoat()
212
- * @Guard(NotBot)
213
- * class AdminCommands {
214
- * @SimpleCommand({ name: 'admin', description: 'Admin only command' })
215
- * async admin(ctx: CommandContext) {
216
- * ctx.reply("You passed the guard check!");
217
- * }
218
- * }
219
- * ```
220
- */
221
- declare function Guard(guardClass: Function): ClassDecorator;
222
- /**
223
- * Get all guards from a decorated class
23
+ * Stored event entry from @On/@Once registration.
224
24
  */
225
- declare function getGuards(target: Function): Function[];
226
-
227
- interface EventDefinition {
25
+ interface RegisteredEvent {
26
+ instance: object;
228
27
  methodName: string;
229
28
  event: string;
230
29
  type: "on" | "once";
231
30
  }
232
31
  /**
233
- * @On
234
- * Triggered on every occurrence of the event.
235
- * Marks a method to be executed whenever the specified client event is emitted.
236
- *
237
- * @example
238
- * ```ts
239
- * import { Stoat, On } from 'stoatx';
240
- * import { Message, Client } from 'stoat.js';
241
- *
242
- * @Stoat()
243
- * class BotEvents {
244
- * @On('messageCreate')
245
- * async onMessage(message: Message, client: Client) {
246
- * console.log('New message received:', message.content);
247
- * }
248
- * }
249
- * ```
250
- *
251
- * @param event The name of the client event to listen to
252
- */
253
- declare function On(event: string): MethodDecorator;
254
- /**
255
- * @Once
256
- * Triggered only fully once.
257
- * Marks a method to be executed only the FIRST time the specified client event is emitted.
32
+ * CommandRegistry - Scans directories and stores commands in a Map
258
33
  *
259
34
  * @example
260
35
  * ```ts
261
- * import { Stoat, Once } from 'stoatx';
262
- * import { Client } from 'stoat.js';
36
+ * const registry = new CommandRegistry();
37
+ * await registry.loadFromDirectory('./src/commands');
263
38
  *
264
- * @Stoat()
265
- * class BotEvents {
266
- * @Once('ready')
267
- * async onReady(client: Client) {
268
- * console.log('Bot successfully started and logged in!');
269
- * }
270
- * }
271
- * ```
272
- *
273
- * @param event The name of the client event to listen to
274
- */
275
- declare function Once(event: string): MethodDecorator;
276
- /**
277
- * Get all event definitions from a @Stoat class
278
- */
279
- declare function getEventsMetadata(target: Function): EventDefinition[];
280
-
281
- /**
282
- * Build CommandMetadata from SimpleCommandOptions
283
- */
284
- declare function buildSimpleCommandMetadata(options: SimpleCommandOptions, methodName: string, category?: string): CommandMetadata;
285
-
286
- /**
287
- * Metadata keys used by decorators
288
- */
289
- declare const METADATA_KEYS: {
290
- readonly IS_STOAT_CLASS: symbol;
291
- readonly SIMPLE_COMMANDS: symbol;
292
- readonly GUARDS: "stoatx:command:guards";
293
- readonly EVENTS: symbol;
294
- };
295
-
296
- interface AutoDiscoveryOptions {
297
- roots?: string[];
298
- include?: string[];
299
- ignore?: string[];
300
- }
301
- /**
302
- * Stored command entry from @Stoat/@SimpleCommand registration.
303
- */
304
- interface RegisteredCommand {
305
- /** Instance of the @Stoat class */
306
- instance: object;
307
- /** Command metadata */
308
- metadata: CommandMetadata;
309
- /** Method name to call */
310
- methodName: string;
311
- /** The original class constructor (for guard validation) */
312
- classConstructor: Function;
313
- }
314
- /**
315
- * Stored event entry from @On/@Once registration.
316
- */
317
- interface RegisteredEvent {
318
- instance: object;
319
- methodName: string;
320
- event: string;
321
- type: "on" | "once";
322
- }
323
- /**
324
- * CommandRegistry - Scans directories and stores commands in a Map
325
- *
326
- * @example
327
- * ```ts
328
- * const registry = new CommandRegistry();
329
- * await registry.loadFromDirectory('./src/commands');
330
- *
331
- * const ping = registry.get('ping');
332
- * const allCommands = registry.getAll();
39
+ * const ping = registry.get('ping');
40
+ * const allCommands = registry.getAll();
333
41
  * ```
334
42
  */
335
43
  declare class CommandRegistry {
@@ -426,29 +134,6 @@ declare class DefaultCooldownManager implements CooldownManager {
426
134
  set(ctx: CommandContext, metadata: CommandMetadata): void;
427
135
  clear(): void;
428
136
  }
429
- /**
430
- * Client - An extended Client that integrates StoatxHandler directly
431
- *
432
- * @example
433
- * ```ts
434
- * import { Client } from 'stoatx';
435
- *
436
- * const client = new Client({
437
- * prefix: '!',
438
- * owners: ['owner-user-id'],
439
- * });
440
- *
441
- * await client.initCommands();
442
- * ```
443
- */
444
- declare class Client extends Client$1 {
445
- readonly handler: StoatxHandler;
446
- constructor(options: Omit<StoatxHandlerOptions, "client">);
447
- /**
448
- * Initialize the StoatxHandler commands
449
- */
450
- initCommands(): Promise<void>;
451
- }
452
137
  /**
453
138
  * StoatxHandler - The execution engine for commands
454
139
  *
@@ -465,6 +150,7 @@ declare class StoatxHandler {
465
150
  private readonly cooldownManager;
466
151
  private readonly disableMentionPrefix;
467
152
  private readonly client;
153
+ private readonly flagPrefix;
468
154
  constructor(options: StoatxHandlerOptions);
469
155
  /**
470
156
  * Initialize the handler - load all commands
@@ -474,6 +160,10 @@ declare class StoatxHandler {
474
160
  * Attach registered events to the client
475
161
  */
476
162
  private attachEvents;
163
+ /**
164
+ * Parses raw string arguments into positional args and key-value options
165
+ */
166
+ private parseCommandOptions;
477
167
  /**
478
168
  * Parse a raw message into command context
479
169
  */
@@ -555,4 +245,346 @@ declare class StoatxHandler {
555
245
  private resolvePrefix;
556
246
  }
557
247
 
558
- 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 };
248
+ /**
249
+ * Client - An extended Client that integrates StoatxHandler directly
250
+ *
251
+ * @example
252
+ * ```ts
253
+ * import { Client } from 'stoatx';
254
+ *
255
+ * const client = new Client({
256
+ * prefix: '!',
257
+ * owners: ['owner-user-id'],
258
+ * });
259
+ *
260
+ * await client.initCommands();
261
+ * ```
262
+ */
263
+ declare class Client extends Client$1 {
264
+ readonly handler: StoatxHandler;
265
+ constructor(options: Omit<StoatxHandlerOptions, "client"> & ClientOptions);
266
+ login(token: string): Promise<string>;
267
+ executeCommand(message: Message): Promise<void>;
268
+ }
269
+
270
+ type OptionType = "string" | "number" | "boolean" | "user" | "channel" | "role";
271
+ interface CommandOptionDefinition {
272
+ /** The name of the flag (e.g., "deleteMessages") */
273
+ name: string;
274
+ /** The expected data type */
275
+ type: OptionType;
276
+ /** Whether the user MUST provide this flag */
277
+ required?: boolean;
278
+ /** Description for help menus */
279
+ description?: string;
280
+ }
281
+ /**
282
+ * Simple command options passed to @SimpleCommand decorator
283
+ * Used with @Stoat() decorated classes for method-based commands
284
+ */
285
+ interface SimpleCommandOptions {
286
+ /** Command name (defaults to method name) */
287
+ name?: string;
288
+ /** Command description */
289
+ description?: string;
290
+ /** Command aliases */
291
+ aliases?: string[];
292
+ /** Required permissions to run the command */
293
+ permissions?: PermissionResolvable[];
294
+ /** Command category (auto-detected from directory if not provided) */
295
+ category?: string;
296
+ /** Cooldown in milliseconds */
297
+ cooldown?: number;
298
+ /** Storage strategy or identifier for cooldowns (e.g. "memory", "database") */
299
+ cooldownStorage?: string;
300
+ /** Whether the command is NSFW only */
301
+ nsfw?: boolean;
302
+ /** Whether the command is owner only */
303
+ ownerOnly?: boolean;
304
+ /** Command options/flags (e.g., --deleteMessages true) */
305
+ options?: CommandOptionDefinition[];
306
+ /** Command args that act like flags without passing flags */
307
+ args?: CommandOptionDefinition[];
308
+ }
309
+ /**
310
+ * Resolved command metadata with required fields
311
+ */
312
+ interface CommandMetadata {
313
+ name: string;
314
+ description: string;
315
+ aliases: string[];
316
+ permissions: PermissionResolvable[];
317
+ category: string;
318
+ cooldown: number;
319
+ cooldownStorage?: string;
320
+ nsfw: boolean;
321
+ ownerOnly: boolean;
322
+ options?: CommandOptionDefinition[];
323
+ args?: CommandOptionDefinition[];
324
+ }
325
+ /**
326
+ * Command execution context
327
+ */
328
+ interface CommandContext<TOptions = Record<string, string | number | boolean>, TArgs extends (string | number | boolean)[] = (string | number | boolean)[], TClient extends Client$1 = Client> {
329
+ /** The client instance */
330
+ client: TClient;
331
+ /** The raw message content */
332
+ content: string;
333
+ /** The author ID */
334
+ authorId: string;
335
+ /** The channel ID */
336
+ channelId: string;
337
+ /** The server/guild ID (if applicable) */
338
+ serverId?: string | undefined;
339
+ /** Parsed command arguments */
340
+ args: TArgs;
341
+ options?: TOptions;
342
+ /** The prefix used */
343
+ prefix: string;
344
+ /** The command name used (could be an alias) */
345
+ commandName: string;
346
+ /** Reply to the message */
347
+ reply: (content: string) => Promise<Message>;
348
+ /** The original message object (platform-specific) */
349
+ message: Message;
350
+ }
351
+ /**
352
+ * Optional lifecycle hooks for @Stoat() class instances
353
+ */
354
+ interface StoatLifecycle {
355
+ /** Optional: Called when an error occurs during command execution */
356
+ onError?(ctx: CommandContext<Client>, error: Error): Promise<void> | void;
357
+ /** Optional: Called when a cooldown is active */
358
+ onCooldown?(ctx: CommandContext<Client>, remaining: number): Promise<void> | void;
359
+ /** Optional: Called when user doesn't have the permissions needed */
360
+ onMissingPermissions?(ctx: CommandContext<Client>, missing: PermissionResolvable[]): Promise<void> | void;
361
+ /** Allows the class to contain other methods (such as your commands) */
362
+ [method: string]: any;
363
+ }
364
+ /**
365
+ * Cooldown manager interface for custom cooldown storage (e.g., database)
366
+ */
367
+ interface CooldownManager {
368
+ check(ctx: CommandContext<any>, metadata: CommandMetadata): boolean | Promise<boolean>;
369
+ getRemaining(ctx: CommandContext<any>, metadata: CommandMetadata): number | Promise<number>;
370
+ set(ctx: CommandContext<any>, metadata: CommandMetadata): void | Promise<void>;
371
+ clear?(): void | Promise<void>;
372
+ }
373
+ interface StoatxGuard {
374
+ run(ctx: CommandContext<Client>): Promise<boolean> | boolean;
375
+ guardFail?(ctx: CommandContext<Client>): Promise<void> | void;
376
+ }
377
+ /**
378
+ * Discovery options for automatic command module loading
379
+ */
380
+ interface StoatxDiscoveryOptions {
381
+ /** Root directories to scan (default: [process.cwd()]) */
382
+ roots?: string[];
383
+ /** Glob patterns relative to each root */
384
+ include?: string[];
385
+ /** Additional ignore patterns */
386
+ ignore?: string[];
387
+ }
388
+ /**
389
+ * Handler options
390
+ */
391
+ interface StoatxHandlerOptions {
392
+ /** The client instance */
393
+ client: Client;
394
+ /** Directory to scan for command modules (absolute path) */
395
+ commandsDir?: string;
396
+ /** Auto-discovery options used when commandsDir is not provided */
397
+ discovery?: StoatxDiscoveryOptions;
398
+ /** Command prefix or prefix resolver function */
399
+ prefix: string | ((ctx: {
400
+ serverId?: string | undefined;
401
+ }) => string | Promise<string>);
402
+ /** Owner IDs for owner-only commands */
403
+ owners?: string[];
404
+ /** File extensions to load (default: ['.js', '.mjs', '.cjs']) */
405
+ extensions?: string[];
406
+ /** Disable mention prefix support (default: false) */
407
+ disableMentionPrefix?: boolean;
408
+ /** Custom cooldown manager */
409
+ cooldownManager?: CooldownManager;
410
+ /** * The prefix used to identify flags/options (defaults to "-")
411
+ * @example "+" for +force, "/" for /force
412
+ */
413
+ flagPrefix?: string;
414
+ }
415
+
416
+ /**
417
+ * @Stoat
418
+ * Marks a class as a Stoat command container.
419
+ * Use this decorator on classes that contain @SimpleCommand methods.
420
+ *
421
+ * @example
422
+ * ```ts
423
+ * import { Stoat, SimpleCommand, CommandContext } from 'stoatx';
424
+ *
425
+ * @Stoat()
426
+ * class ModerationCommands {
427
+ * @SimpleCommand({ name: 'ban', description: 'Ban a user' })
428
+ * async ban(ctx: CommandContext) {
429
+ * await ctx.reply('User banned!');
430
+ * }
431
+ *
432
+ * @SimpleCommand({ name: 'kick', description: 'Kick a user' })
433
+ * async kick(ctx: CommandContext) {
434
+ * await ctx.reply('User kicked!');
435
+ * }
436
+ * }
437
+ * ```
438
+ */
439
+ declare function Stoat(): ClassDecorator;
440
+ /**
441
+ * Check if a class is decorated with @Stoat
442
+ */
443
+ declare function isStoatClass(target: Function): boolean;
444
+
445
+ /**
446
+ * Stored simple command metadata from method decorator
447
+ */
448
+ interface SimpleCommandDefinition {
449
+ methodName: string;
450
+ options: SimpleCommandOptions;
451
+ }
452
+ type CommandMethod = (ctx: CommandContext) => Promise<void>;
453
+ /**
454
+ * @SimpleCommand
455
+ * Marks a method as a simple command within a @Stoat() decorated class.
456
+ *
457
+ * @example
458
+ * ```ts
459
+ * @Stoat()
460
+ * class Example {
461
+ * @SimpleCommand({ name: 'ping', description: 'Replies with Pong!' })
462
+ * async ping(ctx: CommandContext) {
463
+ * await ctx.reply('Pong!');
464
+ * }
465
+ *
466
+ * @SimpleCommand({ aliases: ['perm'], name: 'permission' })
467
+ * async permission(ctx: CommandContext) {
468
+ * await ctx.reply('Access granted');
469
+ * }
470
+ * }
471
+ * ```
472
+ */
473
+ declare function SimpleCommand(options?: SimpleCommandOptions): <T extends CommandMethod>(target: Object, propertyKey: string | symbol, descriptor: TypedPropertyDescriptor<T>) => TypedPropertyDescriptor<T>;
474
+ /**
475
+ * Get all simple command definitions from a @Stoat class
476
+ */
477
+ declare function getSimpleCommands(target: Function): SimpleCommandDefinition[];
478
+
479
+ /**
480
+ * @Guard
481
+ * Runs before a command to check if it should execute.
482
+ * Should return true to allow execution, false to block.
483
+ * Applied on @Stoat classes to guard all contained @SimpleCommand methods.
484
+ *
485
+ * @example
486
+ * ```ts
487
+ * import { Guard, Stoat, SimpleCommand, CommandContext } from 'stoatx';
488
+ *
489
+ * // Define a guard
490
+ * class NotBot implements StoatxGuard {
491
+ * run(ctx: CommandContext): boolean {
492
+ * return !ctx.message.author.bot;
493
+ * }
494
+ *
495
+ * guardFail(ctx: CommandContext): void {
496
+ * ctx.reply("Bots cannot use this command!");
497
+ * }
498
+ * }
499
+ *
500
+ * @Stoat()
501
+ * @Guard(NotBot)
502
+ * class AdminCommands {
503
+ * @SimpleCommand({ name: 'admin', description: 'Admin only command' })
504
+ * async admin(ctx: CommandContext) {
505
+ * ctx.reply("You passed the guard check!");
506
+ * }
507
+ * }
508
+ * ```
509
+ */
510
+ declare function Guard(guardClass: Function): ClassDecorator;
511
+ /**
512
+ * Get all guards from a decorated class
513
+ */
514
+ declare function getGuards(target: Function): Function[];
515
+
516
+ interface EventDefinition {
517
+ methodName: string;
518
+ event: string;
519
+ type: "on" | "once";
520
+ }
521
+ /**
522
+ * @On
523
+ * Triggered on every occurrence of the event.
524
+ * Marks a method to be executed whenever the specified client event is emitted.
525
+ *
526
+ * @example
527
+ * ```ts
528
+ * import { Stoat, On } from 'stoatx';
529
+ * import { Message, Client } from 'stoat.js';
530
+ *
531
+ * @Stoat()
532
+ * class BotEvents {
533
+ * @On('messageCreate')
534
+ * async onMessage(message: Message, client: Client) {
535
+ * console.log('New message received:', message.content);
536
+ * }
537
+ * }
538
+ * ```
539
+ *
540
+ * @param event The name of the client event to listen to
541
+ */
542
+ declare function On(event: string): MethodDecorator;
543
+ /**
544
+ * @Once
545
+ * Triggered only fully once.
546
+ * Marks a method to be executed only the FIRST time the specified client event is emitted.
547
+ *
548
+ * @example
549
+ * ```ts
550
+ * import { Stoat, Once } from 'stoatx';
551
+ * import { Client } from 'stoat.js';
552
+ *
553
+ * @Stoat()
554
+ * class BotEvents {
555
+ * @Once('ready')
556
+ * async onReady(client: Client) {
557
+ * console.log('Bot successfully started and logged in!');
558
+ * }
559
+ * }
560
+ * ```
561
+ *
562
+ * @param event The name of the client event to listen to
563
+ */
564
+ declare function Once(event: string): MethodDecorator;
565
+ /**
566
+ * Get all event definitions from a @Stoat class
567
+ */
568
+ declare function getEventsMetadata(target: Function): EventDefinition[];
569
+
570
+ /**
571
+ * Build CommandMetadata from SimpleCommandOptions
572
+ */
573
+ declare function buildSimpleCommandMetadata(options: SimpleCommandOptions, methodName: string, category?: string): CommandMetadata;
574
+
575
+ /**
576
+ * Metadata keys used by decorators
577
+ */
578
+ declare const METADATA_KEYS: {
579
+ readonly IS_STOAT_CLASS: symbol;
580
+ readonly SIMPLE_COMMANDS: symbol;
581
+ readonly GUARDS: "stoatx:command:guards";
582
+ readonly EVENTS: symbol;
583
+ };
584
+
585
+ declare class CommandValidationError extends Error {
586
+ readonly optionName: string;
587
+ constructor(optionName: string, message: string);
588
+ }
589
+
590
+ 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 };