@yaebal/toml 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,92 @@
+# @yaebal/toml
+
+declarative toml routes for yaebal bots.
+
+status: experimental.
+
+## installation
+
+```sh
+pnpm add @yaebal/toml
+```
+
+## what it is
+
+`@yaebal/toml` lets small bots describe commands, text routes, message filters, callback queries, and simple replies in toml. typescript stays available for real logic through a handler registry.
+
+## bot.toml
+
+```toml
+[bot]
+name = "demo"
+
+[[commands]]
+name = "start"
+description = "start command"
+reply = "привет! я бот из toml."
+
+[[commands]]
+name = "ping"
+handler = "ping"
+
+[[hears]]
+text = "ping"
+reply = "pong"
+
+[[messages]]
+on = "message:text"
+contains = "yaebal"
+reply = "yaebal мощь"
+
+[[callbacks]]
+data = "profile"
+handler = "profileCallback"
+```
+
+## index.ts
+
+```ts
+import { Bot } from "@yaebal/core";
+import { installToml } from "@yaebal/toml";
+
+const bot = new Bot(process.env.BOT_TOKEN!);
+
+installToml(bot, "./bot.toml", {
+	handlers: {
+		ping: async (ctx) => {
+			await ctx.reply("pong from typescript");
+		},
+		profileCallback: async (ctx) => {
+			await ctx.reply("profile");
+		},
+	},
+});
+
+await bot.start();
+```
+
+## handler registry
+
+when a route uses `handler = "name"`, the name must exist in `options.handlers`. if a handler is missing, install fails before routes are registered:
+
+```txt
+Missing handler "ping" referenced in commands[1]
+```
+
+if both `handler` and `reply` are present, the handler wins. the reply is only used when no handler is configured.
+
+## plugin usage
+
+```ts
+import { createTomlPlugin } from "@yaebal/toml";
+
+bot.install(createTomlPlugin("./bot.toml", { handlers }));
+```
+
+## limitations
+
+toml does not replace typescript logic. it only describes routes and simple replies. use the handler registry for validation, database calls, external services, branching flows, and anything that needs compile-time types.
+
+---
+
+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,5 @@
+export { createTomlPlugin, installToml } from "./install.js";
+export { parseTomlConfig } from "./parse.js";
+export { tomlBotConfigSchema, validateTomlConfig } from "./schema.js";
+export type { InstallTomlOptions, TomlBotConfig, TomlHandler, TomlHandlers } from "./types.js";
+//# 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,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC7D,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACtE,YAAY,EAAE,kBAAkB,EAAE,aAAa,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC"}

package/lib/index.js

@@ -0,0 +1,4 @@
+export { createTomlPlugin, installToml } from "./install.js";
+export { parseTomlConfig } from "./parse.js";
+export { tomlBotConfigSchema, validateTomlConfig } from "./schema.js";
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC7D,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,aAAa,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,100 @@
+import assert from "node:assert/strict";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+import { Composer } from "@yaebal/core";
+import { callbackUpdate, createContext, messageUpdate, mockApi, runMiddleware } from "@yaebal/test";
+import { installToml, parseTomlConfig, validateTomlConfig } from "./index.js";
+test("parse raw toml string", () => {
+    const config = parseTomlConfig(`
+[[commands]]
+name = "start"
+reply = "hi"
+`);
+    assert.deepEqual(config.commands, [{ name: "start", reply: "hi" }]);
+});
+test("parse toml file path", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "yaebal-toml-"));
+    const file = join(dir, "bot.toml");
+    try {
+        await writeFile(file, `[[hears]]\ntext = "ping"\nreply = "pong"\n`);
+        const config = parseTomlConfig(file);
+        assert.deepEqual(config.hears, [{ text: "ping", reply: "pong" }]);
+    }
+    finally {
+        await rm(dir, { recursive: true, force: true });
+    }
+});
+test("validate minimal empty config", () => {
+    assert.deepEqual(validateTomlConfig({}), {});
+});
+test("validate command with reply", () => {
+    assert.deepEqual(validateTomlConfig({ commands: [{ name: "start", reply: "hi" }] }), {
+        commands: [{ name: "start", reply: "hi" }],
+    });
+});
+test("validate command with missing reply or handler should fail", () => {
+    assert.throws(() => validateTomlConfig({ commands: [{ name: "start" }] }), /commands\[0\] must define either reply or handler/);
+});
+test("validate message with missing on should fail", () => {
+    assert.throws(() => validateTomlConfig({ messages: [{ reply: "hi" }] }), /messages\[0\]\.on is required/);
+});
+test("install registers command reply", async () => {
+    const composer = new Composer();
+    const { api, calls } = mockApi();
+    installToml(composer, { commands: [{ name: "start", reply: "hi" }] });
+    await runMiddleware(composer, createContext(messageUpdate({ text: "/start" }), api));
+    assert.deepEqual(calls, [
+        {
+            method: "sendMessage",
+            params: { chat_id: 1, text: "hi", reply_parameters: { message_id: 1 } },
+        },
+    ]);
+});
+test("install throws on missing named handler", () => {
+    assert.throws(() => installToml(new Composer(), { commands: [{ name: "ping", handler: "ping" }] }), /Missing handler "ping" referenced in commands\[0\]/);
+});
+test("messages contains filter works", async () => {
+    const composer = new Composer();
+    const { api, calls } = mockApi();
+    installToml(composer, {
+        messages: [{ on: "message:text", contains: "yaebal", reply: "match" }],
+    });
+    await runMiddleware(composer, createContext(messageUpdate({ text: "hello" }), api));
+    await runMiddleware(composer, createContext(messageUpdate({ text: "hello yaebal" }), api));
+    assert.equal(calls.length, 1);
+    assert.equal(calls[0]?.params?.text, "match");
+});
+test("messages equals filter works", async () => {
+    const composer = new Composer();
+    const { api, calls } = mockApi();
+    installToml(composer, {
+        messages: [{ on: "message:text", equals: "secret", reply: "match" }],
+    });
+    await runMiddleware(composer, createContext(messageUpdate({ text: "secret!" }), api));
+    await runMiddleware(composer, createContext(messageUpdate({ text: "secret" }), api));
+    assert.equal(calls.length, 1);
+    assert.equal(calls[0]?.params?.text, "match");
+});
+test("callbacks with handler works", async () => {
+    const composer = new Composer();
+    const { api, calls } = mockApi();
+    installToml(composer, {
+        callbacks: [{ data: "profile", handler: "profileCallback" }],
+    }, {
+        handlers: {
+            profileCallback: async (ctx) => {
+                await ctx.reply("profile");
+            },
+        },
+    });
+    await runMiddleware(composer, createContext(callbackUpdate({ data: "profile" }), api));
+    assert.deepEqual(calls, [
+        {
+            method: "sendMessage",
+            params: { chat_id: 1, text: "profile" },
+        },
+    ]);
+});
+//# 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/lib/install.d.ts

