@yaebal/contexts 0.0.1

package/src/index.test.ts

@@ -0,0 +1,241 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import {
+	CallbackQueryContext,
+	ChannelPostContext,
+	MessageContext,
+	ShippingQueryContext,
+	contextFor,
+} from "./index.js";
+
+interface Call {
+	m: string;
+	// biome-ignore lint/suspicious/noExplicitAny: test recorder
+	p: any;
+}
+const recorder = () => {
+	const calls: Call[] = [];
+	const api = {
+		call: (m: string, p: unknown) => {
+			calls.push({ m, p });
+			return Promise.resolve({});
+		},
+	} as never;
+	return { api, calls };
+};
+
+test("MessageContext merges payload fields onto the context", () => {
+	const { api } = recorder();
+	const ctx = new MessageContext(api, {
+		update_id: 1,
+		message: {
+			message_id: 5,
+			date: 0,
+			chat: { id: 42, type: "private" },
+			from: { id: 7, is_bot: false, first_name: "u" },
+			text: "hi",
+		},
+	} as never);
+	assert.equal(ctx.text, "hi");
+	assert.equal(ctx.message_id, 5);
+	assert.equal(ctx.chat.id, 42);
+});
+
+test("auto-generated reply/delete fill chat_id + message_id", () => {
+	const { api, calls } = recorder();
+	const ctx = new MessageContext(api, {
+		update_id: 1,
+		message: { message_id: 5, date: 0, chat: { id: 42, type: "private" } },
+	} as never);
+
+	ctx.reply({ text: "yo" });
+	assert.deepEqual(calls[0], {
+		m: "sendMessage",
+		p: { chat_id: 42, reply_parameters: { message_id: 5 }, text: "yo" },
+	});
+
+	calls.length = 0;
+	ctx.delete();
+	assert.deepEqual(calls[0], { m: "deleteMessage", p: { chat_id: 42, message_id: 5 } });
+
+	calls.length = 0;
+	ctx.send({ text: "hello" }); // send (no reply_parameters)
+	assert.deepEqual(calls[0], { m: "sendMessage", p: { chat_id: 42, text: "hello" } });
+});
+
+test("sugar: positional send/reply build the params object", () => {
+	const { api, calls } = recorder();
+	const ctx = new MessageContext(api, {
+		update_id: 1,
+		message: { message_id: 5, date: 0, chat: { id: 42, type: "private" } },
+	} as never);
+
+	ctx.send("hi", { parse_mode: "HTML" });
+	assert.deepEqual(calls[0], {
+		m: "sendMessage",
+		p: { chat_id: 42, text: "hi", parse_mode: "HTML" },
+	});
+
+	calls.length = 0;
+	ctx.reply("yo");
+	assert.deepEqual(calls[0], {
+		m: "sendMessage",
+		p: { chat_id: 42, reply_parameters: { message_id: 5 }, text: "yo" },
+	});
+
+	calls.length = 0;
+	ctx.react("🔥");
+	assert.deepEqual(calls[0], {
+		m: "setMessageReaction",
+		p: { chat_id: 42, message_id: 5, reaction: [{ type: "emoji", emoji: "🔥" }] },
+	});
+
+	calls.length = 0;
+	ctx.editText("edited");
+	assert.deepEqual(calls[0], {
+		m: "editMessageText",
+		p: { chat_id: 42, message_id: 5, text: "edited" },
+	});
+});
+
+test("sugar: react accepts custom emoji, shorthand objects and arrays", () => {
+	const { api, calls } = recorder();
+	const ctx = new MessageContext(api, {
+		update_id: 1,
+		message: { message_id: 5, date: 0, chat: { id: 42, type: "private" } },
+	} as never);
+	const reactionOf = () => (calls[0]?.p as { reaction: unknown[] }).reaction;
+
+	ctx.react("🔥", "12345"); // emoji + custom emoji id
+	assert.deepEqual(reactionOf(), [{ type: "custom_emoji", custom_emoji_id: "12345" }]);
+
+	calls.length = 0;
+	ctx.react({ custom_emoji_id: "999" }); // shorthand custom object
+	assert.deepEqual(reactionOf(), [{ type: "custom_emoji", custom_emoji_id: "999" }]);
+
+	calls.length = 0;
+	ctx.react({ emoji: "🎉" }); // shorthand emoji object
+	assert.deepEqual(reactionOf(), [{ type: "emoji", emoji: "🎉" }]);
+
+	calls.length = 0;
+	ctx.react([{ emoji: "👍" }, { custom_emoji_id: "1" }], { is_big: true }); // array + extra
+	assert.deepEqual(calls[0], {
+		m: "setMessageReaction",
+		p: {
+			chat_id: 42,
+			message_id: 5,
+			reaction: [
+				{ type: "emoji", emoji: "👍" },
+				{ type: "custom_emoji", custom_emoji_id: "1" },
+			],
+			is_big: true,
+		},
+	});
+});
+
+test("sugar: convenience getters + react() clears reactions", () => {
+	const { api, calls } = recorder();
+	const ctx = new MessageContext(api, {
+		update_id: 1,
+		message: {
+			message_id: 5,
+			date: 0,
+			chat: { id: 42, type: "private" },
+			from: { id: 7, is_bot: false, first_name: "u" },
+		},
+	} as never);
+	assert.equal(ctx.chatId, 42);
+	assert.equal(ctx.senderId, 7);
+
+	ctx.react(); // no args → clear
+	assert.deepEqual(calls[0], {
+		m: "setMessageReaction",
+		p: { chat_id: 42, message_id: 5, reaction: [] },
+	});
+});
+
+test("sugar: callback answer accepts a bare string and no args", () => {
+	const { api, calls } = recorder();
+	const ctx = new CallbackQueryContext(api, {
+		update_id: 1,
+		callback_query: { id: "q1", from: { id: 7, is_bot: false, first_name: "u" }, data: "x" },
+	} as never);
+
+	ctx.answer("done");
+	assert.deepEqual(calls[0], {
+		m: "answerCallbackQuery",
+		p: { callback_query_id: "q1", text: "done" },
+	});
+
+	calls.length = 0;
+	ctx.answer();
+	assert.deepEqual(calls[0], { m: "answerCallbackQuery", p: { callback_query_id: "q1" } });
+});
+
+test("CallbackQueryContext.answer fills callback_query_id", () => {
+	const { api, calls } = recorder();
+	const ctx = new CallbackQueryContext(api, {
+		update_id: 1,
+		callback_query: {
+			id: "q1",
+			from: { id: 7, is_bot: false, first_name: "u" },
+			message: { message_id: 5, date: 0, chat: { id: 42, type: "private" } },
+			data: "x",
+		},
+	} as never);
+
+	assert.equal(ctx.data, "x");
+	ctx.answer({ text: "ok" });
+	assert.deepEqual(calls[0], {
+		m: "answerCallbackQuery",
+		p: { callback_query_id: "q1", text: "ok" },
+	});
+});
+
+test("shared message mixin applies to other message-based contexts", () => {
+	const { api, calls } = recorder();
+	const ctx = new ChannelPostContext(api, {
+		update_id: 1,
+		channel_post: { message_id: 9, date: 0, chat: { id: -100, type: "channel" } },
+	} as never);
+	assert.equal(ctx.chatId, -100);
+
+	ctx.react("👍");
+	assert.deepEqual(calls[0], {
+		m: "setMessageReaction",
+		p: { chat_id: -100, message_id: 9, reaction: [{ type: "emoji", emoji: "👍" }] },
+	});
+
+	calls.length = 0;
+	ctx.send("hi");
+	assert.deepEqual(calls[0], { m: "sendMessage", p: { chat_id: -100, text: "hi" } });
+});
+
+test("shipping query answer takes a positional ok", () => {
+	const { api, calls } = recorder();
+	const ctx = new ShippingQueryContext(api, {
+		update_id: 1,
+		shipping_query: { id: "sq1", from: { id: 7, is_bot: false, first_name: "u" } },
+	} as never);
+	assert.equal(ctx.senderId, 7);
+
+	ctx.answer(true);
+	assert.deepEqual(calls[0], {
+		m: "answerShippingQuery",
+		p: { shipping_query_id: "sq1", ok: true },
+	});
+});
+
+test("contextFor builds the right class per update type", () => {
+	const { api } = recorder();
+	const m = contextFor("message", api, {
+		update_id: 1,
+		message: { message_id: 1, date: 0, chat: { id: 1, type: "private" } },
+	} as never);
+	assert.ok(m instanceof MessageContext);
+	const c = contextFor("callback_query", api, {
+		update_id: 1,
+		callback_query: { id: "q", from: { id: 1, is_bot: false, first_name: "u" } },
+	} as never);
+	assert.ok(c instanceof CallbackQueryContext);
+});

