@yaebal/test 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,40 @@
+# @yaebal/test
+
+testing utilities for yaebal bots: a fake `Api` that records every call, update factories, and helpers to run middleware in isolation.
+
+## install
+
+```sh
+pnpm add -D @yaebal/test
+```
+
+## usage
+
+```ts
+import { callbackUpdate, createContext, messageUpdate, mockApi, runMiddleware } from "@yaebal/test";
+import { expect, test } from "vitest";
+
+test("replies to /start", async () => {
+  const { api, calls } = mockApi();
+  const update = messageUpdate({ text: "/start", chatId: 42 });
+  const ctx = createContext(update, api);
+
+  await runMiddleware(bot, ctx);
+
+  expect(calls[0]?.method).toBe("sendMessage");
+});
+
+test("callback query", async () => {
+  const { api, calls } = mockApi();
+  const update = callbackUpdate({ data: "vote:up", chatId: 1 });
+  const ctx = createContext(update, api);
+
+  await runMiddleware(bot, ctx);
+
+  expect(calls[0]?.method).toBe("answerCallbackQuery");
+});
+```
+
+---
+
+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,56 @@
+/**
+ * @yaebal/test — testing utilities for yaebal bots.
+ *
+ * every plugin test used to hand-build fake updates and a mock api. this package
+ * extracts that boilerplate: {@link mockApi} records every call, the `*Update`
+ * factories produce real {@link Update} shapes, and {@link createContext} wraps
+ * one in a core {@link Context}.
+ */
+import { type Api, type Composer, Context, type Message, type Update, type UpdateName } from "@yaebal/core";
+/** a single recorded api call: the method name and the params it was given. */
+export interface RecordedCall {
+    method: string;
+    params: Record<string, unknown> | undefined;
+}
+/** result of {@link mockApi}: the fake `api` plus the array it records into. */
+export interface MockApi {
+    api: Api;
+    calls: RecordedCall[];
+}
+/**
+ * a fake {@link Api} whose every method records `{ method, params }` into `calls`
+ * and resolves to a sensible default (`{ message_id: 1 }` for `send*`, `true` for
+ * `answerCallbackQuery`, `{}` otherwise). hook registrars (`before`/`after`/
+ * `onError`) are no-ops that return the api for chaining.
+ */
+export declare function mockApi(): MockApi;
+/** build an {@link Update} from a partial, filling in a fresh `update_id`. */
+export declare function createUpdate(partial?: Partial<Update>): Update;
+/** options for {@link messageUpdate}. */
+export interface MessageUpdateOptions {
+    text?: string;
+    chatId?: number;
+    fromId?: number;
+    chatType?: "private" | "group" | "supergroup" | "channel";
+}
+/** build a message {@link Update}. */
+export declare function messageUpdate(options?: MessageUpdateOptions): Update;
+/** options for {@link callbackUpdate}. */
+export interface CallbackUpdateOptions {
+    data?: string;
+    chatId?: number;
+    fromId?: number;
+}
+/** build a callback_query {@link Update}. */
+export declare function callbackUpdate(options?: CallbackUpdateOptions): Update;
+/** infer which payload key an update carries; defaults to `"message"`. */
+export declare function detectUpdateType(update: Update): UpdateName;
+/**
+ * wrap an {@link Update} in a core {@link Context}. the api defaults to a fresh
+ * {@link mockApi}; pass `updateType` to override the auto-detected one.
+ */
+export declare function createContext(update: Update, api?: Api, updateType?: UpdateName): Context;
+/** run a composer's middleware against a context. resolves when the chain settles. */
+export declare function runMiddleware<C extends Context>(composer: Composer<C>, ctx: C): Promise<void>;
+export type { Message };
+//# 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;;;;;;;GAOG;AAEH,OAAO,EACN,KAAK,GAAG,EACR,KAAK,QAAQ,EACb,OAAO,EACP,KAAK,OAAO,EAEZ,KAAK,MAAM,EACX,KAAK,UAAU,EACf,MAAM,cAAc,CAAC;AAEtB,+EAA+E;AAC/E,MAAM,WAAW,YAAY;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;CAC5C;AAED,gFAAgF;AAChF,MAAM,WAAW,OAAO;IACvB,GAAG,EAAE,GAAG,CAAC;IACT,KAAK,EAAE,YAAY,EAAE,CAAC;CACtB;AAcD;;;;;GAKG;AACH,wBAAgB,OAAO,IAAI,OAAO,CA4BjC;AAID,8EAA8E;AAC9E,wBAAgB,YAAY,CAAC,OAAO,GAAE,OAAO,CAAC,MAAM,CAAM,GAAG,MAAM,CAElE;AAED,yCAAyC;AACzC,MAAM,WAAW,oBAAoB;IACpC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,SAAS,GAAG,OAAO,GAAG,YAAY,GAAG,SAAS,CAAC;CAC1D;AAED,sCAAsC;AACtC,wBAAgB,aAAa,CAAC,OAAO,GAAE,oBAAyB,GAAG,MAAM,CAYxE;AAED,0CAA0C;AAC1C,MAAM,WAAW,qBAAqB;IACrC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,6CAA6C;AAC7C,wBAAgB,cAAc,CAAC,OAAO,GAAE,qBAA0B,GAAG,MAAM,CAgB1E;AAED,0EAA0E;AAC1E,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,CAY3D;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,GAAG,EAAE,UAAU,CAAC,EAAE,UAAU,GAAG,OAAO,CAMzF;AAID,sFAAsF;AACtF,wBAAsB,aAAa,CAAC,CAAC,SAAS,OAAO,EACpD,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,EACrB,GAAG,EAAE,CAAC,GACJ,OAAO,CAAC,IAAI,CAAC,CAEf;AAED,YAAY,EAAE,OAAO,EAAE,CAAC"}