@@ -0,0 +1,9 @@
+import type { Composer, Context, Plugin } from "@yaebal/core";
+import type { InstallTomlOptions, TomlConfigInput } from "./types.js";
+type EmptyPluginOutput = Record<never, never>;
+/** install toml routes on an existing bot or composer and return the same instance. */
+export declare function installToml<C extends Context, T extends Composer<C>>(target: T, configPathOrObject: TomlConfigInput, options?: InstallTomlOptions<C>): T;
+/** create a yaebal plugin that installs toml routes when mounted. */
+export declare function createTomlPlugin<C extends Context = Context>(configPathOrObject: TomlConfigInput, options?: InstallTomlOptions<C>): Plugin<C, EmptyPluginOutput>;
+export {};
+//# sourceMappingURL=install.d.ts.map

package/lib/install.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../src/install.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEX,QAAQ,EACR,OAAO,EAGP,MAAM,EACN,MAAM,cAAc,CAAC;AAEtB,OAAO,KAAK,EACX,kBAAkB,EAElB,eAAe,EAEf,MAAM,YAAY,CAAC;AAEpB,KAAK,iBAAiB,GAAG,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;AA2E9C,uFAAuF;AACvF,wBAAgB,WAAW,CAAC,CAAC,SAAS,OAAO,EAAE,CAAC,SAAS,QAAQ,CAAC,CAAC,CAAC,EACnE,MAAM,EAAE,CAAC,EACT,kBAAkB,EAAE,eAAe,EACnC,OAAO,GAAE,kBAAkB,CAAC,CAAC,CAAM,GACjC,CAAC,CAwCH;AAED,qEAAqE;AACrE,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,OAAO,GAAG,OAAO,EAC3D,kBAAkB,EAAE,eAAe,EACnC,OAAO,GAAE,kBAAkB,CAAC,CAAC,CAAM,GACjC,MAAM,CAAC,CAAC,EAAE,iBAAiB,CAAC,CAG9B"}

package/lib/install.js

@@ -0,0 +1,85 @@
+import { parseTomlConfig } from "./parse.js";
+function replyHandler(text) {
+    return async (ctx) => {
+        await ctx.reply(text);
+    };
+}
+function missingResponseError(kind, index) {
+    return new Error(`${kind}[${index}] must define either reply or handler`);
+}
+function resolveHandler(route, kind, index, options) {
+    if (route.handler !== undefined) {
+        const handler = options.handlers?.[route.handler];
+        if (!handler)
+            throw new Error(`Missing handler "${route.handler}" referenced in ${kind}[${index}]`);
+        return handler;
+    }
+    if (route.reply !== undefined)
+        return replyHandler(route.reply);
+    throw missingResponseError(kind, index);
+}
+function assertHandlersExist(config, options) {
+    for (const [index, route] of (config.commands ?? []).entries()) {
+        if (route.handler !== undefined && !options.handlers?.[route.handler]) {
+            throw new Error(`Missing handler "${route.handler}" referenced in commands[${index}]`);
+        }
+    }
+    for (const [index, route] of (config.hears ?? []).entries()) {
+        if (route.handler !== undefined && !options.handlers?.[route.handler]) {
+            throw new Error(`Missing handler "${route.handler}" referenced in hears[${index}]`);
+        }
+    }
+    for (const [index, route] of (config.messages ?? []).entries()) {
+        if (route.handler !== undefined && !options.handlers?.[route.handler]) {
+            throw new Error(`Missing handler "${route.handler}" referenced in messages[${index}]`);
+        }
+    }
+    for (const [index, route] of (config.callbacks ?? []).entries()) {
+        if (route.handler !== undefined && !options.handlers?.[route.handler]) {
+            throw new Error(`Missing handler "${route.handler}" referenced in callbacks[${index}]`);
+        }
+    }
+}
+function matchesMessageFilters(ctx, filters) {
+    if (filters.contains === undefined && filters.equals === undefined)
+        return true;
+    const text = ctx.text;
+    if (text === undefined)
+        return false;
+    if (filters.equals !== undefined && text !== filters.equals)
+        return false;
+    if (filters.contains !== undefined && !text.includes(filters.contains))
+        return false;
+    return true;
+}
+/** install toml routes on an existing bot or composer and return the same instance. */
+export function installToml(target, configPathOrObject, options = {}) {
+    const config = parseTomlConfig(configPathOrObject);
+    assertHandlersExist(config, options);
+    for (const [index, route] of (config.commands ?? []).entries()) {
+        const handler = resolveHandler(route, "commands", index, options);
+        target.command(route.name, handler);
+    }
+    for (const [index, route] of (config.hears ?? []).entries()) {
+        const handler = resolveHandler(route, "hears", index, options);
+        target.hears(route.text, handler);
+    }
+    for (const [index, route] of (config.messages ?? []).entries()) {
+        const handler = resolveHandler(route, "messages", index, options);
+        target.on(route.on, async (ctx, next) => {
+            if (!matchesMessageFilters(ctx, route))
+                return next();
+            return handler(ctx, next);
+        });
+    }
+    for (const [index, route] of (config.callbacks ?? []).entries()) {
+        const handler = resolveHandler(route, "callbacks", index, options);
+        target.callbackQuery(route.data, handler);
+    }
+    return target;
+}
+/** create a yaebal plugin that installs toml routes when mounted. */
+export function createTomlPlugin(configPathOrObject, options = {}) {
+    return (composer) => installToml(composer, configPathOrObject, options);
+}
+//# sourceMappingURL=install.js.map

