@grammyjs/commands 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) [year] [fullname]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,178 @@
+## grammY Commands Plugin
+
+This plugin provides a convenient way to define and manage commands for your grammY bot. It simplifies the process of
+setting up commands with scopes and localization.
+
+## Installation
+
+On NPM, this plugin is available as `@grammyjs/commands`, and on Deno it's available at
+[deno.land/x/grammy_commands](https://deno.land/x/grammy_commands).
+
+You can install it for Node.js with this command:
+
+```sh
+npm i @grammyjs/commands
+```
+
+## Core Concepts
+
+### The `Commands` class
+
+The `Commands` class is the foundation of this plugin. It allows you to create commands by specifying their names and
+descriptions, along with additional attributes such as scopes and localization.
+
+### The `ctx.setMyCommands` method
+
+The `ctx.setMyCommands` method, provided by the plugin, offers a convenient way to dynamically set the available
+commands for the current chat. By invoking this method and passing an instance of the `Commands` class, you can override
+the default command scopes and make all commands accessible within the current chat. This feature is particularly useful
+when you need to customize the command set for specific chat contexts, ignoring the predefined scopes, which allows for
+a more tailored and context-aware usage of bot commands.
+
+## Usage
+
+### Managing Commands For Multiple Scopes
+
+To manage commands for multiple scopes at once, create an instance of the `Commands` class, add your commands to it, and
+then call the `setFor` method of the class instance. Check out this example:
+
+```typescript
+import { Bot } from "https://deno.land/x/grammy/mod.ts";
+import { Commands } from "https://deno.land/x/grammy_commands/mod.ts";
+
+const bot = new Bot("<your_bot_token>");
+const cmds = new Commands();
+
+// Define your commands...
+
+await cmds.setFor(bot);
+```
+
+### Managing Commands For The Current Chat
+
+To set the commands for the current chat, you can use the `ctx.setMyCommands` method of the `Context` object. For that,
+you will need to install the `CommandsFlavor` to your context, and create an instance of the `Commands` class, to which
+you add your commands to and then pass to `ctx.setMyCommands`. This will override the predefined scopes and make all
+commands available to the current chat. Here's an example:
+
+> Please note that this only works in updates which have a `chat` object. If `ctx.chat` is not defined, an error will be
+> thrown ar runtime.
+
+```typescript
+import { Bot, Context } from "https://deno.land/x/grammy/mod.ts";
+import { Commands, CommandsFlavor } from "https://deno.land/x/grammy_commands/mod.ts";
+
+type MyContext = CommandsFlavor<Context>;
+const bot = new Bot<MyContext>("<your_bot_token>");
+
+bot.on(":text", async (ctx: Context) => {
+  const cmds = new Commands();
+
+  // Define your commands...
+
+  await ctx.setMyCommands(cmds);
+});
+```
+
+### Defining Commands
+
+To define a command, use the `command` method of the `CommandsPlugin` instance. The `command` method takes two
+arguments: the command name and the command description. Here's an example:
+
+```typescript
+commands.command("help", "Sends help");
+```
+
+### Setting handlers
+
+The underlying class returned by the `.command()` method extends the grammY `Composer` class. That means you can use
+`.use`, `.filter`, `.branch`, `.chatType` and every other `Composer` method you already know and love. Alternatively,
+you can pass your middleware as a third parameter to the `.command()` method. You can also use the `onChatType` method
+of the `Command` class to define middleware specific to that chat type. Here are some examples:
+
+#### Example 1
+
+```typescript
+commands.command("start", "Starts the bot", (ctx) => {
+  ctx.reply(`Hello, ${ctx.chat?.first_name ?? "there"}!`);
+});
+```
+
+#### Example 2
+
+```typescript
+commands.command("start", "Starts the bot")
+  .onChatType("private", (ctx) => ctx.reply(`Hello ${ctx.chat.first_name}!`))
+  .onChatType(["group", "supergroup", "channel"], (ctx) => ctx.reply(`Hello members of ${ctx.chat.title}!`))
+  .addToScope("default");
+```
+
+### Localization
+
+You can localize command names and descriptions using the `localize` method. The `localize` method takes the language
+code, the localized command name, and the localized command description. Here's an example:
+
+```typescript
+commands.command("help", "Sends help")
+  .localize("de-DE", "hilfe", "Sendet Hilfe");
+```
+
+### Scopes
+
+Scopes determine the availability of each command, enabling you to control whether a command can be accessed in all
+group chats, private chats, or limited to chat administrators. Commands can be assigned to different scopes using the
+`addToScope` method. Here's an example:
+
+```typescript
+commands.command("help", "Sends help")
+  .addToScope("default")
+  .addToScope("all_group_chats")
+  .addToScope("all_private_chats")
+  .addToScope("all_chat_administrators")
+  .addToScope("chat_administrators", "@grammyjs")
+  .addToScope("chat", "@SpecificUserChat");
+```
+
+### Setting Commands for Current Chat
+
+To set the commands for the current chat, you can use the `setMyCommands` method of the `Context` object. This will
+override the defined scopes and make all commands available to the current chat. Here's an example:
+
+```typescript
+bot.on(":text", async (ctx) => {
+  await ctx.setMyCommands(commands);
+});
+```
+
+This will set all commands defined in the `commands` instance for the current chat.
+
+## Examples
+
+### Example 1: Help Command
+
+This example shows how to define a basic help command:
+
+```typescript
+commands.command("help", "Sends help")
+  .localize("de-DE", "hilfe", "Sendet Hilfe")
+  .addToScope("default")
+  .addToScope("all_group_chats")
+  .addToScope("all_private_chats")
+  .addToScope("all_chat_administrators")
+  .addToScope("chat_administrators", "@grammyjs")
+  .addToScope("chat", "@LWJerri");
+```
+
+### Example 2: Stats Command
+
+This example shows how to define a stats command for group chats:
+
+```typescript
+commands.command("stats", "Sends group stats")
+  .addToScope("all_group_chats")
+  .addToScope("all_chat_administrators")
+  .addToScope("chat_administrators", "@grammyjs")
+  .addToScope("chat", "@LWJerri");
+```
+
+Feel free to add more commands and customize them according to your bot's needs.

package/out/command.d.ts

@@ -0,0 +1,22 @@
+import { BotCommand, BotCommandScope, Chat, ChatTypeContext, CommandMiddleware, Composer, Context, Middleware } from "./deps.node.js";
+export type MaybeArray<T> = T | T[];
+export declare class Command<C extends Context = Context> extends Composer<C> {
+    #private;
+    constructor(name: string, description: string, ...middleware: Array<Middleware<C>>);
+    get languages(): Map<string, {
+        name: string;
+        description: string;
+    }>;
+    get scopes(): BotCommandScope[];
+    get name(): string;
+    get description(): string;
+    addToScope(type: "default" | "all_private_chats" | "all_group_chats" | "all_chat_administrators"): this;
+    addToScope(type: "chat", chatId: string | number): this;
+    addToScope(type: "chat_member", chatId: string | number, userId: number): this;
+    addToScope(type: "chat_administrators", chatId: string | number): this;
+    localize(languageCode: string, name: string, description: string): this;
+    getLocalizedName(languageCode: string): string;
+    getLocalizedDescription(languageCode: string): string;
+    onChatType<T extends Chat["type"]>(chatType: MaybeArray<T>, ...middleware: Array<CommandMiddleware<ChatTypeContext<C, T>>>): this;
+    toObject(languageCode?: string): BotCommand;
+}

package/out/command.js

@@ -0,0 +1,69 @@
+"use strict";
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _Command_scopes, _Command_languages;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Command = void 0;
+const deps_node_js_1 = require("./deps.node.js");
+class Command extends deps_node_js_1.Composer {
+    constructor(name, description, ...middleware) {
+        super();
+        _Command_scopes.set(this, []);
+        _Command_languages.set(this, new Map());
+        if (!name.match(/[a-z0-9_]{1,32}/)) {
+            throw new Error(`${name} is not a valid command name`);
+        }
+        __classPrivateFieldGet(this, _Command_languages, "f").set("default", { name, description });
+        this.command(name, ...middleware);
+    }
+    get languages() {
+        return __classPrivateFieldGet(this, _Command_languages, "f");
+    }
+    get scopes() {
+        return __classPrivateFieldGet(this, _Command_scopes, "f");
+    }
+    get name() {
+        return __classPrivateFieldGet(this, _Command_languages, "f").get("default").name;
+    }
+    get description() {
+        return __classPrivateFieldGet(this, _Command_languages, "f").get("default").description;
+    }
+    addToScope(type, chatId, userId) {
+        const scope = (0, deps_node_js_1.match)({ type, chatId, userId })
+            .with({ type: "default" }, { type: "all_chat_administrators" }, { type: "all_group_chats" }, { type: "all_private_chats" }, ({ type }) => ({ type }))
+            .with({ type: deps_node_js_1.P.union("chat", "chat_administrators"), chatId: deps_node_js_1.P.not(deps_node_js_1.P.nullish) }, ({ type, chatId }) => ({ type, chat_id: chatId }))
+            .with({ type: "chat_member", chatId: deps_node_js_1.P.not(deps_node_js_1.P.nullish), userId: deps_node_js_1.P.not(deps_node_js_1.P.nullish) }, ({ type, chatId, userId }) => ({ type, chat_id: chatId, user_id: userId }))
+            .otherwise(() => null);
+        if (scope)
+            __classPrivateFieldGet(this, _Command_scopes, "f").push(scope);
+        return this;
+    }
+    localize(languageCode, name, description) {
+        __classPrivateFieldGet(this, _Command_languages, "f").set(languageCode, { name, description });
+        return this;
+    }
+    getLocalizedName(languageCode) {
+        var _a, _b;
+        return (_b = (_a = __classPrivateFieldGet(this, _Command_languages, "f").get(languageCode)) === null || _a === void 0 ? void 0 : _a.name) !== null && _b !== void 0 ? _b : this.name;
+    }
+    getLocalizedDescription(languageCode) {
+        var _a, _b;
+        return (_b = (_a = __classPrivateFieldGet(this, _Command_languages, "f").get(languageCode)) === null || _a === void 0 ? void 0 : _a.description) !== null && _b !== void 0 ? _b : this.description;
+    }
+    onChatType(chatType, ...middleware) {
+        const names = Array.from(__classPrivateFieldGet(this, _Command_languages, "f").values()).map(({ name }) => name);
+        this.chatType(chatType).command(names, ...middleware);
+        return this;
+    }
+    toObject(languageCode = "default") {
+        return {
+            command: this.getLocalizedName(languageCode),
+            description: this.getLocalizedDescription(languageCode),
+        };
+    }
+}
+exports.Command = Command;
+_Command_scopes = new WeakMap(), _Command_languages = new WeakMap();

package/out/context.d.ts

@@ -0,0 +1,13 @@
+import { Context, NextFunction } from "./deps.node.js";
+import { Commands } from "./plugin.js";
+export type CommandsFlavor<C extends Context = Context> = C & {
+    /**
+     * Sets the provided commands for the current chat.
+     * Cannot be called on updates that don't have a `chat` property.
+     *
+     * @param commands List of available commands
+     * @returns Promise with the result of the operations
+     */
+    setMyCommands: (commands: Commands<C>) => Promise<true[]>;
+};
+export declare function commands<C extends Context>(): (ctx: CommandsFlavor<C>, next: NextFunction) => Promise<void>;

package/out/context.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.commands = void 0;
+function commands() {
+    return (ctx, next) => {
+        ctx.setMyCommands = (commands) => {
+            if (!ctx.chat)
+                throw new Error("cannot call `ctx.setMyCommands` on an update with no `chat` property");
+            return Promise.all(commands
+                .toSingleScopeArgs({ type: "chat", chat_id: ctx.chat.id })
+                .map((args) => ctx.api.raw.setMyCommands(args)));
+        };
+        return next();
+    };
+}
+exports.commands = commands;

package/out/deps.node.d.ts

@@ -0,0 +1,3 @@
+export { Bot, type ChatTypeContext, type CommandMiddleware, Composer, Context, type Middleware, type NextFunction, } from "grammy";
+export type { BotCommand, BotCommandScope, Chat } from "grammy/types";
+export { match, P } from "ts-pattern";

package/out/deps.node.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.P = exports.match = exports.Context = exports.Composer = exports.Bot = void 0;
+// TODO: Replace with official deno module, once it arrives (https://github.com/gvergnaud/ts-pattern/pull/108)
+var grammy_1 = require("grammy");
+Object.defineProperty(exports, "Bot", { enumerable: true, get: function () { return grammy_1.Bot; } });
+Object.defineProperty(exports, "Composer", { enumerable: true, get: function () { return grammy_1.Composer; } });
+Object.defineProperty(exports, "Context", { enumerable: true, get: function () { return grammy_1.Context; } });
+var ts_pattern_1 = require("ts-pattern");
+Object.defineProperty(exports, "match", { enumerable: true, get: function () { return ts_pattern_1.match; } });
+Object.defineProperty(exports, "P", { enumerable: true, get: function () { return ts_pattern_1.P; } });

package/out/mod.d.ts

@@ -0,0 +1,2 @@
+export * from "./context.js";
+export * from "./plugin.js";

package/out/mod.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+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 });
+__exportStar(require("./context.js"), exports);
+__exportStar(require("./plugin.js"), exports);

