@grammyjs/commands 0.9.0 → 0.11.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;
@@ -56,18 +70,31 @@ export declare class Commands<C extends Context> {
      * @returns An instance of the `Command` class
      */
     command(name: string | RegExp, description: string, options?: Partial<CommandOptions>): Command<C>;
+    /**
+     * Registers a Command that was created by it's own.
+     *
+     * @param command the command or list of commands being added to the group
+     */
+    add(command: Command<C> | Command<C>[]): this;
     /**
      * 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 +108,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 +126,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,37 +1,27 @@
 "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 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;
-};
+const array_js_1 = require("./utils/array.js");
+const set_bot_commands_js_1 = require("./utils/set-bot-commands.js");
+const checks_js_1 = require("./utils/checks.js");
 /**
  * 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)
  * ```
  */
-class Commands {
+class CommandGroup {
     constructor(options = {}) {
+        var _a;
         this._languages = new Set();
         this._scopes = new Map();
         this._commands = [];
@@ -39,6 +29,9 @@ class Commands {
         this._cachedComposerInvalidated = false;
         this._commandOptions = {};
         this._commandOptions = options;
+        if (((_a = this._commandOptions.prefix) === null || _a === void 0 ? void 0 : _a.trim()) === "") {
+            this._commandOptions.prefix = "/";
+        }
     }
     _addCommandToScope(scope, command) {
         var _a;
@@ -58,41 +51,63 @@ class Commands {
         });
     }
     command(name, description, handlerOrOptions, _options) {
-        var _a;
-        const handler = isMiddleware(handlerOrOptions)
+        const handler = (0, checks_js_1.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);
+        const options = !handler && (0, checks_js_1.isCommandOptions)(handlerOrOptions)
+            ? { ...this._commandOptions, ...handlerOrOptions }
+            : { ...this._commandOptions, ..._options };
+        const command = new mod_js_1.Command(name, description, handler, options);
         this._commands.push(command);
         this._cachedComposerInvalidated = true;
         return command;
     }
+    /**
+     * Registers a Command that was created by it's own.
+     *
+     * @param command the command or list of commands being added to the group
+     */
+    add(command) {
+        this._commands.push(...(0, array_js_1.ensureArray)(command));
+        this._cachedComposerInvalidated = true;
+        return this;
+    }
     /**
      * 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 +117,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 +152,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
@@ -179,6 +206,20 @@ class Commands {
         }
         return this._cachedComposer.middleware();
     }
+    /**
+     * @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
      *
@@ -196,4 +237,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,7 @@
-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 BotCommand, 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 { 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, ignoreCase?: boolean) => boolean;
 /**
  * Class that represents a single command and allows you to configure it.
  */
@@ -10,17 +9,62 @@ export declare class Command<C extends Context = Context> implements MiddlewareO
     private _scopes;
     private _languages;
     private _composer;
+    private _defaultScopeComposer;
     private _options;
     /**
-     * Constructor for the `Command` class.
-     * Do not call this directly. Instead, use the `command` method from the `Commands` class
+     * 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 options Options object that should apply to this command only
-     * @access package
+     * @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
      */
@@ -54,7 +98,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" },
@@ -70,9 +114,9 @@ export declare class Command<C extends Context = Context> implements MiddlewareO
      * @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;
+    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
      *