package/lib/install.js.map

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

package/lib/parse.d.ts

@@ -0,0 +1,4 @@
+import type { TomlBotConfig, TomlConfigInput } from "./types.js";
+/** parse a toml config from a file path, raw toml string, or parsed object. */
+export declare function parseTomlConfig(input: TomlConfigInput): TomlBotConfig;
+//# sourceMappingURL=parse.d.ts.map

package/lib/parse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../src/parse.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AA0BjE,+EAA+E;AAC/E,wBAAgB,eAAe,CAAC,KAAK,EAAE,eAAe,GAAG,aAAa,CAarE"}

package/lib/parse.js

@@ -0,0 +1,41 @@
+import { existsSync, readFileSync } from "node:fs";
+import { parse } from "smol-toml";
+import { validateTomlConfig } from "./schema.js";
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function isPathLike(input) {
+    const trimmed = input.trim();
+    if (trimmed === "")
+        return false;
+    if (trimmed.includes("\n") || trimmed.includes("=") || trimmed.startsWith("["))
+        return false;
+    if (existsSync(input))
+        return true;
+    return trimmed.endsWith(".toml") || trimmed.endsWith(".tml");
+}
+function loadTomlSource(input) {
+    if (!isPathLike(input))
+        return input;
+    try {
+        return readFileSync(input, "utf8");
+    }
+    catch (error) {
+        throw new Error(`failed to read toml config file "${input}": ${errorMessage(error)}`);
+    }
+}
+/** parse a toml config from a file path, raw toml string, or parsed object. */
+export function parseTomlConfig(input) {
+    if (typeof input !== "string")
+        return validateTomlConfig(input);
+    const source = loadTomlSource(input);
+    let parsed;
+    try {
+        parsed = parse(source);
+    }
+    catch (error) {
+        throw new Error(`failed to parse toml config: ${errorMessage(error)}`);
+    }
+    return validateTomlConfig(parsed);
+}
+//# sourceMappingURL=parse.js.map

package/lib/parse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse.js","sourceRoot":"","sources":["../src/parse.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,KAAK,EAAE,MAAM,WAAW,CAAC;AAClC,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAGjD,SAAS,YAAY,CAAC,KAAc;IACnC,OAAO,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAC/D,CAAC;AAED,SAAS,UAAU,CAAC,KAAa;IAChC,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAE7B,IAAI,OAAO,KAAK,EAAE;QAAE,OAAO,KAAK,CAAC;IACjC,IAAI,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,OAAO,KAAK,CAAC;IAC7F,IAAI,UAAU,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAEnC,OAAO,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;AAC9D,CAAC;AAED,SAAS,cAAc,CAAC,KAAa;IACpC,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IAErC,IAAI,CAAC;QACJ,OAAO,YAAY,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;IACpC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QAChB,MAAM,IAAI,KAAK,CAAC,oCAAoC,KAAK,MAAM,YAAY,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IACvF,CAAC;AACF,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,eAAe,CAAC,KAAsB;IACrD,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,kBAAkB,CAAC,KAAK,CAAC,CAAC;IAEhE,MAAM,MAAM,GAAG,cAAc,CAAC,KAAK,CAAC,CAAC;IACrC,IAAI,MAAe,CAAC;IAEpB,IAAI,CAAC;QACJ,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC;IACxB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QAChB,MAAM,IAAI,KAAK,CAAC,gCAAgC,YAAY,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IACxE,CAAC;IAED,OAAO,kBAAkB,CAAC,MAAM,CAAC,CAAC;AACnC,CAAC"}

package/lib/schema.d.ts

@@ -0,0 +1,33 @@
+import { z } from "zod";
+import type { TomlBotConfig } from "./types.js";
+export declare const tomlBotConfigSchema: z.ZodObject<{
+    bot: z.ZodOptional<z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    commands: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        reply: z.ZodOptional<z.ZodString>;
+        handler: z.ZodOptional<z.ZodString>;
+        name: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    hears: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        reply: z.ZodOptional<z.ZodString>;
+        handler: z.ZodOptional<z.ZodString>;
+        text: z.ZodString;
+    }, z.core.$strip>>>;
+    messages: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        reply: z.ZodOptional<z.ZodString>;
+        handler: z.ZodOptional<z.ZodString>;
+        on: z.ZodString;
+        contains: z.ZodOptional<z.ZodString>;
+        equals: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    callbacks: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        reply: z.ZodOptional<z.ZodString>;
+        handler: z.ZodOptional<z.ZodString>;
+        data: z.ZodString;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+/** validate an already parsed toml bot config and return the normalized object. */
+export declare function validateTomlConfig(input: unknown): TomlBotConfig;
+//# sourceMappingURL=schema.d.ts.map