package/lib/index.js

@@ -0,0 +1,119 @@
+/**
+ * @yaebal/test — testing utilities for yaebal bots.
+ *
+ * every plugin test used to hand-build fake updates and a mock api. this package
+ * extracts that boilerplate: {@link mockApi} records every call, the `*Update`
+ * factories produce real {@link Update} shapes, and {@link createContext} wraps
+ * one in a core {@link Context}.
+ */
+import { Context, } from "@yaebal/core";
+/** default results for known methods; everything else resolves to `{}`. */
+function defaultResult(method) {
+    if (method.startsWith("send") || method === "copyMessage" || method === "forwardMessage") {
+        return { message_id: 1 };
+    }
+    if (method === "answerCallbackQuery")
+        return true;
+    if (method === "getMe")
+        return { id: 1, is_bot: true, first_name: "bot", username: "bot" };
+    return {};
+}
+/**
+ * a fake {@link Api} whose every method records `{ method, params }` into `calls`
+ * and resolves to a sensible default (`{ message_id: 1 }` for `send*`, `true` for
+ * `answerCallbackQuery`, `{}` otherwise). hook registrars (`before`/`after`/
+ * `onError`) are no-ops that return the api for chaining.
+ */
+export function mockApi() {
+    const calls = [];
+    const record = (method, params) => {
+        calls.push({ method, params });
+        return Promise.resolve(defaultResult(method));
+    };
+    const registrar = {
+        call: (method, params) => record(method, params),
+        fileUrl: (filePath) => `https://example.invalid/file/${filePath}`,
+        before: () => api,
+        after: () => api,
+        onError: () => api,
+    };
+    const api = new Proxy(registrar, {
+        get(obj, prop) {
+            if (prop in obj)
+                return obj[prop];
+            const method = (params) => record(prop, params);
+            obj[prop] = method;
+            return method;
+        },
+    });
+    return { api, calls };
+}
+let updateIdCounter = 0;
+/** build an {@link Update} from a partial, filling in a fresh `update_id`. */
+export function createUpdate(partial = {}) {
+    return { update_id: ++updateIdCounter, ...partial };
+}
+/** build a message {@link Update}. */
+export function messageUpdate(options = {}) {
+    const { text = "", chatId = 1, fromId = chatId, chatType = "private" } = options;
+    return createUpdate({
+        message: {
+            message_id: 1,
+            date: 0,
+            chat: { id: chatId, type: chatType },
+            from: { id: fromId, is_bot: false, first_name: "u" },
+            text,
+        },
+    });
+}
+/** build a callback_query {@link Update}. */
+export function callbackUpdate(options = {}) {
+    const { data = "", chatId = 1, fromId = chatId } = options;
+    return createUpdate({
+        callback_query: {
+            id: "1",
+            chat_instance: "0",
+            from: { id: fromId, is_bot: false, first_name: "u" },
+            message: {
+                message_id: 1,
+                date: 0,
+                chat: { id: chatId, type: "private" },
+            },
+            data,
+        },
+    });
+}
+/** infer which payload key an update carries; defaults to `"message"`. */
+export function detectUpdateType(update) {
+    if (update.message)
+        return "message";
+    if (update.edited_message)
+        return "edited_message";
+    if (update.channel_post)
+        return "channel_post";
+    if (update.callback_query)
+        return "callback_query";
+    const bag = update;
+    for (const key of Object.keys(bag)) {
+        if (key !== "update_id" && bag[key] !== undefined)
+            return key;
+    }
+    return "message";
+}
+/**
+ * wrap an {@link Update} in a core {@link Context}. the api defaults to a fresh
+ * {@link mockApi}; pass `updateType` to override the auto-detected one.
+ */
+export function createContext(update, api, updateType) {
+    return new Context({
+        api: api ?? mockApi().api,
+        update,
+        updateType: updateType ?? detectUpdateType(update),
+    });
+}
+const noop = async () => { };
+/** run a composer's middleware against a context. resolves when the chain settles. */
+export async function runMiddleware(composer, ctx) {
+    await composer.toMiddleware()(ctx, noop);
+}
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

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

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,66 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { Composer, Context } from "@yaebal/core";
+import { callbackUpdate, createContext, createUpdate, messageUpdate, mockApi, runMiddleware, } from "./index.js";
+test("mockApi records calls and resolves sensible defaults", async () => {
+    const { api, calls } = mockApi();
+    const sent = await api.sendMessage({ chat_id: 1, text: "hi" });
+    assert.deepEqual(sent, { message_id: 1 });
+    const answered = await api.answerCallbackQuery({ callback_query_id: "1" });
+    assert.equal(answered, true);
+    const viaCall = await api.call("setMyCommands", { commands: [] });
+    assert.deepEqual(viaCall, {});
+    assert.deepEqual(calls, [
+        { method: "sendMessage", params: { chat_id: 1, text: "hi" } },
+        { method: "answerCallbackQuery", params: { callback_query_id: "1" } },
+        { method: "setMyCommands", params: { commands: [] } },
+    ]);
+});
+test("mockApi hook registrars are chainable no-ops", () => {
+    const { api } = mockApi();
+    assert.equal(api.before(() => undefined), api);
+    assert.equal(api.after((_m, r) => r), api);
+});
+test("messageUpdate produces a valid message update", () => {
+    const update = messageUpdate({ text: "hello", chatId: 42, chatType: "group" });
+    assert.ok(update.update_id > 0);
+    assert.equal(update.message?.text, "hello");
+    assert.equal(update.message?.chat.id, 42);
+    assert.equal(update.message?.chat.type, "group");
+    assert.equal(update.message?.from?.id, 42);
+});
+test("callbackUpdate produces a valid callback_query update", () => {
+    const update = callbackUpdate({ data: "click", chatId: 7, fromId: 9 });
+    assert.equal(update.callback_query?.data, "click");
+    assert.equal(update.callback_query?.from.id, 9);
+    assert.equal(update.callback_query?.message?.chat.id, 7);
+});
+test("createUpdate fills a fresh update_id", () => {
+    const a = createUpdate();
+    const b = createUpdate();
+    assert.notEqual(a.update_id, b.update_id);
+});
+test("createContext yields a Context whose getters work", () => {
+    const ctx = createContext(messageUpdate({ text: "yo", chatId: 5 }));
+    assert.ok(ctx instanceof Context);
+    assert.equal(ctx.updateType, "message");
+    assert.equal(ctx.text, "yo");
+    assert.equal(ctx.chat?.id, 5);
+});
+test("createContext detects callback_query updates", () => {
+    const ctx = createContext(callbackUpdate({ data: "x" }));
+    assert.equal(ctx.updateType, "callback_query");
+    assert.equal(ctx.callbackQuery?.data, "x");
+});
+test("a handler calling ctx.reply records a sendMessage call", async () => {
+    const { api, calls } = mockApi();
+    const composer = new Composer().on("message:text", (ctx) => ctx.reply("pong"));
+    await runMiddleware(composer, createContext(messageUpdate({ text: "ping", chatId: 3 }), api));
+    assert.equal(calls.length, 1);
+    const call = calls[0];
+    assert.equal(call?.method, "sendMessage");
+    assert.equal(call?.params?.chat_id, 3);
+    assert.equal(call?.params?.text, "pong");
+    assert.deepEqual(call?.params?.reply_parameters, { message_id: 1 });
+});
+//# 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,49 @@
+{
+  "name": "@yaebal/test",
+  "version": "0.0.1",
+  "description": "yaebal test — testing utilities for yaebal bots: mock api, update factories, and context builders.",
+  "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",
+    "test",
+    "testing",
+    "mock"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/neverlane/yaebal",
+    "directory": "packages/test"
+  },
+  "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,101 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { Composer, Context } from "@yaebal/core";
+import {
+	callbackUpdate,
+	createContext,
+	createUpdate,
+	messageUpdate,
+	mockApi,
+	runMiddleware,
+} from "./index.js";
+
+test("mockApi records calls and resolves sensible defaults", async () => {
+	const { api, calls } = mockApi();
+
+	const sent = await api.sendMessage({ chat_id: 1, text: "hi" });
+	assert.deepEqual(sent, { message_id: 1 });
+
+	const answered = await api.answerCallbackQuery({ callback_query_id: "1" });
+	assert.equal(answered, true);
+
+	const viaCall = await api.call("setMyCommands", { commands: [] });
+	assert.deepEqual(viaCall, {});
+
+	assert.deepEqual(calls, [
+		{ method: "sendMessage", params: { chat_id: 1, text: "hi" } },
+		{ method: "answerCallbackQuery", params: { callback_query_id: "1" } },
+		{ method: "setMyCommands", params: { commands: [] } },
+	]);
+});
+
+test("mockApi hook registrars are chainable no-ops", () => {
+	const { api } = mockApi();
+	assert.equal(
+		api.before(() => undefined),
+		api,
+	);
+	assert.equal(
+		api.after((_m, r) => r),
+		api,
+	);
+});
+
+test("messageUpdate produces a valid message update", () => {
+	const update = messageUpdate({ text: "hello", chatId: 42, chatType: "group" });
+
+	assert.ok(update.update_id > 0);
+
+	assert.equal(update.message?.text, "hello");
+	assert.equal(update.message?.chat.id, 42);
+	assert.equal(update.message?.chat.type, "group");
+	assert.equal(update.message?.from?.id, 42);
+});
+
+test("callbackUpdate produces a valid callback_query update", () => {
+	const update = callbackUpdate({ data: "click", chatId: 7, fromId: 9 });
+
+	assert.equal(update.callback_query?.data, "click");
+	assert.equal(update.callback_query?.from.id, 9);
+	assert.equal(update.callback_query?.message?.chat.id, 7);
+});
+
+test("createUpdate fills a fresh update_id", () => {
+	const a = createUpdate();
+	const b = createUpdate();
+
+	assert.notEqual(a.update_id, b.update_id);
+});
+
+test("createContext yields a Context whose getters work", () => {
+	const ctx = createContext(messageUpdate({ text: "yo", chatId: 5 }));
+
+	assert.ok(ctx instanceof Context);
+
+	assert.equal(ctx.updateType, "message");
+	assert.equal(ctx.text, "yo");
+	assert.equal(ctx.chat?.id, 5);
+});
+
+test("createContext detects callback_query updates", () => {
+	const ctx = createContext(callbackUpdate({ data: "x" }));
+
+	assert.equal(ctx.updateType, "callback_query");
+	assert.equal(ctx.callbackQuery?.data, "x");
+});
+
+test("a handler calling ctx.reply records a sendMessage call", async () => {
+	const { api, calls } = mockApi();
+
+	const composer = new Composer().on("message:text", (ctx) => ctx.reply("pong"));
+	await runMiddleware(composer, createContext(messageUpdate({ text: "ping", chatId: 3 }), api));
+
+	assert.equal(calls.length, 1);
+
+	const call = calls[0];
+	assert.equal(call?.method, "sendMessage");
+	assert.equal(call?.params?.chat_id, 3);
+	assert.equal(call?.params?.text, "pong");
+
+	assert.deepEqual(call?.params?.reply_parameters, { message_id: 1 });
+});

