@yaebal/core 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,39 @@
+# @yaebal/core (the framework)
+
+the yaebal core is a type-safe, chainable telegram bot api framework. `Bot extends
+Composer` — a koa-style middleware engine where the context type *accumulates* through
+the chain, so `derive` / `decorate` / `install` each return a bot with an enriched
+context and handlers see plugin-added properties with no casting.
+
+## installing
+
+```sh
+pnpm add @yaebal/core
+```
+
+## quick start
+
+```ts
+import { Bot, bold, format } from "@yaebal/core";
+
+const bot = new Bot(process.env.BOT_TOKEN)
+  .command("start", (ctx) => ctx.send("hi 🐴"))
+  .on("message:text", (ctx) => ctx.reply(format`you said: ${bold(ctx.text)}`));
+
+await bot.start(); // long polling — or bot.handleUpdate(update) behind a webhook
+```
+
+## what's inside
+
+- chainable `Composer` — `use` / `on` / `command` / `hears` / `callbackQuery` / `guard` / `derive` / `decorate` / `install`, all type-accumulating.
+- filter queries — `on("message:text")`, `on("callback_query:data")`, narrowing the context type.
+- typed plugins — `install(plugin)` checks a plugin's required context at compile time.
+- `api` — typed methods plus a `call(method, params)` passthrough, with `before` / `after` / `onError` hooks.
+- media — `media.path` / `url` / `buffer` / `fileId` and `ctx.sendPhoto` / `ctx.sendDocument`.
+- both transports — long polling (`start`) and webhooks (`handleUpdate`).
+
+## developing (in this monorepo)
+
+- to type-check, run `pnpm typecheck`.
+- to build to `lib/`, run `pnpm build`.
+- to run the tests, run `pnpm test`.

package/lib/api.d.ts

@@ -0,0 +1,66 @@
+import type { Message, Update, User } from "./telegram-types.js";
+/**
+ * resolve a local `media.path()` into bytes. runtime-specific (node:fs, Bun.file,
+ * Deno.readFile), so it's injected rather than imported — that keeps `@yaebal/core`
+ * free of any `node:` import and loadable on edge/web. the `yaebal` package wires an
+ * auto-detecting default; absent ⇒ `media.path()` throws (e.g. on Cloudflare Workers).
+ */
+export type FileReader = (path: string) => Promise<Uint8Array>;
+/** thrown when telegram replies with `ok: false`. */
+export declare class TelegramError extends Error {
+    readonly method: string;
+    readonly code: number;
+    constructor(method: string, code: number, description: string);
+}
+/** inspect/rewrite params before a request. return new params to replace them. */
+export type BeforeHook = (method: string, params: Record<string, unknown> | undefined) => Record<string, unknown> | undefined | Promise<Record<string, unknown> | undefined>;
+/** inspect/rewrite the result after a successful request. return a value to replace it. */
+export type AfterHook = (method: string, result: unknown) => unknown | Promise<unknown>;
+/** what an error hook can ask the client to do. */
+export interface ErrorAction {
+    /** re-run the same call. */
+    retry?: boolean;
+    /** wait this many ms before retrying. */
+    delayMs?: number;
+}
+/** runs when a request throws. `attempt` is the (1-based) attempt that just failed. */
+export type ErrorHook = (method: string, error: unknown, attempt: number) => ErrorAction | undefined | Promise<ErrorAction | undefined>;
+/**
+ * the API client. known methods are typed; everything else goes through `call`
+ * (the puregram passthrough — a new Bot API method works before its types ship).
+ * `before` / `after` / `onError` are the extension points plugins hang off of.
+ */
+export interface Api {
+    call<T = unknown>(method: string, params?: Record<string, unknown>): Promise<T>;
+    getMe(): Promise<User>;
+    getUpdates(params?: Record<string, unknown>): Promise<Update[]>;
+    sendMessage(params: Record<string, unknown>): Promise<Message>;
+    answerCallbackQuery(params: Record<string, unknown>): Promise<boolean>;
+    /** build the download URL for a `file_path` from `getFile`. contains the bot token — don't log it. */
+    fileUrl(filePath: string): string;
+    /** register a hook that runs before every request; may rewrite params. */
+    before(hook: BeforeHook): Api;
+    /** register a hook that runs after every successful request; may rewrite the result. */
+    after(hook: AfterHook): Api;
+    /** register a hook that runs when a request throws; may request a retry. */
+    onError(hook: ErrorHook): Api;
+}
+export interface ApiOptions {
+    apiRoot?: string;
+    /** resolve `media.path()` to bytes. injected per runtime; absent ⇒ path media throws (e.g. edge). */
+    readFile?: FileReader;
+}
+interface EncodedRequest {
+    body: string | FormData | undefined;
+    contentType?: string;
+}
+/**
+ * encode request params. Plain params (and `url`/`fileId` media) go as JSON;
+ * if any `path`/`buffer` media is present the whole request becomes multipart,
+ * with each upload attached via `attach://`. exported for testing.
+ */
+export declare function encodeRequest(params: Record<string, unknown> | undefined, readFile?: FileReader): Promise<EncodedRequest>;
+/** builds a callable API client with before/after/error hooks. */
+export declare function createApi(token: string, options?: ApiOptions): Api;
+export {};
+//# sourceMappingURL=api.d.ts.map

