@yaebal/test 0.0.1 → 0.2.0

package/lib/api.js

@@ -0,0 +1,186 @@
+import { TelegramError, } from "@yaebal/core";
+import { normalizeParams } from "./normalize.js";
+/**
+ * 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, description, parameters) {
+    return { __yaebalApiError: true, code, description, parameters };
+}
+/** typeguard for a stored `apiError(...)` sentinel. */
+export function isApiErrorSentinel(value) {
+    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 {
+    parameters;
+    constructor(method, code, description, parameters) {
+        super(method, code, description);
+        this.parameters = parameters;
+    }
+}
+/** default results for known methods; everything else resolves to `{}` (or throws, with `strictApi`). */
+const STUBBED_METHODS = new Set(["getMe", "answerCallbackQuery"]);
+function builtinResult(method, nextMessageId) {
+    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) {
+    return (method.startsWith("send") ||
+        method === "copyMessage" ||
+        method === "forwardMessage" ||
+        STUBBED_METHODS.has(method));
+}
+/**
+ * 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, 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 = {}) {
+    const calls = [];
+    const overrides = new Map();
+    const attempts = new Map();
+    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: [],
+        after: [],
+        onError: [],
+    };
+    function resolveReply(method, params) {
+        const attempt = (attempts.get(method) ?? 0) + 1;
+        attempts.set(method, attempt);
+        const override = overrides.get(method);
+        let reply;
+        if (override?.queue.length) {
+            const head = override.queue[0];
+            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(params, attempt);
+        }
+        if (isApiErrorSentinel(reply)) {
+            return new TestApiError(method, reply.code, reply.description, reply.parameters);
+        }
+        return reply;
+    }
+    const call = async (method, rawParams) => {
+        let p = normalizeParams(rawParams);
+        for (const hook of hooks.before) {
+            const next = await hook(method, p);
+            if (next !== undefined)
+                p = next;
+        }
+        for (let attempt = 1;; attempt++) {
+            let result;
+            try {
+                result = resolveReply(method, p);
+                if (result instanceof Error)
+                    throw result;
+            }
+            catch (error) {
+                let retry;
+                for (const hook of hooks.onError) {
+                    const action = await hook(method, error, attempt);
+                    if (action?.retry) {
+                        retry = action;
+                        break;
+                    }
+                }
+                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;
+        }
+    };
+    const registrar = {
+        call: (method, params) => call(method, params),
+        fileUrl: (filePath) => `https://example.invalid/file/${filePath}`,
+        before(hook) {
+            hooks.before.push(hook);
+            return api;
+        },
+        after(hook) {
+            hooks.after.push(hook);
+            return api;
+        },
+        onError(hook) {
+            hooks.onError.push(hook);
+            return api;
+        },
+    };
+    const api = new Proxy(registrar, {
+        get(obj, prop) {
+            if (prop in obj)
+                return obj[prop];
+            const method = (params) => call(prop, params);
+            obj[prop] = method;
+            return method;
+        },
+    });
+    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;
+        },
+    };
+}
+//# sourceMappingURL=api.js.map

package/lib/api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"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"}

package/lib/api.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=api.test.d.ts.map

package/lib/api.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.test.d.ts","sourceRoot":"","sources":["../src/api.test.ts"],"names":[],"mappings":""}

package/lib/api.test.js

@@ -0,0 +1,131 @@
+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, attempt) => attempt <= 2
+                ? new TelegramError("sendMessage", 429, "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("getChat")).stale, true);
+    assert.equal((await api.call("getChat")).stale, true);
+    assert.equal((await api.call("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) => {
+        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, 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" }]],
+    });
+});
+//# sourceMappingURL=api.test.js.map

package/lib/api.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.test.js","sourceRoot":"","sources":["../src/api.test.ts"],"names":[],"mappings":"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"}

package/lib/bot-messages.d.ts

@@ -0,0 +1,42 @@
+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;
+}
+/** install bot-message tracking on a mock `api` via its `after` hook. */
+export declare function attachBotMessageTracking(api: Api, resolveChatType: (chatId: number) => Chat["type"]): BotMessageTracker;
+export {};
+//# sourceMappingURL=bot-messages.d.ts.map

package/lib/bot-messages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bot-messages.d.ts","sourceRoot":"","sources":["../src/bot-messages.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAEvD,wGAAwG;AACxG,KAAK,WAAW,GAAG,WAAW,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC;AAExD;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,CAAA;KAAE,CAAC;IACzC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,WAAW,CAAC;IAC3B,IAAI,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,mBAAmB;IACnC,oGAAoG;IACpG,IAAI,CAAC,EAAE;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC;IACtB,+EAA+E;IAC/E,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,qFAAqF;IACrF,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAA;KAAE,KAAK,OAAO,CAAC;CAC3F;AAED,MAAM,WAAW,iBAAiB;IACjC,cAAc,CAAC,KAAK,CAAC,EAAE,mBAAmB,GAAG,UAAU,GAAG,SAAS,CAAC;IACpE,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAAC;IACtE,KAAK,IAAI,IAAI,CAAC;CACd;AAWD,yEAAyE;AACzE,wBAAgB,wBAAwB,CACvC,GAAG,EAAE,GAAG,EACR,eAAe,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC,MAAM,CAAC,GAC/C,iBAAiB,CAoEnB"}

package/lib/bot-messages.js

@@ -0,0 +1,72 @@
+const SEND_LIKE = (method) => method.startsWith("send") || method === "forwardMessage" || method === "copyMessage";
+function hasInlineKeyboard(markup) {
+    const withRows = markup;
+    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, resolveChatType) {
+    const byKey = new Map();
+    const order = [];
+    const key = (chatId, messageId) => `${chatId}:${messageId}`;
+    api.after((method, params, result) => {
+        const p = params ?? {};
+        if (method.startsWith("edit")) {
+            const chatId = p.chat_id;
+            const messageId = p.message_id;
+            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;
+            if ("reply_markup" in p)
+                entry.reply_markup = p.reply_markup;
+            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;
+        if (chatId === undefined)
+            return;
+        const messageId = result.message_id;
+        const entry = {
+            message_id: messageId,
+            chat: { id: chatId, type: resolveChatType(chatId) },
+            text: p.text,
+            caption: p.caption,
+            reply_markup: p.reply_markup,
+            date: result.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];
+                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;
+        },
+    };
+}
+//# sourceMappingURL=bot-messages.js.map

package/lib/bot-messages.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bot-messages.js","sourceRoot":"","sources":["../src/bot-messages.ts"],"names":[],"mappings":"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"}

package/lib/chat-actor.d.ts

@@ -0,0 +1,45 @@
+import type { Chat, Message } from "@yaebal/core";
+import type { ActorHost, SendText } from "./internal.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;
+}
+/**
+ * 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 declare class ChatActor {
+    readonly id: number;
+    readonly type: ChatType;
+    readonly title?: string;
+    readonly username?: string;
+    readonly members: Set<UserActor>;
+    readonly messages: unknown[];
+    private readonly host;
+    private readonly membership;
+    constructor(host: ActorHost, options: CreateChatOptions);
+    /** 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;
+    /** this chat as a plain {@link Chat} payload, ready to embed in an update. */
+    toChat(): Chat;
+    /** record (or update) a member's status — used by `strictMembership` and `getChatMember`-style assertions. */
+    setMembership(userId: number, membership: ChatMembership): void;
+    /** the tracked membership for a user, or `undefined` if never set. */
+    membershipOf(user: UserActor): ChatMembership | undefined;
+    /**
+     * 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.
+     */
+    post(text: SendText): Promise<Message>;
+}
+//# sourceMappingURL=chat-actor.d.ts.map

