@grammyjs/commands 0.8.1 → 0.10.0

package/README.md

@@ -16,22 +16,22 @@ The main functionality of this plugin is to define your commands, localize them,
 
 ```typescript
 import { Bot } from "grammy";
-import { Commands } from "@grammyjs/commands";
+import { CommandGroup } from "@grammyjs/commands";
 
 const bot = new Bot("<telegram token>");
 
-const myCommands = new Commands();
+const myCommands = new CommandGroup();
 
 myCommands.command("start", "Initializes bot configuration")
-    .localize("pt", "start", "Inicializa as configurações do bot")
-    .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}!`),
-    );
+  .localize("pt", "start", "Inicializa as configurações do bot")
+  .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}!`),
+  );
 
 // Calls `setMyCommands`
 await myCommands.setCommands(bot);
@@ -52,7 +52,7 @@ commands flavor and the plugin itself, like so:
 
 ```typescript
 import { Bot, Context } from "grammy";
-import { Commands, commands, CommandsFlavor } from "@grammyjs/commands";
+import { CommandGroup, commands, CommandsFlavor } from "@grammyjs/commands";
 
 type BotContext = CommandsFlavor;
 
@@ -60,14 +60,14 @@ const bot = new Bot<BotContext>("<telegram_token>");
 bot.use(commands());
 
 bot.on("message", async (ctx) => {
-    const cmds = new Commands();
+  const cmds = new CommandGroup();
 
-    cmds.command("start", "Initializes bot configuration")
-        .localize("pt", "start", "Inicializa as configurações do bot");
+  cmds.command("start", "Initializes bot configuration")
+    .localize("pt", "start", "Inicializa as configurações do bot");
 
-    await ctx.setMyCommands(cmds);
+  await ctx.setMyCommands(cmds);
 
-    return ctx.reply("Commands set!");
+  return ctx.reply("Commands set!");
 });
 
 bot.start();

package/out/{commands.d.ts → command-group.d.ts}

@@ -1,12 +1,14 @@
-import { Command } from "./command.js";
+import { Command, CommandsFlavor } from "./mod.js";
 import { Api, BotCommand, BotCommandScope, CommandContext, Context, type LanguageCode, Middleware } from "./deps.node.js";
 import type { CommandElementals, CommandOptions } from "./types.js";
-import { type MaybeArray } from "./utils.js";
+import { type MaybeArray } from "./utils/array.js";
+import { SetBotCommandsOptions } from "./utils/set-bot-commands.js";
+import { JaroWinklerOptions } from "./utils/jaro-winkler.js";
 /**
  * Interface for grouping {@link BotCommand}s that might (or not)
  * be related to each other by scope and/or language.
  */
-export type SetMyCommandsParams = {
+export interface SetMyCommandsParams {
     /** If defined: scope on which the commands will take effect */
     scope?: BotCommandScope;
     /** If defined: Language on which the commands will take effect.
@@ -15,21 +17,33 @@ export type SetMyCommandsParams = {
     language_code?: LanguageCode;
     /** Commands that can be each one passed to a SetMyCommands Call */
     commands: BotCommand[];
-};
+}
+/**
+ * Interface to represent uncompliance of a command
+ * with the Bot API
+ */
+export interface UncompliantCommand {
+    /** Name of the uncompliant command */
+    name: string;
+    /** Reason why the command was considered uncompliant */
+    reasons: string[];
+    /** Language in which the command is uncompliant */
+    language: LanguageCode | "default";
+}
 /**
  * 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()
+ * const myCommands = new CommandGroup()
  * 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> {
+export declare class CommandGroup<C extends Context> {
     private _languages;
     private _scopes;
     private _commands;
@@ -58,16 +72,23 @@ export declare class Commands<C extends Context> {
     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[];
+    toArgs(): {
+        scopes: SetMyCommandsParams[];
+        uncompliantCommands: UncompliantCommand[];
+    };
     /**
      * 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[];
+    toSingleScopeArgs(scope: BotCommandScope): {
+        commandParams: SetMyCommandsParams[];
+        uncompliantCommands: UncompliantCommand[];
+    };
     /**
      * 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.
@@ -81,7 +102,7 @@ export declare class Commands<C extends Context> {
      */
     setCommands({ api }: {
         api: Api;
-    }): Promise<void>;
+    }, options?: Partial<SetBotCommandsOptions>): Promise<void>;
     /**
      * Serialize all register commands into it's name, prefix and language
      *
@@ -99,4 +120,17 @@ export declare class Commands<C extends Context> {
      */
     toString(): string;
     middleware(): import("grammy").MiddlewareFn<C>;
+    /**
+     * @returns all {@link Command}s contained in the instance
+     */
+    get commands(): Command<C>[];
+    /**
+     * @returns all prefixes registered in this instance
+     */
+    get prefixes(): string[];
 }
+type HaveCommandLike<C extends Context = Context, CF extends CommandsFlavor<C> = CommandsFlavor<C>> = C & CF & {
+    commandSuggestion: string | null;
+};
+export declare function commandNotFound<CF extends CommandsFlavor<C>, C extends Context = Context>(commands: CommandGroup<C> | CommandGroup<C>[], opts?: Omit<Partial<JaroWinklerOptions>, "language">): (ctx: C) => ctx is HaveCommandLike<C, CF>;
+export {};

package/out/{commands.js → command-group.js}

@@ -1,8 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Commands = void 0;
-const command_js_1 = require("./command.js");
+exports.commandNotFound = exports.CommandGroup = void 0;
+const mod_js_1 = require("./mod.js");
 const deps_node_js_1 = require("./deps.node.js");