package/lib/api.d.ts.map

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

package/lib/api.js

@@ -0,0 +1,176 @@
+import { isMediaSource } from "./media.js";
+/** thrown when telegram replies with `ok: false`. */
+export class TelegramError extends Error {
+    method;
+    code;
+    constructor(method, code, description) {
+        super(`[${method}] ${code}: ${description}`);
+        this.name = "TelegramError";
+        this.method = method;
+        this.code = code;
+    }
+}
+function containsMedia(v) {
+    if (isMediaSource(v))
+        return true;
+    if (Array.isArray(v))
+        return v.some(containsMedia);
+    if (v !== null && typeof v === "object")
+        return Object.values(v).some(containsMedia);
+    return false;
+}
+/** basename without node:path — keeps core free of node: imports. */
+const baseName = (p) => p.split(/[\\/]/).pop() || "file";
+const toArrayBuffer = (bytes) => {
+    const copy = new Uint8Array(bytes.byteLength);
+    copy.set(bytes);
+    return copy.buffer;
+};
+async function mediaToBlob(m, readFile) {
+    if (m.kind === "path") {
+        if (!readFile)
+            throw new Error("media.path() needs a filesystem — use the `yaebal` package (auto-detects node/bun/deno), " +
+                "pass `readFile` to the Bot, or send media.buffer()/url() instead (e.g. on edge).");
+        const bytes = await readFile(m.path);
+        return { blob: new Blob([toArrayBuffer(bytes)]), filename: baseName(m.path) };
+    }
+    if (m.kind === "buffer") {
+        return { blob: new Blob([toArrayBuffer(m.buffer)]), filename: m.filename ?? "file" };
+    }
+    throw new Error(`mediaToBlob: ${m.kind} is not an uploadable source`);
+}
+/**
+ * encode request params. Plain params (and `url`/`fileId` media) go as JSON;
+ * if any `path`/`buffer` media is present the whole request becomes multipart,
+ * with each upload attached via `attach://`. exported for testing.
+ */
+export async function encodeRequest(params, readFile) {
+    if (!params)
+        return { body: undefined, contentType: "application/json" };
+    // ponytail: media is only handled at the top level. media nested inside arrays
+    // or objects (e.g. sendMediaGroup's `media[]`) would serialize to garbage, so
+    // fail loud until that method is actually supported.
+    if (Object.values(params).some((v) => !isMediaSource(v) && containsMedia(v))) {
+        throw new Error("encodeRequest: nested MediaSource (e.g. inside sendMediaGroup) is not supported yet — pass media as a top-level param");
+    }
+    const needsUpload = Object.values(params).some((v) => isMediaSource(v) && (v.kind === "path" || v.kind === "buffer"));
+    if (!needsUpload) {
+        const inlined = {};
+        for (const [k, v] of Object.entries(params)) {
+            inlined[k] = isMediaSource(v)
+                ? v.kind === "url"
+                    ? v.url
+                    : v.fileId
+                : v;
+        }
+        return { body: JSON.stringify(inlined), contentType: "application/json" };
+    }
+    const form = new FormData();
+    let n = 0;
+    for (const [k, v] of Object.entries(params)) {
+        if (v === undefined || v === null)
+            continue;
+        if (isMediaSource(v)) {
+            if (v.kind === "fileId")
+                form.set(k, v.fileId);
+            else if (v.kind === "url")
+                form.set(k, v.url);
+            else {
+                const field = `_file${n++}`;
+                const { blob, filename } = await mediaToBlob(v, readFile);
+                form.set(field, blob, filename);
+                form.set(k, `attach://${field}`);
+            }
+        }
+        else if (typeof v === "string") {
+            form.set(k, v);
+        }
+        else {
+            form.set(k, JSON.stringify(v));
+        }
+    }
+    return { body: form };
+}
+/** builds a callable API client with before/after/error hooks. */
+export function createApi(token, options = {}) {
+    const apiRoot = options.apiRoot ?? "https://api.telegram.org";
+    const beforeHooks = [];
+    const afterHooks = [];
+    const errorHooks = [];
+    const rawCall = async (method, params) => {
+        const { body, contentType } = await encodeRequest(params, options.readFile);
+        const res = await fetch(`${apiRoot}/bot${token}/${method}`, {
+            method: "POST",
+            // for multipart, let fetch set the content-type (with its boundary).
+            headers: contentType ? { "content-type": contentType } : undefined,
+            body,
+        });
+        const data = (await res.json());
+        if (!data.ok)
+            throw new TelegramError(method, data.error_code, data.description);
+        return data.result;
+    };
+    const call = async (method, params) => {
+        let p = params;
+        for (const hook of beforeHooks) {
+            const next = await hook(method, p);
+            if (next !== undefined)
+                p = next;
+        }
+        // ponytail: retry loop is bounded by the error hooks themselves (e.g. again caps
+        // attempts). with no hook requesting a retry it throws on the first failure.
+        for (let attempt = 1;; attempt++) {
+            try {
+                let result = await rawCall(method, p);
+                for (const hook of afterHooks) {
+                    const next = await hook(method, result);
+                    if (next !== undefined)
+                        result = next;
+                }
+                return result;
+            }
+            catch (error) {
+                let retry;
+                for (const hook of errorHooks) {
+                    const action = await hook(method, error, attempt);
+                    if (action?.retry) {
+                        retry = action;
+                        break;
+                    }
+                }
+                if (!retry)
+                    throw error;
+                if (retry.delayMs)
+                    await new Promise((r) => setTimeout(r, retry.delayMs));
+            }
+        }
+    };
+    const registrar = {
+        call,
+        fileUrl: (filePath) => `${apiRoot}/file/bot${token}/${filePath}`,
+        before(hook) {
+            beforeHooks.push(hook);
+            return api;
+        },
+        after(hook) {
+            afterHooks.push(hook);
+            return api;
+        },
+        onError(hook) {
+            errorHooks.push(hook);
+            return api;
+        },
+    };
+    const api = new Proxy(registrar, {
+        get(obj, prop) {
+            if (prop in obj)
+                return obj[prop];
+            // lazily materialise `api.<method>(params)` → call(method, params).
+            const method = (params) => call(prop, params);
+            obj[prop] = method;
+            return method;
+        },
+    });
+    return api;
+}
+//# sourceMappingURL=api.js.map

