@yaebal/core 0.0.1

package/src/bot.ts

@@ -0,0 +1,168 @@
+import { type Api, type FileReader, createApi } from "./api.js";
+import { Composer, type Middleware } 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>;
+
+function detectUpdateType(update: Update): UpdateName {
+	for (const key of Object.keys(update)) {
+		if (key === "update_id") continue;
+		return key as UpdateName;
+	}
+
+	return "message" as UpdateName;
+}
+
+/**
+ * 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<C extends Context = Context> extends Composer<C> {
+	readonly api: Api;
+	#running = false;
+	#offset = 0;
+	#info?: User;
+	readonly #options: BotOptions;
+	readonly #startHandlers: StartHandler[] = [];
+	#errorHandler: ErrorHandler = (error) => {
+		console.error("[yaebal] unhandled error in middleware:", error);
+	};
+	#handle?: Middleware<Context>;
+
+	constructor(token: string, options: BotOptions = {}) {
+		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(): User | undefined {
+		return this.#info;
+	}
+
+	override derive<D extends object>(fn: (ctx: C) => D | Promise<D>): Bot<C & D>;
+	override derive<D extends object>(
+		updates: UpdateName | UpdateName[],
+		fn: (ctx: C) => D | Promise<D>,
+	): Bot<C & Partial<D>>;
+	// biome-ignore lint/suspicious/noExplicitAny: overload implementation
+	override derive(a: any, b?: any): any {
+		// biome-ignore lint/suspicious/noExplicitAny: forwarding to the overloaded base
+		(super.derive as any)(a, b);
+		return this;
+	}
+
+	override decorate<D extends object>(value: D): Bot<C & D> {
+		super.decorate(value);
+		return this as unknown as Bot<C & D>;
+	}
+
+	override extend<C2 extends Context>(other: Composer<C2>): Bot<C & C2> {
+		super.extend(other);
+		return this as unknown as Bot<C & C2>;
+	}
+
+	override install<Add extends object>(
+		plugin: (composer: Composer<C>) => Composer<C & Add>,
+	): Bot<C & Add> {
+		plugin(this);
+		return this as unknown as Bot<C & Add>;
+	}
+
+	/** register a callback fired once the bot has started. */
+	onStart(handler: StartHandler): this {
+		this.#startHandlers.push(handler);
+		return this;
+	}
+
+	/** replace the default error handler. */
+	onError(handler: ErrorHandler): this {
+		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: Update): Promise<void> {
+		if (!this.#handle) this.#handle = this.toMiddleware() as unknown as Middleware<Context>;
+
+		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(): Promise<void> {
+		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: Update[];
+
+			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(): void {
+		this.#running = false;
+	}
+}

package/src/composer.ts

@@ -0,0 +1,280 @@
+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 function compose<C>(middlewares: Middleware<C>[]): (ctx: C, next?: NextFn) => Promise<void> {
+	return function composed(ctx, next) {
+		let lastIndex = -1;
+
+		const dispatch = async (i: number): Promise<void> => {
+			if (i <= lastIndex) throw new Error("next() called multiple times");
+			lastIndex = i;
+
+			const fn = i === middlewares.length ? next : middlewares[i];
+			if (!fn) return;
+
+			await fn(ctx, () => dispatch(i + 1));
+		};
+
+		return dispatch(0);
+	};
+}
+
+function checkField(ctx: Context, field: string): boolean {
+	switch (field) {
+		case "text":
+		case "caption":
+			return typeof ctx.text === "string" && ctx.text.length > 0;
+		case "data":
+			return Boolean(ctx.callbackQuery?.data);
+		case "entities":
+			return Boolean(ctx.message?.entities?.length);
+		default: {
+			const msg = ctx.message as Record<string, unknown> | undefined;
+			return Boolean(msg?.[field]);
+		}
+	}
+}
+
+export function matchQuery(ctx: Context, query: string): boolean {
+	const [head, ...rest] = query.split(":");
+	if (head && head.length > 0 && ctx.updateType !== head) return false;
+
+	for (const field of rest) {
+		if (!checkField(ctx, field)) return false;
+	}
+
+	return true;
+}
+
+/**
+ * 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 class Composer<C extends Context = Context> {
+	protected middlewares: Middleware<C>[] = [];
+
+	/** raw middleware. call `next()` to continue the chain. */
+	use(...middleware: Middleware<C>[]): this {
+		this.middlewares.push(...middleware);
+		return this;
+	}
+
+	/** handle a specific update, optionally narrowed by a filter query. */
+	on<Q extends FilterQuery>(query: Q, ...handlers: Middleware<Filtered<C, Q>>[]): this {
+		const handler = compose(handlers as unknown as Middleware<C>[]);
+
+		this.middlewares.push((ctx, next) =>
+			matchQuery(ctx, query as string) ? handler(ctx, next) : next(),
+		);
+
+		return this;
+	}
+
+	/** handle `/<name>` commands. Strips a trailing `@botname` and parses args. */
+	command(name: string, ...handlers: Middleware<C & { command: string; args: string[] }>[]): this {
+		const handler = compose(handlers as unknown as Middleware<C>[]);
+
+		this.middlewares.push((ctx, next) => {
+			const text = ctx.text;
+			if (text === undefined || !text.startsWith("/")) return next();
+
+			const [head, ...args] = text.slice(1).split(/\s+/);
+			const base = head?.split("@")[0];
+			if (base !== name) return next();
+
+			Object.assign(ctx as object, { command: base, args });
+			return handler(ctx, next);
+		});
+
+		return this;
+	}
+
+	/** match message text/caption against a string or regex; exposes `ctx.match`. */
+	hears(
+		trigger: string | RegExp,
+		...handlers: Middleware<C & { match: string | RegExpMatchArray }>[]
+	): this {
+		const handler = compose(handlers as unknown as Middleware<C>[]);
+
+		this.middlewares.push((ctx, next) => {
+			const text = ctx.text;
+			if (text === undefined) return next();
+
+			if (typeof trigger === "string") {
+				if (text !== trigger) return next();
+
+				Object.assign(ctx as object, { match: text });
+			} else {
+				const m = text.match(trigger);
+				if (!m) return next();
+
+				Object.assign(ctx as object, { match: m });
+			}
+
+			return handler(ctx, next);
+		});
+
+		return 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 {
+		const handler = compose(handlers as unknown as Middleware<C>[]);
+
+		this.middlewares.push((ctx, next) => {
+			const data = ctx.callbackQuery?.data;
+
+			if (data === undefined) return next();
+
+			if (typeof trigger === "string") {
+				if (data !== trigger) return next();
+
+				Object.assign(ctx as object, { match: data });
+			} else {
+				const m = data.match(trigger);
+				if (!m) return next();
+
+				Object.assign(ctx as object, { match: m });
+			}
+
+			return handler(ctx, next);
+		});
+
+		return this;
+	}
+
+	/** continue only if the predicate holds. */
+	guard(predicate: (ctx: C) => boolean | Promise<boolean>): this {
+		this.middlewares.push(async (ctx, next) => {
+			if (await predicate(ctx)) await next();
+		});
+
+		return 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 {
+		const handler = compose(handlers as unknown as Middleware<C>[]);
+
+		this.middlewares.push((ctx, next) => (filter.test(ctx) ? handler(ctx, next) : next()));
+		return 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> {
+		return plugin(this);
+	}
+
+	/** 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>>;
+	// biome-ignore lint/suspicious/noExplicitAny: overload implementation
+	derive(a: any, b?: any): any {
+		const scoped = typeof a !== "function";
+		const only: UpdateName[] | null = scoped ? (Array.isArray(a) ? a : [a]) : null;
+		const fn = (scoped ? b : a) as (ctx: C) => object | Promise<object>;
+
+		this.middlewares.push(async (ctx, next) => {
+			if (!only || only.includes(ctx.updateType)) Object.assign(ctx as object, await fn(ctx));
+			await next();
+		});
+
+		return this;
+	}
+
+	/**
+	 * 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> {
+		this.middlewares.push((ctx, next) => {
+			Object.assign(ctx as object, value);
+			return next();
+		});
+		
+		return this as unknown as Composer<C & D>;
+	}
+
+	/** merge another composer in, inheriting its full context type. */
+	extend<C2 extends Context>(other: Composer<C2>): Composer<C & C2> {
+		this.middlewares.push(other.toMiddleware() as unknown as Middleware<C>);
+		return this as unknown as Composer<C & C2>;
+	}
+
+	/** collapse this composer into a single middleware (used by `extend` and `Bot`). */
+	toMiddleware(): Middleware<C> {
+		const composed = compose(this.middlewares);
+		return (ctx, next) => composed(ctx, next);
+	}
+}

package/src/context.ts

@@ -0,0 +1,109 @@
+import type { Api } from "./api.js";
+import type { FormatResult } from "./format.js";
+import type { MediaSource } from "./media.js";
+import type { CallbackQuery, Chat, Message, Update, UpdateName, User } from "./telegram-types.js";
+
+export interface ContextOptions {
+	api: Api;
+	update: Update;
+	updateType: UpdateName;
+}
+
+type SendText = string | FormatResult;
+
+function resolveText(text: SendText): { text: string; entities?: FormatResult["entities"] } {
+	if (typeof text === "string") return { text };
+	return { text: text.text, entities: text.entities };
+}
+
+/**
+ * the base context every update is wrapped in. plugins and `derive`/`decorate`
+ * enrich it with extra properties; those extras are tracked at the type level
+ * by the Composer, so handlers see them without casting.
+ */
+export class Context {
+	readonly api: Api;
+	readonly update: Update;
+	readonly updateType: UpdateName;
+
+	constructor(options: ContextOptions) {
+		this.api = options.api;
+		this.update = options.update;
+		this.updateType = options.updateType;
+	}
+
+	get message(): Message | undefined {
+		return this.update.message ?? this.update.edited_message ?? this.update.channel_post;
+	}
+
+	get callbackQuery(): CallbackQuery | undefined {
+		return this.update.callback_query;
+	}
+
+	get from(): User | undefined {
+		return this.message?.from ?? this.callbackQuery?.from;
+	}
+
+	get chat(): Chat | undefined {
+		return this.message?.chat ?? this.callbackQuery?.message?.chat;
+	}
+
+	get text(): string | undefined {
+		return this.message?.text ?? this.message?.caption;
+	}
+
+	/** narrowing helper in the puregram spirit: `if (ctx.is("callback_query"))`. */
+	is(updateType: UpdateName): boolean {
+		return this.updateType === updateType;
+	}
+
+	/** send a message to the current chat. accepts a plain string or a `format` result. */
+	send(text: SendText, extra: Record<string, unknown> = {}): Promise<Message> {
+		const chatId = this.chat?.id;
+		if (chatId === undefined) {
+			return Promise.reject(new Error("send(): no chat in this update"));
+		}
+
+		return this.api.sendMessage({ chat_id: chatId, ...resolveText(text), ...extra });
+	}
+
+	/** reply to the triggering message. */
+	reply(text: SendText, extra: Record<string, unknown> = {}): Promise<Message> {
+		const replyTo = this.message?.message_id;
+
+		return this.send(text, {
+			...(replyTo !== undefined ? { reply_parameters: { message_id: replyTo } } : {}),
+			...extra,
+		});
+	}
+
+	/** send a photo. accepts a {@link MediaSource} or a raw file_id / URL string. */
+	sendPhoto(photo: MediaSource | string, extra: Record<string, unknown> = {}): Promise<Message> {
+		const chatId = this.chat?.id;
+		if (chatId === undefined)
+			return Promise.reject(new Error("sendPhoto(): no chat in this update"));
+
+		return this.api.call<Message>("sendPhoto", { chat_id: chatId, photo, ...extra });
+	}
+
+	/** send a document. accepts a {@link MediaSource} or a raw file_id / URL string. */
+	sendDocument(
+		document: MediaSource | string,
+		extra: Record<string, unknown> = {},
+	): Promise<Message> {
+		const chatId = this.chat?.id;
+		if (chatId === undefined) {
+			return Promise.reject(new Error("sendDocument(): no chat in this update"));
+		}
+
+		return this.api.call<Message>("sendDocument", { chat_id: chatId, document, ...extra });
+	}
+
+	/** answer the current callback query (no-op if there is none). */
+	answerCallbackQuery(extra: Record<string, unknown> = {}): Promise<boolean> {
+		const id = this.callbackQuery?.id;
+		if (id === undefined) return Promise.resolve(false);
+		
+		return this.api.answerCallbackQuery({ callback_query_id: id, ...extra });
+	}
+}

package/src/core.test.ts

@@ -0,0 +1,108 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { encodeRequest } from "./api.js";
+import { Bot } from "./bot.js";
+import { isMediaSource, media } from "./media.js";
+import { webhookCallback } from "./webhook.js";
+
+test("media helpers are branded and discriminated", () => {
+	assert.ok(isMediaSource(media.fileId("AgAC")));
+	assert.ok(isMediaSource(media.url("https://x/y.png")));
+	assert.equal(isMediaSource({ kind: "fileId", fileId: "x" }), false); // unbranded
+});
+
+test("encodeRequest sends JSON when there is no upload", async () => {
+	const r = await encodeRequest({ chat_id: 1, photo: media.fileId("AgAC") });
+	assert.equal(r.contentType, "application/json");
+	assert.deepEqual(JSON.parse(r.body as string), { chat_id: 1, photo: "AgAC" });
+});
+
+test("encodeRequest inlines a url media to its string", async () => {
+	const r = await encodeRequest({ photo: media.url("https://e/p.png") });
+	assert.deepEqual(JSON.parse(r.body as string), { photo: "https://e/p.png" });
+});
+
+test("encodeRequest builds multipart for a buffer upload", async () => {
+	const r = await encodeRequest({
+		chat_id: 7,
+		photo: media.buffer(new Uint8Array([1, 2, 3]), "pic.png"),
+		reply_markup: { inline_keyboard: [] },
+	});
+	assert.ok(r.body instanceof FormData);
+	const form = r.body as FormData;
+	assert.equal(form.get("photo"), "attach://_file0");
+	assert.ok(form.get("_file0") instanceof Blob);
+	assert.equal(form.get("chat_id"), "7"); // non-string serialized
+	assert.equal(form.get("reply_markup"), '{"inline_keyboard":[]}'); // object → JSON
+});
+
+test("encodeRequest handles no params", async () => {
+	const r = await encodeRequest(undefined);
+	assert.equal(r.body, undefined);
+});
+
+test("encodeRequest rejects nested media (fails loud, no garbage)", async () => {
+	await assert.rejects(
+		() => encodeRequest({ media: [{ type: "photo", media: media.path("./a.jpg") }] }),
+		/nested MediaSource/,
+	);
+});
+
+test("encodeRequest throws a helpful error for media.path() without a readFile (edge)", async () => {
+	await assert.rejects(() => encodeRequest({ photo: media.path("./a.jpg") }), /needs a filesystem/);
+});
+
+test("encodeRequest uses an injected readFile for media.path() (runtime-agnostic)", async () => {
+	const readFile = async (p: string) => {
+		assert.equal(p, "./pics/cat.jpg"); // path forwarded verbatim
+		return new Uint8Array([9, 8, 7]);
+	};
+	const r = await encodeRequest({ chat_id: 1, photo: media.path("./pics/cat.jpg") }, readFile);
+	const form = r.body as FormData;
+	assert.ok(form.get("_file0") instanceof Blob);
+	assert.equal(form.get("photo"), "attach://_file0");
+	assert.equal((form.get("_file0") as File).name, "cat.jpg"); // pure-js basename
+});
+
+test("webhookCallback dispatches a POSTed update and guards method/secret", async () => {
+	const seen: number[] = [];
+	const sink = { handleUpdate: async (u: { update_id: number }) => void seen.push(u.update_id) };
+	const handler = webhookCallback(sink as never, { secretToken: "s3cret" });
+	const body = JSON.stringify({ update_id: 7, message: { text: "hi" } });
+
+	const ok = await handler(
+		new Request("http://x/hook", {
+			method: "POST",
+			headers: { "x-telegram-bot-api-secret-token": "s3cret" },
+			body,
+		}),
+	);
+
+	assert.equal(ok.status, 200);
+	assert.deepEqual(seen, [7]);
+
+	const wrongMethod = await handler(new Request("http://x/hook"));
+	assert.equal(wrongMethod.status, 405);
+
+	const wrongSecret = await handler(
+		new Request("http://x/hook", {
+			method: "POST",
+			headers: { "x-telegram-bot-api-secret-token": "nope" },
+			body,
+		}),
+	);
+	assert.equal(wrongSecret.status, 401);
+});
+
+test("Bot.handleUpdate runs the middleware chain (webhook entry)", async () => {
+	let seen = "";
+	const bot = new Bot("123:abc").on("message:text", (ctx) => {
+		seen = ctx.text;
+	});
+	
+	await bot.handleUpdate({
+		update_id: 1,
+		message: { message_id: 1, date: 0, chat: { id: 1, type: "private" }, text: "hi" },
+	} as never);
+	assert.equal(seen, "hi");
+});