package/lib/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AA6DhD,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAU9B,CAAC;AAsCH,mFAAmF;AACnF,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,aAAa,CAMhE"}

package/lib/schema.js

@@ -0,0 +1,101 @@
+import { z } from "zod";
+const requiredString = z.string().min(1);
+const optionalString = z.string().optional();
+const responseShape = {
+    reply: optionalString,
+    handler: requiredString.optional(),
+};
+function hasResponse(route) {
+    return route.reply !== undefined || route.handler !== undefined;
+}
+const commandSchema = z
+    .object({
+    name: requiredString,
+    description: optionalString,
+    ...responseShape,
+})
+    .superRefine((route, ctx) => {
+    if (!hasResponse(route)) {
+        ctx.addIssue({ code: "custom", message: "must define either reply or handler" });
+    }
+});
+const hearSchema = z
+    .object({
+    text: requiredString,
+    ...responseShape,
+})
+    .superRefine((route, ctx) => {
+    if (!hasResponse(route)) {
+        ctx.addIssue({ code: "custom", message: "must define either reply or handler" });
+    }
+});
+const messageSchema = z
+    .object({
+    on: requiredString,
+    contains: optionalString,
+    equals: optionalString,
+    ...responseShape,
+})
+    .superRefine((route, ctx) => {
+    if (!hasResponse(route)) {
+        ctx.addIssue({ code: "custom", message: "must define either reply or handler" });
+    }
+});
+const callbackSchema = z
+    .object({
+    data: requiredString,
+    ...responseShape,
+})
+    .superRefine((route, ctx) => {
+    if (!hasResponse(route)) {
+        ctx.addIssue({ code: "custom", message: "must define either reply or handler" });
+    }
+});
+export const tomlBotConfigSchema = z.object({
+    bot: z
+        .object({
+        name: optionalString,
+    })
+        .optional(),
+    commands: z.array(commandSchema).optional(),
+    hears: z.array(hearSchema).optional(),
+    messages: z.array(messageSchema).optional(),
+    callbacks: z.array(callbackSchema).optional(),
+});
+function formatPath(path) {
+    let out = "";
+    for (const segment of path) {
+        if (typeof segment === "number") {
+            out += `[${segment}]`;
+        }
+        else {
+            out += out ? `.${String(segment)}` : String(segment);
+        }
+    }
+    return out || "config";
+}
+function isMissingRequired(issue) {
+    const details = issue;
+    const message = issue.message.toLowerCase();
+    return (issue.code === "invalid_type" &&
+        (details.input === undefined ||
+            details.received === "undefined" ||
+            message.includes("required") ||
+            message.includes("undefined")));
+}
+function formatIssue(issue) {
+    const path = formatPath(issue.path);
+    if (issue.code === "custom")
+        return `${path} ${issue.message}`;
+    if (isMissingRequired(issue))
+        return `${path} is required`;
+    return `${path}: ${issue.message}`;
+}
+/** validate an already parsed toml bot config and return the normalized object. */
+export function validateTomlConfig(input) {
+    const result = tomlBotConfigSchema.safeParse(input);
+    if (result.success)
+        return result.data;
+    throw new Error(result.error.issues.map(formatIssue).join("; "));
+}
+//# sourceMappingURL=schema.js.map

