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

package/dist/fake-git-server.js

@@ -0,0 +1,323 @@
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { appendFile, mkdtemp, readFile, rm } from "node:fs/promises";
+import { createServer } from "node:http";
+import { tmpdir } from "node:os";
+import { join, posix } from "node:path";
+const REPO_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+/** Git runs with no user or system config, so a developer's settings never change the repos. */
+function gitEnv(extra = {}) {
+    return {
+        PATH: process.env.PATH ?? "",
+        HOME: tmpdir(),
+        GIT_CONFIG_NOSYSTEM: "1",
+        GIT_CONFIG_GLOBAL: "/dev/null",
+        GIT_AUTHOR_NAME: "Fake Git",
+        GIT_AUTHOR_EMAIL: "fake-git@example.com",
+        GIT_COMMITTER_NAME: "Fake Git",
+        GIT_COMMITTER_EMAIL: "fake-git@example.com",
+        ...extra,
+    };
+}
+function git(args, o = {}) {
+    return new Promise((resolve, reject) => {
+        // A command that reads no input gets no stdin pipe: it can exit before a write to its stdin is
+        // dispatched, and that write then fails with EPIPE (an uncaught error, seen under load on Linux).
+        const p = spawn("git", args, {
+            env: gitEnv(o.env),
+            cwd: o.cwd ?? tmpdir(),
+            stdio: [o.input === undefined ? "ignore" : "pipe", "pipe", "pipe"],
+        });
+        const out = [];
+        const err = [];
+        let stdinError;
+        p.stdout?.on("data", (b) => out.push(b));
+        p.stderr?.on("data", (b) => err.push(b));
+        p.on("error", reject);
+        p.on("close", (code) => {
+            if (code !== 0) {
+                reject(new Error(`git ${args[0]} failed (${code}): ${Buffer.concat(err).toString()}`));
+            }
+            else if (stdinError !== undefined) {
+                // The input was not fully delivered, so the output is not for that input.
+                reject(new Error(`git ${args[0]}: writing stdin failed: ${stdinError.message}`));
+            }
+            else
+                resolve(Buffer.concat(out).toString("utf8").trim());
+        });
+        if (o.input !== undefined && p.stdin !== null) {
+            p.stdin.on("error", (e) => {
+                stdinError = e;
+            });
+            if (o.input.length === 0)
+                p.stdin.end();
+            else
+                p.stdin.end(o.input);
+        }
+    });
+}
+/** Starts `git http-backend` as a CGI script for one request (smart HTTP, read-only). */
+function spawnCgi(root, req) {
+    const url = new URL(req.url ?? "/", "http://127.0.0.1");
+    const env = {
+        GIT_PROJECT_ROOT: root,
+        GIT_HTTP_EXPORT_ALL: "1",
+        PATH_INFO: decodeURIComponent(url.pathname),
+        QUERY_STRING: url.search.replace(/^\?/, ""),
+        REQUEST_METHOD: req.method ?? "GET",
+        CONTENT_TYPE: req.headers["content-type"] ?? "",
+        REMOTE_ADDR: "127.0.0.1",
+    };
+    const len = req.headers["content-length"];
+    if (typeof len === "string")
+        env.CONTENT_LENGTH = len;
+    const proto = req.headers["git-protocol"];
+    if (typeof proto === "string")
+        env.GIT_PROTOCOL = proto;
+    const enc = req.headers["content-encoding"];
+    if (typeof enc === "string")
+        env.HTTP_CONTENT_ENCODING = enc;
+    const p = spawn("git", ["http-backend"], { env: gitEnv(env) });
+    // http-backend may exit without reading the whole body (a GET, or a request it refuses): the
+    // write then fails with EPIPE. Its exit status and output decide the response, not the pipe.
+    p.stdin.on("error", () => { });
+    req.pipe(p.stdin);
+    return p;
+}
+/** The CGI head (`Status:` and the headers) once the blank line after it has arrived. */
+function cgiHead(head) {
+    const crlf = head.indexOf("\r\n\r\n");
+    const lf = head.indexOf("\n\n");
+    const end = crlf >= 0 ? crlf : lf;
+    if (end < 0)
+        return undefined;
+    let status = 200;
+    const headers = {};
+    for (const line of head.subarray(0, end).toString("latin1").split(/\r?\n/)) {
+        const i = line.indexOf(":");
+        if (i < 0)
+            continue;
+        const k = line.slice(0, i).trim().toLowerCase();
+        const v = line.slice(i + 1).trim();
+        if (k === "status")
+            status = Number.parseInt(v, 10);
+        else
+            headers[k] = v;
+    }
+    return { status, headers, bodyStart: end + (crlf >= 0 ? 4 : 2) };
+}
+/** Streams http-backend's answer to one request. */
+function serveCgi(root, req, res) {
+    const p = spawnCgi(root, req);
+    // A client that goes away mid-response needs no more output.
+    res.on("close", () => {
+        if (p.exitCode === null && p.signalCode === null)
+            p.kill();
+    });
+    let head = Buffer.alloc(0);
+    let headDone = false;
+    p.stdout.on("data", (chunk) => {
+        if (headDone) {
+            res.write(chunk);
+            return;
+        }
+        head = Buffer.concat([head, chunk]);
+        const h = cgiHead(head);
+        if (h === undefined)
+            return;
+        headDone = true;
+        res.writeHead(h.status, h.headers);
+        res.write(head.subarray(h.bodyStart));
+    });
+    p.on("close", () => {
+        if (!headDone)
+            res.writeHead(502);
+        res.end();
+    });
+    p.on("error", () => {
+        if (!res.headersSent)
+            res.writeHead(502);
+        res.end();
+    });
+}
+/** Runs http-backend for one request and collects its answer (undefined when it printed none). */
+function runCgi(root, req) {
+    return new Promise((resolve) => {
+        const p = spawnCgi(root, req);
+        const out = [];
+        p.stdout.on("data", (b) => out.push(b));
+        p.on("error", () => resolve(undefined));
+        p.on("close", (code) => {
+            const all = Buffer.concat(out);
+            const h = cgiHead(all);
+            resolve(h === undefined
+                ? undefined
+                : {
+                    status: h.status,
+                    headers: h.headers,
+                    body: all.subarray(h.bodyStart),
+                    ok: code === 0,
+                });
+        });
+    });
+}
+const NL = Buffer.from("\n");
+/** C-style quoting of a fast-import path when it needs it. */
+const fastImportPath = (path) => /^"|[\n"\\]/.test(path)
+    ? `"${path.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\n")}"`
+    : path;
+/**
+ * A fake git host: bare repos in a temp dir, served read-only by the system `git http-backend`
+ * (smart HTTP, as CGI) over a loopback http server. Repos allow fetching any reachable commit by sha
+ * (`uploadpack.allowReachableSHA1InWant`, as GitHub does). Needs `git` on PATH.
+ *
+ * Spawning git is what these tests spend their time on, and it slows down most under load, so the
+ * server spawns as little as it can while every answer still comes from git: a commit is one
+ * `git fast-import`, and a ref advertisement (`GET …/info/refs`) is answered by http-backend once per
+ * repo state, then repeated until the next commit to that repo.
+ */
+export async function startFakeGitServer() {
+    const root = await mkdtemp(join(tmpdir(), "capybara-fake-git-"));
+    const requests = [];
+    let redirect = null;
+    /** Ref advertisements by repo, then by request (path, query and `Git-Protocol`). */
+    const advertised = new Map();
+    /** Bumped by every commit to a repo: an answer read before the commit is not kept. */
+    const generation = new Map();
+    const repoOf = (pathname) => /^\/([^/]+)\.git\/info\/refs$/.exec(pathname)?.[1];
+    const server = createServer((req, res) => {
+        const r = { method: req.method ?? "GET", path: req.url ?? "/" };
+        if (typeof req.headers.authorization === "string")
+            r.authorization = req.headers.authorization;
+        requests.push(r);
+        if (redirect !== null) {
+            res.writeHead(302, { location: redirect }).end();
+            return;
+        }
+        const url = new URL(req.url ?? "/", "http://127.0.0.1");
+        const repo = req.method === "GET" ? repoOf(url.pathname) : undefined;
+        if (repo === undefined) {
+            serveCgi(root, req, res);
+            return;
+        }
+        const key = `${url.pathname}${url.search}|${req.headers["git-protocol"] ?? ""}`;
+        const send = (a) => res.writeHead(a.status, a.headers).end(a.body);
+        const known = advertised.get(repo)?.get(key);
+        if (known !== undefined) {
+            send(known);
+            return;
+        }
+        const gen = generation.get(repo) ?? 0;
+        void runCgi(root, req).then((a) => {
+            if (a === undefined) {
+                res.writeHead(502).end();
+                return;
+            }
+            if (a.ok && a.status === 200 && (generation.get(repo) ?? 0) === gen) {
+                const byKey = advertised.get(repo) ?? new Map();
+                byKey.set(key, a);
+                advertised.set(repo, byKey);
+            }
+            send(a);
+        });
+    });
+    await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+    const port = server.address().port;
+    const repoDir = async (repo) => {
+        if (!REPO_RE.test(repo))
+            throw new Error(`invalid fake repo name: ${repo}`);
+        const dir = join(root, `${repo}.git`);
+        if (!existsSync(dir)) {
+            await git(["init", "--bare", "--quiet", "--initial-branch=main", dir]);
+            await appendFile(join(dir, "config"), "[uploadpack]\n\tallowReachableSHA1InWant = true\n");
+        }
+        return dir;
+    };
+    const commit = async (repo, files, opts = {}) => {
+        const gitDir = await repoDir(repo);
+        const branch = opts.branch ?? "main";
+        const env = { GIT_DIR: gitDir };
+        // the whole tree, by path (a later entry for the same path wins, as a later file write did)
+        const entries = new Map();
+        const blobs = [];
+        // mark :1 is the commit; blobs are :2, :3, …
+        let mark = 1;
+        const inline = (content) => {
+            const b = Buffer.from(content, "utf8");
+            mark++;
+            blobs.push(Buffer.from(`blob\nmark :${mark}\ndata ${b.length}\n`), b, NL);
+            return `:${mark}`;
+        };
+        for (const [path, content] of Object.entries(files)) {
+            const p = posix.normalize(path.replace(/^\.\//, ""));
+            if (p === "." || p === ".." || p.startsWith("../") || posix.isAbsolute(p)) {
+                throw new Error(`fake git path escapes: ${path}`);
+            }
+            entries.set(p, `M 100644 ${inline(content)} ${fastImportPath(p)}`);
+        }
+        for (const [path, linkTarget] of Object.entries(opts.symlinks ?? {})) {
+            entries.set(path, `M 120000 ${inline(linkTarget)} ${fastImportPath(path)}`);
+        }
+        for (const [path, sha] of Object.entries(opts.submodules ?? {})) {
+            entries.set(path, `M 160000 ${sha} ${fastImportPath(path)}`);
+        }
+        if (opts.treeDag !== undefined) {
+            const { name, fanout, depth } = opts.treeDag;
+            let level = await git(["mktree"], { env, input: "" });
+            for (let d = 0; d < depth; d++) {
+                let lines = "";
+                for (let i = 0; i < fanout; i++)
+                    lines += `040000 tree ${level}\td${i}\n`;
+                level = await git(["mktree"], { env, input: lines });
+            }
+            entries.set(name, `M 040000 ${level} ${fastImportPath(name)}`);
+        }
+        const parent = await readFile(join(gitDir, "refs", "heads", branch), "utf8").then((s) => s.trim(), () => "");
+        const who = `Fake Git <fake-git@example.com> ${Math.floor(Date.now() / 1000)} +0000`;
+        const message = Buffer.from(`commit on ${branch}`);
+        const lines = [
+            `commit refs/heads/${branch}`,
+            "mark :1",
+            `author ${who}`,
+            `committer ${who}`,
+            `data ${message.length}`,
+            message.toString(),
+            ...(parent ? [`from ${parent}`] : []),
+            "deleteall",
+            ...entries.values(),
+            "",
+        ];
+        if (opts.tag !== undefined) {
+            const t = opts.tag;
+            if (t.annotated) {
+                const m = `tag ${t.name}`;
+                lines.push(`tag ${t.name}`, "from :1", `tagger ${who}`, `data ${Buffer.byteLength(m)}`, m);
+            }
+            else
+                lines.push(`reset refs/tags/${t.name}`, "from :1", "");
+        }
+        lines.push("get-mark :1", "done", "");
+        const sha = await git(["fast-import", "--quiet", "--force", "--done"], {
+            env,
+            input: Buffer.concat([...blobs, Buffer.from(lines.join("\n"))]),
+        });
+        generation.set(repo, (generation.get(repo) ?? 0) + 1);
+        advertised.delete(repo);
+        return sha;
+    };
+    return {
+        url: (repo) => `http://127.0.0.1:${port}/${repo}.git`,
+        commit,
+        setRedirect: (l) => {
+            redirect = l;
+        },
+        requests,
+        stop: async () => {
+            await new Promise((resolve) => {
+                server.closeAllConnections();
+                server.close(() => resolve());
+            });
+            await rm(root, { recursive: true, force: true });
+        },
+    };
+}

package/dist/fake-lark.d.ts

@@ -0,0 +1,234 @@
+/**
+ * 可编程的假 Lark（Lark 渠道插件测试用），扮演开放平台的三块能力：
+ *
+ * - **OpenAPI**：`tenant_access_token/internal`（App ID 不符 → `10014`，Secret 不符 → `10015`，HTTP 200）、
+ *   `bot/v3/info`、`tenant/v2/tenant/query`、发送消息 `POST /open-apis/im/v1/messages?receive_id_type=chat_id`、
+ *   回复消息 `POST …/messages/:id/reply`（`reply_in_thread`）、更新卡片 `PATCH …/messages/:id`、用户资料
+ *   `GET /open-apis/contact/v3/users/:id`。带 tenant token 的接口校验 `Authorization: Bearer`（未签发或已吊销 →
+ *   HTTP 400 `99991663`）。发送 / 回复按 `uuid` 去重（与 Lark 一致，同一 uuid 只发一条）；请求体超过 30 KB →
+ *   `230025`；卡片须是 JSON 2.0（`schema: "2.0"`，`config.update_multi` 不为 false），否则 `230099`。
+ *   {@link FakeLarkServer.failNext} 让某个接口返回错误码 / HTTP 状态（429 带 `x-ogw-ratelimit-reset`）。
+ * - **长连接**：`POST /callback/ws/endpoint`（官方 SDK `WSClient` 取接入点；凭据不符时与真实 Lark 一样回
+ *   `1000040343 internal error`）返回 `ws://…/ws?…&service_id=1`；WebSocket 上按 SDK 的 protobuf 帧格式
+ *   `pbbp2.Frame`（字段号与 `@larksuiteoapi/node-sdk` 内置的定义一致）收发：测试用 {@link FakeLarkServer.pushEvent}
+ *   推事件帧（`method = 1`，头 `type = event`、`message_id`、`sum = 1`、`seq = 0`），记下客户端回的响应帧
+ *   （`acks`：`code` 200 / 500 与解码后的 `data`）；客户端的 ping 回 pong。
+ *
+ * - **网页登录（OAuth 2.0 授权码 + PKCE）**：授权页 `GET /open-apis/authen/v1/authorize`（真实 Lark 在
+ *   `accounts.larksuite.com`；测试在授权地址后加 `&as=<open_id>` 表示以该用户同意授权，302 回
+ *   `redirect_uri?code=…&state=…`；`client_id` 不符或用户不存在 → `error=access_denied`）、换 token
+ *   `POST /open-apis/authen/v2/oauth/token`（授权码单次有效：未知 → `20003`、用过 → `20065`；`client_secret` 不符 →
+ *   `20002`；`redirect_uri` 必须与授权时完全相同，否则 `20071`；带了 `code_challenge` 的授权码必须给对
+ *   `code_verifier`，否则 `20049`；错误均为 HTTP 400 + `{code, error, error_description}`）、用户信息
+ *   `GET /open-apis/authen/v1/user_info`（Bearer user_access_token；`open_id`、`union_id`、`tenant_key`、`name`、
+ *   `en_name`、`avatar_*`、`email`、`enterprise_email`）。
+ * - **通讯录**：`GET /open-apis/contact/v3/departments/:id/children`（`fetch_child=true` 时递归；`page_size` 最大 50，
+ *   `page_token` / `has_more`）、`GET /open-apis/contact/v3/users/find_by_department`（部门直属用户，根部门为 `0`；
+ *   `page_size` 最大 50；`status` 为 `is_frozen` / `is_resigned` / `is_activated` / `is_exited` / `is_unjoin`，
+ *   {@link FakeLarkServer.hideUserStatus} 模拟没有开通状态字段所需的权限）。
+ *
+ * 记录：`messages`（发出的消息，卡片已解析）、`updates`（对已发消息的更新）、`calls`（每次 OpenAPI 调用）。
+ */
+export interface FakeLarkUser {
+    openId: string;
+    name: string;
+    avatar72?: string;
+    enName?: string;
+    /** 用户所在租户（默认本服务的 `tenantKey`；`user_info` 的 `tenant_key`）。 */
+    tenantKey?: string;
+    email?: string;
+    enterpriseEmail?: string;
+    /** 直属部门（`open_department_id`，根部门为 `"0"`）；不给则不出现在通讯录列表里。 */
+    departments?: string[];
+    /** 通讯录 `status`（缺省：已激活，其他均为 false）。 */
+    status?: {
+        isFrozen?: boolean;
+        isResigned?: boolean;
+        isActivated?: boolean;
+        isExited?: boolean;
+        isUnjoin?: boolean;
+    };
+}
+/** 通讯录部门。 */
+export interface FakeLarkDepartment {
+    openDepartmentId: string;
+    name: string;
+    /** 上级部门（根部门为 `"0"`）。 */
+    parent: string;
+}
+/** 机器人发出（或更新后）的一条消息。 */
+export interface FakeLarkMessage {
+    messageId: string;
+    chatId: string;
+    /** 回复时：话题根消息 id。 */
+    rootId?: string;
+    /** 回复时：被回复的消息 id。 */
+    parentId?: string;
+    replyInThread: boolean;
+    msgType: string;
+    /** 解析后的 `content`（卡片 JSON）。 */
+    card: unknown;
+    uuid?: string;
+    at: number;
+}
+export interface FakeLarkCall {
+    api: string;
+    token: string;
+    query: Record<string, string>;
+    body: Record<string, unknown>;
+}
+/** 客户端对事件帧的响应。 */
+export interface FakeLarkAck {
+    id: string;
+    code: number;
+    /** 响应的 `data`（base64 JSON 解码后）；处理函数没有返回值时为 undefined。 */
+    data?: unknown;
+    at: number;
+}
+export interface FakeLarkFailure {
+    /** HTTP 状态（默认 400）。 */
+    status?: number;
+    /** 响应体的 `code`（不给时只回 HTTP 状态与空体）。 */
+    code?: number;
+    msg?: string;
+    /** 429 时的 `x-ogw-ratelimit-reset`（秒）。 */
+    retryAfter?: number;
+}
+export interface FakeLarkOptions {
+    appId?: string;
+    appSecret?: string;
+    tenantKey?: string;
+    botOpenId?: string;
+    botName?: string;
+    /** 同一租户里的其他自建应用（只能取 tenant token、查企业信息；测试「登录 / 机器人不是同一个应用」）。 */
+    extraApps?: {
+        appId: string;
+        appSecret: string;
+    }[];
+}
+/**
+ * 接口名：`token`、`bot`、`tenant`、`create`、`reply`、`patch`、`user`、`endpoint`、`oauth_token`、`user_info`、
+ * `departments`、`find_by_department`。
+ */
+export type FakeLarkApi = "token" | "bot" | "tenant" | "create" | "reply" | "patch" | "user" | "endpoint" | "oauth_token" | "user_info" | "departments" | "find_by_department";
+export interface FakeLarkServer {
+    /** 开放平台根地址（插件的 `apiUrl` / SDK 的 `domain`）。 */
+    url: string;
+    appId: string;
+    appSecret: string;
+    tenantKey: string;
+    botOpenId: string;
+    botName: string;
+    messages: FakeLarkMessage[];
+    updates: FakeLarkMessage[];
+    calls: FakeLarkCall[];
+    acks: FakeLarkAck[];
+    users: Map<string, FakeLarkUser>;
+    /** 通讯录部门（按插入顺序列出）。 */
+    departments: FakeLarkDepartment[];
+    /** 已签发的 user_access_token 数。 */
+    userTokensIssued(): number;
+    /** 通讯录列表里不带 `status`（模拟没有开通状态字段所需的权限）。 */
+    hideUserStatus(hide: boolean): void;
+    /** 已签发的 tenant token 数。 */
+    tokensIssued(): number;
+    /** 吊销所有已签发的 token（之后的调用回 99991663）。 */
+    revokeTokens(): void;
+    /** 长连接接入点被调用的次数。 */
+    endpointCalls(): number;
+    /** 成功建立的 WebSocket 连接数。 */
+    connectionsOpened(): number;
+    openSockets(): number;
+    maxConcurrentSockets(): number;
+    /**
+     * 当前打开的长连接各自的对端（客户端）TCP 端口，按打开顺序。双副本测试据此（经操作系统查端口属于哪个进程）
+     * 找出持有长连接的副本——真实插件不带 `x-pid` 之类的标记。
+     */
+    socketPeerPorts(): number[];
+    /** 接下来 `count` 次（先放过 `skip` 次正常调用）该接口返回 `failure`。 */
+    failNext(api: FakeLarkApi, failure: FakeLarkFailure, count?: number, skip?: number): void;
+    /**
+     * 模拟应用的通讯录权限范围不是「全部成员」：对根部门（`0`）的子部门列表与直属用户列表回 HTTP 400
+     * `40004`（无部门权限）。
+     */
+    rejectRootDepartment(reject: boolean): void;
+    /** 之后该接口的每次调用先等 `ms` 毫秒再响应（0 取消）。 */
+    delay(api: FakeLarkApi, ms: number): void;
+    /** 接下来 `count` 条 WebSocket 连接在建立后立即被关闭。 */
+    dropNextConnections(count: number): void;
+    /** 登记一条（用户发的）消息，使之可以被回复。`pushEvent` 推的消息事件会自动登记。 */
+    registerMessage(messageId: string, chatId: string): void;
+    /**
+     * 推一个事件（schema 2.0 负载，如 {@link larkMessageEvent} / {@link larkCardAction} 的结果）给最近打开的连接，
+     * 返回帧的 message_id。缺省的 `header.tenant_key` / `app_id` 与 `event.sender.tenant_key` 用本服务的值补上。
+     * 该连接还没收到客户端的第一个 ping 时先暂存、收到后再发：SDK 在 `open` 之后（微任务里）才挂上 message 监听，
+     * 与握手响应一起到达的帧会被它丢掉（服务端此时已算连接打开）。
+     */
+    pushEvent(payload: Record<string, unknown>): string;
+    waitForAck(id: string, timeoutMs?: number): Promise<FakeLarkAck>;
+    acked(id: string): boolean;
+    /** 关闭所有长连接（模拟服务端断开）。 */
+    disconnectAll(): void;
+    /** 消息最终的卡片（有更新取最后一次）。 */
+    finalCard(m: FakeLarkMessage): unknown;
+    /** 卡片里全部 markdown 组件的内容（按顺序，换行连接）。 */
+    cardText(card: unknown): string;
+    stop(): Promise<void>;
+}
+/** 启动假 Lark（监听 127.0.0.1 随机端口）。 */
+export declare function startFakeLark(opts?: FakeLarkOptions): Promise<FakeLarkServer>;
+/** 一条 `im.message.receive_v1` 事件（schema 2.0）。`text` 给的是 text 消息的原文（@ 用 `@_user_N` 占位）。 */
+export declare function larkMessageEvent(o: {
+    openId: string;
+    chatId: string;
+    chatType: "p2p" | "group";
+    text?: string;
+    messageId?: string;
+    rootId?: string;
+    parentId?: string;
+    threadId?: string;
+    mentions?: {
+        key: string;
+        openId: string;
+        name: string;
+    }[];
+    tenantKey?: string;
+    messageType?: string;
+    content?: string;
+}): Record<string, unknown>;
+/** 卡片按钮（{@link findLarkButton} 的结果）。 */
+export interface FakeLarkButton {
+    text: string;
+    type?: string;
+    name?: string;
+    /** 回传值（`behaviors` 里 `callback` 的 `value`）。 */
+    value?: unknown;
+    /** 打开链接（`behaviors` 里 `open_url` 的 `default_url`）。 */
+    url?: string;
+}
+/** 在卡片里找按钮（展开 column_set / form）。 */
+export declare function findLarkButton(card: unknown, match: (b: FakeLarkButton) => boolean): FakeLarkButton | undefined;
+/** 用户点了某条消息卡片上的按钮（`card.action.trigger`，schema 2.0）。`formValue` 为表单提交的数据。 */
+export declare function larkCardAction(user: {
+    openId: string;
+    tenantKey?: string;
+}, message: FakeLarkMessage, button: FakeLarkButton, opts?: {
+    eventId?: string;
+    formValue?: Record<string, unknown>;
+}): Record<string, unknown>;
+/**
+ * Encrypts a Lark webhook payload the way Lark does when an Encrypt Key is set
+ * (https://open.larksuite.com/document/ukTMukTMukTM/uYDNxYjL2QTM24iN0EjN/event-subscription-configure-/encrypt-key-encryption-configuration-case):
+ * AES-256-CBC with key = SHA-256(encryptKey), a random 16-byte IV prepended to the ciphertext,
+ * base64. Returns the request body `{"encrypt":"<base64>"}`.
+ */
+export declare function encryptLarkWebhook(payload: unknown, encryptKey: string): string;
+/**
+ * Signs a Lark webhook request: returns the `x-lark-request-timestamp` (seconds),
+ * `x-lark-request-nonce` and `x-lark-signature` headers, where the signature is
+ * hex SHA-256(timestamp + nonce + encryptKey + raw body).
+ */
+export declare function signLarkWebhook(body: string | Uint8Array, encryptKey: string, opts?: {
+    timestamp?: number;
+    nonce?: string;
+}): Record<string, string>;