@capybara-hq/testing 0.0.0-stage → 0.1.0-rc.0

package/dist/dual-replica.d.ts

@@ -0,0 +1,121 @@
+import type { BootstrapManifest } from "@capybara-hq/plugin-sdk";
+/** 双副本测试工具的选项。 */
+export interface DualReplicaOptions {
+    /** Extensions to load (absolute paths, file URLs, or package names resolved from `resolveFrom`). */
+    extensions: string[];
+    /** 解析裸包名插件的目录，默认调用方的 `process.cwd()`（与 `createKernel` 的 resolveFrom 同义）。 */
+    resolveFrom?: string;
+    /** 部署级插件配置，按插件名索引。 */
+    extensionConfig?: Record<string, unknown>;
+    /**
+     * The bootstrap step (package ecosystem spec §7): every replica's kernel gets `bootstrapDir: dir`
+     * and `bootstrapManifest: manifest`, so the replicas run it at start (once across them, under the
+     * advisory lock) before loading extensions, as a deployment without an init container does. `dir`
+     * holds the packages the manifest pins (`<name>-<version>.tgz`); build both with the kernel
+     * tests' `bootstrapFixture` helper (it packs plugin directories with `pnpm pack-plugin`).
+     */
+    bootstrap?: {
+        dir: string;
+        manifest: BootstrapManifest;
+    };
+    /**
+     * 复用已有的 PostgreSQL（管理员连接串，需能 CREATE DATABASE）。传入则只创建并在 stop() 时删除本 harness 的 `cap_*` 库。
+     * Omitted: use the run-wide shared PostgreSQL of the vitest globalSetup (same per-harness database),
+     * or, without one / with `CAPYBARA_TEST_NO_SHARED=1`, start a container and stop it in stop().
+     */
+    pgUrl?: string;
+    /**
+     * 复用已有的 Redis。省略则每个 harness 自己起一个容器（完全隔离）；
+     * 传入时不做隔离，调用方须保证同一 Redis 不被多个同时存活的 harness 共用。
+     */
+    redisUrl?: string;
+    /**
+     * 额外的内核配置，深合并进副本配置（如 `{ auth: { cookieSecure: false, setupToken: "…" } }`）。
+     * 与 harness 自身设定的键冲突时以这里为准（数组整体替换）。经 IPC 传给副本，不进 argv / env。
+     * harness 默认开启 `extensionPermissions.autoApprove`（插件权限自动批准），传 `false` 可关闭。
+     */
+    config?: Record<string, unknown>;
+    /**
+     * Kernel roles per replica (`[replica 0, replica 1]`), e.g. `[["api", "worker"], ["gateway"]]`.
+     * Defaults to all roles (`api`, `worker`, `gateway`) on both. `request()` only goes to replicas
+     * with the `api` role; use `requestTo(index, …)` to reach a specific replica.
+     */
+    roles?: [string[], string[]];
+}
+/** 一个副本（独立子进程）的句柄。 */
+export interface ReplicaHandle {
+    /** Replica index (0 and 1 for the two base replicas). */
+    index: number;
+    /** Kernel roles this replica runs. */
+    roles: string[];
+    /** 该副本实际监听的 HTTP 端口（127.0.0.1）。 */
+    port: number;
+    /** 该副本子进程 pid。 */
+    pid: number;
+}
+/** A replica added with `Harness.startExtraReplica`; `kill()` SIGKILLs it like `Harness.kill(index)`. */
+export interface ExtraReplicaHandle extends ReplicaHandle {
+    kill(): Promise<void>;
+}
+/** 副本在响应头里标明自己的序号（runner 把 `http.replicaId` 设为 `"0"` / `"1"`）。 */
+export declare const REPLICA_HEADER = "x-capybara-replica";
+/**
+ * Reads the `x-capybara-replica` response header to get the index of the replica that handled the
+ * request; undefined when the response did not come from a harness replica (no header, or not a
+ * non-negative integer). Use it to confirm where a direct `fetch` to a replica port (e.g. SSE) landed.
+ */
+export declare function replicaOf(res: Response): number | undefined;
+/** `Harness.request` 的返回值：普通 `Response` 加上处理它的副本序号（取自 `x-capybara-replica` 响应头）。 */
+export type ReplicaResponse = Response & {
+    readonly replica: number;
+};
+/** Two kernel replicas in separate processes, plus a round-robin request entry over the api replicas. */
+export interface Harness {
+    /**
+     * Round-robin over the replicas that run the `api` role. With the default roles this strictly
+     * alternates: calls 1, 3, 5… go to replica 0 and calls 2, 4, 6… to replica 1.
+     * The result's `replica` comes from the `x-capybara-replica` response header; throws when the
+     * header is missing or does not match the target, or when no replica runs the `api` role.
+     */
+    request(path: string, init?: RequestInit): Promise<ReplicaResponse>;
+    /**
+     * Sends the request to replica `index`, whatever its roles (a replica without `api` only serves
+     * health endpoints and, with `gateway`, plugin routes). Same header check as `request()`.
+     */
+    requestTo(index: number, path: string, init?: RequestInit): Promise<ReplicaResponse>;
+    replicas: [ReplicaHandle, ReplicaHandle];
+    /**
+     * Starts one more replica with the given roles on the same PG / Redis / masterKey and resolves
+     * once it is ready. It gets the next index (2, 3, …): `requestTo(index)` and `kill(index)` reach
+     * it, an `api` replica joins the `request()` rotation, and `stop()` stops it too.
+     */
+    startExtraReplica(roles: string[]): Promise<ExtraReplicaHandle>;
+    /** 本 harness 独占数据库的连接串，测试可直接连上去查表。 */
+    dbUrl: string;
+    /** The Redis the replicas share (tests may read kernel keys from it). */
+    redisUrl: string;
+    /**
+     * 模拟副本硬崩溃：对该副本子进程发 SIGKILL 并等它退出（不走优雅停机）。之后发往它的请求直接抛错；
+     * 另一个副本照常工作。已退出时是空操作。
+     */
+    kill(index: number): Promise<void>;
+    /** 停两个副本（15s 后 SIGKILL）、删临时库、关自有容器；幂等。 */
+    stop(): Promise<void>;
+}
+/**
+ * 子进程的 node 参数。`.ts` 的 runner（monorepo / 开发态）需要 tsx 与源码导出条件；
+ * 编译后的 `.js` runner（发布态）直接用 node，不依赖 tsx。
+ */
+export declare function runnerArgv(runnerPath: string): string[];
+/**
+ * 子进程的环境变量。`.ts` 的 runner 额外设置 `TSX_TSCONFIG_PATH` 指向仓库的 tsconfig.base.json：
+ * tsx 只认子进程 cwd 下（且 include 覆盖到的）tsconfig，否则内核源码丢掉 experimentalDecorators，
+ * Nest 装饰器无法编译。编译后的 `.js` runner 不经 tsx，环境原样传入。
+ */
+export declare function runnerEnv(runnerPath: string, env?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+/**
+ * 启动两个共享同一套 PG / Redis、同一 masterKey 的内核副本，**每个副本一个独立子进程**，
+ * 模块缓存、进程内状态完全隔离，贴近生产多副本。请求经真实 HTTP 交替发往含 api 角色的副本。
+ * 两个副本都就绪后才 resolve；用来暴露「只在多副本下才出现」的进程内状态缺陷。
+ */
+export declare function createDualReplicaHarness(opts: DualReplicaOptions): Promise<Harness>;

package/dist/dual-replica.js

@@ -0,0 +1,247 @@
+import { spawn } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { extname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createFreshDatabase, sharedPgAdminUrl, startPostgresContainer, startTestRedis, } from "./containers.js";
+/** 副本在响应头里标明自己的序号（runner 把 `http.replicaId` 设为 `"0"` / `"1"`）。 */
+export const REPLICA_HEADER = "x-capybara-replica";
+/**
+ * Reads the `x-capybara-replica` response header to get the index of the replica that handled the
+ * request; undefined when the response did not come from a harness replica (no header, or not a
+ * non-negative integer). Use it to confirm where a direct `fetch` to a replica port (e.g. SSE) landed.
+ */
+export function replicaOf(res) {
+    const v = res.headers.get(REPLICA_HEADER);
+    return v !== null && /^(0|[1-9][0-9]*)$/.test(v) ? Number(v) : undefined;
+}
+/** Default roles of every replica. */
+const ALL_ROLES = ["api", "worker", "gateway"];
+const STOP_TIMEOUT_MS = 15_000;
+const START_TIMEOUT_MS = 60_000;
+const STDERR_TAIL = 4000;
+/** runner 与本文件同目录；源码下是 .ts，编译后是 .js。 */
+const runnerPath = fileURLToPath(new URL(`./replica-runner${extname(fileURLToPath(import.meta.url))}`, import.meta.url));
+/**
+ * 子进程的 node 参数。`.ts` 的 runner（monorepo / 开发态）需要 tsx 与源码导出条件；
+ * 编译后的 `.js` runner（发布态）直接用 node，不依赖 tsx。
+ */
+export function runnerArgv(runnerPath) {
+    return runnerPath.endsWith(".ts")
+        ? ["--import", "tsx", "--conditions=@capybara-hq/source", runnerPath]
+        : [runnerPath];
+}
+/** 仓库根的 tsconfig.base.json（仅 monorepo 源码态存在）。 */
+const REPO_TSCONFIG = fileURLToPath(new URL("../../../tsconfig.base.json", import.meta.url));
+/**
+ * 子进程的环境变量。`.ts` 的 runner 额外设置 `TSX_TSCONFIG_PATH` 指向仓库的 tsconfig.base.json：
+ * tsx 只认子进程 cwd 下（且 include 覆盖到的）tsconfig，否则内核源码丢掉 experimentalDecorators，
+ * Nest 装饰器无法编译。编译后的 `.js` runner 不经 tsx，环境原样传入。
+ */
+export function runnerEnv(runnerPath, env = process.env) {
+    return runnerPath.endsWith(".ts") ? { ...env, TSX_TSCONFIG_PATH: REPO_TSCONFIG } : env;
+}
+/** 启动一个副本子进程，等它通过 IPC 报告 ready。失败时抛出带 输出尾部的错误（不含配置）。 */
+async function startReplica(config, index) {
+    const child = spawn(process.execPath, runnerArgv(runnerPath), {
+        stdio: ["ignore", "pipe", "pipe", "ipc"],
+        env: runnerEnv(runnerPath),
+        cwd: fileURLToPath(new URL("..", import.meta.url)),
+    });
+    let tail = "";
+    const onData = (b) => {
+        tail = (tail + b.toString()).slice(-STDERR_TAIL);
+    };
+    child.stderr?.on("data", onData);
+    child.stdout?.on("data", onData);
+    const runner = {
+        child,
+        output: () => tail,
+        exited: Promise.resolve(),
+        crashed: undefined,
+    };
+    runner.exited = new Promise((resolve) => child.once("exit", (code, signal) => {
+        runner.crashed = `exited with ${signal ? `signal ${signal}` : `code ${code}`}`;
+        resolve();
+    }));
+    const exited = runner.exited;
+    const port = await new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error("replica start timed out")), START_TIMEOUT_MS);
+        const fail = (why) => {
+            clearTimeout(timer);
+            reject(new Error(`replica failed to start: ${why}\n${tail}`));
+        };
+        child.on("message", (m) => {
+            if (m.type === "ready" && typeof m.port === "number") {
+                clearTimeout(timer);
+                resolve(m.port);
+            }
+            else if (m.type === "failed")
+                fail(m.error ?? "unknown");
+        });
+        child.once("exit", (code) => fail(`runner exited with code ${code}`));
+        child.once("error", (e) => fail(e.message));
+        child.send({ type: "start", config: { ...config, replicaId: String(index) } });
+    }).catch(async (e) => {
+        child.kill("SIGKILL");
+        await exited;
+        throw e;
+    });
+    return { runner, port };
+}
+/**
+ * 启动两个共享同一套 PG / Redis、同一 masterKey 的内核副本，**每个副本一个独立子进程**，
+ * 模块缓存、进程内状态完全隔离，贴近生产多副本。请求经真实 HTTP 交替发往含 api 角色的副本。
+ * 两个副本都就绪后才 resolve；用来暴露「只在多副本下才出现」的进程内状态缺陷。
+ */
+export async function createDualReplicaHarness(opts) {
+    const owned = [];
+    const runners = [];
+    let dropDb;
+    let stopPromise;
+    const stopRunner = async (r) => {
+        if (r.child.exitCode !== null || r.child.signalCode !== null)
+            return;
+        if (r.child.connected)
+            r.child.send({ type: "stop" });
+        let timer;
+        const killed = new Promise((resolve) => {
+            timer = setTimeout(() => {
+                r.child.kill("SIGKILL");
+                resolve();
+            }, STOP_TIMEOUT_MS);
+        });
+        await Promise.race([r.exited, killed]);
+        clearTimeout(timer);
+        await r.exited;
+    };
+    const stop = () => {
+        stopPromise ??= (async () => {
+            await Promise.allSettled(runners.map(stopRunner));
+            await Promise.allSettled([dropDb?.()]);
+            await Promise.allSettled(owned.map((c) => c.stop()));
+        })();
+        return stopPromise;
+    };
+    try {
+        // Without `pgUrl`: the run-wide shared PostgreSQL when the vitest globalSetup started one,
+        // else a container of our own. Either way the replicas get a fresh database created below.
+        let pgUrl = opts.pgUrl ?? sharedPgAdminUrl();
+        if (pgUrl === undefined) {
+            const c = await startPostgresContainer();
+            owned.push(c);
+            pgUrl = c.url;
+        }
+        let redisUrl = opts.redisUrl;
+        if (redisUrl === undefined) {
+            const c = await startTestRedis();
+            owned.push(c);
+            redisUrl = c.url;
+        }
+        const db = await createFreshDatabase(pgUrl);
+        dropDb = db.drop;
+        const config = {
+            dbUrl: db.url,
+            redisUrl,
+            masterKey: randomBytes(32).toString("base64"),
+            extensions: opts.extensions,
+            ...(opts.bootstrap !== undefined && {
+                bootstrapDir: resolve(opts.bootstrap.dir),
+                bootstrapManifest: opts.bootstrap.manifest,
+            }),
+            // 副本进程的 cwd 不是调用方的 cwd，相对路径必须先按调用方 cwd 绝对化再经 IPC 传过去
+            resolveFrom: resolve(opts.resolveFrom ?? process.cwd()),
+            extensionConfig: opts.extensionConfig ?? {},
+            overrides: opts.config ?? {},
+        };
+        const roles = opts.roles ?? [ALL_ROLES, ALL_ROLES];
+        const started = await Promise.allSettled(roles.map((r, i) => startReplica({ ...config, roles: [...r] }, i)));
+        for (const s of started)
+            if (s.status === "fulfilled")
+                runners.push(s.value.runner);
+        const failed = started.find((s) => s.status === "rejected");
+        if (failed)
+            throw failed.reason;
+        const [a, b] = started.map((s) => s.value);
+        const replicas = [
+            { index: 0, roles: [...roles[0]], port: a.port, pid: a.runner.child.pid },
+            { index: 1, roles: [...roles[1]], port: b.port, pid: b.runner.child.pid },
+        ];
+        // Index-aligned with `replicas`; extra replicas append to both.
+        const handles = [...replicas];
+        const replicaRunners = [a.runner, b.runner];
+        const runnerAt = (index) => {
+            const handle = handles[index];
+            const runner = replicaRunners[index];
+            if (handle === undefined || runner === undefined)
+                throw new Error(`no replica ${index}`);
+            return { handle, runner };
+        };
+        const send = async (index, path, init) => {
+            const { handle: r, runner } = runnerAt(index);
+            if (runner.crashed !== undefined) {
+                throw new Error(`replica ${index} (pid ${r.pid}) ${runner.crashed}\n${runner.output()}`);
+            }
+            const res = await fetch(`http://127.0.0.1:${r.port}${path}`, init);
+            const replica = replicaOf(res);
+            if (replica !== index) {
+                await res.body?.cancel();
+                throw new Error(`response from port ${r.port} has ${REPLICA_HEADER}=${replica}, want ${index}`);
+            }
+            return Object.assign(res, { replica });
+        };
+        let calls = 0;
+        let extraChain = Promise.resolve();
+        const kill = async (index) => {
+            const { runner: r } = runnerAt(index);
+            if (r.child.exitCode === null && r.child.signalCode === null)
+                r.child.kill("SIGKILL");
+            await r.exited;
+        };
+        return {
+            replicas,
+            dbUrl: db.url,
+            redisUrl,
+            stop,
+            kill,
+            startExtraReplica(extraRoles) {
+                // Extra starts run one at a time: the index is the next free slot when the start begins,
+                // and a failed start appends nothing, so there are never holes in the replica indexes
+                const p = extraChain.then(async () => {
+                    if (stopPromise)
+                        throw new Error("harness is stopped");
+                    const index = handles.length;
+                    const started = await startReplica({ ...config, roles: [...extraRoles] }, index);
+                    runners.push(started.runner);
+                    // A stop() that began while this replica was starting must not leave it running
+                    if (stopPromise) {
+                        await stopRunner(started.runner);
+                        throw new Error("harness is stopped");
+                    }
+                    const handle = {
+                        index,
+                        roles: [...extraRoles],
+                        port: started.port,
+                        pid: started.runner.child.pid,
+                    };
+                    handles.push(handle);
+                    replicaRunners.push(started.runner);
+                    return { ...handle, kill: () => kill(index) };
+                });
+                extraChain = p.then(() => { }, () => { });
+                return p;
+            },
+            async request(path, init) {
+                const api = handles.filter((h) => h.roles.includes("api"));
+                if (api.length === 0)
+                    throw new Error("no replica runs the api role");
+                const target = api[calls++ % api.length];
+                return send(target.index, path, init);
+            },
+            requestTo: send,
+        };
+    }
+    catch (e) {
+        await stop();
+        throw e;
+    }
+}