package/lib/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;AACzC,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC;AAE7C,MAAM,aAAa,GAAG;IACrB,KAAK,EAAE,cAAc;IACrB,OAAO,EAAE,cAAc,CAAC,QAAQ,EAAE;CAClC,CAAC;AAEF,SAAS,WAAW,CAAC,KAA2C;IAC/D,OAAO,KAAK,CAAC,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,OAAO,KAAK,SAAS,CAAC;AACjE,CAAC;AAED,MAAM,aAAa,GAAG,CAAC;KACrB,MAAM,CAAC;IACP,IAAI,EAAE,cAAc;IACpB,WAAW,EAAE,cAAc;IAC3B,GAAG,aAAa;CAChB,CAAC;KACD,WAAW,CAAC,CAAC,KAAK,EAAE,GAAG,EAAE,EAAE;IAC3B,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,GAAG,CAAC,QAAQ,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,qCAAqC,EAAE,CAAC,CAAC;IAClF,CAAC;AACF,CAAC,CAAC,CAAC;AAEJ,MAAM,UAAU,GAAG,CAAC;KAClB,MAAM,CAAC;IACP,IAAI,EAAE,cAAc;IACpB,GAAG,aAAa;CAChB,CAAC;KACD,WAAW,CAAC,CAAC,KAAK,EAAE,GAAG,EAAE,EAAE;IAC3B,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,GAAG,CAAC,QAAQ,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,qCAAqC,EAAE,CAAC,CAAC;IAClF,CAAC;AACF,CAAC,CAAC,CAAC;AAEJ,MAAM,aAAa,GAAG,CAAC;KACrB,MAAM,CAAC;IACP,EAAE,EAAE,cAAc;IAClB,QAAQ,EAAE,cAAc;IACxB,MAAM,EAAE,cAAc;IACtB,GAAG,aAAa;CAChB,CAAC;KACD,WAAW,CAAC,CAAC,KAAK,EAAE,GAAG,EAAE,EAAE;IAC3B,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,GAAG,CAAC,QAAQ,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,qCAAqC,EAAE,CAAC,CAAC;IAClF,CAAC;AACF,CAAC,CAAC,CAAC;AAEJ,MAAM,cAAc,GAAG,CAAC;KACtB,MAAM,CAAC;IACP,IAAI,EAAE,cAAc;IACpB,GAAG,aAAa;CAChB,CAAC;KACD,WAAW,CAAC,CAAC,KAAK,EAAE,GAAG,EAAE,EAAE;IAC3B,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,GAAG,CAAC,QAAQ,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,qCAAqC,EAAE,CAAC,CAAC;IAClF,CAAC;AACF,CAAC,CAAC,CAAC;AAEJ,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC3C,GAAG,EAAE,CAAC;SACJ,MAAM,CAAC;QACP,IAAI,EAAE,cAAc;KACpB,CAAC;SACD,QAAQ,EAAE;IACZ,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC,QAAQ,EAAE;IAC3C,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,QAAQ,EAAE;IACrC,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC,QAAQ,EAAE;IAC3C,SAAS,EAAE,CAAC,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC,QAAQ,EAAE;CAC7C,CAAC,CAAC;AAEH,SAAS,UAAU,CAAC,IAAmB;IACtC,IAAI,GAAG,GAAG,EAAE,CAAC;IAEb,KAAK,MAAM,OAAO,IAAI,IAAI,EAAE,CAAC;QAC5B,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;YACjC,GAAG,IAAI,IAAI,OAAO,GAAG,CAAC;QACvB,CAAC;aAAM,CAAC;YACP,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QACtD,CAAC;IACF,CAAC;IAED,OAAO,GAAG,IAAI,QAAQ,CAAC;AACxB,CAAC;AAED,SAAS,iBAAiB,CAAC,KAAiB;IAC3C,MAAM,OAAO,GAAG,KAA4D,CAAC;IAC7E,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC;IAE5C,OAAO,CACN,KAAK,CAAC,IAAI,KAAK,cAAc;QAC7B,CAAC,OAAO,CAAC,KAAK,KAAK,SAAS;YAC3B,OAAO,CAAC,QAAQ,KAAK,WAAW;YAChC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC;YAC5B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC,CAC/B,CAAC;AACH,CAAC;AAED,SAAS,WAAW,CAAC,KAAiB;IACrC,MAAM,IAAI,GAAG,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAEpC,IAAI,KAAK,CAAC,IAAI,KAAK,QAAQ;QAAE,OAAO,GAAG,IAAI,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;IAC/D,IAAI,iBAAiB,CAAC,KAAK,CAAC;QAAE,OAAO,GAAG,IAAI,cAAc,CAAC;IAE3D,OAAO,GAAG,IAAI,KAAK,KAAK,CAAC,OAAO,EAAE,CAAC;AACpC,CAAC;AAED,mFAAmF;AACnF,MAAM,UAAU,kBAAkB,CAAC,KAAc;IAChD,MAAM,MAAM,GAAG,mBAAmB,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAEpD,IAAI,MAAM,CAAC,OAAO;QAAE,OAAO,MAAM,CAAC,IAAI,CAAC;IAEvC,MAAM,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;AAClE,CAAC"}

package/lib/types.d.ts

@@ -0,0 +1,37 @@
+import type { Context, Middleware } from "@yaebal/core";
+export interface TomlBotConfig {
+    bot?: {
+        name?: string;
+    };
+    commands?: TomlCommandRoute[];
+    hears?: TomlHearRoute[];
+    messages?: TomlMessageRoute[];
+    callbacks?: TomlCallbackRoute[];
+}
+export interface TomlRouteResponse {
+    reply?: string;
+    handler?: string;
+}
+export interface TomlCommandRoute extends TomlRouteResponse {
+    name: string;
+    description?: string;
+}
+export interface TomlHearRoute extends TomlRouteResponse {
+    text: string;
+}
+export interface TomlMessageRoute extends TomlRouteResponse {
+    on: string;
+    contains?: string;
+    equals?: string;
+}
+export interface TomlCallbackRoute extends TomlRouteResponse {
+    data: string;
+}
+export type TomlHandler<C extends Context = Context> = Middleware<C>;
+export type TomlHandlers<C extends Context = Context> = Record<string, TomlHandler<C>>;
+export interface InstallTomlOptions<C extends Context = Context> {
+    /** named handlers referenced by `handler = "name"` in toml routes. */
+    handlers?: TomlHandlers<C>;
+}
+export type TomlConfigInput = string | TomlBotConfig | Record<string, unknown>;
+//# sourceMappingURL=types.d.ts.map

package/lib/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAExD,MAAM,WAAW,aAAa;IAC7B,GAAG,CAAC,EAAE;QACL,IAAI,CAAC,EAAE,MAAM,CAAC;KACd,CAAC;IACF,QAAQ,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAC9B,KAAK,CAAC,EAAE,aAAa,EAAE,CAAC;IACxB,QAAQ,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAC9B,SAAS,CAAC,EAAE,iBAAiB,EAAE,CAAC;CAChC;AAED,MAAM,WAAW,iBAAiB;IACjC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,gBAAiB,SAAQ,iBAAiB;IAC1D,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,aAAc,SAAQ,iBAAiB;IACvD,IAAI,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,gBAAiB,SAAQ,iBAAiB;IAC1D,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,iBAAkB,SAAQ,iBAAiB;IAC3D,IAAI,EAAE,MAAM,CAAC;CACb;AAED,MAAM,MAAM,WAAW,CAAC,CAAC,SAAS,OAAO,GAAG,OAAO,IAAI,UAAU,CAAC,CAAC,CAAC,CAAC;AAErE,MAAM,MAAM,YAAY,CAAC,CAAC,SAAS,OAAO,GAAG,OAAO,IAAI,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC;AAEvF,MAAM,WAAW,kBAAkB,CAAC,CAAC,SAAS,OAAO,GAAG,OAAO;IAC9D,sEAAsE;IACtE,QAAQ,CAAC,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC;CAC3B;AAED,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC"}