package/lib/api.js.map

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

package/lib/bot.d.ts

@@ -0,0 +1,58 @@
+import { type Api, type FileReader } from "./api.js";
+import { Composer } from "./composer.js";
+import { Context } from "./context.js";
+import type { Update, UpdateName, User } from "./telegram-types.js";
+export interface BotOptions {
+    apiRoot?: string;
+    /**
+     * resolve `media.path()` into bytes. injected per runtime so core stays free of any
+     * `node:` import. the `yaebal` package wires an auto-detecting default; on bare core
+     * (or edge) leave it unset and `media.path()` throws — send `media.buffer()`/`url()`.
+     */
+    readFile?: FileReader;
+    /** update types to request; `undefined` = telegram default. */
+    allowedUpdates?: UpdateName[];
+    /**
+     * build the context for each update. defaults to the base {@link Context}.
+     * gigher-level packages (e.g. the `yaebal` meta-package) inject a factory here
+     * to produce richer per-update contexts with auto-generated shortcut methods.
+     */
+    contextFactory?: (api: Api, update: Update, updateType: UpdateName) => Context;
+}
+type StartHandler = (info: User) => unknown | Promise<unknown>;
+type ErrorHandler = (error: unknown, ctx: Context) => unknown | Promise<unknown>;
+/**
+ * the bot. extends {@link Composer}, so the whole chainable, type-accumulating
+ * surface is available — and `derive` / `decorate` / `extend` keep returning a
+ * `Bot` (not a bare `Composer`) so lifecycle methods stay reachable down the chain.
+ */
+export declare class Bot<C extends Context = Context> extends Composer<C> {
+    #private;
+    readonly api: Api;
+    constructor(token: string, options?: BotOptions);
+    /** bot account info, available after `start()`. */
+    get info(): User | undefined;
+    derive<D extends object>(fn: (ctx: C) => D | Promise<D>): Bot<C & D>;
+    derive<D extends object>(updates: UpdateName | UpdateName[], fn: (ctx: C) => D | Promise<D>): Bot<C & Partial<D>>;
+    decorate<D extends object>(value: D): Bot<C & D>;
+    extend<C2 extends Context>(other: Composer<C2>): Bot<C & C2>;
+    install<Add extends object>(plugin: (composer: Composer<C>) => Composer<C & Add>): Bot<C & Add>;
+    /** register a callback fired once the bot has started. */
+    onStart(handler: StartHandler): this;
+    /** replace the default error handler. */
+    onError(handler: ErrorHandler): this;
+    /**
+     * run the middleware chain for a single update. this is the webhook entry
+     * point — call it from your HTTP handler. errors go to the error handler.
+     *
+     * the chain is realized (and frozen) on the first call, so register all
+     * middleware/plugins before the first `handleUpdate` / `start`.
+     */
+    handleUpdate(update: Update): Promise<void>;
+    /** start long polling. resolves only when `stop()` is called. */
+    start(): Promise<void>;
+    /** stop the polling loop. */
+    stop(): void;
+}
+export {};
+//# sourceMappingURL=bot.d.ts.map