package/dist/extension-config.d.ts

@@ -0,0 +1,9 @@
+import type { ExtensionManifest } from "@capybara-hq/plugin-sdk";
+/**
+ * For extension tests: runs the kernel's secret marker check done when loading an extension (the same
+ * `assertSecretsReachable` as `ExtensionHost` uses); throws when a `secret()` is not on an object
+ * field path (the kernel would refuse to load the extension).
+ */
+export declare function assertExtensionSecretsReachable(manifest: ExtensionManifest): void;
+/** For extension tests: the deployment config secret values the kernel registers for log redaction (the same collection logic as `ExtensionHost` uses when loading). */
+export declare function extensionDeploymentSecretValues(manifest: ExtensionManifest, config: unknown): string[];

package/dist/extension-config.js

@@ -0,0 +1,16 @@
+import { assertSecretsReachable, secretValues } from "@capybara-hq/kernel";
+/**
+ * For extension tests: runs the kernel's secret marker check done when loading an extension (the same
+ * `assertSecretsReachable` as `ExtensionHost` uses); throws when a `secret()` is not on an object
+ * field path (the kernel would refuse to load the extension).
+ */
+export function assertExtensionSecretsReachable(manifest) {
+    assertSecretsReachable(manifest);
+}
+/** For extension tests: the deployment config secret values the kernel registers for log redaction (the same collection logic as `ExtensionHost` uses when loading). */
+export function extensionDeploymentSecretValues(manifest, config) {
+    const schema = manifest.config?.deployment;
+    if (!schema)
+        return [];
+    return secretValues(schema, schema.parse(config));
+}

