@yaebal/core 0.0.1

package/src/filter.test.ts

@@ -0,0 +1,202 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { Composer, Context } from "./index.js";
+import type { Filter } from "./index.js";
+import type { Update } from "./telegram-types.js";
+
+/** minimal no-op api stub — composer tests never make real api calls. */
+const stubApi = null as unknown as InstanceType<typeof Context>["api"];
+
+function makeCtx(update: Update): Context {
+	const keys = Object.keys(update).filter((k) => k !== "update_id") as (keyof Update)[];
+	const updateType = keys[0] as Context["updateType"];
+
+	return new Context({ api: stubApi, update, updateType });
+}
+
+function makeMessageCtx(text?: string): Context {
+	return makeCtx({
+		update_id: 1,
+		message: {
+			message_id: 1,
+			date: 0,
+			chat: { id: 1, type: "private" as const },
+			...(text !== undefined ? { text } : {}),
+		},
+	} as Update);
+}
+
+function makeCallbackCtx(data = "btn"): Context {
+	return makeCtx({
+		update_id: 2,
+		callback_query: {
+			id: "q1",
+			from: { id: 99, is_bot: false, first_name: "U" },
+			chat_instance: "ci",
+			data,
+		},
+	} as unknown as Update);
+}
+
+/** run `composer.toMiddleware()` against ctx and resolve when the chain ends. */
+async function run(composer: Composer, ctx: Context): Promise<void> {
+	await composer.toMiddleware()(ctx, async () => {});
+}
+
+test("filter: runs handlers when filter.test returns true", async () => {
+	const alwaysTrue: Filter = {
+		test(_ctx): _ctx is Context {
+			return true;
+		},
+	};
+
+	let called = false;
+	const composer = new Composer().filter(alwaysTrue, (_ctx) => {
+		called = true;
+	});
+
+	await run(composer, makeMessageCtx("hi"));
+	assert.ok(called, "handler should have been called");
+});
+
+test("filter: skips handlers and calls next when filter.test returns false", async () => {
+	const alwaysFalse: Filter = {
+		test(_ctx): _ctx is Context {
+			return false;
+		},
+	};
+
+	let handlerCalled = false;
+	let nextCalled = false;
+
+	const composer = new Composer()
+		.filter(alwaysFalse, (_ctx) => {
+			handlerCalled = true;
+		})
+		.use((_ctx, next) => {
+			nextCalled = true;
+			return next();
+		});
+
+	await run(composer, makeMessageCtx());
+	assert.equal(handlerCalled, false, "handler must not run when filter rejects");
+	assert.ok(nextCalled, "next middleware must still be reached");
+});
+
+test("filter: handler sees data attached by filter.test via Object.assign", async () => {
+	interface WithMatch {
+		match: RegExpMatchArray;
+	}
+
+	const regexFilter: Filter<Context, WithMatch> = {
+		test(ctx): ctx is Context & WithMatch {
+			const m = ctx.text?.match(/hello (\w+)/);
+			if (!m) return false;
+
+			Object.assign(ctx as object, { match: m });
+			return true;
+		},
+	};
+
+	let captured: RegExpMatchArray | undefined;
+	const composer = new Composer().filter(regexFilter, (ctx) => {
+		captured = (ctx as Context & WithMatch).match;
+	});
+
+	await run(composer, makeMessageCtx("hello world"));
+	assert.ok(captured, "match should be set on ctx");
+	assert.equal(captured[1], "world");
+});
+
+test("filter: filter.test that attaches data is not called for non-matching ctx", async () => {
+	interface WithMatch {
+		match: RegExpMatchArray;
+	}
+
+	const regexFilter: Filter<Context, WithMatch> = {
+		test(ctx): ctx is Context & WithMatch {
+			const m = ctx.text?.match(/hello (\w+)/);
+			if (!m) return false;
+
+			Object.assign(ctx as object, { match: m });
+			return true;
+		},
+	};
+
+	let handlerCalled = false;
+	const composer = new Composer().filter(regexFilter, (_ctx) => {
+		handlerCalled = true;
+	});
+
+	// callback_query ctx has no text — regex won't match
+	await run(composer, makeCallbackCtx());
+	assert.equal(handlerCalled, false);
+});
+
+test("filter: type guard narrows — handler sees ctx.tag added by filter", async () => {
+	const tagFilter: Filter<Context, { tag: number }> = {
+		test(ctx): ctx is Context & { tag: number } {
+			Object.assign(ctx as object, { tag: 42 });
+			return true;
+		},
+	};
+
+	let seenTag: number | undefined;
+	const composer = new Composer().filter(tagFilter, (ctx) => {
+		// typescript sees ctx.tag as number here (narrowed by the Filter type)
+		seenTag = (ctx as Context & { tag: number }).tag;
+	});
+
+	await run(composer, makeMessageCtx());
+	assert.equal(seenTag, 42);
+});
+
+test("derive scoped: fn runs for the listed update type and field is present", async () => {
+	const composer = new Composer().derive("message", (_ctx) => ({ enriched: true }));
+
+	const msgCtx = makeMessageCtx("test");
+	await run(composer, msgCtx);
+	assert.equal((msgCtx as unknown as { enriched?: boolean }).enriched, true);
+});
+
+test("derive scoped: fn does NOT run for a different update type", async () => {
+	const composer = new Composer().derive("message", (_ctx) => ({ enriched: true }));
+
+	const cbCtx = makeCallbackCtx();
+	await run(composer, cbCtx);
+	assert.equal((cbCtx as unknown as { enriched?: boolean }).enriched, undefined);
+});
+
+test("derive scoped: both updateTypes work when given an array", async () => {
+	const composer = new Composer().derive(["message", "callback_query"], (_ctx) => ({
+		enriched: true,
+	}));
+
+	const msgCtx = makeMessageCtx();
+	const cbCtx = makeCallbackCtx();
+
+	await run(composer, msgCtx);
+	await run(composer, cbCtx);
+
+	assert.equal((msgCtx as unknown as { enriched?: boolean }).enriched, true);
+	assert.equal((cbCtx as unknown as { enriched?: boolean }).enriched, true);
+});
+
+test("derive scoped: unscoped array — non-listed type is not enriched", async () => {
+	const composer = new Composer().derive("message", (_ctx) => ({ enriched: true }));
+
+	const cbCtx = makeCallbackCtx();
+	await run(composer, cbCtx);
+
+	assert.equal((cbCtx as unknown as { enriched?: boolean }).enriched, undefined);
+});
+
+test("derive scoped: fn receives the context for async enrichment", async () => {
+	const composer = new Composer().derive("message", async (ctx) => ({
+		textLen: ctx.text?.length ?? 0,
+	}));
+
+	const msgCtx = makeMessageCtx("hello");
+	await run(composer, msgCtx);
+	assert.equal((msgCtx as unknown as { textLen?: number }).textLen, 5);
+});

