@yaebal/test 0.1.0 → 0.2.1

package/src/api.test.ts

@@ -0,0 +1,180 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { TelegramError } from "@yaebal/core";
+import { apiError, isApiErrorSentinel, mockApi, TestApiError } from "./api.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.equal(calls.length, 3);
+	assert.equal(calls[0]?.method, "sendMessage");
+	assert.deepEqual(calls[0]?.params, { chat_id: 1, text: "hi" });
+	assert.deepEqual(calls[0]?.result, { message_id: 1 });
+	assert.equal(typeof calls[0]?.at, "number");
+});
+
+test("mockApi hook registrars are chainable", () => {
+	const { api } = mockApi();
+	assert.equal(
+		api.before(() => undefined),
+		api,
+	);
+	assert.equal(
+		api.after((_m, _p, r) => r),
+		api,
+	);
+});
+
+test("mockApi auto-increments message_id across send* calls", async () => {
+	const { api } = mockApi();
+
+	const first = await api.sendMessage({ chat_id: 1, text: "a" });
+	const second = await api.sendMessage({ chat_id: 1, text: "b" });
+
+	assert.deepEqual(first, { message_id: 1 });
+	assert.deepEqual(second, { message_id: 2 });
+});
+
+test("mockApi results: static override replaces the built-in default", async () => {
+	const { api } = mockApi({ results: { sendMessage: { message_id: 99 } } });
+
+	assert.deepEqual(await api.sendMessage({ chat_id: 1 }), { message_id: 99 });
+});
+
+test("mockApi results: an Error value makes the call throw", async () => {
+	const { api } = mockApi({
+		results: { sendMessage: new TelegramError("sendMessage", 400, "Bad Request") },
+	});
+
+	await assert.rejects(api.sendMessage({ chat_id: 1 }), TelegramError);
+});
+
+test("mockApi results: a function sees params and a running attempt count", async () => {
+	const { api } = mockApi({
+		results: {
+			sendMessage: (params: Record<string, unknown> | undefined, attempt: number) =>
+				attempt <= 2
+					? new TelegramError("sendMessage", 429, "Too Many Requests", { retry_after: 0 })
+					: { message_id: 1, echo: params?.text },
+		},
+	});
+
+	api.onError((_m, _e, attempt) => (attempt <= 2 ? { retry: true } : undefined));
+
+	const result = await api.sendMessage({ chat_id: 1, text: "hi" });
+	assert.deepEqual(result, { message_id: 1, echo: "hi" });
+});
+
+test("onApi sets a permanent override; reset() clears calls and counters but keeps it", async () => {
+	const { api, calls, onApi, reset } = mockApi();
+
+	await api.sendMessage({ chat_id: 1 });
+	onApi("sendMessage", { message_id: 42 });
+	assert.deepEqual(await api.sendMessage({ chat_id: 1 }), { message_id: 42 });
+	assert.equal(calls.length, 2);
+
+	reset();
+	assert.equal(calls.length, 0);
+	assert.deepEqual(await api.sendMessage({ chat_id: 1 }), { message_id: 42 });
+});
+
+test("onApi with { times } is one-shot, then falls back to the previous permanent reply", async () => {
+	const { api, onApi } = mockApi({ results: { sendMessage: { message_id: 1 } } });
+
+	onApi("sendMessage", apiError(429, "Too Many Requests"), { times: 1 });
+
+	await assert.rejects(api.sendMessage({ chat_id: 1 }), TestApiError);
+	assert.deepEqual(await api.sendMessage({ chat_id: 1 }), { message_id: 1 });
+});
+
+test("onApi { times: 2 } is consumed over exactly two calls", async () => {
+	const { api, onApi } = mockApi();
+
+	onApi("getChat", { id: 1, type: "private", stale: true }, { times: 2 });
+	onApi("getChat", { id: 1, type: "private", stale: false });
+
+	assert.equal((await api.call<{ stale: boolean }>("getChat")).stale, true);
+	assert.equal((await api.call<{ stale: boolean }>("getChat")).stale, true);
+	assert.equal((await api.call<{ stale: boolean }>("getChat")).stale, false);
+});
+
+test("offApi drops a method's override, or every override with no argument", async () => {
+	const { api, onApi, offApi } = mockApi();
+
+	onApi("sendMessage", { message_id: 99 });
+	offApi("sendMessage");
+	assert.deepEqual(await api.sendMessage({ chat_id: 1 }), { message_id: 1 });
+
+	onApi("getMe", { id: 7, is_bot: true, first_name: "x" });
+	offApi();
+	assert.deepEqual(await api.getMe(), { id: 1, is_bot: true, first_name: "bot", username: "bot" });
+});
+
+test("apiError() produces a sentinel that throws a TestApiError carrying parameters", async () => {
+	const sentinel = apiError(429, "Too Many Requests", { retry_after: 30 });
+	assert.ok(isApiErrorSentinel(sentinel));
+
+	const { api } = mockApi({ results: { sendMessage: sentinel } });
+
+	await assert.rejects(api.sendMessage({ chat_id: 1 }), (error: unknown) => {
+		assert.ok(error instanceof TestApiError);
+		assert.ok(error instanceof TelegramError);
+		assert.equal(error.code, 429);
+		assert.deepEqual(error.parameters, { retry_after: 30 });
+		return true;
+	});
+});
+
+test("strictApi throws for methods with no builtin default and no override", async () => {
+	const { api } = mockApi({ strictApi: true });
+
+	await assert.rejects(api.call("getChatMember"), /no stub for "getChatMember"/);
+	assert.deepEqual(await api.sendMessage({ chat_id: 1 }), { message_id: 1 });
+});
+
+test("mockApi.lastCall and callsTo filter recorded calls", async () => {
+	const { api, lastCall, callsTo } = mockApi();
+
+	await api.sendMessage({ chat_id: 1, text: "a" });
+	await api.answerCallbackQuery({ callback_query_id: "1" });
+	await api.sendMessage({ chat_id: 1, text: "b" });
+
+	assert.equal(lastCall()?.method, "sendMessage");
+	assert.equal(lastCall("answerCallbackQuery")?.method, "answerCallbackQuery");
+	assert.equal(lastCall("sendMessage")?.params?.text, "b");
+	assert.equal(callsTo("sendMessage").length, 2);
+});
+
+test("mockApi hooks actually run: before rewrites params, after rewrites result", async () => {
+	const { api } = mockApi();
+
+	api.before((_method, params) => ({ ...params, injected: true }));
+	api.after((_method, _params, result) => ({ ...(result as object), tagged: true }));
+
+	const result = await api.sendMessage({ chat_id: 1 });
+
+	assert.deepEqual(result, { message_id: 1, tagged: true });
+});
+
+test("reply_markup builder instances are normalized to plain JSON on recorded calls", async () => {
+	const { api, calls } = mockApi();
+
+	await api.sendMessage({
+		chat_id: 1,
+		text: "hi",
+		reply_markup: { toJSON: () => ({ inline_keyboard: [[{ text: "ok", callback_data: "ok" }]] }) },
+	});
+
+	assert.deepEqual(calls[0]?.params?.reply_markup, {
+		inline_keyboard: [[{ text: "ok", callback_data: "ok" }]],
+	});
+});

