@prajwalshete/telegram-plugin 0.0.0-stage → 0.1.0

package/dist/testing/index.d.ts

@@ -0,0 +1,7 @@
+import { silentLog } from "../adapters/console-log.js";
+import { HtmlCheck, checkTelegramHtml } from "./fake-html.js";
+import { BotRef, FakeBotInfo, FakeBotInit, FakeCall, FakeChatInit, FakeChatStatus, FakeFailure, FakeSentFile, FakeSentMessage, FakeTelegram, FakeTelegramOptions, FakeWebhook } from "./fake-telegram.js";
+import { REFERENCE_SQL_FILE, splitSqlStatements } from "./reference-sql.js";
+import { CapturedLog, TestActor, TestClock, TestPlugin, TestPluginOptions, TestUser, createTestPlugin, memoryLog } from "./test-plugin.js";
+import { FAKE_BOT_ID, FAKE_BOT_USERNAME, FAKE_GROUP_ID, UpdateBuilderOptions, UpdateBuilders, commandEntities, createUpdateBuilders, fakeBotUser, fakeUpdate, fakeUser } from "./updates.js";
+export { BotRef, type CapturedLog, FAKE_BOT_ID, FAKE_BOT_USERNAME, FAKE_GROUP_ID, FakeBotInfo, FakeBotInit, FakeCall, FakeChatInit, FakeChatStatus, FakeFailure, FakeSentFile, FakeSentMessage, FakeTelegram, FakeTelegramOptions, FakeWebhook, type HtmlCheck, REFERENCE_SQL_FILE, type TestActor, TestClock, type TestPlugin, type TestPluginOptions, type TestUser, UpdateBuilderOptions, UpdateBuilders, checkTelegramHtml, commandEntities, createTestPlugin, createUpdateBuilders, fakeBotUser, fakeUpdate, fakeUser, memoryLog, silentLog, splitSqlStatements };

package/dist/testing/index.js

@@ -0,0 +1,7 @@
+import { silentLog } from "../adapters/console-log.js";
+import { checkTelegramHtml } from "./fake-html.js";
+import { FakeTelegram } from "./fake-telegram.js";
+import { REFERENCE_SQL_FILE, splitSqlStatements } from "./reference-sql.js";
+import { TestClock, createTestPlugin, memoryLog } from "./test-plugin.js";
+import { FAKE_BOT_ID, FAKE_BOT_USERNAME, FAKE_GROUP_ID, commandEntities, createUpdateBuilders, fakeBotUser, fakeUpdate, fakeUser } from "./updates.js";
+export { FAKE_BOT_ID, FAKE_BOT_USERNAME, FAKE_GROUP_ID, FakeTelegram, REFERENCE_SQL_FILE, TestClock, checkTelegramHtml, commandEntities, createTestPlugin, createUpdateBuilders, fakeBotUser, fakeUpdate, fakeUser, memoryLog, silentLog, splitSqlStatements };

package/dist/testing/reference-sql.d.ts

@@ -0,0 +1,4 @@
+/** Package-relative path of the reference schema (`@prajwalshete/telegram-plugin/schema/reference.sql`). */
+export declare const REFERENCE_SQL_FILE = "@prajwalshete/telegram-plugin/schema/reference.sql";
+/** Splits reference SQL into statements (for `D1Database.batch` or `applyD1Migrations`). */
+export declare function splitSqlStatements(sqlText: string): string[];

package/dist/testing/reference-sql.js

@@ -0,0 +1,8 @@
+// src/testing/reference-sql.ts
+/** Package-relative path of the reference schema (`@prajwalshete/telegram-plugin/schema/reference.sql`). */
+const REFERENCE_SQL_FILE = "@prajwalshete/telegram-plugin/schema/reference.sql";
+/** Splits reference SQL into statements (for `D1Database.batch` or `applyD1Migrations`). */
+function splitSqlStatements(sqlText) {
+	return sqlText.split(/;\s*(?:\n|$)/).map((s) => s.split("\n").filter((l) => !l.trim().startsWith("--")).join("\n").trim()).filter((s) => s.length > 0);
+}
+export { REFERENCE_SQL_FILE, splitSqlStatements };