package/src/format.ts

@@ -0,0 +1,80 @@
+import type { MessageEntity } from "./telegram-types.js";
+
+/**
+ * formatting without `parse_mode`: tagged template literals that build proper
+ * `MessageEntity` objects, so there is nothing to escape (the GramIO idea).
+ */
+export interface FormatResult {
+	text: string;
+	entities: MessageEntity[];
+}
+
+/** a piece of text that carries its own entities, used inside `format`. */
+export class Stringable implements FormatResult {
+	constructor(
+		readonly text: string,
+		readonly entities: MessageEntity[] = [],
+	) {}
+}
+
+type Insertable = Stringable | FormatResult | string | number | bigint;
+
+function isFormatResult(value: unknown): value is FormatResult {
+	return (
+		typeof value === "object" &&
+		value !== null &&
+		"text" in value &&
+		"entities" in value &&
+		Array.isArray((value as FormatResult).entities)
+	);
+}
+
+/** stitches the literal parts and interpolations into one `{ text, entities }`. */
+export function format(strings: TemplateStringsArray, ...subs: Insertable[]): FormatResult {
+	let text = "";
+	const entities: MessageEntity[] = [];
+
+	for (let i = 0; i < strings.length; i++) {
+		text += strings[i] ?? "";
+
+		if (i < subs.length) {
+			const sub = subs[i] as Insertable;
+			const offset = text.length;
+
+			if (isFormatResult(sub)) {
+				text += sub.text;
+				
+				for (const entity of sub.entities) {
+					entities.push({ ...entity, offset: entity.offset + offset });
+				}
+			} else {
+				text += String(sub);
+			}
+		}
+	}
+
+	return { text, entities };
+}
+
+function wrap(type: string, extra: Partial<MessageEntity> = {}) {
+	return (value: string): Stringable =>
+		new Stringable(value, [{ type, offset: 0, length: value.length, ...extra }]);
+}
+
+export const bold = wrap("bold");
+export const italic = wrap("italic");
+export const underline = wrap("underline");
+export const strikethrough = wrap("strikethrough");
+export const spoiler = wrap("spoiler");
+export const code = wrap("code");
+export const pre = wrap("pre");
+
+export function link(text: string, url: string): Stringable {
+	return new Stringable(text, [{ type: "text_link", offset: 0, length: text.length, url }]);
+}
+
+export function mention(text: string, user: { id: number }): Stringable {
+	return new Stringable(text, [
+		{ type: "text_mention", offset: 0, length: text.length, user: user as never },
+	]);
+}

