@grammyjs/commands 0.5.0 → 0.6.0

package/out/command.d.ts

@@ -1,49 +1,125 @@
 import { type BotCommand, type BotCommandScope, type BotCommandScopeAllChatAdministrators, type BotCommandScopeAllGroupChats, type BotCommandScopeAllPrivateChats, type ChatTypeMiddleware, type Context, type Middleware, type MiddlewareObj } from "./deps.node.js";
+import { CommandOptions } from "./types.js";
 export type MaybeArray<T> = T | T[];
-export type CommandOptions = {
-    /**
-     * The prefix used to identify a command.
-     * Defaults to `/`.
-     */
-    prefix: string;
-    /**
-     * Whether the command should only be matched at the start of the message.
-     * Defaults to `true`.
-     */
-    matchOnlyAtStart: boolean;
-    /**
-     * Whether to ignore or only care about commands ending with the bot's username.
-     * Defaults to `"optional"`.
-     *
-     * - `"ignored"`: only non-targeted commands are matched
-     * - `"optional"`: both targeted and non-targeted commands are matched
-     * - `"ignored"`: only targeted commands are matched
-     */
-    targetedCommands: "ignored" | "optional" | "required";
-};
 type BotCommandGroupsScope = BotCommandScopeAllGroupChats | BotCommandScopeAllChatAdministrators;
 export declare const matchesPattern: (value: string, pattern: string | RegExp) => boolean;
+/**
+ * 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 _composer;
     private _options;
+    /**
+     * Constructor for the `Command` class.
+     * Do not call this directly. Instead, use the `command` method from the `Commands` class
+     *
+     * @param name Default command name
+     * @param description Default command description
+     * @param options Options object that shuold apply to this command only
+     * @access package
+     */
     constructor(name: string | RegExp, description: string, options?: Partial<CommandOptions>);
+    /**
+     * Get registered scopes for this command
+     */
     get scopes(): BotCommandScope[];
+    /**
+     * Get registered languages for this command
+     */
     get languages(): Map<string, {
         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;
+    /**
+     * 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 Commands();
+     * 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;
+    /**
+     * 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
+     * @param name Localized command name
+     * @param description Localized command description
+     */
     localize(languageCode: string, 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: string): 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: string): 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?: string): BotCommand;
     middleware(): import("grammy").MiddlewareFn<C>;
 }

package/out/command.js

@@ -4,10 +4,24 @@ exports.Command = exports.matchesPattern = void 0;
 const deps_node_js_1 = require("./deps.node.js");
 const errors_js_1 = require("./errors.js");
 const ensureArray = (value) => Array.isArray(value) ? value : [value];
-const isAdmin = (ctx) => ctx.getAuthor().then((author) => ["administrator", "creator"].includes(author.status));
+const isAdmin = (ctx) => ctx
+    .getAuthor()
+    .then((author) => ["administrator", "creator"].includes(author.status));
 const matchesPattern = (value, pattern) => typeof pattern === "string" ? value === pattern : pattern.test(value);
 exports.matchesPattern = matchesPattern;