package/lib/bot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bot.d.ts","sourceRoot":"","sources":["../src/bot.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,GAAG,EAAE,KAAK,UAAU,EAAa,MAAM,UAAU,CAAC;AAChE,OAAO,EAAE,QAAQ,EAAmB,MAAM,eAAe,CAAC;AAC1D,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,qBAAqB,CAAC;AAEpE,MAAM,WAAW,UAAU;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,UAAU,CAAC;IACtB,+DAA+D;IAC/D,cAAc,CAAC,EAAE,UAAU,EAAE,CAAC;IAC9B;;;;OAIG;IACH,cAAc,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,KAAK,OAAO,CAAC;CAC/E;AAED,KAAK,YAAY,GAAG,CAAC,IAAI,EAAE,IAAI,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AAC/D,KAAK,YAAY,GAAG,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AAWjF;;;;GAIG;AACH,qBAAa,GAAG,CAAC,CAAC,SAAS,OAAO,GAAG,OAAO,CAAE,SAAQ,QAAQ,CAAC,CAAC,CAAC;;IAChE,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC;gBAWN,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,UAAe;IAQnD,mDAAmD;IACnD,IAAI,IAAI,IAAI,IAAI,GAAG,SAAS,CAE3B;IAEQ,MAAM,CAAC,CAAC,SAAS,MAAM,EAAE,EAAE,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC;IACpE,MAAM,CAAC,CAAC,SAAS,MAAM,EAC/B,OAAO,EAAE,UAAU,GAAG,UAAU,EAAE,EAClC,EAAE,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAC5B,GAAG,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAQb,QAAQ,CAAC,CAAC,SAAS,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC;IAKhD,MAAM,CAAC,EAAE,SAAS,OAAO,EAAE,KAAK,EAAE,QAAQ,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC;IAK5D,OAAO,CAAC,GAAG,SAAS,MAAM,EAClC,MAAM,EAAE,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,KAAK,QAAQ,CAAC,CAAC,GAAG,GAAG,CAAC,GAClD,GAAG,CAAC,CAAC,GAAG,GAAG,CAAC;IAKf,0DAA0D;IAC1D,OAAO,CAAC,OAAO,EAAE,YAAY,GAAG,IAAI;IAKpC,yCAAyC;IACzC,OAAO,CAAC,OAAO,EAAE,YAAY,GAAG,IAAI;IAKpC;;;;;;OAMG;IACG,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAejD,iEAAiE;IAC3D,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAkC5B,6BAA6B;IAC7B,IAAI,IAAI,IAAI;CAGZ"}