package/src/api.ts

@@ -0,0 +1,281 @@
+import {
+	type AfterHook,
+	type Api,
+	type BeforeHook,
+	type ErrorAction,
+	type ErrorHook,
+	type ResponseParameters,
+	TelegramError,
+} from "@yaebal/core";
+import { normalizeParams } from "./normalize.js";
+
+/** a single recorded api call: the method, the params it was given, and how it resolved. */
+export interface RecordedCall {
+	method: string;
+	params: Record<string, unknown> | undefined;
+	/** the resolved result, if the call succeeded. */
+	result?: unknown;
+	/** the thrown error, if the call failed (and no `onError` hook rescued it). */
+	error?: unknown;
+	/** ms since epoch when the call was made — honors an installed {@link TestClock}. */
+	at: number;
+}
+
+/** a canned result for one method: a static value, an {@link ApiErrorSentinel}/`Error`, or a function of `(params, attempt)`. */
+export type MockResult =
+	| unknown
+	| Error
+	| ApiErrorSentinel
+	| ((params: Record<string, unknown> | undefined, attempt: number) => unknown);
+
+/** the shape `apiError(...)` returns — a sentinel telling the mock to throw a {@link TestApiError}. */
+export interface ApiErrorSentinel {
+	readonly __yaebalApiError: true;
+	code: number;
+	description: string;
+	parameters?: ResponseParameters;
+}
+
+/**
+ * simulate a real Telegram Bot API error response — the bot sees exactly what it would see
+ * from the real api: a thrown {@link TestApiError} (a {@link TelegramError} subclass).
+ *
+ * @example
+ * env.onApi("sendMessage", apiError(403, "Forbidden: bot was blocked by the user"));
+ * env.onApi("sendMessage", apiError(429, "Too Many Requests", { retry_after: 30 }));
+ */
+export function apiError(
+	code: number,
+	description: string,
+	parameters?: ResponseParameters,
+): ApiErrorSentinel {
+	return { __yaebalApiError: true, code, description, parameters };
+}
+
+/** typeguard for a stored `apiError(...)` sentinel. */
+export function isApiErrorSentinel(value: unknown): value is ApiErrorSentinel {
+	return typeof value === "object" && value !== null && "__yaebalApiError" in value;
+}
+
+/** a {@link TelegramError} carrying the optional `parameters` bag (e.g. `retry_after`) real errors ship. */
+export class TestApiError extends TelegramError {
+	constructor(method: string, code: number, description: string, parameters?: ResponseParameters) {
+		super(method, code, description, parameters);
+	}
+}
+
+/** options accepted by `{ times }` overrides: one-shot (or N-shot) replies. */
+export interface OnApiOptions {
+	/** consume this override for exactly `times` calls, then fall back to the next queued/permanent reply. default: permanent (never expires). */
+	times?: number;
+}
+
+export interface MockApiOptions {
+	/** per-method canned results/errors, keyed by method name — seeds the permanent override, same as calling `onApi(method, result)` for each entry. */
+	results?: Record<string, MockResult>;
+	/** throw instead of falling back to `{}` when a method has no builtin default and no override registered. catches "forgot to stub this" in tests that care. default `false`. */
+	strictApi?: boolean;
+	/** clock to timestamp recorded calls with; defaults to the real `Date.now`. */
+	now?: () => number;
+}
+
+/** result of {@link mockApi}: the fake `api`, its recorded calls, and inspection/stubbing helpers. */
+export interface MockApi {
+	api: Api;
+	calls: RecordedCall[];
+	/** hooks registered on `api` via `before`/`after`/`onError` — inspect them or invoke them yourself. */
+	hooks: { before: BeforeHook[]; after: AfterHook[]; onError: ErrorHook[] };
+	/** the most recent recorded call, optionally filtered to a method. */
+	lastCall(method?: string): RecordedCall | undefined;
+	/** every recorded call to a given method, in call order. */
+	callsTo(method: string): RecordedCall[];
+	/** override a method's reply. permanent unless `opts.times` is given (then it's consumed after `times` calls and the previous permanent, if any, resumes). */
+	onApi(method: string, reply: MockResult, opts?: OnApiOptions): void;
+	/** drop a method's overrides (or every method's, if none given) — reverts to the builtin default. */
+	offApi(method?: string): void;
+	/** clear recorded calls and per-method attempt counters. keeps hooks and overrides. */
+	reset(): void;
+}
+
+/** default results for known methods; everything else resolves to `{}` (or throws, with `strictApi`). */
+const STUBBED_METHODS = new Set(["getMe", "answerCallbackQuery"]);
+
+function builtinResult(method: string, nextMessageId: () => number): unknown {
+	if (method.startsWith("send") || method === "copyMessage" || method === "forwardMessage") {
+		return { message_id: nextMessageId() };
+	}
+
+	if (method === "answerCallbackQuery") return true;
+	if (method === "getMe") return { id: 1, is_bot: true, first_name: "bot", username: "bot" };
+
+	return {};
+}
+
+function hasBuiltin(method: string): boolean {
+	return (
+		method.startsWith("send") ||
+		method === "copyMessage" ||
+		method === "forwardMessage" ||
+		STUBBED_METHODS.has(method)
+	);
+}
+
+interface QueuedReply {
+	reply: MockResult;
+	remaining: number;
+}
+
+interface MethodOverride {
+	queue: QueuedReply[];
+	permanent?: MockResult;
+}
+
+/**
+ * a fake {@link Api} whose every method records `{ method, params, result | error, at }` into
+ * `calls` and resolves to a sensible default (auto-incrementing `message_id` for `send*`, `true`
+ * for `answerCallbackQuery`, `{}` otherwise) — or to whatever `onApi`/`options.results` says.
+ * `before`/`after`/`onError` are real hook registrars (not no-ops): register a hook the same way
+ * you would on the production `Api` and it actually runs on each attempt, including retries requested by an
+ * `onError` hook. the mock never actually waits on a requested `delayMs` — retries settle
+ * instantly, so tests stay fast (pair with {@link installTestClock} if the code under test
+ * schedules the retry itself via `setTimeout`).
+ */
+export function mockApi(options: MockApiOptions = {}): MockApi {
+	const calls: RecordedCall[] = [];
+	const overrides = new Map<string, MethodOverride>();
+	const attempts = new Map<string, number>();
+	const now = options.now ?? (() => Date.now());
+	let nextMessageId = 1;
+
+	for (const [method, reply] of Object.entries(options.results ?? {})) {
+		overrides.set(method, { queue: [], permanent: reply });
+	}
+
+	const hooks = {
+		before: [] as BeforeHook[],
+		after: [] as AfterHook[],
+		onError: [] as ErrorHook[],
+	};
+
+	function resolveReply(method: string, params: Record<string, unknown> | undefined): unknown {
+		const attempt = (attempts.get(method) ?? 0) + 1;
+		attempts.set(method, attempt);
+
+		const override = overrides.get(method);
+		let reply: MockResult | undefined;
+
+		if (override?.queue.length) {
+			const head = override.queue[0] as QueuedReply;
+			head.remaining--;
+			reply = head.reply;
+			if (head.remaining <= 0) override.queue.shift();
+		} else if (override && "permanent" in override) {
+			reply = override.permanent;
+		} else if (options.strictApi && !hasBuiltin(method)) {
+			throw new Error(
+				`mockApi: no stub for "${method}" — register one with onApi("${method}", ...), or disable strictApi`,
+			);
+		} else {
+			return builtinResult(method, () => nextMessageId++);
+		}
+
+		if (typeof reply === "function") {
+			return (reply as (p: typeof params, a: number) => unknown)(params, attempt);
+		}
+
+		if (isApiErrorSentinel(reply)) {
+			return new TestApiError(method, reply.code, reply.description, reply.parameters);
+		}
+
+		return reply;
+	}
+
+	const call = async (method: string, rawParams?: Record<string, unknown>): Promise<never> => {
+		for (let attempt = 1; ; attempt++) {
+			let p = normalizeParams(rawParams);
+			for (const hook of hooks.before) {
+				const next = await hook(method, p);
+				if (next !== undefined) p = next;
+			}
+
+			let result: unknown;
+
+			try {
+				result = resolveReply(method, p);
+				if (result instanceof Error) throw result;
+			} catch (error) {
+				let retry: ErrorAction | undefined;
+				for (const hook of hooks.onError) {
+					const action = await hook(method, error, attempt, p);
+					if (!retry && action?.retry) {
+						retry = action;
+					}
+				}
+
+				calls.push({ method, params: p, error, at: now() });
+				if (!retry) throw error;
+				continue; // the mock never actually waits on retry.delayMs
+			}
+
+			for (const hook of hooks.after) {
+				const next = await hook(method, p, result);
+				if (next !== undefined) result = next;
+			}
+
+			calls.push({ method, params: p, result, at: now() });
+			return result as never;
+		}
+	};
+
+	const registrar: Record<string, unknown> = {
+		call: (method: string, params?: Record<string, unknown>) => call(method, params),
+		fileUrl: (filePath: string) => `https://example.invalid/file/${filePath}`,
+		before(hook: BeforeHook) {
+			hooks.before.push(hook);
+			return api;
+		},
+		after(hook: AfterHook) {
+			hooks.after.push(hook);
+			return api;
+		},
+		onError(hook: ErrorHook) {
+			hooks.onError.push(hook);
+			return api;
+		},
+	};
+
+	const api = new Proxy(registrar, {
+		get(obj, prop: string) {
+			if (prop in obj) return obj[prop];
+
+			const method = (params?: Record<string, unknown>) => call(prop, params);
+			obj[prop] = method;
+
+			return method;
+		},
+	}) as unknown as Api;
+
+	return {
+		api,
+		calls,
+		hooks,
+		lastCall: (method) =>
+			method ? [...calls].reverse().find((c) => c.method === method) : calls.at(-1),
+		callsTo: (method) => calls.filter((c) => c.method === method),
+		onApi: (method, reply, opts) => {
+			const entry = overrides.get(method) ?? { queue: [] };
+			if (opts?.times !== undefined) entry.queue.push({ reply, remaining: opts.times });
+			else entry.permanent = reply;
+			overrides.set(method, entry);
+		},
+		offApi: (method) => {
+			if (method) overrides.delete(method);
+			else overrides.clear();
+		},
+		reset: () => {
+			calls.length = 0;
+			attempts.clear();
+			nextMessageId = 1;
+		},
+	};
+}