+/**
+ * Class that represents a single command and allows you to configure it.
+ */
 class Command {
+    /**
+     * Constructor for the `Command` class.
+     * Do not call this directly. Instead, use the `command` method from the `Commands` class
+     *
+     * @param name Default command name
+     * @param description Default command description
+     * @param options Options object that shuold apply to this command only
+     * @access package
+     */
     constructor(name, description, options = {}) {
         this._scopes = [];
         this._languages = new Map();
@@ -22,18 +36,33 @@ class Command {
             this._options.prefix = "/";
         this._languages.set("default", { name: name, description });
     }
+    /**
+     * Get registered scopes for this command
+     */
     get scopes() {
         return this._scopes;
     }
+    /**
+     * Get registered languages for this command
+     */
     get languages() {
         return this._languages;
     }
+    /**
+     * Get registered names for this command
+     */
     get names() {
         return Array.from(this._languages.values()).map(({ name }) => name);
     }
+    /**
+     * Get the default name for this command
+     */
     get name() {
         return this._languages.get("default").name;
     }
+    /**
+     * Get the default description for this command
+     */
     get description() {
         return this._languages.get("default").description;
     }
@@ -89,6 +118,22 @@ class Command {
         this._scopes.push(scope);
         return this;
     }
+    /**
+     * 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, options) {
         const { matchOnlyAtStart, prefix, targetedCommands } = options;
         return (ctx) => {
@@ -109,12 +154,27 @@ class Command {
                     continue;
                 if (username && username !== ctx.me.username)
                     continue;
-                if (commandNames.some((name) => (0, exports.matchesPattern)(command.replace(prefix, ""), name)))
+                if (commandNames.some((name) => (0, exports.matchesPattern)(command.replace(prefix, ""), name))) {
                     return true;
+                }
             }
             return false;
         };
     }
+    /**
+     * 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
+     * @param name Localized command name
+     * @param description Localized command description
+     */
     localize(languageCode, name, description) {
         this._languages.set(languageCode, {
             name: new RegExp(name),
@@ -122,14 +182,31 @@ class Command {
         });
         return this;
     }
+    /**
+     * Gets the localized command name of an existing translation
+     * @param languageCode Language to get the name for
+     * @returns Localized command name
+     */
     getLocalizedName(languageCode) {
         var _a, _b;
         return (_b = (_a = this._languages.get(languageCode)) === null || _a === void 0 ? void 0 : _a.name) !== null && _b !== void 0 ? _b : this.name;
     }
+    /**
+     * Gets the localized command name of an existing translation
+     * @param languageCode Language to get the name for
+     * @returns Localized command name
+     */
     getLocalizedDescription(languageCode) {
         var _a, _b;
         return (_b = (_a = this._languages.get(languageCode)) === null || _a === void 0 ? void 0 : _a.description) !== null && _b !== void 0 ? _b : this.description;
     }
+    /**
+     * 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 = "default") {
         const localizedName = this.getLocalizedName(languageCode);
         return {

package/out/commands.d.ts

@@ -1,10 +1,27 @@
-import { Command, CommandOptions } from "./command.js";
-import { Api, BotCommand, BotCommandScope, Context } from "./deps.node.js";
+import { Command, MaybeArray } from "./command.js";
+import { Api, BotCommand, BotCommandScope, Context, Middleware } from "./deps.node.js";
+import { CommandOptions } from "./types.js";
 type SetMyCommandsParams = {
+    /**
+     * Scope
+     */
     scope?: BotCommandScope;
     language_code?: string;
     commands: BotCommand[];
 };
+/**
+ * Central class that manages all registered commands.
+ * This is the starting point for the plugin, and this is what you should pass to `bot.use` so your commands get properly registered.
+ *
+ * @example
+ * ```typescript
+ * const myCommands = new Commands()
+ * commands.command("start", "start the bot configuration", (ctx) => ctx.reply("Hello there!"))
+ *
+ * // Registers the commands with the bot instance.
+ * bot.use(myCommands)
+ * ```
+ */
 export declare class Commands<C extends Context> {
     private _languages;
     private _scopes;
@@ -15,13 +32,52 @@ export declare class Commands<C extends Context> {
     private _addCommandToScope;
     private _populateComposer;
     private _populateMetadata;
+    /**
+     * Registers a new command with a default handler.
+     * @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
+     */
+    command(name: string | RegExp, description: string, handler: MaybeArray<Middleware<C>>, options?: Partial<CommandOptions>): Command<C>;
+    /**
+     * Registers a new command with no handlers.
+     * @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
+     */
     command(name: string | RegExp, description: string, options?: Partial<CommandOptions>): Command<C>;
+    /**
+     * Serializes the commands into multiple objects that can each be passed to a `setMyCommands` call.
+     *
+     * @returns One item for each combination of command + scope + language
+     */
     toArgs(): SetMyCommandsParams[];
+    /**
+     * Serializes the commands of a single scope into objects that can each be passed to a `setMyCommands` call.
+     *
+     * @param scope Selected scope to be serialized
+     * @returns One item per command per language
+     */
     toSingleScopeArgs(scope: BotCommandScope): SetMyCommandsParams[];
+    /**
+     * Registers all commands to be displayed by clients according to their scopes and languages
+     * Calls `setMyCommands` for each language of each scope of each command.
+     *
+     * @param Instance of `bot` or { api: bot.api }
+     */
     setCommands({ api }: {
         api: Api;
     }): Promise<void>;
+    /**
+     * Alias for {@link toArgs}
+     */
     toJSON(): SetMyCommandsParams[];
+    /**
+     * @returns A JSON serialized version of all the currently registered commands
+     */
     toString(): string;
     middleware(): import("grammy").MiddlewareFn<C>;
 }

package/out/commands.js

@@ -3,6 +3,33 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.Commands = void 0;
 const command_js_1 = require("./command.js");
 const deps_node_js_1 = require("./deps.node.js");
+const isMiddleware = (obj) => {
+    if (!obj)
+        return false;
+    if (Array.isArray(obj))
+        return obj.every(isMiddleware);
+    const objType = typeof obj;
+    switch (objType) {
+        case "function":
+            return true;
+        case "object":
+            return Object.keys(obj).includes("middleware");
+    }
+    return false;
+};
+/**
+ * Central class that manages all registered commands.
+ * This is the starting point for the plugin, and this is what you should pass to `bot.use` so your commands get properly registered.
+ *
+ * @example
+ * ```typescript
+ * const myCommands = new Commands()
+ * commands.command("start", "start the bot configuration", (ctx) => ctx.reply("Hello there!"))
+ *
+ * // Registers the commands with the bot instance.
+ * bot.use(myCommands)
+ * ```
+ */
 class Commands {
     constructor(options = {}) {
         this._languages = new Set();
@@ -34,11 +61,25 @@ class Commands {
             }
         });
     }
-    command(name, description, options = this._commandOptions) {
+    command(name, description, handlerOrOptions, _options) {
+        var _a;
+        const handler = isMiddleware(handlerOrOptions)
+            ? handlerOrOptions
+            : undefined;
+        const options = handler
+            ? _options !== null && _options !== void 0 ? _options : this._commandOptions
+            : (_a = handlerOrOptions) !== null && _a !== void 0 ? _a : this._commandOptions;
         const command = new command_js_1.Command(name, description, options);
+        if (handler)
+            command.addToScope({ type: "default" }, handler);
         this._commands.push(command);
         return command;
     }
+    /**
+     * Serializes the commands into multiple objects that can each be passed to a `setMyCommands` call.
+     *
+     * @returns One item for each combination of command + scope + language
+     */
     toArgs() {
         this._populateMetadata();
         const params = [];
@@ -56,6 +97,12 @@ class Commands {
         }
         return params.filter((params) => params.commands.length > 0);
     }
+    /**
+     * Serializes the commands of a single scope into objects that can each be passed to a `setMyCommands` call.
+     *
+     * @param scope Selected scope to be serialized
+     * @returns One item per command per language
+     */
     toSingleScopeArgs(scope) {
         this._populateMetadata();
         const params = [];
@@ -70,12 +117,24 @@ class Commands {
         }
         return params;
     }
+    /**
+     * Registers all commands to be displayed by clients according to their scopes and languages
+     * Calls `setMyCommands` for each language of each scope of each command.
+     *
+     * @param Instance of `bot` or { api: bot.api }
+     */
     async setCommands({ api }) {
         await Promise.all(this.toArgs().map((args) => api.raw.setMyCommands(args)));
     }
+    /**
+     * Alias for {@link toArgs}
+     */
     toJSON() {
         return this.toArgs();
     }
+    /**
+     * @returns A JSON serialized version of all the currently registered commands
+     */
     toString() {
         return JSON.stringify(this);
     }
@@ -83,9 +142,19 @@ class Commands {
         this._populateComposer();
         return this._composer.middleware();
     }
+    /**
+     * Replaces the `toString` method on node.js
+     *
+     * @see toString
+     */
     [Symbol.for("Deno.customInspect")]() {
         return this.toString();
     }
+    /**
+     * Replaces the `toString` method on Deno
+     *
+     * @see toString
+     */
     [Symbol.for("nodejs.util.inspect.custom")]() {
         return this.toString();
     }

package/out/mod.d.ts

@@ -1,2 +1,4 @@
+export { Command } from "./command.js";
 export * from "./commands.js";
 export * from "./context.js";
+export type { CommandOptions } from "./types.js";

package/out/mod.js

@@ -14,5 +14,8 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.Command = void 0;
+var command_js_1 = require("./command.js");
+Object.defineProperty(exports, "Command", { enumerable: true, get: function () { return command_js_1.Command; } });
 __exportStar(require("./commands.js"), exports);
 __exportStar(require("./context.js"), exports);

package/out/types.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Supported command options
+ */
+export interface CommandOptions {
+    /**
+     * The prefix used to identify a command.
+     * Defaults to `/`.
+     */
+    prefix: string;
+    /**
+     * Whether the command should only be matched at the start of the message.
+     * Defaults to `true`.
+     */
+    matchOnlyAtStart: boolean;
+    /**
+     * Whether to ignore or only care about commands ending with the bot's username.
+     * Defaults to `"optional"`.
+     *
+     * - `"ignored"`: only non-targeted commands are matched
+     * - `"optional"`: both targeted and non-targeted commands are matched
+     * - `"required"`: only targeted commands are matched
+     */
+    targetedCommands: "ignored" | "optional" | "required";
+}

package/out/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@grammyjs/commands",
-    "version": "0.5.0",
+    "version": "0.6.0",
     "description": "grammY Commands Plugin",
     "main": "out/mod.js",
     "scripts": {