@yaebal/commands 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 neverlane
+
+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,13 @@
+# @yaebal/commands
+
+define a command: its name, menu description, and handler(s).
+
+## install
+
+```sh
+pnpm add @yaebal/commands
+```
+
+---
+
+part of [**yaebal**](https://github.com/neverlane/yaebal) — a type-safe, runtime-agnostic Telegram Bot API framework. MIT.

package/lib/index.d.ts

@@ -0,0 +1,28 @@
+import type { Context, Middleware, Plugin } from "@yaebal/core";
+export interface BotCommand {
+    command: string;
+    description: string;
+}
+interface CommandApi {
+    call<T = unknown>(method: string, params?: Record<string, unknown>): Promise<T>;
+}
+export interface CommandsRegistry {
+    /** Define a command: its name, menu description, and handler(s). */
+    add(name: string, description: string, ...handlers: Middleware<Context>[]): CommandsRegistry;
+    /** The `{ command, description }[]` for `setMyCommands`. */
+    list(): BotCommand[];
+    /** A plugin that registers every command's handler on the bot. */
+    plugin(): Plugin<Context, Record<never, never>>;
+    /** Push the command list to Telegram (so they show in the `/` menu). */
+    register(api: CommandApi, options?: {
+        languageCode?: string;
+    }): Promise<unknown>;
+}
+/**
+ * A single source of truth for commands: name + menu description + handler.
+ * `bot.install(cmd.plugin())` wires the handlers; `cmd.register(bot.api)` pushes
+ * the menu to Telegram.
+ */
+export declare function commands(): CommandsRegistry;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAEhE,MAAM,WAAW,UAAU;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;CACpB;AAED,UAAU,UAAU;IACnB,IAAI,CAAC,CAAC,GAAG,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CAChF;AAED,MAAM,WAAW,gBAAgB;IAChC,oEAAoE;IACpE,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,QAAQ,EAAE,UAAU,CAAC,OAAO,CAAC,EAAE,GAAG,gBAAgB,CAAC;IAC7F,4DAA4D;IAC5D,IAAI,IAAI,UAAU,EAAE,CAAC;IACrB,kEAAkE;IAClE,MAAM,IAAI,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC;IAChD,wEAAwE;IACxE,QAAQ,CAAC,GAAG,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE;QAAE,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACjF;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,IAAI,gBAAgB,CA6B3C"}

package/lib/index.js

@@ -0,0 +1,32 @@
+/**
+ * A single source of truth for commands: name + menu description + handler.
+ * `bot.install(cmd.plugin())` wires the handlers; `cmd.register(bot.api)` pushes
+ * the menu to Telegram.
+ */
+export function commands() {
+    const defs = [];
+    const registry = {
+        add(name, description, ...handlers) {
+            defs.push({ name, description, handlers });
+            return registry;
+        },
+        list() {
+            return defs.map((d) => ({ command: d.name, description: d.description }));
+        },
+        plugin() {
+            return (composer) => {
+                for (const d of defs)
+                    composer.command(d.name, ...d.handlers);
+                return composer;
+            };
+        },
+        register(api, options) {
+            return api.call("setMyCommands", {
+                commands: registry.list(),
+                ...(options?.languageCode ? { language_code: options.languageCode } : {}),
+            });
+        },
+    };
+    return registry;
+}
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAsBA;;;;GAIG;AACH,MAAM,UAAU,QAAQ;IACvB,MAAM,IAAI,GAAkF,EAAE,CAAC;IAE/F,MAAM,QAAQ,GAAqB;QAClC,GAAG,CAAC,IAAI,EAAE,WAAW,EAAE,GAAG,QAAQ;YACjC,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,QAAQ,EAAE,CAAC,CAAC;YAC3C,OAAO,QAAQ,CAAC;QACjB,CAAC;QAED,IAAI;YACH,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,IAAI,EAAE,WAAW,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC;QAC3E,CAAC;QAED,MAAM;YACL,OAAO,CAAC,QAAQ,EAAE,EAAE;gBACnB,KAAK,MAAM,CAAC,IAAI,IAAI;oBAAE,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC;gBAC9D,OAAO,QAAQ,CAAC;YACjB,CAAC,CAAC;QACH,CAAC;QAED,QAAQ,CAAC,GAAG,EAAE,OAAO;YACpB,OAAO,GAAG,CAAC,IAAI,CAAC,eAAe,EAAE;gBAChC,QAAQ,EAAE,QAAQ,CAAC,IAAI,EAAE;gBACzB,GAAG,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aACzE,CAAC,CAAC;QACJ,CAAC;KACD,CAAC;IAEF,OAAO,QAAQ,CAAC;AACjB,CAAC"}

package/lib/index.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.test.d.ts.map

package/lib/index.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.test.d.ts","sourceRoot":"","sources":["../src/index.test.ts"],"names":[],"mappings":""}

package/lib/index.test.js

@@ -0,0 +1,57 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { Composer, Context } from "@yaebal/core";
+import { commands } from "./index.js";
+const noop = async () => { };
+const entry = (c) => c.toMiddleware();
+const api = {};
+const cmdCtx = (text) => new Context({
+    api,
+    update: {
+        update_id: 1,
+        message: {
+            message_id: 1,
+            date: 0,
+            chat: { id: 1, type: "private" },
+            from: { id: 1, is_bot: false, first_name: "u" },
+            text,
+        },
+    },
+    updateType: "message",
+});
+test("list() yields the {command, description} menu", () => {
+    const cmd = commands()
+        .add("start", "start the bot", () => { })
+        .add("help", "show help", () => { });
+    assert.deepEqual(cmd.list(), [
+        { command: "start", description: "start the bot" },
+        { command: "help", description: "show help" },
+    ]);
+});
+test("plugin() registers the handlers", async () => {
+    let started = false;
+    const cmd = commands().add("start", "start", () => {
+        started = true;
+    });
+    const mw = entry(new Composer().install(cmd.plugin()));
+    await mw(cmdCtx("/start"), noop);
+    assert.equal(started, true);
+});
+test("register() pushes the list via setMyCommands", async () => {
+    const calls = [];
+    const fakeApi = {
+        call: (method, params) => {
+            calls.push({ method, params });
+            return Promise.resolve(true);
+        },
+    };
+    const cmd = commands().add("start", "go", () => { });
+    await cmd.register(fakeApi, { languageCode: "en" });
+    assert.deepEqual(calls, [
+        {
+            method: "setMyCommands",
+            params: { commands: [{ command: "start", description: "go" }], language_code: "en" },
+        },
+    ]);
+});
+//# sourceMappingURL=index.test.js.map

package/lib/index.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.test.js","sourceRoot":"","sources":["../src/index.test.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@yaebal/commands",
+  "version": "0.0.1",
+  "description": "yaebal commands — one registry for command handlers + the telegram command menu.",
+  "type": "module",
+  "main": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "import": "./lib/index.js"
+    }
+  },
+  "files": [
+    "lib",
+    "src"
+  ],
+  "dependencies": {
+    "@yaebal/core": "0.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "latest"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "telegram",
+    "telegram-bot",
+    "yaebal",
+    "commands",
+    "setmycommands"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/neverlane/yaebal",
+    "directory": "packages/commands"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "node --test lib"
+  }
+}