package/src/bot-messages.ts

@@ -0,0 +1,117 @@
+import type { Api, Chat, Message } from "@yaebal/core";
+
+/** `Message`'s own `reply_markup` union — reused so a `BotMessage` structurally satisfies `Message`. */
+type ReplyMarkup = NonNullable<Message["reply_markup"]>;
+
+/**
+ * a live mirror of one message the bot sent — built from the outgoing `send*` params (so it's
+ * populated even against the builtin `{ message_id }` stub, no `onApi` override needed) and kept
+ * in sync in place as `editMessageText`/`editMessageCaption`/`editMessageReplyMarkup` calls land,
+ * so a reference captured before an edit still reflects it after.
+ */
+export interface BotMessage {
+	message_id: number;
+	chat: { id: number; type: Chat["type"] };
+	text?: string;
+	caption?: string;
+	reply_markup?: ReplyMarkup;
+	date: number;
+}
+
+export interface LastBotMessageQuery {
+	/** scope to a specific chat (an `{ id }`-shaped value — a `ChatActor` or `pmChat` both qualify). */
+	chat?: { id: number };
+	/** only consider messages currently carrying a non-empty `inline_keyboard`. */
+	withReplyMarkup?: boolean;
+	/** arbitrary predicate over the call that produced (or last touched) the message. */
+	where?: (call: { method: string; params: Record<string, unknown> | undefined }) => boolean;
+}
+
+export interface BotMessageTracker {
+	lastBotMessage(query?: LastBotMessageQuery): BotMessage | undefined;
+	botMessage(chatId: number, messageId: number): BotMessage | undefined;
+	clear(): void;
+}
+
+const SEND_LIKE = (method: string): boolean =>
+	method.startsWith("send") || method === "forwardMessage" || method === "copyMessage";
+
+function hasInlineKeyboard(markup: ReplyMarkup | undefined): boolean {
+	const withRows = markup as { inline_keyboard?: unknown[] } | undefined;
+	const rows = withRows?.inline_keyboard;
+	return Array.isArray(rows) && rows.length > 0;
+}
+
+/** install bot-message tracking on a mock `api` via its `after` hook. */
+export function attachBotMessageTracking(
+	api: Api,
+	resolveChatType: (chatId: number) => Chat["type"],
+): BotMessageTracker {
+	interface Entry extends BotMessage {
+		lastCall: { method: string; params: Record<string, unknown> | undefined };
+	}
+
+	const byKey = new Map<string, Entry>();
+	const order: Entry[] = [];
+	const key = (chatId: number, messageId: number): string => `${chatId}:${messageId}`;
+
+	api.after((method, params, result) => {
+		const p = params ?? {};
+
+		if (method.startsWith("edit")) {
+			const chatId = p.chat_id as number | undefined;
+			const messageId = p.message_id as number | undefined;
+			if (chatId === undefined || messageId === undefined) return;
+
+			const entry = byKey.get(key(chatId, messageId));
+			if (!entry) return;
+
+			if (method === "editMessageText" && typeof p.text === "string") entry.text = p.text;
+			if (method === "editMessageCaption") entry.caption = p.caption as string | undefined;
+			if ("reply_markup" in p) entry.reply_markup = p.reply_markup as ReplyMarkup | undefined;
+
+			entry.lastCall = { method, params: p };
+			return;
+		}
+
+		if (!SEND_LIKE(method)) return;
+		if (!result || typeof result !== "object" || !("message_id" in result)) return;
+
+		const chatId = p.chat_id as number | undefined;
+		if (chatId === undefined) return;
+
+		const messageId = (result as { message_id: number }).message_id;
+		const entry: Entry = {
+			message_id: messageId,
+			chat: { id: chatId, type: resolveChatType(chatId) },
+			text: p.text as string | undefined,
+			caption: p.caption as string | undefined,
+			reply_markup: p.reply_markup as ReplyMarkup | undefined,
+			date: (result as { date?: number }).date ?? Date.now(),
+			lastCall: { method, params: p },
+		};
+
+		byKey.set(key(chatId, messageId), entry);
+		order.push(entry);
+	});
+
+	return {
+		lastBotMessage(query = {}) {
+			for (let i = order.length - 1; i >= 0; i--) {
+				const entry = order[i] as Entry;
+				if (query.chat && entry.chat.id !== query.chat.id) continue;
+				if (query.withReplyMarkup && !hasInlineKeyboard(entry.reply_markup)) continue;
+				if (query.where && !query.where(entry.lastCall)) continue;
+
+				return entry;
+			}
+
+			return undefined;
+		},
+		botMessage: (chatId, messageId) => byKey.get(key(chatId, messageId)),
+		clear() {
+			byKey.clear();
+			order.length = 0;
+		},
+	};
+}

