@grammyjs/commands
Version:
grammY Commands Plugin
213 lines (212 loc) • 8.25 kB
TypeScript
import { type BotCommandScope, type BotCommandScopeAllChatAdministrators, type BotCommandScopeAllGroupChats, type BotCommandScopeAllPrivateChats, type ChatTypeMiddleware, CommandContext, type Context, type LanguageCode, type Middleware, type MiddlewareObj } from "./deps.node.js";
import type { BotCommandX, CommandOptions } from "./types.js";
import { type MaybeArray } from "./utils/array.js";
type BotCommandGroupsScope = BotCommandScopeAllGroupChats | BotCommandScopeAllChatAdministrators;
/**
* Represents a matched command, the result of the RegExp match, and the rest of the input.
*/
export interface CommandMatch {
/**
* The matched command.
*/
command: string | RegExp;
/**
* The rest of the input after the command.
*/
rest: string;
/**
* The result of the RegExp match.
*
* Only defined if the command is a RegExp.
*/
match?: RegExpExecArray | null;
}
/**
* Class that represents a single command and allows you to configure it.
*/
export declare class Command<C extends Context = Context> implements MiddlewareObj<C> {
private _scopes;
private _languages;
private _defaultScopeComposer;
private _options;
private _scopeHandlers;
private _cachedComposer;
private _cachedComposerInvalidated;
private _hasHandler;
/**
* Initialize a new command with a default handler.
*
* [!IMPORTANT] This class by its own does nothing. It needs to be imported into a `CommandGroup`
* via the `add` method.
*
* @example
* ```ts
* const sayHi = new Command("hi","say hi", (ctx) => ctx.reply("hi"))
* const myCmds = new CommandGroup().add(sayHi)
* ```
*
* @param name Default command name
* @param description Default command description
* @param handler Default command handler
* @param options Extra options that should apply only to this command
* @returns An instance of the `Command` class
*/
constructor(name: string | RegExp, description: string, handler: MaybeArray<Middleware<CommandContext<C>>>, options?: Partial<CommandOptions>);
/**
* Initialize a new command with no handlers.
*
* [!IMPORTANT] This class by its own does nothing. It needs to be imported into a `CommandGroup`
* via the `add` method
*
* @example
* ```ts
* const sayHi = new Command("hi","say hi", (ctx) => ctx.reply("hi") )
* const myCmds = new CommandGroup().add(sayHi)
* ```
*
* @param name Default command name
* @param description Default command description
* @param options Extra options that should apply only to this command
* @returns An instance of the `Command` class
*/
constructor(name: string | RegExp, description: string, options?: Partial<CommandOptions>);
constructor(name: string | RegExp, description: string, handlerOrOptions?: MaybeArray<Middleware<CommandContext<C>>> | Partial<CommandOptions>, options?: Partial<CommandOptions>);
/**
* Whether the command has a custom prefix
*/
get hasCustomPrefix(): boolean | "";
/**
* Gets the command name as string
*/
get stringName(): string;
/**
* Whether the command can be passed to a `setMyCommands` API call
* and, if not, the reason.
*/
isApiCompliant(language?: LanguageCode | "default"): [result: true] | [
result: false,
...reasons: string[]
];
/**
* Get registered scopes for this command
*/
get scopes(): BotCommandScope[];
/**
* Get registered languages for this command
*/
get languages(): Map<LanguageCode | "default", {
name: string | RegExp;
description: string;
}>;
/**
* Get registered names for this command
*/
get names(): (string | RegExp)[];
/**
* Get the default name for this command
*/
get name(): string | RegExp;
/**
* Get the default description for this command
*/
get description(): string;
/**
* Get the prefix for this command
*/
get prefix(): string;
/**
* Get if this command has a handler
*/
get hasHandler(): boolean;
/**
* Registers the command to a scope to allow it to be handled and used with `setMyCommands`.
* This will automatically apply filtering middlewares for you, so the handler only runs on the specified scope.
*
* @example
* ```ts
* const myCommands = new CommandGroup();
* myCommands.command("start", "Initializes bot configuration")
* .addToScope(
* { type: "all_private_chats" },
* (ctx) => ctx.reply(`Hello, ${ctx.chat.first_name}!`),
* )
* .addToScope(
* { type: "all_group_chats" },
* (ctx) => ctx.reply(`Hello, members of ${ctx.chat.title}!`),
* );
* ```
*
* @param scope Which scope this command should be available on
* @param middleware The handler for this command on the specified scope
* @param options Additional options that should apply only to this scope
*/
addToScope(scope: BotCommandGroupsScope, middleware?: MaybeArray<ChatTypeMiddleware<C, "group" | "supergroup">>, options?: Partial<CommandOptions>): this;
addToScope(scope: BotCommandScopeAllPrivateChats, middleware?: MaybeArray<ChatTypeMiddleware<C, "private">>, options?: Partial<CommandOptions>): this;
addToScope(scope: BotCommandScope, middleware?: MaybeArray<Middleware<C>>, options?: Partial<CommandOptions>): this;
/**
* Finds the matching command in the given context
*
* @example
* ```ts
* // ctx.msg.text = "/delete_123 something"
* const match = Command.findMatchingCommand(/delete_(.*)/, { prefix: "/", ignoreCase: true }, ctx)
* // match is { command: /delete_(.*)/, rest: ["something"], match: ["delete_123"] }
* ```
*/
static findMatchingCommand(command: MaybeArray<string | RegExp>, options: CommandOptions, ctx: Context): CommandMatch | null;
/**
* Creates a matcher for the given command that can be used in filtering operations
*
* @example
* ```ts
* bot
* .filter(
* Command.hasCommand(/delete_(.*)/),
* (ctx) => ctx.reply(`Deleting ${ctx.message?.text?.split("_")[1]}`)
* )
* ```
*
* @param command Command name or RegEx
* @param options Options that should apply to the matching algorithm
* @returns A predicate that matches the given command
*/
static hasCommand(command: MaybeArray<string | RegExp>, options: CommandOptions): (ctx: Context) => boolean;
/**
* Adds a new translation for the command
*
* @example
* ```ts
* myCommands
* .command("start", "Starts the bot configuration")
* .localize("pt", "iniciar", "Inicia a configuração do bot")
* ```
*
* @param languageCode Language this translation applies to. @see https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes
* @param name Localized command name
* @param description Localized command description
*/
localize(languageCode: LanguageCode, name: string | RegExp, description: string): this;
/**
* Gets the localized command name of an existing translation
* @param languageCode Language to get the name for
* @returns Localized command name
*/
getLocalizedName(languageCode: LanguageCode | "default"): string | RegExp;
/**
* Gets the localized command name of an existing translation
* @param languageCode Language to get the name for
* @returns Localized command name
*/
getLocalizedDescription(languageCode: LanguageCode | "default"): string;
/**
* Converts command to an object representation.
* Useful for JSON serialization.
*
* @param languageCode If specified, uses localized versions of the command name and description
* @returns Object representation of this command
*/
toObject(languageCode?: LanguageCode | "default"): Pick<BotCommandX, "command" | "description" | "hasHandler">;
private registerScopeHandlers;
middleware(): import("grammy").MiddlewareFn<C>;
}
export {};