package/src/index.ts

@@ -0,0 +1,9 @@
+/**
+ * @yaebal/contexts — a context class per Update type (`MessageContext`,
+ * `CallbackQueryContext`, …), each merging the raw payload fields and exposing
+ * shortcut methods (`reply`, `editText`, `delete`, `answer`, …) that are
+ * AUTO-GENERATED from the Bot API methods + the ids the context carries.
+ * Regenerate with `pnpm --filter @yaebal/contexts generate`.
+ */
+export * from "./generated/index.js";
+export type { ReactionInput } from "./sugar/message.js";

package/src/sugar/business-message.ts

@@ -0,0 +1,5 @@
+import { BusinessMessageContextBase } from "../generated/business-message.js";
+import { MessageSugar } from "./message-mixin.js";
+
+/** BusinessMessageContext = generated base + the shared Message sugar. */
+export class BusinessMessageContext extends MessageSugar(BusinessMessageContextBase) {}

package/src/sugar/callback-query.ts

@@ -0,0 +1,41 @@
+import type * as t from "@yaebal/types";
+import { CallbackQueryContextBase } from "../generated/callback-query.js";
+
+type AnswerExtra = Omit<t.AnswerCallbackQueryParams, "callback_query_id" | "text">;
+type EditExtra = Omit<t.EditMessageTextParams, "chat_id" | "message_id" | "text">;
+
+/**
+ * CallbackQueryContext = generated base + hand-written ergonomic overloads.
+ * Positional-string sugar for `answer` (the toast you fire on every tap) and
+ * `editText` (editing the message the button is attached to).
+ */
+export class CallbackQueryContext extends CallbackQueryContextBase {
+	/** Id of the chat the button's message is in (if still accessible). */
+	get chatId(): number | undefined {
+		return this.message?.chat?.id;
+	}
+
+	/** Answer the callback query. Pass a string to flash text to the user. */
+	override answer(text: string, params?: AnswerExtra): Promise<boolean>;
+	override answer(
+		params?: Omit<t.AnswerCallbackQueryParams, "callback_query_id">,
+	): Promise<boolean>;
+	override answer(
+		a?: string | Omit<t.AnswerCallbackQueryParams, "callback_query_id">,
+		b?: AnswerExtra,
+	): Promise<boolean> {
+		return super.answer(typeof a === "string" ? { text: a, ...b } : (a ?? {}));
+	}
+
+	/** Edit the attached message's text. Pass a string for the common case. */
+	override editText(text: string, params?: EditExtra): Promise<t.Message | boolean>;
+	override editText(
+		params: Omit<t.EditMessageTextParams, "chat_id" | "message_id">,
+	): Promise<t.Message | boolean>;
+	override editText(
+		a: string | Omit<t.EditMessageTextParams, "chat_id" | "message_id">,
+		b?: EditExtra,
+	): Promise<t.Message | boolean> {
+		return super.editText(typeof a === "string" ? { text: a, ...b } : a);
+	}
+}