package/dist/testing/test-plugin.d.ts

@@ -0,0 +1,126 @@
+import { LogFields, LogPort } from "../ports/ports.js";
+import { TgUpdate } from "../telegram/update.js";
+import { TelegramLogLevel, TelegramPluginOptions } from "../engine/options.js";
+import { TelegramPlugin } from "../server/plugin.js";
+import { BotRef, FakeTelegram } from "./fake-telegram.js";
+import { Hono } from "hono";
+/** The actor type of `createTestPlugin` (users from `users`, group / role audiences synthesized). */
+export interface TestActor {
+  /** User id, or null for an audience actor. */
+  userId: string | null;
+  /** Role (`"group"` for a group audience without a role). */
+  role: string;
+  /** Display name (default the user id). */
+  name: string;
+  /** Preferred locale. */
+  locale?: string;
+  /** Plugin / host permission names, or `"*"` for all. */
+  permissions: readonly string[] | "*";
+}
+/** One entry of the test user table. */
+export interface TestUser {
+  /** Role (looked up in `roles` for permissions). */
+  role: string;
+  /** Display name. Default the user id. */
+  name?: string;
+  /** Preferred locale. */
+  locale?: string;
+  /** Overrides the role's permissions. */
+  permissions?: readonly string[] | "*";
+  /** Disabled users resolve to no actor (as a revoked host user would). */
+  disabled?: boolean;
+}
+/** Epoch-ms clock that only moves when told to; `sleep` advances it (so drain pacing runs instantly). */
+export declare class TestClock {
+  #private;
+  constructor(start?: number);
+  /** Current time (epoch ms UTC). */
+  now: () => number;
+  /** Moves the clock forward by `ms` (negative values are ignored); returns the new time. */
+  advance(ms: number): number;
+  /** Sets the clock to `ms` (may go backwards). */
+  set(ms: number): void;
+  /** Advances the clock by `ms` and resolves at once. */
+  sleep: (ms: number) => Promise<void>;
+}
+/** One line kept by `memoryLog`. */
+export interface CapturedLog {
+  /** Log level. */
+  level: "debug" | "info" | "warn" | "error";
+  /** Event name (`tg.send`, …). */
+  evt: string;
+  /** Structured fields. */
+  fields: LogFields;
+}
+/** A logger that keeps every line (to assert on events, or to scan for secrets). */
+export declare function memoryLog(): LogPort & {
+  lines: CapturedLog[];
+  text(): string;
+};
+/** Options of `createTestPlugin`. */
+export interface TestPluginOptions<E> {
+  /** Worker env with the D1 binding (`env.DB`), with the plugin's reference SQL applied. */
+  env: E;
+  /** Bot API fake to use. Default a new `FakeTelegram` on `clock`. */
+  fake?: FakeTelegram;
+  /** Clock to use. Default a new `TestClock` (2026-10-25 09:00 UTC). */
+  clock?: TestClock;
+  /** Role → permissions. Default: `owner` has everything, `staff` only `telegram.self.link`. */
+  roles?: Record<string, readonly string[] | "*">;
+  /** User id → user. Default: `owner-1` (owner) and `staff-1` (staff). */
+  users?: Record<string, TestUser>;
+  /** Default `https://app.example.com/api/telegram`; null = polling mode. */
+  publicBaseUrl?: string | null;
+  /** `env.appEnv`. Default `"test"` (the dev polling route is available). */
+  appEnv?: string;
+  /** Pass the queue binding to use the queue transport. */
+  queue?: Queue<unknown>;
+  /** Pass a TelegramBotDO namespace to use the DO transport. */
+  botDO?: DurableObjectNamespace;
+  /** `TELEGRAM_KEYRING` JSON. Default a fresh `generateKeyringSecret({ kid: "k1" })`. */
+  keyring?: string;
+  /** Default `silentLog` (tests stay quiet); pass `memoryLog()` to assert on events. */
+  log?: LogPort | TelegramLogLevel;
+  /** Anything else `createTelegramPlugin` accepts (features, limits, hooks, registries…). */
+  options?: Partial<Omit<TelegramPluginOptions<E, TestActor>, "env" | "ports">> & {
+    ports?: Partial<TelegramPluginOptions<E, TestActor>["ports"]>;
+  };
+}
+/** What `createTestPlugin` returns. */
+export interface TestPlugin<E> {
+  /** The real plugin, wired to the fakes. */
+  plugin: TelegramPlugin<E, TestActor>;
+  /** The Bot API fake (inspect sent messages, script errors). */
+  fake: FakeTelegram;
+  /** The controllable clock. */
+  clock: TestClock;
+  /** The keyring secret in use. */
+  keyring: string;
+  /** The user table (mutate it to disable users or change roles). */
+  users: Record<string, TestUser>;
+  /** Calls the plugin routes as a user (header `x-test-user`), with an execution context `flush()` awaits. */
+  request(path: string, init?: RequestInit & {
+    as?: string | null;
+    json?: unknown;
+  }): Promise<Response>;
+  /** Delivers an update the way Telegram would (registered webhook URL + secret header). */
+  webhook(update: TgUpdate, o?: {
+    bot?: BotRef;
+    secret?: string | null;
+  }): Promise<Response>;
+  /** The host app the plugin routes are mounted on (`/api/telegram`). */
+  host: Hono;
+  /** Waits for all `waitUntil` work (webhook processing, kicks). */
+  flush(): Promise<void>;
+  /** The execution context passed to every request (collects `waitUntil` work for `flush()`). */
+  exec: ExecutionContext;
+  /** The live actor of a user id, or null when unknown or disabled. */
+  actor(userId: string): TestActor | null;
+}
+/**
+ * A plugin on FakeTelegram (no network), a `TestClock` and a small user/role table. Callers pick the user with
+ * `request(path, { as: userId })`; the `x-test-user` header is the test session. Test use only.
+ */
+export declare function createTestPlugin<E extends {
+  DB: D1Database;
+}>(opts: TestPluginOptions<E>): TestPlugin<E>;