package/out/plugin.d.ts

@@ -0,0 +1,18 @@
+import { Command } from "./command.js";
+import { Bot, BotCommand, BotCommandScope, Context, Middleware } from "./deps.node.js";
+type SetMyCommandsParams = {
+    scope?: BotCommandScope;
+    language_code?: string;
+    commands: BotCommand[];
+};
+export declare class Commands<C extends Context> {
+    #private;
+    constructor(commands?: Command<C>[]);
+    command(name: string, description: string, ...middleware: Array<Middleware<C>>): Command<C>;
+    toArgs(): SetMyCommandsParams[];
+    toSingleScopeArgs(scope: BotCommandScope): SetMyCommandsParams[];
+    setFor<C extends Context>(bot: Bot<C>): Promise<true[]>;
+    toJSON(): SetMyCommandsParams[];
+    toString(): string;
+}
+export {};

package/out/plugin.js

@@ -0,0 +1,88 @@
+"use strict";
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var _Commands_instances, _Commands_languages, _Commands_scopes, _Commands_commands, _Commands_addCommandToScope, _Commands_populate;
+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");
+class Commands {
+    constructor(commands = []) {
+        _Commands_instances.add(this);
+        _Commands_languages.set(this, new Set());
+        _Commands_scopes.set(this, new Map());
+        _Commands_commands.set(this, []);
+        commands.forEach((command) => __classPrivateFieldGet(this, _Commands_commands, "f").push(command));
+    }
+    command(name, description, ...middleware) {
+        const command = new command_js_1.Command(name, description, ...middleware);
+        __classPrivateFieldGet(this, _Commands_commands, "f").push(command);
+        return command;
+    }
+    toArgs() {
+        __classPrivateFieldGet(this, _Commands_instances, "m", _Commands_populate).call(this);
+        const params = [];
+        for (const [scope, commands] of __classPrivateFieldGet(this, _Commands_scopes, "f").entries()) {
+            for (const language of __classPrivateFieldGet(this, _Commands_languages, "f")) {
+                params.push({
+                    scope: JSON.parse(scope),
+                    language_code: language === "default" ? undefined : language,
+                    commands: commands.map((command) => command.toObject(language)),
+                });
+            }
+        }
+        return params.filter((params) => params.commands.length > 0);
+    }
+    toSingleScopeArgs(scope) {
+        __classPrivateFieldGet(this, _Commands_instances, "m", _Commands_populate).call(this);
+        const params = [];
+        for (const language of __classPrivateFieldGet(this, _Commands_languages, "f")) {
+            params.push({
+                scope,
+                language_code: (0, deps_node_js_1.match)(language).with("default", () => undefined).otherwise((value) => value),
+                commands: __classPrivateFieldGet(this, _Commands_commands, "f")
+                    .filter((command) => command.scopes.length)
+                    .map((command) => command.toObject(language)),
+            });
+        }
+        return params;
+    }
+    setFor(bot) {
+        const argsArray = this.toArgs();
+        const promises = argsArray.map((args) => bot.api.raw.setMyCommands(args));
+        return Promise.all(promises);
+    }
+    toJSON() {
+        return this.toArgs();
+    }
+    toString() {
+        return JSON.stringify(this);
+    }
+    [(_Commands_languages = new WeakMap(), _Commands_scopes = new WeakMap(), _Commands_commands = new WeakMap(), _Commands_instances = new WeakSet(), _Commands_addCommandToScope = function _Commands_addCommandToScope(scope, command) {
+        var _a;
+        const commands = (_a = __classPrivateFieldGet(this, _Commands_scopes, "f").get(JSON.stringify(scope))) !== null && _a !== void 0 ? _a : [];
+        __classPrivateFieldGet(this, _Commands_scopes, "f").set(JSON.stringify(scope), commands.concat([command]));
+    }, _Commands_populate = function _Commands_populate() {
+        __classPrivateFieldSet(this, _Commands_languages, new Set(), "f");
+        __classPrivateFieldSet(this, _Commands_scopes, new Map(), "f");
+        __classPrivateFieldGet(this, _Commands_commands, "f").forEach((command) => {
+            command.scopes.forEach((scope) => __classPrivateFieldGet(this, _Commands_instances, "m", _Commands_addCommandToScope).call(this, scope, command));
+            Array.from(command.languages.keys()).forEach((language) => __classPrivateFieldGet(this, _Commands_languages, "f").add(language));
+        });
+    }, Symbol.for("Deno.customInspect"))]() {
+        return this.toString();
+    }
+    [Symbol.for("nodejs.util.inspect.custom")]() {
+        return this.toString();
+    }
+}
+exports.Commands = Commands;

package/package.json

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