package/src/chat-actor.ts

@@ -0,0 +1,101 @@
+import type { Chat, Message } from "@yaebal/core";
+import type { ActorHost, SendText } from "./internal.js";
+import { resolveSendText } from "./internal.js";
+import { createUpdate } from "./updates.js";
+import type { UserActor } from "./user-actor.js";
+
+export type ChatType = "private" | "group" | "supergroup" | "channel";
+
+export interface CreateChatOptions {
+	type: ChatType;
+	id?: number;
+	title?: string;
+	username?: string;
+}
+
+/** a chat member's tracked status — set via {@link ChatActor.setMembership}. */
+export interface ChatMembership {
+	status: string;
+	since?: number;
+}
+
+let chatIdCounter = -1000;
+
+/**
+ * a passive container actors send into — a group/supergroup/channel/private chat. tracks who's
+ * currently a member (best-effort — nothing enforces it unless you opt into `strictMembership`
+ * via {@link createTestEnv}) and every message dispatched through it.
+ */
+export class ChatActor {
+	readonly id: number;
+	readonly type: ChatType;
+	readonly title?: string;
+	readonly username?: string;
+	readonly members = new Set<UserActor>();
+	readonly messages: unknown[] = [];
+
+	private readonly host: ActorHost;
+	private readonly membership = new Map<number, ChatMembership>();
+
+	constructor(host: ActorHost, options: CreateChatOptions) {
+		this.host = host;
+		this.id = options.id ?? chatIdCounter--;
+		this.type = options.type;
+		this.title = options.title;
+		this.username = options.username;
+	}
+
+	/** reconstruct a `ChatActor` from a raw `Chat` payload seen on an update (e.g. to find the chat a message you didn't create arrived in). not registered with any `TestEnv`. */
+	static fromChat(host: ActorHost, chat: Chat): ChatActor {
+		return new ChatActor(host, {
+			type: chat.type as ChatType,
+			id: chat.id,
+			title: chat.title,
+			username: chat.username,
+		});
+	}
+
+	/** this chat as a plain {@link Chat} payload, ready to embed in an update. */
+	toChat(): Chat {
+		return {
+			id: this.id,
+			type: this.type,
+			...(this.title !== undefined ? { title: this.title } : {}),
+			...(this.username !== undefined ? { username: this.username } : {}),
+		};
+	}
+
+	/** record (or update) a member's status — used by `strictMembership` and `getChatMember`-style assertions. */
+	setMembership(userId: number, membership: ChatMembership): void {
+		this.membership.set(userId, membership);
+	}
+
+	/** the tracked membership for a user, or `undefined` if never set. */
+	membershipOf(user: UserActor): ChatMembership | undefined {
+		return this.membership.get(user.id);
+	}
+
+	/**
+	 * an anonymous channel post — `update.channel_post`, with no `from` (matching real Telegram:
+	 * channel posts aren't attributed to a user). throws on non-channel chats.
+	 */
+	async post(text: SendText): Promise<Message> {
+		if (this.type !== "channel") {
+			throw new Error("ChatActor.post(): only channel chats can post — did you mean a user actor?");
+		}
+
+		const { text: resolvedText, entities } = resolveSendText(text);
+		const message = {
+			message_id: this.host.nextMessageId(),
+			date: this.host.now(),
+			chat: this.toChat(),
+			text: resolvedText,
+			...(entities.length ? { entities } : {}),
+		};
+
+		this.messages.push(message);
+		await this.host.dispatch(createUpdate({ channel_post: message }));
+
+		return message as Message;
+	}
+}