package/src/index.test.ts

@@ -0,0 +1,71 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { Composer, Context, type Middleware } from "@yaebal/core";
+import { commands } from "./index.js";
+
+const noop = async () => {};
+const entry = <C extends Context>(c: Composer<C>) =>
+	c.toMiddleware() as unknown as Middleware<Context>;
+
+const api = {} as never;
+const cmdCtx = (text: string) =>
+	new Context({
+		api,
+
+		update: {
+			update_id: 1,
+			message: {
+				message_id: 1,
+				date: 0,
+				chat: { id: 1, type: "private" },
+				from: { id: 1, is_bot: false, first_name: "u" },
+				text,
+			},
+		} as never,
+
+		updateType: "message",
+	});
+
+test("list() yields the {command, description} menu", () => {
+	const cmd = commands()
+		.add("start", "start the bot", () => {})
+		.add("help", "show help", () => {});
+
+	assert.deepEqual(cmd.list(), [
+		{ command: "start", description: "start the bot" },
+		{ command: "help", description: "show help" },
+	]);
+});
+
+test("plugin() registers the handlers", async () => {
+	let started = false;
+
+	const cmd = commands().add("start", "start", () => {
+		started = true;
+	});
+
+	const mw = entry(new Composer<Context>().install(cmd.plugin()));
+	await mw(cmdCtx("/start"), noop);
+
+	assert.equal(started, true);
+});
+
+test("register() pushes the list via setMyCommands", async () => {
+	const calls: Array<{ method: string; params: unknown }> = [];
+	const fakeApi = {
+		call: (method: string, params: unknown) => {
+			calls.push({ method, params });
+			return Promise.resolve(true);
+		},
+	};
+
+	const cmd = commands().add("start", "go", () => {});
+	await cmd.register(fakeApi as never, { languageCode: "en" });
+	
+	assert.deepEqual(calls, [
+		{
+			method: "setMyCommands",
+			params: { commands: [{ command: "start", description: "go" }], language_code: "en" },
+		},
+	]);
+});

package/src/index.ts

@@ -0,0 +1,57 @@
+import type { Context, Middleware, Plugin } from "@yaebal/core";
+
+export interface BotCommand {
+	command: string;
+	description: string;
+}
+
+interface CommandApi {
+	call<T = unknown>(method: string, params?: Record<string, unknown>): Promise<T>;
+}
+
+export interface CommandsRegistry {
+	/** Define a command: its name, menu description, and handler(s). */
+	add(name: string, description: string, ...handlers: Middleware<Context>[]): CommandsRegistry;
+	/** The `{ command, description }[]` for `setMyCommands`. */
+	list(): BotCommand[];
+	/** A plugin that registers every command's handler on the bot. */
+	plugin(): Plugin<Context, Record<never, never>>;
+	/** Push the command list to Telegram (so they show in the `/` menu). */
+	register(api: CommandApi, options?: { languageCode?: string }): Promise<unknown>;
+}
+
+/**
+ * A single source of truth for commands: name + menu description + handler.
+ * `bot.install(cmd.plugin())` wires the handlers; `cmd.register(bot.api)` pushes
+ * the menu to Telegram.
+ */
+export function commands(): CommandsRegistry {
+	const defs: Array<{ name: string; description: string; handlers: Middleware<Context>[] }> = [];
+
+	const registry: CommandsRegistry = {
+		add(name, description, ...handlers) {
+			defs.push({ name, description, handlers });
+			return registry;
+		},
+
+		list() {
+			return defs.map((d) => ({ command: d.name, description: d.description }));
+		},
+
+		plugin() {
+			return (composer) => {
+				for (const d of defs) composer.command(d.name, ...d.handlers);
+				return composer;
+			};
+		},
+
+		register(api, options) {
+			return api.call("setMyCommands", {
+				commands: registry.list(),
+				...(options?.languageCode ? { language_code: options.languageCode } : {}),
+			});
+		},
+	};
+	
+	return registry;
+}