package/src/index.ts

@@ -0,0 +1,53 @@
+/**
+ * @yaebal/core — core of Yet Another tElegram Bot Api Library.
+ *
+ * public surface: the `Bot`, the standalone `Composer`, the `Context`,
+ * the entity-based `format` helpers, the low-level `Api`, and the telegram types.
+ */
+
+export { Bot, type BotOptions } from "./bot.js";
+export {
+	Composer,
+	compose,
+	matchQuery,
+	type Filter,
+	type FilterQuery,
+	type Filtered,
+	type Middleware,
+	type NextFn,
+	type Plugin,
+} from "./composer.js";
+export { Context, type ContextOptions } from "./context.js";
+export { media, isMediaSource, type MediaSource } from "./media.js";
+export {
+	webhookCallback,
+	nodeWebhookCallback,
+	type UpdateSink,
+	type WebhookOptions,
+} from "./webhook.js";
+export {
+	createApi,
+	TelegramError,
+	type Api,
+	type ApiOptions,
+	type FileReader,
+	type BeforeHook,
+	type AfterHook,
+	type ErrorHook,
+	type ErrorAction,
+} from "./api.js";
+export {
+	format,
+	Stringable,
+	bold,
+	italic,
+	underline,
+	strikethrough,
+	spoiler,
+	code,
+	pre,
+	link,
+	mention,
+	type FormatResult,
+} from "./format.js";
+export type * from "./telegram-types.js";

package/src/media.ts

@@ -0,0 +1,29 @@
+// media abstraction (the puregram idea): a uniform way to point at a file —
+// local path, URL, in-memory buffer, or an already-uploaded telegram file_id.
+// the api layer turns each into the right wire form (multipart vs plain string).
+
+const MEDIA: unique symbol = Symbol.for("yaebal.media");
+
+export type MediaSource = { readonly [MEDIA]: true } & (
+	| { kind: "path"; path: string }
+	| { kind: "url"; url: string }
+	| { kind: "buffer"; buffer: Uint8Array; filename?: string }
+	| { kind: "fileId"; fileId: string }
+);
+
+/** build a {@link MediaSource}. `media.path("./a.jpg")`, `media.url(...)`, etc. */
+export const media = {
+	path: (path: string): MediaSource => ({ [MEDIA]: true, kind: "path", path }),
+	url: (url: string): MediaSource => ({ [MEDIA]: true, kind: "url", url }),
+	buffer: (buffer: Uint8Array, filename?: string): MediaSource => ({
+		[MEDIA]: true,
+		kind: "buffer",
+		filename,
+		buffer,
+	}),
+	fileId: (fileId: string): MediaSource => ({ [MEDIA]: true, kind: "fileId", fileId }),
+};
+
+export function isMediaSource(x: unknown): x is MediaSource {
+	return typeof x === "object" && x !== null && MEDIA in x;
+}

package/src/telegram-types.ts