package/src/index.ts

@@ -0,0 +1,173 @@
+/**
+ * @yaebal/test — testing utilities for yaebal bots.
+ *
+ * every plugin test used to hand-build fake updates and a mock api. this package
+ * extracts that boilerplate: {@link mockApi} records every call, the `*Update`
+ * factories produce real {@link Update} shapes, and {@link createContext} wraps
+ * one in a core {@link Context}.
+ */
+
+import {
+	type Api,
+	type Composer,
+	Context,
+	type Message,
+	type NextFn,
+	type Update,
+	type UpdateName,
+} from "@yaebal/core";
+
+/** a single recorded api call: the method name and the params it was given. */
+export interface RecordedCall {
+	method: string;
+	params: Record<string, unknown> | undefined;
+}
+
+/** result of {@link mockApi}: the fake `api` plus the array it records into. */
+export interface MockApi {
+	api: Api;
+	calls: RecordedCall[];
+}
+
+/** default results for known methods; everything else resolves to `{}`. */
+function defaultResult(method: string): unknown {
+	if (method.startsWith("send") || method === "copyMessage" || method === "forwardMessage") {
+		return { message_id: 1 };
+	}
+
+	if (method === "answerCallbackQuery") return true;
+	if (method === "getMe") return { id: 1, is_bot: true, first_name: "bot", username: "bot" };
+
+	return {};
+}
+
+/**
+ * a fake {@link Api} whose every method records `{ method, params }` into `calls`
+ * and resolves to a sensible default (`{ message_id: 1 }` for `send*`, `true` for
+ * `answerCallbackQuery`, `{}` otherwise). hook registrars (`before`/`after`/
+ * `onError`) are no-ops that return the api for chaining.
+ */
+export function mockApi(): MockApi {
+	const calls: RecordedCall[] = [];
+
+	const record = (method: string, params?: Record<string, unknown>): Promise<never> => {
+		calls.push({ method, params });
+		return Promise.resolve(defaultResult(method) as never);
+	};
+
+	const registrar: Record<string, unknown> = {
+		call: (method: string, params?: Record<string, unknown>) => record(method, params),
+		fileUrl: (filePath: string) => `https://example.invalid/file/${filePath}`,
+		before: () => api,
+		after: () => api,
+		onError: () => api,
+	};
+
+	const api = new Proxy(registrar, {
+		get(obj, prop: string) {
+			if (prop in obj) return obj[prop];
+
+			const method = (params?: Record<string, unknown>) => record(prop, params);
+			obj[prop] = method;
+
+			return method;
+		},
+	}) as unknown as Api;
+
+	return { api, calls };
+}
+
+let updateIdCounter = 0;
+
+/** build an {@link Update} from a partial, filling in a fresh `update_id`. */
+export function createUpdate(partial: Partial<Update> = {}): Update {
+	return { update_id: ++updateIdCounter, ...partial };
+}
+
+/** options for {@link messageUpdate}. */
+export interface MessageUpdateOptions {
+	text?: string;
+	chatId?: number;
+	fromId?: number;
+	chatType?: "private" | "group" | "supergroup" | "channel";
+}
+
+/** build a message {@link Update}. */
+export function messageUpdate(options: MessageUpdateOptions = {}): Update {
+	const { text = "", chatId = 1, fromId = chatId, chatType = "private" } = options;
+
+	return createUpdate({
+		message: {
+			message_id: 1,
+			date: 0,
+			chat: { id: chatId, type: chatType },
+			from: { id: fromId, is_bot: false, first_name: "u" },
+			text,
+		},
+	});
+}
+
+/** options for {@link callbackUpdate}. */
+export interface CallbackUpdateOptions {
+	data?: string;
+	chatId?: number;
+	fromId?: number;
+}
+
+/** build a callback_query {@link Update}. */
+export function callbackUpdate(options: CallbackUpdateOptions = {}): Update {
+	const { data = "", chatId = 1, fromId = chatId } = options;
+
+	return createUpdate({
+		callback_query: {
+			id: "1",
+			chat_instance: "0",
+			from: { id: fromId, is_bot: false, first_name: "u" },
+			message: {
+				message_id: 1,
+				date: 0,
+				chat: { id: chatId, type: "private" },
+			},
+			data,
+		},
+	});
+}
+
+/** infer which payload key an update carries; defaults to `"message"`. */
+export function detectUpdateType(update: Update): UpdateName {
+	if (update.message) return "message";
+	if (update.edited_message) return "edited_message";
+	if (update.channel_post) return "channel_post";
+	if (update.callback_query) return "callback_query";
+
+	const bag = update as unknown as Record<string, unknown>;
+	for (const key of Object.keys(bag)) {
+		if (key !== "update_id" && bag[key] !== undefined) return key as UpdateName;
+	}
+
+	return "message";
+}
+
+/**
+ * wrap an {@link Update} in a core {@link Context}. the api defaults to a fresh
+ * {@link mockApi}; pass `updateType` to override the auto-detected one.
+ */
+export function createContext(update: Update, api?: Api, updateType?: UpdateName): Context {
+	return new Context({
+		api: api ?? mockApi().api,
+		update,
+		updateType: updateType ?? detectUpdateType(update),
+	});
+}
+
+const noop: NextFn = async () => {};
+
+/** run a composer's middleware against a context. resolves when the chain settles. */
+export async function runMiddleware<C extends Context>(
+	composer: Composer<C>,
+	ctx: C,
+): Promise<void> {
+	await composer.toMiddleware()(ctx, noop);
+}
+
+export type { Message };