package/dist/testing/test-plugin.js

@@ -0,0 +1,182 @@
+import { silentLog } from "../adapters/console-log.js";
+import { generateKeyringSecret } from "../adapters/keyring.js";
+import { fetchTelegram } from "../telegram/client.js";
+import { createTelegramPlugin } from "../server/plugin.js";
+import { FakeTelegram } from "./fake-telegram.js";
+import { Hono } from "hono";
+// src/testing/test-plugin.ts
+const BASE = "https://app.example.com/api/telegram";
+/** Epoch-ms clock that only moves when told to; `sleep` advances it (so drain pacing runs instantly). */
+var TestClock = class {
+	#now;
+	constructor(start = Date.UTC(2026, 9, 25, 9, 0, 0)) {
+		this.#now = start;
+	}
+	/** Current time (epoch ms UTC). */
+	now = () => this.#now;
+	/** Moves the clock forward by `ms` (negative values are ignored); returns the new time. */
+	advance(ms) {
+		this.#now += Math.max(0, ms);
+		return this.#now;
+	}
+	/** Sets the clock to `ms` (may go backwards). */
+	set(ms) {
+		this.#now = ms;
+	}
+	/** Advances the clock by `ms` and resolves at once. */
+	sleep = async (ms) => {
+		this.advance(ms);
+	};
+};
+/** A logger that keeps every line (to assert on events, or to scan for secrets). */
+function memoryLog() {
+	const lines = [];
+	const add = (level) => (evt, fields = {}) => {
+		lines.push({
+			level,
+			evt,
+			fields
+		});
+	};
+	return {
+		lines,
+		debug: add("debug"),
+		info: add("info"),
+		warn: add("warn"),
+		error: add("error"),
+		text: () => lines.map((l) => JSON.stringify(l)).join("\n")
+	};
+}
+const DEFAULT_ROLES = {
+	owner: "*",
+	staff: ["telegram.self.link"]
+};
+const DEFAULT_USERS = {
+	"owner-1": {
+		role: "owner",
+		name: "Owner One"
+	},
+	"staff-1": {
+		role: "staff",
+		name: "Staff One"
+	}
+};
+/**
+* A plugin on FakeTelegram (no network), a `TestClock` and a small user/role table. Callers pick the user with
+* `request(path, { as: userId })`; the `x-test-user` header is the test session. Test use only.
+*/
+function createTestPlugin(opts) {
+	const clock = opts.clock ?? new TestClock();
+	const fake = opts.fake ?? new FakeTelegram({ now: () => clock.now() });
+	const roles = {
+		...DEFAULT_ROLES,
+		...opts.roles
+	};
+	const users = {
+		...DEFAULT_USERS,
+		...opts.users
+	};
+	const keyring = opts.keyring ?? generateKeyringSecret({ kid: "k1" });
+	const permsOf = (role, override) => override ?? roles[role] ?? [];
+	const actor = (userId) => {
+		const u = users[userId];
+		if (!u || u.disabled) return null;
+		return {
+			userId,
+			role: u.role,
+			name: u.name ?? userId,
+			permissions: permsOf(u.role, u.permissions),
+			...u.locale ? { locale: u.locale } : {}
+		};
+	};
+	const audienceActor = (a) => "role" in a ? {
+		userId: null,
+		role: a.role,
+		name: a.role,
+		permissions: permsOf(a.role)
+	} : {
+		userId: null,
+		role: "group",
+		name: "group",
+		permissions: []
+	};
+	const pending = [];
+	const exec = {
+		waitUntil(p) {
+			pending.push(p);
+		},
+		passThroughOnException() {},
+		props: {}
+	};
+	const extra = opts.options ?? {};
+	const plugin = createTelegramPlugin({
+		...extra,
+		env: (env) => ({
+			db: env.DB,
+			keyring,
+			queue: opts.queue,
+			botDO: opts.botDO,
+			publicBaseUrl: opts.publicBaseUrl === null ? void 0 : opts.publicBaseUrl ?? BASE,
+			appEnv: opts.appEnv ?? "test"
+		}),
+		ports: {
+			actor: {
+				fromRequest: (c) => {
+					const id = c.req.header("x-test-user");
+					return id ? actor(id) : null;
+				},
+				forUser: (id) => actor(id),
+				forAudience: (a) => audienceActor(a),
+				describe: (a) => ({
+					userId: a.userId,
+					role: a.role,
+					name: a.name,
+					locale: a.locale
+				})
+			},
+			authorize: (a, permission) => a.permissions === "*" || a.permissions.includes(permission),
+			clock: {
+				now: clock.now,
+				sleep: clock.sleep
+			},
+			log: opts.log ?? silentLog,
+			...extra.ports
+		},
+		telegram: extra.telegram ?? fetchTelegram({ fetch: fake.fetch })
+	});
+	const host = new Hono();
+	host.route("/api/telegram", plugin.routes);
+	return {
+		plugin,
+		host,
+		fake,
+		clock,
+		keyring,
+		users,
+		exec,
+		actor,
+		async request(path, init = {}) {
+			const { as, json, ...rest } = init;
+			const headers = new Headers(rest.headers);
+			if (as) headers.set("x-test-user", as);
+			let body = rest.body;
+			if (json !== void 0) {
+				headers.set("content-type", "application/json");
+				body = JSON.stringify(json);
+			}
+			const url = path.startsWith("http") ? path : `${BASE}${path}`;
+			return host.fetch(new Request(url, {
+				...rest,
+				headers,
+				...body === void 0 ? {} : { body }
+			}), opts.env, exec);
+		},
+		async webhook(update, o = {}) {
+			return host.fetch(fake.webhookRequest(update, o), opts.env, exec);
+		},
+		async flush() {
+			while (pending.length > 0) await Promise.allSettled(pending.splice(0));
+		}
+	};
+}
+export { TestClock, createTestPlugin, memoryLog };