package/src/sugar/channel-post.ts

@@ -0,0 +1,5 @@
+import { ChannelPostContextBase } from "../generated/channel-post.js";
+import { MessageSugar } from "./message-mixin.js";
+
+/** ChannelPostContext = generated base + the shared Message sugar. */
+export class ChannelPostContext extends MessageSugar(ChannelPostContextBase) {}

package/src/sugar/chat-join-request.ts

@@ -0,0 +1,13 @@
+import { ChatJoinRequestContextBase } from "../generated/chat-join-request.js";
+
+/** ChatJoinRequestContext = generated base + `approve()` / `decline()` shortcuts. */
+export class ChatJoinRequestContext extends ChatJoinRequestContextBase {
+	/** Approve this chat join request. */
+	approve(): Promise<boolean> {
+		return this.approveChatJoinRequest();
+	}
+	/** Decline this chat join request. */
+	decline(): Promise<boolean> {
+		return this.declineChatJoinRequest();
+	}
+}

package/src/sugar/edited-business-message.ts

@@ -0,0 +1,5 @@
+import { EditedBusinessMessageContextBase } from "../generated/edited-business-message.js";
+import { MessageSugar } from "./message-mixin.js";
+
+/** EditedBusinessMessageContext = generated base + the shared Message sugar. */
+export class EditedBusinessMessageContext extends MessageSugar(EditedBusinessMessageContextBase) {}