package/lib/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/lib/types.js.map

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

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@yaebal/toml",
+  "version": "0.0.1",
+  "description": "yaebal toml — declarative toml routes for yaebal bots.",
+  "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": {
+    "smol-toml": "^1.7.0",
+    "zod": "^4.4.3",
+    "@yaebal/core": "0.0.5"
+  },
+  "devDependencies": {
+    "@types/node": "latest",
+    "@yaebal/test": "0.0.1"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "telegram",
+    "telegram-bot",
+    "yaebal",
+    "toml",
+    "config",
+    "routes"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/neverlane/yaebal",
+    "directory": "packages/toml"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "node --test lib/index.test.js"
+  }
+}

package/src/index.test.ts

@@ -0,0 +1,137 @@
+import assert from "node:assert/strict";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+import { Composer } from "@yaebal/core";
+import { callbackUpdate, createContext, messageUpdate, mockApi, runMiddleware } from "@yaebal/test";
+import { installToml, parseTomlConfig, validateTomlConfig } from "./index.js";
+
+test("parse raw toml string", () => {
+	const config = parseTomlConfig(`
+[[commands]]
+name = "start"
+reply = "hi"
+`);
+
+	assert.deepEqual(config.commands, [{ name: "start", reply: "hi" }]);
+});
+
+test("parse toml file path", async () => {
+	const dir = await mkdtemp(join(tmpdir(), "yaebal-toml-"));
+	const file = join(dir, "bot.toml");
+
+	try {
+		await writeFile(file, `[[hears]]\ntext = "ping"\nreply = "pong"\n`);
+
+		const config = parseTomlConfig(file);
+
+		assert.deepEqual(config.hears, [{ text: "ping", reply: "pong" }]);
+	} finally {
+		await rm(dir, { recursive: true, force: true });
+	}
+});
+
+test("validate minimal empty config", () => {
+	assert.deepEqual(validateTomlConfig({}), {});
+});
+
+test("validate command with reply", () => {
+	assert.deepEqual(validateTomlConfig({ commands: [{ name: "start", reply: "hi" }] }), {
+		commands: [{ name: "start", reply: "hi" }],
+	});
+});
+
+test("validate command with missing reply or handler should fail", () => {
+	assert.throws(
+		() => validateTomlConfig({ commands: [{ name: "start" }] }),
+		/commands\[0\] must define either reply or handler/,
+	);
+});
+
+test("validate message with missing on should fail", () => {
+	assert.throws(
+		() => validateTomlConfig({ messages: [{ reply: "hi" }] }),
+		/messages\[0\]\.on is required/,
+	);
+});
+
+test("install registers command reply", async () => {
+	const composer = new Composer();
+	const { api, calls } = mockApi();
+
+	installToml(composer, { commands: [{ name: "start", reply: "hi" }] });
+	await runMiddleware(composer, createContext(messageUpdate({ text: "/start" }), api));
+
+	assert.deepEqual(calls, [
+		{
+			method: "sendMessage",
+			params: { chat_id: 1, text: "hi", reply_parameters: { message_id: 1 } },
+		},
+	]);
+});
+
+test("install throws on missing named handler", () => {
+	assert.throws(
+		() => installToml(new Composer(), { commands: [{ name: "ping", handler: "ping" }] }),
+		/Missing handler "ping" referenced in commands\[0\]/,
+	);
+});
+
+test("messages contains filter works", async () => {
+	const composer = new Composer();
+	const { api, calls } = mockApi();
+
+	installToml(composer, {
+		messages: [{ on: "message:text", contains: "yaebal", reply: "match" }],
+	});
+
+	await runMiddleware(composer, createContext(messageUpdate({ text: "hello" }), api));
+	await runMiddleware(composer, createContext(messageUpdate({ text: "hello yaebal" }), api));
+
+	assert.equal(calls.length, 1);
+	assert.equal(calls[0]?.params?.text, "match");
+});
+
+test("messages equals filter works", async () => {
+	const composer = new Composer();
+	const { api, calls } = mockApi();
+
+	installToml(composer, {
+		messages: [{ on: "message:text", equals: "secret", reply: "match" }],
+	});
+
+	await runMiddleware(composer, createContext(messageUpdate({ text: "secret!" }), api));
+	await runMiddleware(composer, createContext(messageUpdate({ text: "secret" }), api));
+
+	assert.equal(calls.length, 1);
+	assert.equal(calls[0]?.params?.text, "match");
+});
+
+test("callbacks with handler works", async () => {
+	const composer = new Composer();
+	const { api, calls } = mockApi();
+
+	installToml(
+		composer,
+		{
+			callbacks: [{ data: "profile", handler: "profileCallback" }],
+		},
+		{
+			handlers: {
+				profileCallback: async (ctx) => {
+					await ctx.reply("profile");
+				},
+			},
+		},
+	);
+
+	await runMiddleware(composer, createContext(callbackUpdate({ data: "profile" }), api));
+
+	assert.deepEqual(calls, [
+		{
+			method: "sendMessage",
+			params: { chat_id: 1, text: "profile" },
+		},
+	]);
+});

package/src/index.ts

@@ -0,0 +1,4 @@
+export { createTomlPlugin, installToml } from "./install.js";
+export { parseTomlConfig } from "./parse.js";
+export { tomlBotConfigSchema, validateTomlConfig } from "./schema.js";
+export type { InstallTomlOptions, TomlBotConfig, TomlHandler, TomlHandlers } from "./types.js";