package/dist/testing/updates.d.ts

@@ -0,0 +1,100 @@
+import { TgMessageEntity, TgUpdate, TgUser } from "../telegram/update.js";
+/** Username of the default fake bot. */
+export declare const FAKE_BOT_USERNAME = "FakeTestBot";
+/** Telegram id of the default fake bot. */
+export declare const FAKE_BOT_ID = 7000000001;
+/** Default supergroup chat id in the builders. */
+export declare const FAKE_GROUP_ID = -1001234567890;
+/** A Telegram user (default: Asha, id 1001, `en`) with overrides. */
+export declare function fakeUser(overrides?: Partial<TgUser>): TgUser;
+/** The fake bot as a Telegram user (`is_bot: true`). */
+export declare function fakeBotUser(overrides?: Partial<TgUser>): TgUser;
+type ChatType = "private" | "group" | "supergroup" | "channel";
+/** `bot_command` entity for text that starts with `/cmd` or `/cmd@bot`. */
+export declare function commandEntities(text: string): TgMessageEntity[] | undefined;
+/** Options for {@link createUpdateBuilders}. */
+export interface UpdateBuilderOptions {
+  /** First update_id (default 10000). */
+  startId?: number;
+  /** Clock for `date` fields (epoch ms). */
+  now?: () => number;
+  botUsername?: string;
+  botId?: number;
+}
+interface MessageBase {
+  from?: TgUser;
+  chatId?: number;
+  threadId?: number;
+}
+/** Builders for realistic updates (commands, text, callbacks, media, membership) with increasing `update_id` / `message_id`. */
+export declare function createUpdateBuilders(opts?: UpdateBuilderOptions): {
+  bot: {
+    [x: string]: unknown;
+    id: number;
+    is_bot: boolean;
+    first_name: string;
+    last_name?: string | undefined;
+    username?: string | undefined;
+    language_code?: string | undefined;
+  };
+  /** The id the next builder will use. */
+  peekUpdateId: () => number;
+  /** A private-chat text (commands get a `bot_command` entity automatically). */
+  privateText(text: string, o?: MessageBase): TgUpdate;
+  /** Plain text in a group (only replies to the bot reach a privacy-mode bot). */
+  groupText(text: string, o?: MessageBase & {
+    chatType?: "group" | "supergroup";
+    title?: string;
+  }): TgUpdate;
+  /** `/command@bot args` in a group. `mention: false` sends a bare `/command`. */
+  groupCommand(command: string, o?: MessageBase & {
+    args?: string;
+    mention?: boolean | string;
+    chatType?: "group" | "supergroup";
+    title?: string;
+    isForum?: boolean;
+  }): TgUpdate;
+  /** Button tap. `inaccessible` gives a message with `date: 0` (too old for the bot to read). */
+  callback(data: string, o?: MessageBase & {
+    messageId?: number;
+    chatType?: ChatType;
+    inaccessible?: boolean;
+  }): TgUpdate;
+  /** The bot's own membership changed (added, removed, blocked by a user, promoted). */
+  myChatMember(o: {
+    chatId?: number;
+    chatType?: ChatType;
+    title?: string;
+    from?: TgUser;
+    oldStatus?: string;
+    newStatus: string;
+  }): TgUpdate;
+  /**
+   * Group → supergroup migration. `side: "to"` (default) is the service message in the old group with
+   * `migrate_to_chat_id`; `side: "from"` is the one in the new supergroup with `migrate_from_chat_id`.
+   */
+  migrate(o: {
+    fromChatId: number;
+    toChatId: number;
+    title?: string;
+    side?: "to" | "from";
+    from?: TgUser;
+  }): TgUpdate;
+  photo(o?: MessageBase & {
+    fileId?: string;
+    caption?: string;
+    chatType?: ChatType;
+  }): TgUpdate;
+  document(o?: MessageBase & {
+    fileId?: string;
+    fileName?: string;
+    mime?: string;
+    caption?: string;
+    chatType?: ChatType;
+  }): TgUpdate;
+};
+/** The builders returned by {@link createUpdateBuilders}. */
+export type UpdateBuilders = ReturnType<typeof createUpdateBuilders>;
+/** Shared default builders (ids keep increasing across a test file). */
+export declare const fakeUpdate: UpdateBuilders;
+export {};