package/src/sugar/edited-channel-post.ts

@@ -0,0 +1,5 @@
+import { EditedChannelPostContextBase } from "../generated/edited-channel-post.js";
+import { MessageSugar } from "./message-mixin.js";
+
+/** EditedChannelPostContext = generated base + the shared Message sugar. */
+export class EditedChannelPostContext extends MessageSugar(EditedChannelPostContextBase) {}

package/src/sugar/edited-message.ts

@@ -0,0 +1,5 @@
+import { EditedMessageContextBase } from "../generated/edited-message.js";
+import { MessageSugar } from "./message-mixin.js";
+
+/** EditedMessageContext = generated base + the shared Message sugar. */
+export class EditedMessageContext extends MessageSugar(EditedMessageContextBase) {}

package/src/sugar/inline-query.ts

@@ -0,0 +1,20 @@
+import type * as t from "@yaebal/types";
+import { InlineQueryContextBase } from "../generated/inline-query.js";
+
+type AnswerExtra = Omit<t.AnswerInlineQueryParams, "inline_query_id" | "results">;
+
+/**
+ * InlineQueryContext = generated base + hand-written ergonomic overloads.
+ * Positional sugar for `answer` — pass the results array directly.
+ */
+export class InlineQueryContext extends InlineQueryContextBase {
+	/** Answer the inline query with a list of results. */
+	override answer(results: t.InlineQueryResult[], params?: AnswerExtra): Promise<boolean>;
+	override answer(params: Omit<t.AnswerInlineQueryParams, "inline_query_id">): Promise<boolean>;
+	override answer(
+		a: t.InlineQueryResult[] | Omit<t.AnswerInlineQueryParams, "inline_query_id">,
+		b?: AnswerExtra,
+	): Promise<boolean> {
+		return super.answer(Array.isArray(a) ? { results: a, ...b } : a);
+	}
+}

package/src/sugar/message-mixin.ts