package/lib/chat-actor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat-actor.d.ts","sourceRoot":"","sources":["../src/chat-actor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAGzD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEjD,MAAM,MAAM,QAAQ,GAAG,SAAS,GAAG,OAAO,GAAG,YAAY,GAAG,SAAS,CAAC;AAEtE,MAAM,WAAW,iBAAiB;IACjC,IAAI,EAAE,QAAQ,CAAC;IACf,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,gFAAgF;AAChF,MAAM,WAAW,cAAc;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CACf;AAID;;;;GAIG;AACH,qBAAa,SAAS;IACrB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,iBAAwB;IACxC,QAAQ,CAAC,QAAQ,EAAE,OAAO,EAAE,CAAM;IAElC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAY;IACjC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAqC;gBAEpD,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,iBAAiB;IAQvD,+KAA+K;IAC/K,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,GAAG,SAAS;IASvD,8EAA8E;IAC9E,MAAM,IAAI,IAAI;IASd,8GAA8G;IAC9G,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,cAAc,GAAG,IAAI;IAI/D,sEAAsE;IACtE,YAAY,CAAC,IAAI,EAAE,SAAS,GAAG,cAAc,GAAG,SAAS;IAIzD;;;OAGG;IACG,IAAI,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC;CAmB5C"}

package/lib/chat-actor.js