package/src/install.ts

@@ -0,0 +1,146 @@
+import type {
+	CallbackQuery,
+	Composer,
+	Context,
+	FilterQuery,
+	Middleware,
+	Plugin,
+} from "@yaebal/core";
+import { parseTomlConfig } from "./parse.js";
+import type {
+	InstallTomlOptions,
+	TomlBotConfig,
+	TomlConfigInput,
+	TomlRouteResponse,
+} from "./types.js";
+
+type EmptyPluginOutput = Record<never, never>;
+
+function replyHandler<C extends Context>(text: string): Middleware<C> {
+	return async (ctx) => {
+		await ctx.reply(text);
+	};
+}
+
+function missingResponseError(kind: string, index: number): Error {
+	return new Error(`${kind}[${index}] must define either reply or handler`);
+}
+
+function resolveHandler<C extends Context>(
+	route: TomlRouteResponse,
+	kind: string,
+	index: number,
+	options: InstallTomlOptions<C>,
+): Middleware<C> {
+	if (route.handler !== undefined) {
+		const handler = options.handlers?.[route.handler];
+
+		if (!handler)
+			throw new Error(`Missing handler "${route.handler}" referenced in ${kind}[${index}]`);
+
+		return handler;
+	}
+
+	if (route.reply !== undefined) return replyHandler(route.reply);
+
+	throw missingResponseError(kind, index);
+}
+
+function assertHandlersExist<C extends Context>(
+	config: TomlBotConfig,
+	options: InstallTomlOptions<C>,
+): void {
+	for (const [index, route] of (config.commands ?? []).entries()) {
+		if (route.handler !== undefined && !options.handlers?.[route.handler]) {
+			throw new Error(`Missing handler "${route.handler}" referenced in commands[${index}]`);
+		}
+	}
+
+	for (const [index, route] of (config.hears ?? []).entries()) {
+		if (route.handler !== undefined && !options.handlers?.[route.handler]) {
+			throw new Error(`Missing handler "${route.handler}" referenced in hears[${index}]`);
+		}
+	}
+
+	for (const [index, route] of (config.messages ?? []).entries()) {
+		if (route.handler !== undefined && !options.handlers?.[route.handler]) {
+			throw new Error(`Missing handler "${route.handler}" referenced in messages[${index}]`);
+		}
+	}
+
+	for (const [index, route] of (config.callbacks ?? []).entries()) {
+		if (route.handler !== undefined && !options.handlers?.[route.handler]) {
+			throw new Error(`Missing handler "${route.handler}" referenced in callbacks[${index}]`);
+		}
+	}
+}
+
+function matchesMessageFilters(
+	ctx: Context,
+	filters: { contains?: string; equals?: string },
+): boolean {
+	if (filters.contains === undefined && filters.equals === undefined) return true;
+
+	const text = ctx.text;
+	if (text === undefined) return false;
+	if (filters.equals !== undefined && text !== filters.equals) return false;
+	if (filters.contains !== undefined && !text.includes(filters.contains)) return false;
+
+	return true;
+}
+
+/** install toml routes on an existing bot or composer and return the same instance. */
+export function installToml<C extends Context, T extends Composer<C>>(
+	target: T,
+	configPathOrObject: TomlConfigInput,
+	options: InstallTomlOptions<C> = {},
+): T {
+	const config = parseTomlConfig(configPathOrObject);
+
+	assertHandlersExist(config, options);
+
+	for (const [index, route] of (config.commands ?? []).entries()) {
+		const handler = resolveHandler(route, "commands", index, options) as Middleware<
+			C & { command: string; args: string[] }
+		>;
+
+		target.command(route.name, handler);
+	}
+
+	for (const [index, route] of (config.hears ?? []).entries()) {
+		const handler = resolveHandler(route, "hears", index, options) as Middleware<
+			C & { match: string | RegExpMatchArray }
+		>;
+
+		target.hears(route.text, handler);
+	}
+
+	for (const [index, route] of (config.messages ?? []).entries()) {
+		const handler = resolveHandler(route, "messages", index, options);
+
+		target.on(route.on as FilterQuery, async (ctx, next) => {
+			if (!matchesMessageFilters(ctx, route)) return next();
+
+			return handler(ctx as C, next);
+		});
+	}
+
+	for (const [index, route] of (config.callbacks ?? []).entries()) {
+		const handler = resolveHandler(route, "callbacks", index, options) as Middleware<
+			C & { match: string | RegExpMatchArray; callbackQuery: CallbackQuery }
+		>;
+
+		target.callbackQuery(route.data, handler);
+	}
+
+	return target;
+}
+
+/** create a yaebal plugin that installs toml routes when mounted. */
+export function createTomlPlugin<C extends Context = Context>(
+	configPathOrObject: TomlConfigInput,
+	options: InstallTomlOptions<C> = {},
+): Plugin<C, EmptyPluginOutput> {
+	return <D extends C>(composer: Composer<D>) =>
+		installToml(composer, configPathOrObject, options as InstallTomlOptions<D>);
+}

package/src/parse.ts