package/lib/bot.js

@@ -0,0 +1,125 @@
+import { createApi } from "./api.js";
+import { Composer } from "./composer.js";
+import { Context } from "./context.js";
+function detectUpdateType(update) {
+    for (const key of Object.keys(update)) {
+        if (key === "update_id")
+            continue;
+        return key;
+    }
+    return "message";
+}
+/**
+ * the bot. extends {@link Composer}, so the whole chainable, type-accumulating
+ * surface is available — and `derive` / `decorate` / `extend` keep returning a
+ * `Bot` (not a bare `Composer`) so lifecycle methods stay reachable down the chain.
+ */
+export class Bot extends Composer {
+    api;
+    #running = false;
+    #offset = 0;
+    #info;
+    #options;
+    #startHandlers = [];
+    #errorHandler = (error) => {
+        console.error("[yaebal] unhandled error in middleware:", error);
+    };
+    #handle;
+    constructor(token, options = {}) {
+        super();
+        if (!token)
+            throw new Error("Bot(token): token is required");
+        this.#options = options;
+        this.api = createApi(token, { apiRoot: options.apiRoot, readFile: options.readFile });
+    }
+    /** bot account info, available after `start()`. */
+    get info() {
+        return this.#info;
+    }
+    // biome-ignore lint/suspicious/noExplicitAny: overload implementation
+    derive(a, b) {
+        // biome-ignore lint/suspicious/noExplicitAny: forwarding to the overloaded base
+        super.derive(a, b);
+        return this;
+    }
+    decorate(value) {
+        super.decorate(value);
+        return this;
+    }
+    extend(other) {
+        super.extend(other);
+        return this;
+    }
+    install(plugin) {
+        plugin(this);
+        return this;
+    }
+    /** register a callback fired once the bot has started. */
+    onStart(handler) {
+        this.#startHandlers.push(handler);
+        return this;
+    }
+    /** replace the default error handler. */
+    onError(handler) {
+        this.#errorHandler = handler;
+        return this;
+    }
+    /**
+     * run the middleware chain for a single update. this is the webhook entry
+     * point — call it from your HTTP handler. errors go to the error handler.
+     *
+     * the chain is realized (and frozen) on the first call, so register all
+     * middleware/plugins before the first `handleUpdate` / `start`.
+     */
+    async handleUpdate(update) {
+        if (!this.#handle)
+            this.#handle = this.toMiddleware();
+        const updateType = detectUpdateType(update);
+        const ctx = this.#options.contextFactory
+            ? this.#options.contextFactory(this.api, update, updateType)
+            : new Context({ api: this.api, update, updateType });
+        try {
+            await this.#handle(ctx, async () => { });
+        }
+        catch (error) {
+            await this.#errorHandler(error, ctx);
+        }
+    }
+    /** start long polling. resolves only when `stop()` is called. */
+    async start() {
+        if (this.#running)
+            return;
+        this.#running = true;
+        this.#info = await this.api.getMe();
+        for (const handler of this.#startHandlers)
+            await handler(this.#info);
+        while (this.#running) {
+            let updates;
+            try {
+                updates = await this.api.getUpdates({
+                    offset: this.#offset,
+                    timeout: 30,
+                    ...(this.#options.allowedUpdates
+                        ? { allowed_updates: this.#options.allowedUpdates }
+                        : {}),
+                });
+            }
+            catch (error) {
+                if (!this.#running)
+                    break;
+                console.error("[yaebal] getUpdates failed, retrying in 3s:", error);
+                await new Promise((r) => setTimeout(r, 3000));
+                continue;
+            }
+            for (const update of updates) {
+                this.#offset = update.update_id + 1;
+                await this.handleUpdate(update);
+            }
+        }
+    }
+    /** stop the polling loop. */
+    stop() {
+        this.#running = false;
+    }
+}
+//# sourceMappingURL=bot.js.map

package/lib/bot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bot.js","sourceRoot":"","sources":["../src/bot.ts"],"names":[],"mappings":"AAAA,OAAO,EAA6B,SAAS,EAAE,MAAM,UAAU,CAAC;AAChE,OAAO,EAAE,QAAQ,EAAmB,MAAM,eAAe,CAAC;AAC1D,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAwBvC,SAAS,gBAAgB,CAAC,MAAc;IACvC,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;QACvC,IAAI,GAAG,KAAK,WAAW;YAAE,SAAS;QAClC,OAAO,GAAiB,CAAC;IAC1B,CAAC;IAED,OAAO,SAAuB,CAAC;AAChC,CAAC;AAED;;;;GAIG;AACH,MAAM,OAAO,GAAiC,SAAQ,QAAW;IACvD,GAAG,CAAM;IAClB,QAAQ,GAAG,KAAK,CAAC;IACjB,OAAO,GAAG,CAAC,CAAC;IACZ,KAAK,CAAQ;IACJ,QAAQ,CAAa;IACrB,cAAc,GAAmB,EAAE,CAAC;IAC7C,aAAa,GAAiB,CAAC,KAAK,EAAE,EAAE;QACvC,OAAO,CAAC,KAAK,CAAC,yCAAyC,EAAE,KAAK,CAAC,CAAC;IACjE,CAAC,CAAC;IACF,OAAO,CAAuB;IAE9B,YAAY,KAAa,EAAE,UAAsB,EAAE;QAClD,KAAK,EAAE,CAAC;QACR,IAAI,CAAC,KAAK;YAAE,MAAM,IAAI,KAAK,CAAC,+BAA+B,CAAC,CAAC;QAE7D,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC;QACxB,IAAI,CAAC,GAAG,GAAG,SAAS,CAAC,KAAK,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;IACvF,CAAC;IAED,mDAAmD;IACnD,IAAI,IAAI;QACP,OAAO,IAAI,CAAC,KAAK,CAAC;IACnB,CAAC;IAOD,sEAAsE;IAC7D,MAAM,CAAC,CAAM,EAAE,CAAO;QAC9B,gFAAgF;QAC/E,KAAK,CAAC,MAAc,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QAC5B,OAAO,IAAI,CAAC;IACb,CAAC;IAEQ,QAAQ,CAAmB,KAAQ;QAC3C,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;QACtB,OAAO,IAA6B,CAAC;IACtC,CAAC;IAEQ,MAAM,CAAqB,KAAmB;QACtD,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACpB,OAAO,IAA8B,CAAC;IACvC,CAAC;IAEQ,OAAO,CACf,MAAoD;QAEpD,MAAM,CAAC,IAAI,CAAC,CAAC;QACb,OAAO,IAA+B,CAAC;IACxC,CAAC;IAED,0DAA0D;IAC1D,OAAO,CAAC,OAAqB;QAC5B,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAClC,OAAO,IAAI,CAAC;IACb,CAAC;IAED,yCAAyC;IACzC,OAAO,CAAC,OAAqB;QAC5B,IAAI,CAAC,aAAa,GAAG,OAAO,CAAC;QAC7B,OAAO,IAAI,CAAC;IACb,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,YAAY,CAAC,MAAc;QAChC,IAAI,CAAC,IAAI,CAAC,OAAO;YAAE,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,YAAY,EAAoC,CAAC;QAExF,MAAM,UAAU,GAAG,gBAAgB,CAAC,MAAM,CAAC,CAAC;QAC5C,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC,cAAc;YACvC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,cAAc,CAAC,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,CAAC;YAC5D,CAAC,CAAC,IAAI,OAAO,CAAC,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC,CAAC;QAEtD,IAAI,CAAC;YACJ,MAAM,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,KAAK,IAAI,EAAE,GAAE,CAAC,CAAC,CAAC;QACzC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YAChB,MAAM,IAAI,CAAC,aAAa,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;QACtC,CAAC;IACF,CAAC;IAED,iEAAiE;IACjE,KAAK,CAAC,KAAK;QACV,IAAI,IAAI,CAAC,QAAQ;YAAE,OAAO;QAC1B,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC;QAErB,IAAI,CAAC,KAAK,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC;QACpC,KAAK,MAAM,OAAO,IAAI,IAAI,CAAC,cAAc;YAAE,MAAM,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAErE,OAAO,IAAI,CAAC,QAAQ,EAAE,CAAC;YACtB,IAAI,OAAiB,CAAC;YAEtB,IAAI,CAAC;gBACJ,OAAO,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC;oBACnC,MAAM,EAAE,IAAI,CAAC,OAAO;oBACpB,OAAO,EAAE,EAAE;oBACX,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,cAAc;wBAC/B,CAAC,CAAC,EAAE,eAAe,EAAE,IAAI,CAAC,QAAQ,CAAC,cAAc,EAAE;wBACnD,CAAC,CAAC,EAAE,CAAC;iBACN,CAAC,CAAC;YACJ,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBAChB,IAAI,CAAC,IAAI,CAAC,QAAQ;oBAAE,MAAM;gBAE1B,OAAO,CAAC,KAAK,CAAC,6CAA6C,EAAE,KAAK,CAAC,CAAC;gBAEpE,MAAM,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC;gBAC9C,SAAS;YACV,CAAC;YAED,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;gBAC9B,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC,SAAS,GAAG,CAAC,CAAC;gBACpC,MAAM,IAAI,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC;YACjC,CAAC;QACF,CAAC;IACF,CAAC;IAED,6BAA6B;IAC7B,IAAI;QACH,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAC;IACvB,CAAC;CACD"}

package/lib/composer.d.ts

@@ -0,0 +1,97 @@
+import type { Context } from "./context.js";
+import type { CallbackQuery, MessageEntity, UpdateName } from "./telegram-types.js";
+export type NextFn = () => Promise<void>;
+export type Middleware<C> = (ctx: C, next: NextFn) => unknown | Promise<unknown>;
+/**
+ * a plugin enriches the context. dependencies are expressed by the type it
+ * requires (`In`), so installing a plugin before its dependency is a compile
+ * error — not a runtime surprise (core invariant #4).
+ *
+ * @example
+ * const session: Plugin<Context, { session: Session }>;
+ * const auth:    Plugin<Context & { session: Session }, { user: User }>;
+ * bot.install(auth);                  // ❌ no `session` on the context
+ * bot.install(session).install(auth); // ✅
+ */
+export type Plugin<In extends Context = Context, Out extends object = Record<never, never>> = <C extends In>(composer: Composer<C>) => Composer<C & Out>;
+/**
+ * a composable filter (the mtcute idea). `test` is a type guard, so a matching
+ * filter narrows the context to `C & Add`; filters may also attach `Add` fields
+ * onto the context as a side effect (e.g. `regex` exposes `ctx.match`). combine
+ * with `and` / `or` / `not` from `@yaebal/filters`.
+ */
+export interface Filter<C = Context, Add extends object = Record<never, never>> {
+    test(ctx: C): ctx is C & Add;
+}
+/**
+ * filter query mini-language (the grammY idea), e.g.
+ * `"message:text"`, `"callback_query:data"`, `":photo"`.
+ */
+export type FilterQuery = UpdateName | `${UpdateName}:${string}` | `:${string}`;
+/** narrows the context type for known queries so handlers get non-optional fields. */
+export type Filtered<C, Q extends string> = Q extends `${string}:text` | `${string}:caption` ? C & {
+    text: string;
+} : Q extends `${string}:data` | "callback_query" ? C & {
+    callbackQuery: CallbackQuery;
+} : Q extends `${string}:entities${string}` ? C & {
+    entities: MessageEntity[];
+} : C;
+/** koa-style middleware composer with single-`next()` protection. */
+export declare function compose<C>(middlewares: Middleware<C>[]): (ctx: C, next?: NextFn) => Promise<void>;
+export declare function matchQuery(ctx: Context, query: string): boolean;
+/**
+ * the chainable middleware pipeline. every context-enriching method returns a
+ * composer whose context type carries the new properties — types flow through
+ * the whole chain (the GramIO idea). `Composer` is also usable standalone, so
+ * feature files can be plain composers with no `Bot` and no token.
+ */
+export declare class Composer<C extends Context = Context> {
+    protected middlewares: Middleware<C>[];
+    /** raw middleware. call `next()` to continue the chain. */
+    use(...middleware: Middleware<C>[]): this;
+    /** handle a specific update, optionally narrowed by a filter query. */
+    on<Q extends FilterQuery>(query: Q, ...handlers: Middleware<Filtered<C, Q>>[]): this;
+    /** handle `/<name>` commands. Strips a trailing `@botname` and parses args. */
+    command(name: string, ...handlers: Middleware<C & {
+        command: string;
+        args: string[];
+    }>[]): this;
+    /** match message text/caption against a string or regex; exposes `ctx.match`. */
+    hears(trigger: string | RegExp, ...handlers: Middleware<C & {
+        match: string | RegExpMatchArray;
+    }>[]): this;
+    /** match callback-query data against a string or regex; exposes `ctx.match`. */
+    callbackQuery(trigger: string | RegExp, ...handlers: Middleware<C & {
+        match: string | RegExpMatchArray;
+        callbackQuery: CallbackQuery;
+    }>[]): this;
+    /** continue only if the predicate holds. */
+    guard(predicate: (ctx: C) => boolean | Promise<boolean>): this;
+    /**
+     * run `handlers` only when `filter` matches. the filter narrows the context
+     * (and may attach data), so handlers see `C & Add`. compose filters with
+     * `and` / `or` / `not` from `@yaebal/filters`.
+     */
+    filter<Add extends object>(filter: Filter<Context, Add>, ...handlers: Middleware<C & Add>[]): this;
+    /** apply a plugin. its required context (`In`) is checked at compile time. */
+    install<Add extends object>(plugin: (composer: Composer<C>) => Composer<C & Add>): Composer<C & Add>;
+    /** async, per-request context enrichment. adds `D` to the context type. */
+    derive<D extends object>(fn: (ctx: C) => D | Promise<D>): Composer<C & D>;
+    /**
+     * scoped enrichment (the GramIO idea): `fn` runs only for the listed update
+     * types, so irrelevant updates pay nothing. the fields are typed as optional
+     * (`Partial<D>`) since they are absent on other update types.
+     */
+    derive<D extends object>(updates: UpdateName | UpdateName[], fn: (ctx: C) => D | Promise<D>): Composer<C & Partial<D>>;
+    /**
+     * static context enrichment. adds `D` to the context type.
+     * NOTE: a production build would hoist this out of the per-request path entirely;
+     * here it is applied once at the top of the chain for simplicity.
+     */
+    decorate<D extends object>(value: D): Composer<C & D>;
+    /** merge another composer in, inheriting its full context type. */
+    extend<C2 extends Context>(other: Composer<C2>): Composer<C & C2>;
+    /** collapse this composer into a single middleware (used by `extend` and `Bot`). */
+    toMiddleware(): Middleware<C>;
+}
+//# sourceMappingURL=composer.d.ts.map

package/lib/composer.d.ts.map

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