@@ -0,0 +1,25 @@
+/**
+ * Telegram Bot API types — re-exported from the code-generated `@yaebal/types`,
+ * the single source of truth (generated from the official schema on every API
+ * release). core only keeps the API-response envelope and the `UpdateName`
+ * helper, which aren't part of the object schema.
+ */
+import type { Update } from "@yaebal/types";
+
+export type { User, Chat, MessageEntity, Message, CallbackQuery, Update } from "@yaebal/types";
+
+/** the keys of `Update` that carry a payload (everything except `update_id`). */
+export type UpdateName = Exclude<keyof Update, "update_id" | symbol | number>;
+
+export interface ApiResponseOk<T> {
+	ok: true;
+	result: T;
+}
+
+export interface ApiResponseError {
+	ok: false;
+	error_code: number;
+	description: string;
+}
+
+export type ApiResponse<T> = ApiResponseOk<T> | ApiResponseError;

package/src/webhook.ts

@@ -0,0 +1,117 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { Update } from "./telegram-types.js";
+
+/** telegram updates are tiny; reject anything wildly larger to avoid memory abuse. */
+const MAX_BODY = 1 << 20; // 1 MiB
+
+/**
+ * constant-time string compare so the secret-token check can't be timed.
+ * pure js (no node:crypto / Buffer) so it runs on node, bun, deno and edge/web.
+ */
+function safeEqual(a: string, b: string): boolean {
+	if (a.length !== b.length) return false;
+	let diff = 0;
+
+	for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+	return diff === 0;
+}
+
+/** anything that can take a single update — i.e. a `Bot`. */
+export interface UpdateSink {
+	handleUpdate(update: Update): Promise<void>;
+}
+
+export interface WebhookOptions {
+	/** if set, require telegram's `X-Telegram-Bot-Api-Secret-Token` header to match. */
+	secretToken?: string;
+}
+
+/**
+ * a fetch-style webhook handler — `(Request) => Response`. works on bun, deno,
+ * cloudflare workers, and any runtime with the fetch globals.
+ */
+export function webhookCallback(
+	bot: UpdateSink,
+	options: WebhookOptions = {},
+): (request: Request) => Promise<Response> {
+	return async (request) => {
+		if (request.method !== "POST") return new Response("method not allowed", { status: 405 });
+
+		if (
+			options.secretToken &&
+			!safeEqual(request.headers.get("x-telegram-bot-api-secret-token") ?? "", options.secretToken)
+		) {
+			return new Response("unauthorized", { status: 401 });
+		}
+
+		if (Number(request.headers.get("content-length") ?? 0) > MAX_BODY) {
+			return new Response("payload too large", { status: 413 });
+		}
+
+		let update: Update;
+		try {
+			update = (await request.json()) as Update;
+		} catch {
+			return new Response("bad request", { status: 400 });
+		}
+
+		await bot.handleUpdate(update);
+		return new Response("ok");
+	};
+}
+
+/** a node `http` webhook handler — `http.createServer(nodeWebhookCallback(bot))`. */
+export function nodeWebhookCallback(
+	bot: UpdateSink,
+	options: WebhookOptions = {},
+): (req: IncomingMessage, res: ServerResponse) => void {
+	return (req, res) => {
+		if (req.method !== "POST") {
+			res.statusCode = 405;
+			res.end();
+
+			return;
+		}
+
+		const got = req.headers["x-telegram-bot-api-secret-token"];
+		if (
+			options.secretToken &&
+			!safeEqual(typeof got === "string" ? got : "", options.secretToken)
+		) {
+			res.statusCode = 401;
+			res.end();
+
+			return;
+		}
+
+		const chunks: Buffer[] = [];
+
+		let size = 0;
+		req.on("data", (c: Buffer) => {
+			size += c.length;
+
+			if (size > MAX_BODY) {
+				res.statusCode = 413;
+				res.end();
+				req.destroy();
+
+				return;
+			}
+
+			chunks.push(c);
+		});
+
+		req.on("end", async () => {
+			try {
+				const update = JSON.parse(Buffer.concat(chunks).toString("utf8")) as Update;
+				await bot.handleUpdate(update);
+				
+				res.statusCode = 200;
+				res.end("ok");
+			} catch {
+				res.statusCode = 400;
+				res.end();
+			}
+		});
+	};
+}