+const array_js_1 = require("./utils/array.js");
+const set_bot_commands_js_1 = require("./utils/set-bot-commands.js");
 const isMiddleware = (obj) => {
     if (!obj)
         return false;
@@ -23,14 +25,14 @@ const isMiddleware = (obj) => {
  *
  * @example
  * ```typescript
- * const myCommands = new Commands()
+ * const myCommands = new CommandGroup()
  * commands.command("start", "start the bot configuration", (ctx) => ctx.reply("Hello there!"))
  *
  * // Registers the commands with the bot instance.
  * bot.use(myCommands)
  * ```
  */
-class Commands {
+class CommandGroup {
     constructor(options = {}) {
         this._languages = new Set();
         this._scopes = new Map();
@@ -65,7 +67,7 @@ class Commands {
         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);
+        const command = new mod_js_1.Command(name, description, options);
         if (handler)
             command.addToScope({ type: "default" }, handler);
         this._commands.push(command);
@@ -74,25 +76,40 @@ class Commands {
     }
     /**
      * 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 = [];
+        const scopes = [];
+        const uncompliantCommands = [];
         for (const [scope, commands] of this._scopes.entries()) {
             for (const language of this._languages) {
-                params.push({
-                    scope: JSON.parse(scope),
-                    language_code: language === "default"
-                        ? undefined
-                        : language,
-                    commands: commands
-                        .filter((command) => typeof command.name === "string")
-                        .map((command) => command.toObject(language)),
+                const compliantScopedCommands = [];
+                commands.forEach((command) => {
+                    const [isApiCompliant, ...reasons] = command.isApiCompliant(language);
+                    if (isApiCompliant) {
+                        return compliantScopedCommands.push(command);
+                    }
+                    uncompliantCommands.push({
+                        name: command.stringName,
+                        reasons: reasons,
+                        language,
+                    });
                 });
+                if (compliantScopedCommands.length) {
+                    scopes.push({
+                        scope: JSON.parse(scope),
+                        language_code: language === "default" ? undefined : language,
+                        commands: compliantScopedCommands.map((command) => command.toObject(language)),
+                    });
+                }
             }
         }
-        return params.filter((params) => params.commands.length > 0);
+        return {
+            scopes,
+            uncompliantCommands,
+        };
     }
     /**
      * Serializes the commands of a single scope into objects that can each be passed to a `setMyCommands` call.
@@ -102,18 +119,29 @@ class Commands {
      */
     toSingleScopeArgs(scope) {
         this._populateMetadata();
-        const params = [];
+        const commandParams = [];
+        const uncompliantCommands = [];
         for (const language of this._languages) {
-            params.push({
+            const compliantCommands = [];
+            this._commands.forEach((command) => {
+                const [isApiCompliant, ...reasons] = command.isApiCompliant(language);
+                if (!isApiCompliant) {
+                    return uncompliantCommands.push({
+                        name: command.stringName,
+                        reasons: reasons,
+                        language,
+                    });
+                }
+                if (command.scopes.length)
+                    compliantCommands.push(command);
+            });
+            commandParams.push({
                 scope,
                 language_code: language === "default" ? undefined : language,
-                commands: this._commands
-                    .filter((command) => command.scopes.length)
-                    .filter((command) => typeof command.name === "string")
-                    .map((command) => command.toObject(language)),
+                commands: compliantCommands.map((command) => command.toObject(language)),
             });
         }
-        return params;
+        return { commandParams, uncompliantCommands };
     }
     /**
      * Registers all commands to be displayed by clients according to their scopes and languages
@@ -126,8 +154,9 @@ class Commands {
      *
      * @param Instance of `bot` or { api: bot.api }
      */
-    async setCommands({ api }) {
-        await Promise.all(this.toArgs().map((args) => api.raw.setMyCommands(args)));
+    async setCommands({ api }, options) {
+        const { scopes, uncompliantCommands } = this.toArgs();
+        await (0, set_bot_commands_js_1.setBotCommands)(api, scopes, uncompliantCommands, options);
     }
     /**
      * Serialize all register commands into it's name, prefix and language
@@ -180,7 +209,21 @@ class Commands {
         return this._cachedComposer.middleware();
     }
     /**
-     * Replaces the `toString` method on node.js
+     * @returns all {@link Command}s contained in the instance
+     */
+    get commands() {
+        return this._commands;
+    }
+    /**
+     * @returns all prefixes registered in this instance
+     */
+    get prefixes() {
+        return [
+            ...new Set(this._commands.flatMap((command) => command.prefix)),
+        ];
+    }
+    /**
+     * Replaces the `toString` method on Deno
      *
      * @see toString
      */
@@ -188,7 +231,7 @@ class Commands {
         return this.toString();
     }
     /**
-     * Replaces the `toString` method on Deno
+     * Replaces the `toString` method on Node.js
      *
      * @see toString
      */
@@ -196,4 +239,30 @@ class Commands {
         return this.toString();
     }
 }
-exports.Commands = Commands;
+exports.CommandGroup = CommandGroup;
+function commandNotFound(commands, opts = {}) {
+    return function (ctx) {
+        if (containsCommands(ctx, commands)) {
+            ctx
+                .commandSuggestion = ctx
+                .getNearestCommand(commands, opts);
+            return true;
+        }
+        return false;
+    };
+}
+exports.commandNotFound = commandNotFound;
+function containsCommands(ctx, commands) {
+    let allPrefixes = [
+        ...new Set((0, array_js_1.ensureArray)(commands).flatMap((cmds) => cmds.prefixes)),
+    ];
+    if (allPrefixes.length < 1) {
+        allPrefixes = ["/"];
+    }
+    for (const prefix of allPrefixes) {
+        const regex = (0, array_js_1.getCommandsRegex)(prefix);
+        if (ctx.hasText(regex))
+            return true;
+    }
+    return false;
+}

package/out/command.d.ts

@@ -1,8 +1,8 @@
 import { type BotCommand, type BotCommandScope, type BotCommandScopeAllChatAdministrators, type BotCommandScopeAllGroupChats, type BotCommandScopeAllPrivateChats, type ChatTypeMiddleware, type Context, type LanguageCode, type Middleware, type MiddlewareObj } from "./deps.node.js";
 import type { CommandOptions } from "./types.js";
-import { type MaybeArray } from "./utils.js";
+import { type MaybeArray } from "./utils/array.js";
 type BotCommandGroupsScope = BotCommandScopeAllGroupChats | BotCommandScopeAllChatAdministrators;
-export declare const matchesPattern: (value: string, pattern: string | RegExp) => boolean;
+export declare const matchesPattern: (value: string, pattern: string | RegExp, ignoreCase?: boolean) => boolean;
 /**
  * Class that represents a single command and allows you to configure it.
  */
@@ -21,6 +21,22 @@ export declare class Command<C extends Context = Context> implements MiddlewareO
      * @access package
      */
     constructor(name: string | RegExp, description: string, 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
      */
@@ -54,7 +70,7 @@ export declare class Command<C extends Context = Context> implements MiddlewareO
      *
      * @example
      * ```ts
-     * const myCommands = new Commands();
+     * const myCommands = new CommandGroup();
      * myCommands.command("start", "Initializes bot configuration")
      *     .addToScope(
      *         { type: "all_private_chats" },

package/out/command.js

@@ -2,13 +2,22 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Command = exports.matchesPattern = void 0;
 const deps_node_js_1 = require("./deps.node.js");
-const errors_js_1 = require("./errors.js");
-const utils_js_1 = require("./utils.js");
+const errors_js_1 = require("./utils/errors.js");
+const array_js_1 = require("./utils/array.js");
 const isAdmin = (ctx) => ctx
     .getAuthor()
     .then((author) => ["administrator", "creator"].includes(author.status));
-const matchesPattern = (value, pattern) => typeof pattern === "string" ? value === pattern : pattern.test(value);
+const matchesPattern = (value, pattern, ignoreCase = false) => {
+    const transformedValue = ignoreCase ? value.toLowerCase() : value;
+    const transformedPattern = pattern instanceof RegExp && ignoreCase && !pattern.flags.includes("i")
+        ? new RegExp(pattern, pattern.flags + "i")
+        : pattern;
+    return typeof transformedPattern === "string"
+        ? transformedValue === transformedPattern
+        : transformedPattern.test(transformedValue);
+};
 exports.matchesPattern = matchesPattern;
+const NOCASE_COMMAND_NAME_REGEX = /^[0-9a-z_]+$/i;
 /**
  * Class that represents a single command and allows you to configure it.
  */
@@ -30,12 +39,51 @@ class Command {
             prefix: "/",
             matchOnlyAtStart: true,
             targetedCommands: "optional",
+            ignoreCase: false,
         };
         this._options = { ...this._options, ...options };
         if (this._options.prefix === "")
             this._options.prefix = "/";
         this._languages.set("default", { name: name, description });
     }
+    /**
+     * Whether the command has a custom prefix
+     */
+    get hasCustomPrefix() {
+        return this.prefix && this.prefix !== "/";
+    }
+    /**
+     * Gets the command name as string
+     */
+    get stringName() {
+        return typeof this.name === "string" ? this.name : this.name.source;
+    }
+    /**
+     * Whether the command can be passed to a `setMyCommands` API call
+     * and, if not, the reason.
+     */
+    isApiCompliant(language) {
+        const problems = [];
+        if (this.hasCustomPrefix) {
+            problems.push(`Command has custom prefix: ${this._options.prefix}`);
+        }
+        const name = language ? this.getLocalizedName(language) : this.name;
+        if (typeof name !== "string") {
+            problems.push("Command has a regular expression name");
+        }
+        if (typeof name === "string") {
+            if (name.toLowerCase() !== name) {
+                problems.push("Command name has uppercase characters");
+            }
+            if (name.length > 32) {
+                problems.push(`Command name is too long (${name.length} characters). Maximum allowed is 32 characters`);
+            }
+            if (!NOCASE_COMMAND_NAME_REGEX.test(name)) {
+                problems.push(`Command name has special characters (${name.replace(/[0-9a-z_]/ig, "")}). Only letters, digits and _ are allowed`);
+            }
+        }
+        return problems.length ? [false, ...problems] : [true];
+    }
     /**
      * Get registered scopes for this command
      */
@@ -73,7 +121,7 @@ class Command {
         return this._options.prefix;
     }
     addToScope(scope, middleware, options = this._options) {
-        const middlewareArray = (0, utils_js_1.ensureArray)(middleware);
+        const middlewareArray = (0, array_js_1.ensureArray)(middleware);
         const optionsObject = { ...this._options, ...options };
         switch (scope.type) {
             case "default":
@@ -148,7 +196,7 @@ class Command {
             if (matchOnlyAtStart && !ctx.msg.text.startsWith(prefix)) {
                 return false;
             }
-            const commandNames = (0, utils_js_1.ensureArray)(command);
+            const commandNames = (0, array_js_1.ensureArray)(command);
             const commands = prefix === "/"
                 ? ctx.entities("bot_command")
                 : ctx.msg.text.split(prefix).map((text) => ({ text }));
@@ -160,7 +208,7 @@ 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, options.ignoreCase))) {
                     return true;
                 }
             }

package/out/context.d.ts

@@ -1,7 +1,9 @@
-import { Commands } from "./commands.js";
+import { CommandGroup } from "./command-group.js";
 import { BotCommandScopeChat, Context, NextFunction } from "./deps.node.js";
-import { JaroWinklerOptions } from "./jaro-winkler.js";
 import { SetMyCommandsParams } from "./mod.js";
+import { BotCommandEntity } from "./types.js";
+import { JaroWinklerOptions } from "./utils/jaro-winkler.js";
+import { SetBotCommandsOptions } from "./utils/set-bot-commands.js";
 export interface CommandsFlavor<C extends Context = Context> extends Context {
     /**
      * Sets the provided commands for the current chat.
@@ -25,7 +27,7 @@ export interface CommandsFlavor<C extends Context = Context> extends Context {
      * @param commands List of available commands
      * @returns Promise with the result of the operations
      */
-    setMyCommands: (commands: Commands<C> | Commands<C>[], ...moreCommands: Commands<C>[]) => Promise<void>;
+    setMyCommands: (commands: CommandGroup<C> | CommandGroup<C>[], options?: SetBotCommandsOptions) => Promise<void>;
     /**
      * Returns the nearest command to the user input.
      * If no command is found, returns `null`.
@@ -34,7 +36,12 @@ export interface CommandsFlavor<C extends Context = Context> extends Context {
      * @param options Options for the Jaro-Winkler algorithm
      * @returns The nearest command or `null`
      */
-    getNearestCommand: (commands: Commands<C> | Commands<C>[], options?: Omit<Partial<JaroWinklerOptions>, "language">) => string | null;
+    getNearestCommand: (commands: CommandGroup<C> | CommandGroup<C>[], options?: Omit<Partial<JaroWinklerOptions>, "language">) => string | null;
+    /**
+     * @param commands
+     * @returns command entities hydrated with the custom prefixes
+     */
+    getCommandEntities: (commands: CommandGroup<C> | CommandGroup<C>[]) => BotCommandEntity[];
 }
 /**
  * Installs the commands flavor into the context.
@@ -46,46 +53,52 @@ export declare function commands<C extends Context>(): (ctx: CommandsFlavor<C>,
  */
 export declare class MyCommandParams {
     /**
-     * Merges and serialize one or more Commands instances into a single array
-     * of commands params that can be used to set the commands menu displayed to the user.
-     * @example
-        ```ts
-        const adminCommands = new Commands();
-        const userCommands = new Commands();
-        adminCommands
-            .command("do a",
-                     "a description",
-                     (ctx) => ctx.doA());
-        userCommands
-            .command("do b",
-                     "b description",
-                     (ctx) => ctx.doB());
-        const mergedParams =
-            MyCommandParams.from([a, b], someChatId);
-        ```
-     * @param commands An array of one or more Commands instances.
-     * @returns an array of {@link SetMyCommandsParams} grouped by language
-     */
-    static from<C extends Context>(commands: Commands<C>[], chat_id: BotCommandScopeChat["chat_id"]): SetMyCommandsParams[];
+       * Merges and serialize one or more Commands instances into a single array
+       * of commands params that can be used to set the commands menu displayed to the user.
+       * @example
+          ```ts
+          const adminCommands = new CommandGroup();
+          const userCommands = new CommandGroup();
+          adminCommands
+              .command("do a",
+                       "a description",
+                       (ctx) => ctx.doA());
+          userCommands
+              .command("do b",
+                       "b description",
+                       (ctx) => ctx.doB());
+          const mergedParams =
+              MyCommandParams.from([a, b], someChatId);
+          ```
+       * @param commands An array of one or more Commands instances.
+       * @returns an array of {@link SetMyCommandsParams} grouped by language
+       */
+    static from<C extends Context>(commands: CommandGroup<C>[], chat_id: BotCommandScopeChat["chat_id"]): {
+        commandsParams: SetMyCommandsParams[];
+        uncompliantCommands: import("./command-group.js").UncompliantCommand[];
+    };
     /**
-     * Serializes one or multiple {@link Commands} instances, each one into their respective
-     * single scoped SetMyCommandsParams version.
-     * @example
-        ```ts
-        const adminCommands = new Commands();
-        // add to scope, localize, etc
-        const userCommands = new Commands();
-        // add to scope, localize, etc
-        const [
-            singleScopedAdminParams,
-            singleScopedUserParams
-        ] = MyCommandsParams.serialize([adminCommands,userCommands])
-        ```
-     * @param commandsArr an array of one or more commands instances
-     * @param chat_id the chat id relative to the message update, coming from the ctx object.
-     * @returns an array of scoped {@link SetMyCommandsParams} mapped from their respective Commands instances
-     */
-    static _serialize<C extends Context>(commandsArr: Commands<C>[], chat_id: BotCommandScopeChat["chat_id"]): SetMyCommandsParams[][];
+       * Serializes one or multiple {@link CommandGroup} instances, each one into their respective
+       * single scoped SetMyCommandsParams version.
+       * @example
+          ```ts
+          const adminCommands = new CommandGroup();
+          // add to scope, localize, etc
+          const userCommands = new CommandGroup();
+          // add to scope, localize, etc
+          const [
+              singleScopedAdminParams,
+              singleScopedUserParams
+          ] = MyCommandsParams.serialize([adminCommands,userCommands])
+          ```
+       * @param commandsArr an array of one or more commands instances
+       * @param chat_id the chat id relative to the message update, coming from the ctx object.
+       * @returns an array of scoped {@link SetMyCommandsParams} mapped from their respective Commands instances
+       */
+    static _serialize<C extends Context>(commandsArr: CommandGroup<C>[], chat_id: BotCommandScopeChat["chat_id"]): {
+        commandParams: SetMyCommandsParams[];
+        uncompliantCommands: import("./command-group.js").UncompliantCommand[];
+    }[];
     /**
      * Lexicographically sorts commandParams based on their language code.
      * @returns the sorted array

package/out/context.js

@@ -1,42 +1,71 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MyCommandParams = exports.commands = void 0;
-const jaro_winkler_js_1 = require("./jaro-winkler.js");
-const utils_js_1 = require("./utils.js");
+const array_js_1 = require("./utils/array.js");
+const jaro_winkler_js_1 = require("./utils/jaro-winkler.js");
+const set_bot_commands_js_1 = require("./utils/set-bot-commands.js");
 /**
  * Installs the commands flavor into the context.
  */
 function commands() {
     return (ctx, next) => {
-        ctx.setMyCommands = async (commands, ...moreCommands) => {
+        ctx.setMyCommands = async (commands, options) => {
             if (!ctx.chat) {
                 throw new Error("cannot call `ctx.setMyCommands` on an update with no `chat` property");
             }
-            commands = (0, utils_js_1.ensureArray)(commands).concat(moreCommands);
-            await Promise.all(MyCommandParams.from(commands, ctx.chat.id)
-                .map((args) => ctx.api.raw.setMyCommands(args)));
+            const { uncompliantCommands, commandsParams: currentChatCommandParams, } = MyCommandParams.from((0, array_js_1.ensureArray)(commands), ctx.chat.id);
+            await (0, set_bot_commands_js_1.setBotCommands)(ctx.api, currentChatCommandParams, uncompliantCommands, options);
         };
         ctx.getNearestCommand = (commands, options) => {
-            var _a;
-            if ((_a = ctx.msg) === null || _a === void 0 ? void 0 : _a.text) {
-                commands = (0, utils_js_1.ensureArray)(commands);
-                const results = commands.map((commands) => {
-                    var _a;
-                    const userInput = ctx.msg.text.substring(1);
-                    const result = (0, jaro_winkler_js_1.fuzzyMatch)(userInput, commands, {
-                        ...options,
-                        language: !(options === null || options === void 0 ? void 0 : options.ignoreLocalization)
-                            ? (_a = ctx.from) === null || _a === void 0 ? void 0 : _a.language_code
-                            : undefined,
-                    });
-                    return result;
-                }).sort((a, b) => { var _a, _b; return ((_a = b === null || b === void 0 ? void 0 : b.similarity) !== null && _a !== void 0 ? _a : 0) - ((_b = a === null || a === void 0 ? void 0 : a.similarity) !== null && _b !== void 0 ? _b : 0); });
-                const result = results[0];
-                if (!result || !result.command)
-                    return null;
-                return result.command.prefix + result.command.name;
+            if (!ctx.has(":text")) {
+                throw new Error("cannot call `ctx.getNearestCommand` on an update with no `text`");
             }
-            return null;
+            const results = (0, array_js_1.ensureArray)(commands)
+                .map((commands) => {
+                var _a;
+                const firstMatch = ctx.getCommandEntities(commands)[0];
+                const commandLike = (firstMatch === null || firstMatch === void 0 ? void 0 : firstMatch.text.replace(firstMatch.prefix, "")) ||
+                    "";
+                const result = (0, jaro_winkler_js_1.fuzzyMatch)(commandLike, commands, {
+                    ...options,
+                    language: !(options === null || options === void 0 ? void 0 : options.ignoreLocalization)
+                        ? (_a = ctx.from) === null || _a === void 0 ? void 0 : _a.language_code
+                        : undefined,
+                });
+                return result;
+            }).sort((a, b) => { var _a, _b; return ((_a = b === null || b === void 0 ? void 0 : b.similarity) !== null && _a !== void 0 ? _a : 0) - ((_b = a === null || a === void 0 ? void 0 : a.similarity) !== null && _b !== void 0 ? _b : 0); });
+            const result = results[0];
+            if (!result || !result.command)
+                return null;
+            return result.command.prefix + result.command.name;
+        };
+        ctx.getCommandEntities = (commands) => {
+            if (!ctx.has(":text")) {
+                throw new Error("cannot call `ctx.commandEntities` on an update with no `text`");
+            }
+            const text = ctx.msg.text;
+            if (!text)
+                return [];
+            const prefixes = (0, array_js_1.ensureArray)(commands).flatMap((cmds) => cmds.prefixes);
+            if (!prefixes.length)
+                return [];
+            const regexes = prefixes.map((prefix) => (0, array_js_1.getCommandsRegex)(prefix));
+            const entities = regexes.flatMap((regex) => {
+                let match;
+                const matches = [];
+                while ((match = regex.exec(text)) !== null) {
+                    const text = match[0].trim();
+                    matches.push({
+                        text,
+                        offset: match.index,
+                        prefix: match.groups.prefix,
+                        type: "bot_command",
+                        length: text.length,
+                    });
+                }
+                return matches;
+            });
+            return entities;
         };
         return next();
     };
@@ -48,50 +77,57 @@ exports.commands = commands;
  */
 class MyCommandParams {
     /**
-     * Merges and serialize one or more Commands instances into a single array
-     * of commands params that can be used to set the commands menu displayed to the user.
-     * @example
-        ```ts
-        const adminCommands = new Commands();
-        const userCommands = new Commands();
-        adminCommands
-            .command("do a",
-                     "a description",
-                     (ctx) => ctx.doA());
-        userCommands
-            .command("do b",
-                     "b description",
-                     (ctx) => ctx.doB());
-        const mergedParams =
-            MyCommandParams.from([a, b], someChatId);
-        ```
-     * @param commands An array of one or more Commands instances.
-     * @returns an array of {@link SetMyCommandsParams} grouped by language
-     */
+       * Merges and serialize one or more Commands instances into a single array
+       * of commands params that can be used to set the commands menu displayed to the user.
+       * @example
+          ```ts
+          const adminCommands = new CommandGroup();
+          const userCommands = new CommandGroup();
+          adminCommands
+              .command("do a",
+                       "a description",
+                       (ctx) => ctx.doA());
+          userCommands
+              .command("do b",
+                       "b description",
+                       (ctx) => ctx.doB());
+          const mergedParams =
+              MyCommandParams.from([a, b], someChatId);
+          ```
+       * @param commands An array of one or more Commands instances.
+       * @returns an array of {@link SetMyCommandsParams} grouped by language
+       */
     static from(commands, chat_id) {
-        const commandsParams = this._serialize(commands, chat_id).flat();
-        if (!commandsParams.length)
-            return [];
-        return this.mergeByLanguage(commandsParams);
+        const serializedCommands = this._serialize(commands, chat_id);
+        const commandsParams = serializedCommands
+            .map(({ commandParams }) => commandParams)
+            .flat();
+        const uncompliantCommands = serializedCommands
+            .map(({ uncompliantCommands }) => uncompliantCommands)
+            .flat();
+        return {
+            commandsParams: this.mergeByLanguage(commandsParams),
+            uncompliantCommands,
+        };
     }
     /**
-     * Serializes one or multiple {@link Commands} instances, each one into their respective
-     * single scoped SetMyCommandsParams version.
-     * @example
-        ```ts
-        const adminCommands = new Commands();
-        // add to scope, localize, etc
-        const userCommands = new Commands();
-        // add to scope, localize, etc
-        const [
-            singleScopedAdminParams,
-            singleScopedUserParams
-        ] = MyCommandsParams.serialize([adminCommands,userCommands])
-        ```
-     * @param commandsArr an array of one or more commands instances
-     * @param chat_id the chat id relative to the message update, coming from the ctx object.
-     * @returns an array of scoped {@link SetMyCommandsParams} mapped from their respective Commands instances
-     */
+       * Serializes one or multiple {@link CommandGroup} instances, each one into their respective
+       * single scoped SetMyCommandsParams version.
+       * @example
+          ```ts
+          const adminCommands = new CommandGroup();
+          // add to scope, localize, etc
+          const userCommands = new CommandGroup();
+          // add to scope, localize, etc
+          const [
+              singleScopedAdminParams,
+              singleScopedUserParams
+          ] = MyCommandsParams.serialize([adminCommands,userCommands])
+          ```
+       * @param commandsArr an array of one or more commands instances
+       * @param chat_id the chat id relative to the message update, coming from the ctx object.
+       * @returns an array of scoped {@link SetMyCommandsParams} mapped from their respective Commands instances
+       */
     static _serialize(commandsArr, chat_id) {
         return commandsArr.map((commands) => commands.toSingleScopeArgs({
             type: "chat",
@@ -120,6 +156,8 @@ class MyCommandParams {
      * @returns an array containing all commands grouped by language
      */
     static mergeByLanguage(params) {
+        if (!params.length)
+            return [];
         const sorted = this._sortByLanguage(params);
         return sorted.reduce((result, current, i, arr) => {
             if (i === 0 || current.language_code !== arr[i - 1].language_code) {

package/out/deps.node.d.ts

@@ -1,3 +1,3 @@
 export { Api, Bot, type ChatTypeContext, type ChatTypeMiddleware, type CommandContext, type CommandMiddleware, Composer, Context, type Middleware, type MiddlewareObj, type NextFunction, } from "grammy";
-export type { BotCommand, BotCommandScope, BotCommandScopeAllChatAdministrators, BotCommandScopeAllGroupChats, BotCommandScopeAllPrivateChats, BotCommandScopeChat, Chat, LanguageCode, } from "@grammyjs/types";
+export type { BotCommand, BotCommandScope, BotCommandScopeAllChatAdministrators, BotCommandScopeAllGroupChats, BotCommandScopeAllPrivateChats, BotCommandScopeChat, Chat, LanguageCode, MessageEntity } from "@grammyjs/types";
 export { LanguageCodes } from "@grammyjs/types";

package/out/mod.d.ts

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

package/out/mod.js

@@ -17,5 +17,5 @@ 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("./command-group.js"), exports);
 __exportStar(require("./context.js"), exports);

package/out/types.d.ts

@@ -1,4 +1,4 @@
-import type { BotCommandScope, LanguageCode } from "./deps.node.js";
+import type { BotCommandScope, LanguageCode, MessageEntity } from "./deps.node.js";
 /**
  * Supported command options
  */
@@ -22,6 +22,11 @@ export interface CommandOptions {
      * - `"required"`: only targeted commands are matched
      */
     targetedCommands: "ignored" | "optional" | "required";
+    /**
+     * Whether match against commands in a case-insensitive manner.
+     * Defaults to `false`.
+     */
+    ignoreCase: boolean;
 }
 export interface CommandElementals {
     name: string;
@@ -30,3 +35,9 @@ export interface CommandElementals {
     scopes: BotCommandScope[];
     description: string;
 }
+/** represents a bot__command entity inside a text message */
+export interface BotCommandEntity extends MessageEntity.CommonMessageEntity {
+    type: "bot_command";
+    text: string;
+    prefix: string;
+}

package/out/utils/array.d.ts

@@ -0,0 +1,4 @@
+export type MaybeArray<T> = T | T[];
+export declare const ensureArray: <T>(value: MaybeArray<T>) => T[];
+export declare function escapeSpecial(str: string): string;
+export declare function getCommandsRegex(prefix: string): RegExp;

package/out/utils/array.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getCommandsRegex = exports.escapeSpecial = exports.ensureArray = void 0;
+const ensureArray = (value) => Array.isArray(value) ? value : [value];
+exports.ensureArray = ensureArray;
+const specialChars = "\\.^$|?*+()[]{}-".split("");
+const replaceAll = (s, find, replace) => s.replace(new RegExp(`\\${find}`, "g"), replace);
+function escapeSpecial(str) {
+    return specialChars.reduce((acc, char) => replaceAll(acc, char, `\\${char}`), str);
+}
+exports.escapeSpecial = escapeSpecial;
+function getCommandsRegex(prefix) {
+    return new RegExp(`(\?\<\!\\S)(\?<prefix>${escapeSpecial(prefix)})\\S+(\\s|$)`, "g");
+}
+exports.getCommandsRegex = getCommandsRegex;

package/out/utils/errors.d.ts

@@ -0,0 +1,12 @@
+import { UncompliantCommand } from "../command-group.js";
+import { BotCommandScope } from "../deps.node.js";
+export declare class InvalidScopeError extends Error {
+    constructor(scope: BotCommandScope);
+}
+export declare class CustomPrefixNotSupportedError extends Error {
+    readonly offendingCommands: string[];
+    constructor(message: string, offendingCommands: string[]);
+}
+export declare class UncompliantCommandsError extends Error {
+    constructor(commands: Array<UncompliantCommand>);
+}

package/out/utils/errors.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UncompliantCommandsError = exports.CustomPrefixNotSupportedError = exports.InvalidScopeError = void 0;
+class InvalidScopeError extends Error {
+    constructor(scope) {
+        super(`Invalid scope: ${scope}`);
+        this.name = "InvalidScopeError";
+    }
+}
+exports.InvalidScopeError = InvalidScopeError;
+class CustomPrefixNotSupportedError extends Error {
+    constructor(message, offendingCommands) {
+        super(message);
+        this.offendingCommands = offendingCommands;
+        this.name = "CustomPrefixNotSupportedError";
+    }
+}
+exports.CustomPrefixNotSupportedError = CustomPrefixNotSupportedError;
+class UncompliantCommandsError extends Error {
+    constructor(commands) {
+        const message = [
+            `Tried to set bot commands with one or more commands that do not comply with the Bot API requirements for command names. Offending command(s):`,
+            commands.map(({ name, reasons, language }) => `- (language: ${language}) ${name}: ${reasons.join(", ")}`)
+                .join("\n"),
+            "If you want to filter these commands out automatically, set `ignoreUncompliantCommands` to `true`",
+        ].join("\n");
+        super(message);
+    }
+}
+exports.UncompliantCommandsError = UncompliantCommandsError;

package/out/{jaro-winkler.d.ts → utils/jaro-winkler.d.ts}

@@ -1,6 +1,6 @@
-import { Commands } from "./commands.js";
-import { Context, LanguageCode } from "./deps.node.js";
-import type { CommandElementals } from "./types.js";
+import { CommandGroup } from "../command-group.js";
+import { Context, LanguageCode } from "../deps.node.js";
+import type { CommandElementals } from "../types.js";
 export declare function distance(s1: string, s2: string): number;
 export type JaroWinklerOptions = {
     ignoreCase?: boolean;
@@ -14,5 +14,5 @@ type CommandSimilarity = {
 };
 export declare function JaroWinklerDistance(s1: string, s2: string, options: Pick<Partial<JaroWinklerOptions>, "ignoreCase">): number;
 export declare function isLanguageCode(value: string | undefined): value is LanguageCode;
-export declare function fuzzyMatch<C extends Context>(userInput: string, commands: Commands<C>, options: Partial<JaroWinklerOptions>): CommandSimilarity | null;
+export declare function fuzzyMatch<C extends Context>(userInput: string, commands: CommandGroup<C>, options: Partial<JaroWinklerOptions>): CommandSimilarity | null;
 export {};

package/out/{jaro-winkler.js → utils/jaro-winkler.js}

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.fuzzyMatch = exports.isLanguageCode = exports.JaroWinklerDistance = exports.distance = void 0;
-const deps_node_js_1 = require("./deps.node.js");
+const deps_node_js_1 = require("../deps.node.js");
 function distance(s1, s2) {
     if (s1.length === 0 || s2.length === 0) {
         return 0;
@@ -102,9 +102,7 @@ function fuzzyMatch(userInput, commands, options) {
      * https://en.wikipedia.org/wiki/IETF_language_tag
      */
     const possiblyISO639 = (_a = options.language) === null || _a === void 0 ? void 0 : _a.split("-")[0];
-    const language = isLanguageCode(possiblyISO639)
-        ? possiblyISO639
-        : undefined;
+    const language = isLanguageCode(possiblyISO639) ? possiblyISO639 : undefined;
     const cmds = options.ignoreLocalization
         ? commands.toElementals()
         : commands.toElementals(language);
@@ -112,9 +110,7 @@ function fuzzyMatch(userInput, commands, options) {
         const similarity = JaroWinklerDistance(userInput, command.name, {
             ...options,
         });
-        return similarity > best.similarity
-            ? { command, similarity }
-            : best;
+        return similarity > best.similarity ? { command, similarity } : best;
     }, { command: null, similarity: 0 });
     return bestMatch.similarity > similarityThreshold ? bestMatch : null;
 }

package/out/utils/set-bot-commands.d.ts

@@ -0,0 +1,24 @@
+import { SetMyCommandsParams, UncompliantCommand } from "../command-group.js";
+import { Api } from "../deps.node.js";
+/**
+ * Options for the `setBotCommands` function.
+ */
+export interface SetBotCommandsOptions {
+    /**
+     * Whether to remove invalid commands from the list of calls to the Bot API.
+     *
+     * If set to `false`, the method will throw an error if any of the commands
+     * is invalid according to the {@link https://core.telegram.org/bots/api#botcommand|official Bot API documentation}.
+     *
+     * Defaults to `false`.
+     */
+    ignoreUncompliantCommands?: boolean;
+}
+/**
+ * Performs validation and sets the provided commands for the bot.
+ * @param api Instance of the Api class for the bot the commands are being set for.
+ * @param commandParams List of commands to set.
+ * @param uncompliantCommands List of commands that do not comply with the Bot API rules.
+ * @param options Options object`
+ */
+export declare function setBotCommands(api: Api, commandParams: SetMyCommandsParams[], uncompliantCommands: UncompliantCommand[], options?: Partial<SetBotCommandsOptions>): Promise<void>;

package/out/utils/set-bot-commands.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setBotCommands = void 0;
+const errors_js_1 = require("./errors.js");
+/**
+ * Performs validation and sets the provided commands for the bot.
+ * @param api Instance of the Api class for the bot the commands are being set for.
+ * @param commandParams List of commands to set.
+ * @param uncompliantCommands List of commands that do not comply with the Bot API rules.
+ * @param options Options object`
+ */
+async function setBotCommands(api, commandParams, uncompliantCommands, options) {
+    const { ignoreUncompliantCommands = false } = options !== null && options !== void 0 ? options : {};
+    if (uncompliantCommands.length && !ignoreUncompliantCommands) {
+        throw new errors_js_1.UncompliantCommandsError(uncompliantCommands);
+    }
+    await Promise.all(commandParams.map((args) => api.raw.setMyCommands(args)));
+}
+exports.setBotCommands = setBotCommands;

package/package.json

@@ -1,30 +1,30 @@
 {
-    "name": "@grammyjs/commands",
-    "version": "0.8.1",
-    "description": "grammY Commands Plugin",
-    "main": "out/mod.js",
-    "scripts": {
-        "backport": "deno task backport",
-        "prepare": "deno task backport"
-    },
-    "keywords": [
-        "grammY",
-        "telegram",
-        "bot",
-        "commands"
-    ],
-    "author": "Roz <roz@rjmunhoz.me>",
-    "license": "MIT",
-    "dependencies": {
-        "@grammyjs/types": "^3.8.1",
-        "grammy": "^1.17.1",
-        "ts-pattern": "^5.0.1"
-    },
-    "devDependencies": {
-        "deno-bin": "^1.45.2",
-        "typescript": "^5.1.6"
-    },
-    "files": [
-        "out"
-    ]
+  "name": "@grammyjs/commands",
+  "version": "0.10.0",
+  "description": "grammY Commands Plugin",
+  "main": "out/mod.js",
+  "scripts": {
+    "backport": "deno task backport",
+    "prepare": "deno task backport"
+  },
+  "keywords": [
+    "grammY",
+    "telegram",
+    "bot",
+    "commands"
+  ],
+  "author": "Roz <roz@rjmunhoz.me>",
+  "license": "MIT",
+  "dependencies": {
+    "@grammyjs/types": "^3.8.1",
+    "grammy": "^1.17.1",
+    "ts-pattern": "^5.0.1"
+  },
+  "devDependencies": {
+    "deno-bin": "^1.45.2",
+    "typescript": "^5.1.6"
+  },
+  "files": [
+    "out"
+  ]
 }

package/out/errors.d.ts

@@ -1,4 +0,0 @@
-import { BotCommandScope } from "./deps.node.js";
-export declare class InvalidScopeError extends Error {
-    constructor(scope: BotCommandScope);
-}

package/out/errors.js

@@ -1,10 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.InvalidScopeError = void 0;
-class InvalidScopeError extends Error {
-    constructor(scope) {
-        super(`Invalid scope: ${scope}`);
-        this.name = "InvalidScopeError";
-    }
-}
-exports.InvalidScopeError = InvalidScopeError;

package/out/utils.d.ts

@@ -1,2 +0,0 @@
-export type MaybeArray<T> = T | T[];
-export declare const ensureArray: <T>(value: MaybeArray<T>) => T[];

package/out/utils.js

@@ -1,5 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.ensureArray = void 0;
-const ensureArray = (value) => Array.isArray(value) ? value : [value];
-exports.ensureArray = ensureArray;