@@ -0,0 +1,137 @@
+import type { Api } from "@yaebal/core";
+import type * as t from "@yaebal/types";
+
+/** A friendly reaction: an emoji string, a `{ emoji }` / `{ custom_emoji_id }` shorthand, or a raw `ReactionType`. */
+export type ReactionInput =
+	| string
+	| { emoji: string }
+	| { custom_emoji_id: string }
+	| t.ReactionType;
+
+function toReaction(r: ReactionInput): t.ReactionType {
+	if (typeof r === "string") return { type: "emoji", emoji: r };
+	if ("type" in r) return r;
+	if ("custom_emoji_id" in r) return { type: "custom_emoji", custom_emoji_id: r.custom_emoji_id };
+	return { type: "emoji", emoji: r.emoji };
+}
+
+type SendExtra = Omit<t.SendMessageParams, "chat_id" | "text">;
+type EditExtra = Omit<t.EditMessageTextParams, "chat_id" | "message_id" | "text">;
+type CaptionExtra = Omit<t.EditMessageCaptionParams, "chat_id" | "message_id" | "caption">;
+type ReactExtra = Omit<t.SetMessageReactionParams, "chat_id" | "message_id" | "reaction">;
+
+/** Fields every Message-based context carries (merged from the payload). */
+interface MessageFields {
+	readonly api: Api;
+	chat: t.Chat;
+	message_id: number;
+	from?: t.User;
+}
+
+// biome-ignore lint/suspicious/noExplicitAny: mixin base constructor
+type Ctor<T> = abstract new (...args: any[]) => T;
+
+/**
+ * Adds the ergonomic positional overloads + convenience getters shared by every
+ * Message-based context (message, channel_post, edited_*, business_*). Methods
+ * call `this.api.call` directly (so the mixin needs no `super`).
+ */
+export function MessageSugar<TBase extends Ctor<MessageFields>>(Base: TBase) {
+	abstract class Sugared extends Base {
+		/** Send a new message to this chat. Pass a string for the common case. */
+		send(text: string, params?: SendExtra): Promise<t.Message>;
+		send(params: Omit<t.SendMessageParams, "chat_id">): Promise<t.Message>;
+		send(a: string | Omit<t.SendMessageParams, "chat_id">, b?: SendExtra): Promise<t.Message> {
+			const params = typeof a === "string" ? { text: a, ...b } : a;
+			return this.api.call<t.Message>("sendMessage", { chat_id: this.chat.id, ...params });
+		}
+
+		/** Reply to this message. Pass a string for the common case. */
+		reply(text: string, params?: SendExtra): Promise<t.Message>;
+		reply(params: Omit<t.SendMessageParams, "chat_id">): Promise<t.Message>;
+		reply(a: string | Omit<t.SendMessageParams, "chat_id">, b?: SendExtra): Promise<t.Message> {
+			const params = typeof a === "string" ? { text: a, ...b } : a;
+			return this.api.call<t.Message>("sendMessage", {
+				chat_id: this.chat.id,
+				reply_parameters: { message_id: this.message_id },
+				...params,
+			});
+		}
+
+		/** Edit this message's text. Pass a string for the common case. */
+		editText(text: string, params?: EditExtra): Promise<t.Message | boolean>;
+		editText(
+			params: Omit<t.EditMessageTextParams, "chat_id" | "message_id">,
+		): Promise<t.Message | boolean>;
+		editText(
+			a: string | Omit<t.EditMessageTextParams, "chat_id" | "message_id">,
+			b?: EditExtra,
+		): Promise<t.Message | boolean> {
+			const params = typeof a === "string" ? { text: a, ...b } : a;
+			return this.api.call<t.Message | boolean>("editMessageText", {
+				chat_id: this.chat.id,
+				message_id: this.message_id,
+				...params,
+			});
+		}
+
+		/** Edit this message's caption. Pass a string for the common case. */
+		editCaption(caption: string, params?: CaptionExtra): Promise<t.Message | boolean>;
+		editCaption(
+			params: Omit<t.EditMessageCaptionParams, "chat_id" | "message_id">,
+		): Promise<t.Message | boolean>;
+		editCaption(
+			a: string | Omit<t.EditMessageCaptionParams, "chat_id" | "message_id">,
+			b?: CaptionExtra,
+		): Promise<t.Message | boolean> {
+			const params = typeof a === "string" ? { caption: a, ...b } : a;
+			return this.api.call<t.Message | boolean>("editMessageCaption", {
+				chat_id: this.chat.id,
+				message_id: this.message_id,
+				...params,
+			});
+		}
+
+		/** Clear all reactions on this message. */
+		react(): Promise<boolean>;
+		/** React with a single emoji. */
+		react(emoji: string, params?: ReactExtra): Promise<boolean>;
+		/** React with a custom emoji (the emoji string is a readable fallback). */
+		react(emoji: string, customEmojiId: string, params?: ReactExtra): Promise<boolean>;
+		/** React with one or many reactions (emoji / `{ emoji }` / `{ custom_emoji_id }` / raw). */
+		react(reactions: ReactionInput | ReactionInput[], params?: ReactExtra): Promise<boolean>;
+		/** React with raw `setMessageReaction` params. */
+		react(params: Omit<t.SetMessageReactionParams, "chat_id" | "message_id">): Promise<boolean>;
+		react(
+			a?:
+				| string
+				| ReactionInput
+				| ReactionInput[]
+				| Omit<t.SetMessageReactionParams, "chat_id" | "message_id">,
+			b?: string | ReactExtra,
+			c?: ReactExtra,
+		): Promise<boolean> {
+			let params: Omit<t.SetMessageReactionParams, "chat_id" | "message_id">;
+			if (a === undefined) {
+				params = { reaction: [] };
+			} else if (typeof a === "string") {
+				params =
+					typeof b === "string"
+						? { reaction: [{ type: "custom_emoji", custom_emoji_id: b }], ...c }
+						: { reaction: [{ type: "emoji", emoji: a }], ...b };
+			} else if (Array.isArray(a)) {
+				params = { reaction: a.map(toReaction), ...(b as ReactExtra) };
+			} else if ("emoji" in a || "custom_emoji_id" in a || "type" in a) {
+				params = { reaction: [toReaction(a as ReactionInput)], ...(b as ReactExtra) };
+			} else {
+				params = a;
+			}
+			return this.api.call<boolean>("setMessageReaction", {
+				chat_id: this.chat.id,
+				message_id: this.message_id,
+				...params,
+			});
+		}
+	}
+	return Sugared;
+}