@@ -0,0 +1,44 @@
+import { existsSync, readFileSync } from "node:fs";
+import { parse } from "smol-toml";
+import { validateTomlConfig } from "./schema.js";
+import type { TomlBotConfig, TomlConfigInput } from "./types.js";
+
+function errorMessage(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}
+
+function isPathLike(input: string): boolean {
+	const trimmed = input.trim();
+
+	if (trimmed === "") return false;
+	if (trimmed.includes("\n") || trimmed.includes("=") || trimmed.startsWith("[")) return false;
+	if (existsSync(input)) return true;
+
+	return trimmed.endsWith(".toml") || trimmed.endsWith(".tml");
+}
+
+function loadTomlSource(input: string): string {
+	if (!isPathLike(input)) return input;
+
+	try {
+		return readFileSync(input, "utf8");
+	} catch (error) {
+		throw new Error(`failed to read toml config file "${input}": ${errorMessage(error)}`);
+	}
+}
+
+/** parse a toml config from a file path, raw toml string, or parsed object. */
+export function parseTomlConfig(input: TomlConfigInput): TomlBotConfig {
+	if (typeof input !== "string") return validateTomlConfig(input);
+
+	const source = loadTomlSource(input);
+	let parsed: unknown;
+
+	try {
+		parsed = parse(source);
+	} catch (error) {
+		throw new Error(`failed to parse toml config: ${errorMessage(error)}`);
+	}
+
+	return validateTomlConfig(parsed);
+}

package/src/schema.ts

@@ -0,0 +1,118 @@
+import { z } from "zod";
+import type { TomlBotConfig } from "./types.js";
+
+const requiredString = z.string().min(1);
+const optionalString = z.string().optional();
+
+const responseShape = {
+	reply: optionalString,
+	handler: requiredString.optional(),
+};
+
+function hasResponse(route: { reply?: string; handler?: string }): boolean {
+	return route.reply !== undefined || route.handler !== undefined;
+}
+
+const commandSchema = z
+	.object({
+		name: requiredString,
+		description: optionalString,
+		...responseShape,
+	})
+	.superRefine((route, ctx) => {
+		if (!hasResponse(route)) {
+			ctx.addIssue({ code: "custom", message: "must define either reply or handler" });
+		}
+	});
+
+const hearSchema = z
+	.object({
+		text: requiredString,
+		...responseShape,
+	})
+	.superRefine((route, ctx) => {
+		if (!hasResponse(route)) {
+			ctx.addIssue({ code: "custom", message: "must define either reply or handler" });
+		}
+	});
+
+const messageSchema = z
+	.object({
+		on: requiredString,
+		contains: optionalString,
+		equals: optionalString,
+		...responseShape,
+	})
+	.superRefine((route, ctx) => {
+		if (!hasResponse(route)) {
+			ctx.addIssue({ code: "custom", message: "must define either reply or handler" });
+		}
+	});
+
+const callbackSchema = z
+	.object({
+		data: requiredString,
+		...responseShape,
+	})
+	.superRefine((route, ctx) => {
+		if (!hasResponse(route)) {
+			ctx.addIssue({ code: "custom", message: "must define either reply or handler" });
+		}
+	});
+
+export const tomlBotConfigSchema = z.object({
+	bot: z
+		.object({
+			name: optionalString,
+		})
+		.optional(),
+	commands: z.array(commandSchema).optional(),
+	hears: z.array(hearSchema).optional(),
+	messages: z.array(messageSchema).optional(),
+	callbacks: z.array(callbackSchema).optional(),
+});
+
+function formatPath(path: PropertyKey[]): string {
+	let out = "";
+
+	for (const segment of path) {
+		if (typeof segment === "number") {
+			out += `[${segment}]`;
+		} else {
+			out += out ? `.${String(segment)}` : String(segment);
+		}
+	}
+
+	return out || "config";
+}
+
+function isMissingRequired(issue: z.ZodIssue): boolean {
+	const details = issue as z.ZodIssue & { input?: unknown; received?: string };
+	const message = issue.message.toLowerCase();
+
+	return (
+		issue.code === "invalid_type" &&
+		(details.input === undefined ||
+			details.received === "undefined" ||
+			message.includes("required") ||
+			message.includes("undefined"))
+	);
+}
+
+function formatIssue(issue: z.ZodIssue): string {
+	const path = formatPath(issue.path);
+
+	if (issue.code === "custom") return `${path} ${issue.message}`;
+	if (isMissingRequired(issue)) return `${path} is required`;
+
+	return `${path}: ${issue.message}`;
+}
+
+/** validate an already parsed toml bot config and return the normalized object. */
+export function validateTomlConfig(input: unknown): TomlBotConfig {
+	const result = tomlBotConfigSchema.safeParse(input);
+
+	if (result.success) return result.data;
+
+	throw new Error(result.error.issues.map(formatIssue).join("; "));
+}

package/src/types.ts

@@ -0,0 +1,46 @@
+import type { Context, Middleware } from "@yaebal/core";
+
+export interface TomlBotConfig {
+	bot?: {
+		name?: string;
+	};
+	commands?: TomlCommandRoute[];
+	hears?: TomlHearRoute[];
+	messages?: TomlMessageRoute[];
+	callbacks?: TomlCallbackRoute[];
+}
+
+export interface TomlRouteResponse {
+	reply?: string;
+	handler?: string;
+}
+
+export interface TomlCommandRoute extends TomlRouteResponse {
+	name: string;
+	description?: string;
+}
+
+export interface TomlHearRoute extends TomlRouteResponse {
+	text: string;
+}
+
+export interface TomlMessageRoute extends TomlRouteResponse {
+	on: string;
+	contains?: string;
+	equals?: string;
+}
+
+export interface TomlCallbackRoute extends TomlRouteResponse {
+	data: string;
+}
+
+export type TomlHandler<C extends Context = Context> = Middleware<C>;
+
+export type TomlHandlers<C extends Context = Context> = Record<string, TomlHandler<C>>;
+
+export interface InstallTomlOptions<C extends Context = Context> {
+	/** named handlers referenced by `handler = "name"` in toml routes. */
+	handlers?: TomlHandlers<C>;
+}
+
+export type TomlConfigInput = string | TomlBotConfig | Record<string, unknown>;