package/dist/fake-channel.d.ts

@@ -0,0 +1,162 @@
+import type { CardAction, ChannelTarget, DirectoryMember, InboundEvent, OutboundMessage } from "@capybara-hq/plugin-sdk";
+/**
+ * 可编程的假 IM 平台（渠道插件测试用）：一个 HTTP 服务同时扮演 IM 平台的几块能力——
+ *
+ * - **机器人**：`POST /bot/verify` 校验应用凭据；`GET /connect?connection=<id>` 建一条 NDJSON 长连接，
+ *   测试用 {@link FakeChannelServer.push} 向某个渠道连接当前在线的长连接推入站事件；`POST /send`、`POST /update`
+ *   记下机器人发出 / 更新的消息（含卡片），`/send` 按 `idempotencyKey` 去重（同一应用、同一键只发一次，
+ *   重复的请求原样返回第一次的 messageId，并记进 `duplicateSends`）。
+ * - **登录（OAuth）**：`GET /oauth/authorize` 以 `as=<externalId>` 指定「在平台上登录的人」，签发一次性授权码并
+ *   302 回 `redirect_uri`；`POST /oauth/token` 用授权码换该用户资料与发起时的 nonce。授权时带了 PKCE
+ *   `code_challenge`（S256）的，换 token 必须带对应的 `codeVerifier`，否则 `invalid_grant`。
+ * - **通讯录**：`GET /d/<key>/members?cursor=<n>` 按页返回 {@link FakeChannelServer.book} 的成员，可让某页失败、让第一页挂起。
+ * - **其他写操作**：`POST /posts` 记下插件工具发的「公告」（`posts`），供断言工具确实执行（且只执行一次）。
+ *
+ * - **Webhook** (the platform calling the kernel): {@link signFakeWebhook} signs a body with HMAC-SHA256
+ *   for the `x-fake-signature` header; {@link fakeWebhookEvents} / {@link fakeWebhookChallenge} build bodies.
+ *
+ * 所有请求读 `x-pid` 头记下发起进程，双副本测试据此判断是哪个副本连上 / 发出的。
+ * It tracks the peak number of concurrent long connections per channel connection (at most one at
+ * any time). The matching test extension is this package's fake `fake-im`
+ * (`fakeExtensionEntry("fake-im")`).
+ */
+/** 一条长连接。 */
+export interface FakeChannelStream {
+    connectionId: string;
+    /** 请求头 `x-app-id`。 */
+    appId: string;
+    /** 发起连接的进程 pid（请求头 `x-pid`）。 */
+    pid: number;
+    openedAt: number;
+    closedAt: number | undefined;
+}
+/** 机器人发出（或更新）的一条消息。 */
+export interface FakeChannelSent {
+    appId: string;
+    target: ChannelTarget;
+    message: OutboundMessage;
+    messageId: string;
+    /** 发出请求的进程 pid（请求头 `x-pid`）。 */
+    pid: number;
+    /** 内核给的幂等键（`ChannelSendArgs.idempotencyKey`）。 */
+    idempotencyKey?: string;
+    /** 内核给的组织语言（`ChannelSendArgs.locale`）。 */
+    locale?: "zh" | "en";
+    at: number;
+}
+/** 平台上的一个用户（OAuth 登录时可用 `as=<externalId>` 选中）。 */
+export interface FakeChannelUser {
+    externalId: string;
+    tenantId: string;
+    email?: string;
+    emailVerified?: boolean;
+    displayName: string;
+}
+/** 一份假通讯录（按路径前缀 `/d/<key>` 区分）。 */
+export interface FakeDirectoryBook {
+    /** 通讯录插件的组织级配置 `url`。 */
+    url: string;
+    members: DirectoryMember[];
+    /** 每页条数（默认 100）。 */
+    pageSize: number;
+    /** 第几页（从 0 计）返回 500；null 不失败。 */
+    failOnPage: number | null;
+    /** 给了就让第一页（不带游标的请求）等它 resolve 再返回。 */
+    hold: Promise<void> | null;
+    /** 每次请求的页号与发起进程 pid。 */
+    requests: {
+        page: number;
+        pid: number;
+    }[];
+    /** 整轮同步开始的次数（不带游标的请求数）。 */
+    starts(): number;
+}
+/** 插件工具经 `POST /posts` 发出的一条记录。 */
+export interface FakeChannelPost {
+    body: Record<string, unknown>;
+    pid: number;
+    at: number;
+}
+export interface FakeChannelServerOptions {
+    /**
+     * `/send` 是否按 `(appId, idempotencyKey)` 去重（默认 true，像飞书的 `uuid`）。
+     * 断言「内核自己就不重发」的测试传 false：每次发送都记进 `sent`，重发即可见。
+     */
+    dedupeSends?: boolean;
+}
+export interface FakeChannelServer {
+    url: string;
+    streams: FakeChannelStream[];
+    /** 平台上真实出现的消息（去重后）。 */
+    sent: FakeChannelSent[];
+    /** 机器人对已发消息的更新（`messageId` 为被更新的消息）。 */
+    updated: FakeChannelSent[];
+    /** 命中幂等键、被平台去重的发送请求（没有产生新消息）。 */
+    duplicateSends: FakeChannelSent[];
+    /** 插件工具发的公告。 */
+    posts: FakeChannelPost[];
+    /** 平台用户（OAuth 登录用），按 externalId 索引。 */
+    users: Map<string, FakeChannelUser>;
+    /**
+     * 让接下来 `count` 次 `/send`（或 `/update`）返回该状态码（不记录）；`retryAfterMs` 与 `reason` 放进响应体，
+     * 测试插件据此抛 `ChannelSendError`（429 / 5xx 可重试，带等待时长；其他不可重试，带失败原因）。
+     * `delayMs`：失败响应推迟这么久才返回（模拟慢的失败请求，让会话的后续事件在投递任务持锁期间到达）。
+     */
+    failNext(path: "/send" | "/update", status: number, count?: number, retryAfterMs?: number, reason?: "auth" | "target_gone" | "rejected" | "too_large", delayMs?: number): void;
+    /**
+     * Delay the response of the next `count` successful `/send` (or `/update`) requests by `delayMs`.
+     * The message is recorded (visible in `sent` / `updated`) as soon as the request arrives; only the
+     * response carrying its `messageId` is late (a slow platform API, or a sender that dies mid-call).
+     * `onlyCards`: count and delay only requests whose message carries cards.
+     */
+    delayNext(path: "/send" | "/update", delayMs: number, opts?: {
+        count?: number;
+        onlyCards?: boolean;
+    }): void;
+    /** 让 /connect 返回该状态码（null 恢复正常）。 */
+    failConnect(status: number | null): void;
+    /** 该渠道连接当前在线的长连接。 */
+    active(connectionId: string): FakeChannelStream[];
+    /** 该渠道连接同时在线长连接数的峰值。 */
+    maxConcurrent(connectionId: string): number;
+    /** 推送给该渠道连接当前所有在线长连接，返回推送到的条数。 */
+    push(connectionId: string, event: InboundEvent): number;
+    /** 取（没有则新建）一份通讯录。 */
+    book(key: string): FakeDirectoryBook;
+    /** 消息最终显示的文本：有更新取最后一次更新，否则为发出时的文本。 */
+    finalText(s: FakeChannelSent): string;
+    stop(): Promise<void>;
+}
+/** 校验应用凭据时一律拒绝的密钥。 */
+export declare const FAKE_CHANNEL_BAD_SECRET = "bad-secret";
+/** 启动假 IM 平台（监听 127.0.0.1 随机端口）。 */
+export declare function startFakeChannelServer(opts?: FakeChannelServerOptions): Promise<FakeChannelServer>;
+/** 平台上的发言人资料（`InboundSender` 的可选字段）。 */
+export interface FakeSenderProfile {
+    displayName?: string;
+    avatarUrl?: string;
+}
+/** 私聊文本消息（chat id 为 `dm-<externalId>`）；`profile` 给了就带上发言人的显示名 / 头像。 */
+export declare function fakeDm(messageId: string, externalId: string, text: string, tenantId?: string, profile?: FakeSenderProfile): InboundEvent;
+/** 群聊文本消息（默认 chat `grp-1`、@ 了机器人）。 */
+export declare function fakeGroupMessage(messageId: string, externalId: string, text: string, opts?: {
+    chatId?: string;
+    threadId?: string;
+    mentionsBot?: boolean;
+    tenantId?: string;
+} & FakeSenderProfile): InboundEvent;
+/** 卡片按钮操作；`target` 取卡片所在的消息目标（群里带 threadId）。 */
+export declare function fakeCardAction(messageId: string, externalId: string, action: CardAction, target: ChannelTarget, tenantId?: string, profile?: FakeSenderProfile): InboundEvent;
+/** 通讯录成员（租户 t1；邮箱缺省 `<id>@corp.example`、已验证）。 */
+export declare function fakeDirectoryMember(externalId: string, over?: Partial<DirectoryMember>): DirectoryMember;
+/** Signature header of the fake platform's webhooks (`sha256=<hex HMAC-SHA256 of the raw body>`). */
+export declare const FAKE_WEBHOOK_SIGNATURE_HEADER = "x-fake-signature";
+/**
+ * Signs a fake-platform webhook body the way the `fake-im` test plugin verifies it: returns the
+ * value for {@link FAKE_WEBHOOK_SIGNATURE_HEADER}, `sha256=` + hex HMAC-SHA256(secret, body).
+ */
+export declare function signFakeWebhook(body: string | Uint8Array, secret: string): string;
+/** Body of a fake-platform webhook that delivers events (`fake-im` answers with its ack). */
+export declare const fakeWebhookEvents: (events: InboundEvent[]) => string;
+/** Body of a fake-platform URL verification request (`fake-im` echoes `{ challenge }`). */
+export declare const fakeWebhookChallenge: (challenge: string) => string;