package/src/sugar/message.ts

@@ -0,0 +1,7 @@
+import { MessageContextBase } from "../generated/message.js";
+import { MessageSugar } from "./message-mixin.js";
+
+export type { ReactionInput } from "./message-mixin.js";
+
+/** MessageContext = generated base + the shared Message sugar (positional overloads + getters). */
+export class MessageContext extends MessageSugar(MessageContextBase) {}

package/src/sugar/pre-checkout-query.ts

@@ -0,0 +1,19 @@
+import type * as t from "@yaebal/types";
+import { PreCheckoutQueryContextBase } from "../generated/pre-checkout-query.js";
+
+type Extra = Omit<t.AnswerPreCheckoutQueryParams, "pre_checkout_query_id" | "ok">;
+
+/** PreCheckoutQueryContext = generated base + a positional `answer(ok)`. */
+export class PreCheckoutQueryContext extends PreCheckoutQueryContextBase {
+	/** Answer the pre-checkout query. Pass `true` to approve, `false` (+ error_message) to reject. */
+	override answer(ok: boolean, params?: Extra): Promise<boolean>;
+	override answer(
+		params: Omit<t.AnswerPreCheckoutQueryParams, "pre_checkout_query_id">,
+	): Promise<boolean>;
+	override answer(
+		a: boolean | Omit<t.AnswerPreCheckoutQueryParams, "pre_checkout_query_id">,
+		b?: Extra,
+	): Promise<boolean> {
+		return super.answer(typeof a === "boolean" ? { ok: a, ...b } : a);
+	}
+}

package/src/sugar/shipping-query.ts

@@ -0,0 +1,17 @@
+import type * as t from "@yaebal/types";
+import { ShippingQueryContextBase } from "../generated/shipping-query.js";
+
+type Extra = Omit<t.AnswerShippingQueryParams, "shipping_query_id" | "ok">;
+
+/** ShippingQueryContext = generated base + a positional `answer(ok)`. */
+export class ShippingQueryContext extends ShippingQueryContextBase {
+	/** Answer the shipping query. Pass `true`/`false` for the common case. */
+	override answer(ok: boolean, params?: Extra): Promise<boolean>;
+	override answer(params: Omit<t.AnswerShippingQueryParams, "shipping_query_id">): Promise<boolean>;
+	override answer(
+		a: boolean | Omit<t.AnswerShippingQueryParams, "shipping_query_id">,
+		b?: Extra,
+	): Promise<boolean> {
+		return super.answer(typeof a === "boolean" ? { ok: a, ...b } : a);
+	}
+}