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/README.md +3 -264
- package/dist/index.d.mts +367 -335
- package/dist/index.d.ts +367 -335
- package/dist/index.js +427 -147
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +428 -147
- package/dist/index.mjs.map +1 -1
- package/package.json +3 -3
package/dist/index.d.mts
CHANGED
|
@@ -1,335 +1,43 @@
|
|
|
1
|
-
import { Client as Client$1,
|
|
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
|
-
*
|
|
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
|
|
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
|
-
|
|
19
|
+
/** The original class constructor (for guard validation) */
|
|
20
|
+
classConstructor: Function;
|
|
163
21
|
}
|
|
164
22
|
/**
|
|
165
|
-
* @
|
|
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
|
-
|
|
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
|
-
*
|
|
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
|
-
*
|
|
262
|
-
*
|
|
36
|
+
* const registry = new CommandRegistry();
|
|
37
|
+
* await registry.loadFromDirectory('./src/commands');
|
|
263
38
|
*
|
|
264
|
-
*
|
|
265
|
-
*
|
|
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
|
-
|
|
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 };
|