package/dist/testing/updates.js

@@ -0,0 +1,212 @@
+// src/testing/updates.ts
+/** Username of the default fake bot. */
+const FAKE_BOT_USERNAME = "FakeTestBot";
+/** Telegram id of the default fake bot. */
+const FAKE_BOT_ID = 7000000001;
+/** Default supergroup chat id in the builders. */
+const FAKE_GROUP_ID = -0xe91e3b12d2;
+/** A Telegram user (default: Asha, id 1001, `en`) with overrides. */
+function fakeUser(overrides = {}) {
+	return {
+		id: 1001,
+		is_bot: false,
+		first_name: "Asha",
+		username: "asha",
+		language_code: "en",
+		...overrides
+	};
+}
+/** The fake bot as a Telegram user (`is_bot: true`). */
+function fakeBotUser(overrides = {}) {
+	return {
+		id: FAKE_BOT_ID,
+		is_bot: true,
+		first_name: "Fake Test",
+		username: FAKE_BOT_USERNAME,
+		...overrides
+	};
+}
+function chatOf(id, type, from, title, isForum) {
+	if (type === "private") return {
+		id,
+		type,
+		first_name: from.first_name,
+		...from.username === void 0 ? {} : { username: from.username }
+	};
+	return {
+		id,
+		type,
+		title: title ?? "Site Team",
+		...isForum ? { is_forum: true } : {}
+	};
+}
+/** `bot_command` entity for text that starts with `/cmd` or `/cmd@bot`. */
+function commandEntities(text) {
+	const m = /^\/[A-Za-z0-9_]{1,32}(?:@[A-Za-z0-9_]{3,64})?(?=\s|$)/.exec(text);
+	return m ? [{
+		type: "bot_command",
+		offset: 0,
+		length: m[0].length
+	}] : void 0;
+}
+/** Builders for realistic updates (commands, text, callbacks, media, membership) with increasing `update_id` / `message_id`. */
+function createUpdateBuilders(opts = {}) {
+	let nextUpdate = opts.startId ?? 1e4;
+	let nextMessage = 1;
+	let nextQuery = 1;
+	const now = opts.now ?? (() => Date.now());
+	const botUsername = opts.botUsername ?? "FakeTestBot";
+	const bot = fakeBotUser({
+		id: opts.botId ?? 7000000001,
+		username: botUsername
+	});
+	const date = () => Math.floor(now() / 1e3);
+	function message(chat, from, extra = {}) {
+		const { threadId, ...rest } = extra;
+		return {
+			message_id: nextMessage++,
+			date: date(),
+			chat,
+			from,
+			...threadId === void 0 ? {} : {
+				message_thread_id: threadId,
+				is_topic_message: true
+			},
+			...rest
+		};
+	}
+	const update = (body) => ({
+		update_id: nextUpdate++,
+		...body
+	});
+	function withText(text) {
+		const entities = commandEntities(text);
+		return entities ? {
+			text,
+			entities
+		} : { text };
+	}
+	return {
+		bot,
+		/** The id the next builder will use. */
+		peekUpdateId: () => nextUpdate,
+		/** A private-chat text (commands get a `bot_command` entity automatically). */
+		privateText(text, o = {}) {
+			const from = o.from ?? fakeUser();
+			return update({ message: message(chatOf(o.chatId ?? from.id, "private", from), from, {
+				...withText(text),
+				threadId: o.threadId
+			}) });
+		},
+		/** Plain text in a group (only replies to the bot reach a privacy-mode bot). */
+		groupText(text, o = {}) {
+			const from = o.from ?? fakeUser();
+			const chat = chatOf(o.chatId ?? -0xe91e3b12d2, o.chatType ?? "supergroup", from, o.title);
+			return update({ message: message(chat, from, {
+				...withText(text),
+				threadId: o.threadId
+			}) });
+		},
+		/** `/command@bot args` in a group. `mention: false` sends a bare `/command`. */
+		groupCommand(command, o = {}) {
+			const from = o.from ?? fakeUser();
+			const text = `/${command}${o.mention === false ? "" : `@${typeof o.mention === "string" ? o.mention : botUsername}`}${o.args ? ` ${o.args}` : ""}`;
+			const chat = chatOf(o.chatId ?? -0xe91e3b12d2, o.chatType ?? "supergroup", from, o.title, o.isForum);
+			return update({ message: message(chat, from, {
+				...withText(text),
+				threadId: o.threadId
+			}) });
+		},
+		/** Button tap. `inaccessible` gives a message with `date: 0` (too old for the bot to read). */
+		callback(data, o = {}) {
+			const from = o.from ?? fakeUser();
+			const chat = chatOf(o.chatId ?? from.id, o.chatType ?? "private", from);
+			const msg = o.inaccessible ? {
+				message_id: o.messageId ?? nextMessage++,
+				date: 0,
+				chat
+			} : {
+				...message(chat, bot, {
+					text: "…",
+					threadId: o.threadId
+				}),
+				...o.messageId === void 0 ? {} : { message_id: o.messageId }
+			};
+			return update({ callback_query: {
+				id: `cbq-${nextQuery++}`,
+				from,
+				chat_instance: `ci${chat.id}`,
+				message: msg,
+				data
+			} });
+		},
+		/** The bot's own membership changed (added, removed, blocked by a user, promoted). */
+		myChatMember(o) {
+			const from = o.from ?? fakeUser();
+			const type = o.chatType ?? "supergroup";
+			const chat = chatOf(o.chatId ?? (type === "private" ? from.id : -0xe91e3b12d2), type, from, o.title);
+			return update({ my_chat_member: {
+				chat,
+				from,
+				date: date(),
+				old_chat_member: {
+					status: o.oldStatus ?? (o.newStatus === "member" ? "left" : "member"),
+					user: bot
+				},
+				new_chat_member: {
+					status: o.newStatus,
+					user: bot
+				}
+			} });
+		},
+		/**
+		* Group → supergroup migration. `side: "to"` (default) is the service message in the old group with
+		* `migrate_to_chat_id`; `side: "from"` is the one in the new supergroup with `migrate_from_chat_id`.
+		*/
+		migrate(o) {
+			const from = o.from ?? fakeUser();
+			return o.side === "from" ? update({ message: message(chatOf(o.toChatId, "supergroup", from, o.title), from, { migrate_from_chat_id: o.fromChatId }) }) : update({ message: message(chatOf(o.fromChatId, "group", from, o.title), from, { migrate_to_chat_id: o.toChatId }) });
+		},
+		photo(o = {}) {
+			const from = o.from ?? fakeUser();
+			const fileId = o.fileId ?? `fake-photo-${nextMessage}`;
+			const chat = chatOf(o.chatId ?? from.id, o.chatType ?? "private", from);
+			return update({ message: message(chat, from, {
+				photo: [{
+					file_id: `${fileId}-s`,
+					file_unique_id: `${fileId}-us`,
+					width: 90,
+					height: 90,
+					file_size: 1200
+				}, {
+					file_id: fileId,
+					file_unique_id: `${fileId}-u`,
+					width: 1280,
+					height: 960,
+					file_size: 12e4
+				}],
+				...o.caption === void 0 ? {} : { caption: o.caption },
+				threadId: o.threadId
+			}) });
+		},
+		document(o = {}) {
+			const from = o.from ?? fakeUser();
+			const fileId = o.fileId ?? `fake-doc-${nextMessage}`;
+			const chat = chatOf(o.chatId ?? from.id, o.chatType ?? "private", from);
+			return update({ message: message(chat, from, {
+				document: {
+					file_id: fileId,
+					file_unique_id: `${fileId}-u`,
+					file_name: o.fileName ?? "site-photo.pdf",
+					mime_type: o.mime ?? "application/pdf",
+					file_size: 2048
+				},
+				...o.caption === void 0 ? {} : { caption: o.caption },
+				threadId: o.threadId
+			}) });
+		}
+	};
+}
+/** Shared default builders (ids keep increasing across a test file). */
+const fakeUpdate = createUpdateBuilders();
+export { FAKE_BOT_ID, FAKE_BOT_USERNAME, FAKE_GROUP_ID, commandEntities, createUpdateBuilders, fakeBotUser, fakeUpdate, fakeUser };