@@ -0,0 +1,72 @@
+import { resolveSendText } from "./internal.js";
+import { createUpdate } from "./updates.js";
+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 {
+    id;
+    type;
+    title;
+    username;
+    members = new Set();
+    messages = [];
+    host;
+    membership = new Map();
+    constructor(host, options) {
+        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, chat) {
+        return new ChatActor(host, {
+            type: chat.type,
+            id: chat.id,
+            title: chat.title,
+            username: chat.username,
+        });
+    }
+    /** this chat as a plain {@link Chat} payload, ready to embed in an update. */
+    toChat() {
+        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, membership) {
+        this.membership.set(userId, membership);
+    }
+    /** the tracked membership for a user, or `undefined` if never set. */
+    membershipOf(user) {
+        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) {
+        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;
+    }
+}
+//# sourceMappingURL=chat-actor.js.map

package/lib/chat-actor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat-actor.js","sourceRoot":"","sources":["../src/chat-actor.ts"],"names":[],"mappings":"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"}

package/lib/clock.d.ts

@@ -0,0 +1,22 @@
+/**
+ * a virtual clock: overrides `Date.now`, `setTimeout`/`clearTimeout`, and
+ * `setInterval`/`clearInterval` so TTL / retry-delay / debounce code under test
+ * can be advanced instantly instead of waited on for real. installs globally
+ * for the lifetime of the clock; always `.restore()` when done (or let
+ * {@link TestEnv.shutdown} do it for you).
+ */
+export interface TestClock {
+    /** the clock's current virtual time, in ms since epoch. */
+    now(): number;
+    /** advance the clock by `ms`, firing every timer whose deadline falls inside the window (in deadline order). intervals re-arm and may fire multiple times. */
+    advance(ms: number): Promise<void>;
+    /** uninstall — restores the real `Date.now`/`setTimeout`/`setInterval`. */
+    restore(): void;
+}
+/**
+ * install a virtual clock, overriding the global timer functions. `startAt`
+ * defaults to the real current time so unrelated `Date.now()` reads (e.g. log
+ * timestamps) stay plausible.
+ */
+export declare function installTestClock(startAt?: number): TestClock;
+//# sourceMappingURL=clock.d.ts.map

package/lib/clock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clock.d.ts","sourceRoot":"","sources":["../src/clock.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,WAAW,SAAS;IACzB,2DAA2D;IAC3D,GAAG,IAAI,MAAM,CAAC;IACd,8JAA8J;IAC9J,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,2EAA2E;IAC3E,OAAO,IAAI,IAAI,CAAC;CAChB;AAWD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,GAAE,MAAmB,GAAG,SAAS,CAuFxE"}