@evandu/super-pi 0.1.151 → 0.1.153

package/dist/server/feishu.js

@@ -1,695 +0,0 @@
-/**
- * THE FEISHU CLIENT: everything Super Pi knows how to do with a cloud document on Feishu.
- *
- * WHY THIS LAYER EXISTS AT ALL. Feishu's document API is not "read a file" and "write a file". A
- * document is a TREE OF BLOCKS, the API refuses to create a document with content in it, and the
- * official way to put Markdown into a document is a three-step dance (convert to blocks, then
- * insert them as nested blocks under the page block). An agent that had to know that would be
- * writing protocol details into every prompt. So the protocol lives here, once, and what is left
- * above it is "read this document" and "write this document".
- *
- * WHY AN HTTP CLIENT AND NOT THE OFFICIAL SDK. The official SDK (`@larksuiteoapi/node-sdk`) is a
- * good library, but it is a dependency of the PACKAGE, and this package's whole point is that it
- * installs and runs. Every call it makes is a plain HTTP call with a bearer token, so the four
- * endpoints this feature needs are four functions - and the credential handling (a token that
- * expires, a token that has to be refreshed, a rate limit that has to be waited out) is the part
- * that is worth writing carefully and testing on its own.
- *
- * WHAT THE IDENTITY IS. Everything here runs as the APPLICATION (`tenant_access_token`), never as
- * a person. That is the identity that needs no OAuth dance and no browser, and it is also the
- * identity that can only touch the documents the application has been made a collaborator on.
- * See `docs/FEISHU.md` for the setup that implies, because it is the one thing a user must do
- * before any of this works.
- */
-/** The tool that reads a Feishu document. */
-export const FEISHU_READ_TOOL_NAME = "feishu_doc_read";
-/** The tool that writes a Feishu document. */
-export const FEISHU_WRITE_TOOL_NAME = "feishu_doc_write";
-/**
- * The two hosts a domain is made of.
- *
- * The token endpoint is on a DIFFERENT host from the API (`accounts.` rather than `open.`), which
- * is the kind of detail that produces a confusing 404 the first time and never again.
- */
-const DOMAINS = {
-    feishu: { api: "https://open.feishu.cn", accounts: "https://accounts.feishu.cn" },
-    lark: { api: "https://open.larksuite.com", accounts: "https://accounts.larksuite.com" },
-};
-/**
- * The gap between two writes to Feishu.
- *
- * The document API allows THREE write calls per second per application AND per document, and the
- * refusal is a 429 in the middle of a three-call sequence (create, convert, insert) that a user
- * would otherwise never notice. 360ms is a little over the 333ms the limit implies, so the limit
- * is never what stops us.
- */
-const WRITE_INTERVAL_MS = 360;
-/** How long a token is treated as fresh. The real lifetime is two hours; this is the safety margin. */
-const TOKEN_SKEW_MS = 120_000;
-/** The most blocks one nested-block call may carry. */
-const MAX_DESCENDANTS_PER_CALL = 1000;
-/** The most blocks one list call returns. */
-const MAX_BLOCKS_PER_PAGE = 500;
-/**
- * THE BLOCK TYPE NUMBERS, and the key each type stores its payload under.
- *
- * The payload key is part of the wire format: a block of type 2 carries `text`, a block of type 3
- * carries `heading1`, and a reader that guessed the key would read an empty document. The table is
- * the official one, and the ones this code does not render are listed anyway so that an unknown
- * type can still be recognised and descended into.
- */
-const BLOCK_TYPE_KEYS = {
-    1: "page", 2: "text", 3: "heading1", 4: "heading2", 5: "heading3", 6: "heading4", 7: "heading5",
-    8: "heading6", 9: "heading7", 10: "heading8", 11: "heading9", 12: "ordered", 13: "bullet",
-    14: "code", 15: "quote", 17: "todo", 18: "bitable", 19: "callout", 21: "diagram", 22: "divider",
-    23: "file", 24: "grid", 25: "grid_column", 26: "image", 29: "mindnote", 30: "sheet", 31: "table",
-    32: "table_cell", 34: "quote_container",
-};
-/**
- * THE CODE LANGUAGES, by the number the API uses.
- *
- * Only the ones worth naming are here. A wrong name in a code fence is a cosmetic mistake, and a
- * fence with no name at all is also fine - so the fallback is an unnamed fence rather than a
- * guess.
- */
-const CODE_LANGUAGES = {
-    1: "text", 8: "c", 17: "cpp", 22: "csharp", 27: "go", 30: "java", 35: "javascript",
-    43: "kotlin", 49: "python", 56: "sql", 60: "shell", 63: "typescript", 67: "yaml", 75: "toml",
-};
-/**
- * A REFUSAL FROM FEISHU, with the code kept alongside the message.
- *
- * The code is kept because the message Feishu sends is written for a developer reading a log,
- * and the part a person needs - "add this application as a collaborator", "open this permission
- * point" - is not in it.
- */
-export class FeishuError extends Error {
-    code;
-    hint;
-    constructor(code, message, hint) {
-        super(message);
-        this.code = code;
-        this.hint = hint;
-        this.name = "FeishuError";
-    }
-}
-/**
- * WHAT TO DO ABOUT A FEISHU ERROR CODE, in the words of the person who has to act on it.
- *
- * These are the failures a user WILL hit, because they are the setup steps: the application has
- * no permission point, or the application has never been added to the document, or the
- * credentials are wrong. Each one names the place in the Feishu interface where it is fixed,
- * because "code 99991672" is not something anybody can act on.
- */
-const ERROR_HINTS = {
-    20002: "App Secret 不正确。请到「设置 → 飞书」核对 App ID 与 App Secret（开发者后台：凭证与基础信息）。",
-    20009: "这个应用没有安装到当前企业。请在飞书管理后台确认应用已被启用并发布。",
-    20042: "应用已被停用。请到飞书管理后台重新启用它。",
-    20068: "应用没有开通这个接口所需的权限点。请在开发者后台「权限管理」里开通后发布新版本。",
-    99991663: "访问凭证无效或已过期。Super Pi 会自动重新获取，请重试一次；若仍然失败，请检查应用状态。",
-    99991672: "应用缺少调用这个接口的权限点。请在开发者后台「权限管理」里开通后发布新版本。",
-    99991400: "触发了飞书的频率限制。Super Pi 会自动等待后重试。",
-    1069902: "当前应用没有这篇文档的权限。请在文档页面右上角「…」→「更多」→「添加文档应用」，把这个应用加为协作者（需要文档所有者或管理员操作）。",
-    1069908: "应用没有目标文件夹的权限。请把该文件夹分享给含有这个应用的群组。",
-    1069912: "目标文件夹不存在。",
-    131005: "这个知识库节点不存在，或应用没有它的权限。",
-    131006: "应用没有这个知识库的权限。",
-    1770002: "文档不存在，或已被删除。",
-    1770004: "文档的块数量已达上限。",
-    1770006: "块的父子关系不合法。",
-    1770007: "某个块的子块过多。",
-    1770014: "块的父子关系与文档结构不符。",
-    1770021: "文档版本过旧，请重新读取文档后再写。",
-};
-/**
- * The message a refusal is shown with: what Feishu said, and what to do about it.
- */
-export function describeFeishuError(code, message) {
-    const hint = ERROR_HINTS[code];
-    const base = `飞书接口拒绝了这次请求（错误码 ${code}）：${message || "没有给出原因"}`;
-    return hint ? `${base}。${hint}` : base;
-}
-/**
- * The document kinds this code cannot read, and why.
- *
- * A refusal that names the kind is worth much more than "unsupported": a person who pasted a
- * spreadsheet link knows exactly what to do next.
- */
-const UNSUPPORTED_KINDS = {
-    sheets: "电子表格（sheet）暂不支持读写，请先用飞书把内容转成新版文档（docx）。",
-    base: "旧版文档（doc）暂不支持读写，请先在飞书里把它升级为新版文档（docx）。",
-    file: "云空间里的文件（file）不是文档，Super Pi 不读它。",
-    bitable: "多维表格（bitable）暂不支持读写。",
-    mindnote: "思维导图（mindnote）暂不支持读写。",
-    slides: "幻灯片（slides）暂不支持读写。",
-    docs: "旧版文档（doc）暂不支持读写，请先在飞书里把它升级为新版文档（docx）。",
-};
-/**
- * Reads a document reference: a full URL, or a bare token.
- *
- * WHY BARE TOKENS ARE ACCEPTED. A person reading a document's URL sees the token in it, and an
- * agent that has been handed `doxcn...` should not have to be told to wrap it in a URL first.
- */
-export function parseFeishuTarget(input) {
-    const raw = String(input ?? "").trim();
-    if (!raw)
-        throw new Error("没有给出飞书文档的链接或 token。");
-    if (raw.includes("://")) {
-        let url;
-        try {
-            url = new URL(raw);
-        }
-        catch {
-            throw new Error(`这不像一个飞书链接：${raw}`);
-        }
-        const parts = url.pathname.split("/").filter(Boolean);
-        const kindIndex = parts.findIndex((part) => part in UNSUPPORTED_KINDS || part === "docx" || part === "wiki");
-        if (kindIndex === -1)
-            throw new Error(`这个链接不像飞书云文档：${raw}`);
-        const kind = parts[kindIndex];
-        const token = parts[kindIndex + 1];
-        if (!token)
-            throw new Error(`这个飞书链接里没有文档 token：${raw}`);
-        if (kind in UNSUPPORTED_KINDS)
-            throw new Error(UNSUPPORTED_KINDS[kind]);
-        return { kind: kind === "wiki" ? "wiki" : "docx", token, host: url.hostname };
-    }
-    const bare = raw.replace(/^\/+/, "");
-    if (bare.includes("/"))
-        throw new Error(`这不像一个飞书文档的 token：${raw}`);
-    if (bare.startsWith("wik"))
-        return { kind: "wiki", token: bare };
-    if (bare.startsWith("docc"))
-        throw new Error(UNSUPPORTED_KINDS.base);
-    if (bare.startsWith("sht"))
-        throw new Error(UNSUPPORTED_KINDS.sheets);
-    return { kind: "docx", token: bare };
-}
-/** The text of a text-like payload, with links and mentions rendered as Markdown. */
-function textOf(payload) {
-    const holder = (payload ?? {});
-    const elements = Array.isArray(holder.elements) ? holder.elements : [];
-    let out = "";
-    for (const element of elements) {
-        if (element.text_run) {
-            const content = element.text_run.content ?? "";
-            const link = element.text_run.text_element_style?.link?.url;
-            if (link) {
-                // Feishu stores the URL encoded, and a decode that trips over a stray percent sign must not
-                // lose the text: the link is decoration, the words are the content.
-                let target = link;
-                try {
-                    target = decodeURIComponent(link);
-                }
-                catch { /* keep the raw value */ }
-                out += `[${content}](${target})`;
-            }
-            else {
-                out += content;
-            }
-        }
-        else if (element.mention_user) {
-            out += `@${element.mention_user.user_id ?? "某人"}`;
-        }
-        else if (element.mention_doc) {
-            out += `[文档：${element.mention_doc.title ?? element.mention_doc.token ?? ""}]`;
-        }
-        else if (element.equation) {
-            out += `$${element.equation.content ?? ""}$`;
-        }
-        else if (element.file) {
-            out += `[文件：${element.file.name ?? element.file.token ?? ""}]`;
-        }
-        else if (element.reminder) {
-            out += "[提醒]";
-        }
-    }
-    return out;
-}
-/** The payload of a block, whichever key its type stores it under. */
-function payloadOf(block) {
-    const key = BLOCK_TYPE_KEYS[block.block_type];
-    if (!key)
-        return undefined;
-    return block[key];
-}
-/** The plain text of a block, ignoring its children. */
-function blockText(block) {
-    return textOf(payloadOf(block));
-}
-/**
- * The children of a block, in order.
- */
-function childrenOf(block) {
-    return Array.isArray(block?.children) ? block.children : [];
-}
-/**
- * A table, rendered as a Markdown table.
- *
- * The cells arrive as a flat list in row-major order, and the shape of the table is in the table
- * block's own property. A table whose shape cannot be read is rendered as one column per cell,
- * which is wrong but not misleading: the words are all still there.
- */
-function renderTable(block, byId) {
-    const cells = childrenOf(block).map((id) => byId.get(id)).filter((item) => Boolean(item));
-    const property = block.table?.property;
-    const columns = Math.max(1, property?.column_size ?? 1);
-    const rows = [];
-    for (const cell of cells) {
-        const text = childrenOf(cell).map((id) => byId.get(id)).filter((item) => Boolean(item)).map(blockText).join(" ").trim();
-        if (rows.length && rows[rows.length - 1].length < columns)
-            rows[rows.length - 1].push(text);
-        else
-            rows.push([text]);
-    }
-    if (!rows.length)
-        return [];
-    const width = Math.max(columns, ...rows.map((row) => row.length));
-    const pad = (row) => [...row, ...Array(Math.max(0, width - row.length)).fill("")];
-    const lines = [`| ${pad(rows[0]).join(" | ")} |`, `| ${Array(width).fill("---").join(" | ")} |`];
-    for (const row of rows.slice(1))
-        lines.push(`| ${pad(row).join(" | ")} |`);
-    return lines;
-}
-/**
- * Renders a document's blocks as Markdown.
- *
- * WHY MARKDOWN AND NOT THE RAW TEXT. `raw_content` gives the words without the shape: a heading
- * arrives as a heading's text, a list arrives as separate lines, and a reader cannot tell them
- * apart. The block tree is the document, and Markdown is the closest plain-text shape this side of
- * the product already understands.
- */
-export function blocksToMarkdown(blocks) {
-    const byId = new Map();
-    for (const block of blocks)
-        byId.set(block.block_id, block);
-    // The page block is the root of the tree: it has no parent, and its id is the document id.
-    const root = blocks.find((block) => block.block_type === 1 && !block.parent_id) ?? blocks.find((block) => !block.parent_id);
-    if (!root)
-        return "";
-    const lines = renderChildren(childrenOf(root), byId, 0);
-    return lines.join("\n").replace(/\n{3,}/g, "\n\n").trim();
-}
-/**
- * Renders a list of blocks that hang under one parent.
- */
-function renderChildren(ids, byId, depth) {
-    const out = [];
-    let ordered = 0;
-    for (const id of ids) {
-        const block = byId.get(id);
-        if (!block)
-            continue;
-        if (block.block_type === 12)
-            ordered += 1;
-        else
-            ordered = 0;
-        out.push(...renderBlock(block, byId, depth, ordered));
-    }
-    return out;
-}
-/**
- * Renders one block, and whatever hangs under it.
- */
-function renderBlock(block, byId, depth, orderedIndex) {
-    const indent = "  ".repeat(depth);
-    const nested = (nextDepth = depth + 1) => renderChildren(childrenOf(block), byId, nextDepth);
-    switch (block.block_type) {
-        case 1: // page
-            return renderChildren(childrenOf(block), byId, depth);
-        case 2: { // text
-            const text = blockText(block);
-            return text ? [`${indent}${text}`, ...nested()] : nested();
-        }
-        case 3:
-        case 4:
-        case 5:
-        case 6:
-        case 7:
-        case 8:
-        case 9:
-        case 10:
-        case 11: { // heading1..9
-            const level = block.block_type - 2;
-            return [`${indent}${"#".repeat(level)} ${blockText(block)}`.trimEnd(), ...nested()];
-        }
-        case 12: // ordered
-            return [`${indent}${orderedIndex}. ${blockText(block)}`.trimEnd(), ...nested()];
-        case 13: // bullet
-            return [`${indent}- ${blockText(block)}`.trimEnd(), ...nested()];
-        case 14: { // code
-            const language = CODE_LANGUAGES[(payloadOf(block)?.style?.language ?? 1)] ?? "";
-            const text = blockText(block);
-            return [`${indent}\`\`\`${language}`, ...text.split("\n"), `${indent}\`\`\``];
-        }
-        case 15: // quote
-            return [`${indent}> ${blockText(block)}`.trimEnd(), ...nested()];
-        case 17: { // todo
-            const done = payloadOf(block)?.style?.done === true;
-            return [`${indent}- [${done ? "x" : " "}] ${blockText(block)}`.trimEnd(), ...nested()];
-        }
-        case 19: // callout
-            return [`${indent}> ${blockText(block)}`.trimEnd(), ...nested()];
-        case 22: // divider
-            return [`${indent}---`, ...nested()];
-        case 23: { // file
-            const file = block.file;
-            return [`${indent}[文件：${file?.name ?? file?.token ?? ""}]`, ...nested()];
-        }
-        case 24:
-        case 25: // grid, grid_column
-            return nested();
-        case 26: { // image
-            const image = block.image;
-            return [`${indent}![图片](${image?.token ?? ""})`];
-        }
-        case 30: // sheet
-            return [`${indent}[电子表格]`, ...nested()];
-        case 31: // table
-            return [...renderTable(block, byId), ...nested()];
-        case 32: // table cell, seen on its own
-            return nested();
-        case 34: { // quote container
-            const quoted = renderChildren(childrenOf(block), byId, depth);
-            return quoted.map((line) => (line ? `> ${line}` : ">"));
-        }
-        default: {
-            const text = blockText(block);
-            const children = nested();
-            return text ? [`${indent}${text}`, ...children] : children;
-        }
-    }
-}
-const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
-export class FeishuClient {
-    options;
-    token;
-    /** Whether the newer OAuth token endpoint works for this application. */
-    useLegacyAuth = false;
-    /** The write queue. One write at a time, spaced by the interval the API allows. */
-    writeChain = Promise.resolve();
-    lastWriteAt = 0;
-    constructor(options) {
-        this.options = options;
-    }
-    get apiBase() {
-        return DOMAINS[this.options.domain ?? "feishu"].api;
-    }
-    get accountsBase() {
-        return DOMAINS[this.options.domain ?? "feishu"].accounts;
-    }
-    get fetchImpl() {
-        return this.options.fetchImpl ?? fetch;
-    }
-    /**
-     * THE ACCESS TOKEN, fetched once and reused.
-     *
-     * The lifetime is two hours and the API says to believe the number it returns rather than a
-     * hardcoded one, so the expiry comes from the response and the token is renewed a couple of
-     * minutes before it runs out.
-     */
-    async accessToken(force = false) {
-        if (!force && this.token && this.token.expiresAt - Date.now() > TOKEN_SKEW_MS)
-            return this.token.value;
-        const token = this.useLegacyAuth ? await this.fetchLegacyToken() : await this.fetchOAuthToken();
-        this.token = token;
-        return token.value;
-    }
-    /**
-     * The current OAuth endpoint: `POST https://accounts.feishu.cn/oauth/v3/token`.
-     *
-     * It is the one the documentation recommends. If it refuses - an older application, a tenant
-     * that has not been migrated - the legacy endpoint is tried instead, and the client remembers
-     * so the failing call is not made again on every token refresh.
-     */
-    async fetchOAuthToken() {
-        const body = new URLSearchParams({
-            grant_type: "client_credentials",
-            client_id: this.options.appId,
-            client_secret: this.options.appSecret,
-        });
-        let response;
-        try {
-            response = await this.fetchImpl(`${this.accountsBase}/oauth/v3/token`, {
-                method: "POST",
-                headers: { "content-type": "application/x-www-form-urlencoded" },
-                body: body.toString(),
-            });
-        }
-        catch (error) {
-            // A network failure here says nothing about the credentials, so the legacy endpoint gets a
-            // turn before the failure is reported.
-            return this.fetchLegacyToken();
-        }
-        const payload = (await response.json().catch(() => ({})));
-        const value = payload.access_token;
-        if (!value || (payload.code !== undefined && payload.code !== 0)) {
-            this.useLegacyAuth = true;
-            try {
-                return await this.fetchLegacyToken();
-            }
-            catch {
-                const code = payload.code ?? response.status;
-                throw new FeishuError(code, describeFeishuError(code, payload.msg ?? `获取访问凭证失败（HTTP ${response.status}）`), ERROR_HINTS[code]);
-            }
-        }
-        return { value, expiresAt: Date.now() + Math.max(60, payload.expires_in ?? 7200) * 1000 };
-    }
-    /**
-     * The historical endpoint: `POST /open-apis/auth/v3/tenant_access_token/internal`.
-     *
-     * It is documented as superseded, but it is the endpoint every 自建应用 has worked with for
-     * years, and a fallback that costs one request is cheaper than a feature that does not run.
-     */
-    async fetchLegacyToken() {
-        const response = await this.fetchImpl(`${this.apiBase}/open-apis/auth/v3/tenant_access_token/internal`, {
-            method: "POST",
-            headers: { "content-type": "application/json; charset=utf-8" },
-            body: JSON.stringify({ app_id: this.options.appId, app_secret: this.options.appSecret }),
-        });
-        const payload = (await response.json().catch(() => ({})));
-        if (!payload.tenant_access_token || (payload.code !== undefined && payload.code !== 0)) {
-            const code = payload.code ?? response.status;
-            throw new FeishuError(code, describeFeishuError(code, payload.msg ?? `获取访问凭证失败（HTTP ${response.status}）`), ERROR_HINTS[code]);
-        }
-        return { value: payload.tenant_access_token, expiresAt: Date.now() + Math.max(60, payload.expire ?? 7200) * 1000 };
-    }
-    /**
-     * ONE CALL, with the bearer token attached.
-     *
-     * A 429 is waited out rather than reported: the API tells us how many seconds until the window
-     * resets, and a write that gives up because it was 200ms early is a write that did not happen.
-     */
-    async request(method, path, body, options = {}) {
-        const attempt = async () => {
-            const token = await this.accessToken();
-            const response = await this.fetchImpl(`${this.apiBase}${path}`, {
-                method,
-                headers: {
-                    Authorization: `Bearer ${token}`,
-                    "content-type": "application/json; charset=utf-8",
-                },
-                ...(body === undefined ? {} : { body: JSON.stringify(body) }),
-            });
-            const payload = (await response.json().catch(() => ({})));
-            if (response.status === 429) {
-                const reset = Number(response.headers.get("x-ogw-ratelimit-reset") ?? "1");
-                await delay(Math.max(500, Math.min(10_000, (Number.isFinite(reset) ? reset : 1) * 1000)));
-                throw new FeishuError(99991400, "触发了飞书的频率限制");
-            }
-            if (payload.code !== undefined && payload.code !== 0) {
-                // A token that has expired is the one error worth a second attempt with a fresh one: the
-                // credential was good an hour ago, and the fix is a new token, not a different request.
-                if (payload.code === 99991663 || payload.code === 99991664) {
-                    await this.accessToken(true);
-                }
-                throw new FeishuError(payload.code, describeFeishuError(payload.code, payload.msg ?? ""), ERROR_HINTS[payload.code]);
-            }
-            if (!response.ok) {
-                throw new FeishuError(response.status, payload.msg ?? `飞书接口返回 HTTP ${response.status}`);
-            }
-            return (payload.data ?? payload);
-        };
-        const withSlot = async () => {
-            let lastError;
-            for (let tries = 0; tries < 3; tries += 1) {
-                try {
-                    return await attempt();
-                }
-                catch (error) {
-                    lastError = error;
-                    // Two errors are worth another attempt: a rate limit (the API says when to come back)
-                    // and an expired token (a fresh one was just fetched).
-                    if (error instanceof FeishuError && (error.code === 99991400 || error.code === 99991663 || error.code === 99991664) && tries < 2)
-                        continue;
-                    throw error;
-                }
-            }
-            throw lastError;
-        };
-        return options.write ? this.withWriteSlot(withSlot) : withSlot();
-    }
-    /**
-     * Runs one write, spaced from the last one.
-     */
-    async withWriteSlot(fn) {
-        const result = this.writeChain.then(async () => {
-            const wait = WRITE_INTERVAL_MS - (Date.now() - this.lastWriteAt);
-            if (wait > 0)
-                await delay(wait);
-            this.lastWriteAt = Date.now();
-            return fn();
-        });
-        this.writeChain = result.then(() => undefined, () => undefined);
-        return result;
-    }
-    /** The basic information about a document: its title and its version. */
-    async documentMeta(documentId) {
-        const data = await this.request("GET", `/open-apis/docx/v1/documents/${encodeURIComponent(documentId)}`);
-        const document = data?.document ?? {};
-        return { documentId: document.document_id ?? documentId, title: document.title, revisionId: document.revision_id };
-    }
-    /** Every block of a document, across every page. */
-    async documentBlocks(documentId) {
-        const items = [];
-        let pageToken;
-        do {
-            const query = new URLSearchParams({ page_size: String(MAX_BLOCKS_PER_PAGE) });
-            if (pageToken)
-                query.set("page_token", pageToken);
-            const data = await this.request("GET", `/open-apis/docx/v1/documents/${encodeURIComponent(documentId)}/blocks?${query.toString()}`);
-            items.push(...(data?.items ?? []));
-            pageToken = data?.has_more && data.page_token ? data.page_token : undefined;
-        } while (pageToken);
-        return items;
-    }
-    /** The plain text of a document, without any structure. */
-    async rawContent(documentId) {
-        const data = await this.request("GET", `/open-apis/docx/v1/documents/${encodeURIComponent(documentId)}/raw_content`);
-        return data?.content ?? "";
-    }
-    /** The blocks directly under the page block - the document's top level. */
-    async rootChildren(documentId) {
-        const ids = [];
-        let pageToken;
-        let answered = false;
-        do {
-            const query = new URLSearchParams({ page_size: String(MAX_BLOCKS_PER_PAGE) });
-            if (pageToken)
-                query.set("page_token", pageToken);
-            const data = await this.request("GET", `/open-apis/docx/v1/documents/${encodeURIComponent(documentId)}/blocks/${encodeURIComponent(documentId)}/children?${query.toString()}`);
-            if (!Array.isArray(data?.items))
-                break;
-            answered = true;
-            ids.push(...data.items.map((item) => item.block_id));
-            pageToken = data.has_more && data.page_token ? data.page_token : undefined;
-        } while (pageToken);
-        if (answered)
-            return ids;
-        // The dedicated children endpoint is the cheap way to ask this question; if the API declines
-        // it, the full block list still knows the answer.
-        const blocks = await this.documentBlocks(documentId);
-        const root = blocks.find((block) => block.block_type === 1 && !block.parent_id);
-        return root ? childrenOf(root) : [];
-    }
-    /** Creates an empty document. The content goes in afterwards, because the API has no other way. */
-    async createDocument(title, folderToken) {
-        const data = await this.request("POST", "/open-apis/docx/v1/documents", { ...(folderToken ? { folder_token: folderToken } : {}), title }, { write: true });
-        const document = data?.document ?? {};
-        if (!document.document_id)
-            throw new FeishuError(-1, "飞书没有返回新文档的 id");
-        return { documentId: document.document_id, revisionId: document.revision_id };
-    }
-    /** Resolves a knowledge-base node to the document behind it. */
-    async wikiNode(token) {
-        const query = new URLSearchParams({ token, obj_type: "wiki" });
-        const data = await this.request("GET", `/open-apis/wiki/v2/spaces/get_node?${query.toString()}`);
-        const node = data?.node ?? {};
-        if (!node.obj_token || !node.obj_type)
-            throw new FeishuError(131005, "知识库节点没有对应的云文档");
-        return { objToken: node.obj_token, objType: node.obj_type, title: node.title };
-    }
-    /**
-     * Turns Markdown into the blocks that represent it.
-     *
-     * The API will not create a document with content in it, and building the blocks by hand would
-     * mean reimplementing the conversion Feishu already does - tables, code fences, todos and all.
-     */
-    async convertMarkdown(markdown) {
-        const data = await this.request("POST", "/open-apis/docx/v1/documents/blocks/convert", { content_type: "markdown", content: markdown });
-        const blocks = (data?.blocks ?? []).map(stripTableMergeInfo);
-        const firstLevelBlockIds = data?.first_level_block_ids ?? [];
-        return { blocks, firstLevelBlockIds };
-    }
-    /**
-     * Inserts blocks under the page block.
-     *
-     * THE CHUNKING IS NOT AN OPTIMISATION. The API accepts at most 1000 blocks per call, and the
-     * blocks of one subtree cannot be split across calls - so the top-level blocks are packed into
-     * batches that each fit, and a document of any length goes in.
-     */
-    async insertBlocks(documentId, blocks, firstLevelBlockIds, index = -1) {
-        if (!blocks.length)
-            return undefined;
-        const byId = new Map();
-        for (const block of blocks)
-            byId.set(block.block_id, block);
-        const tops = firstLevelBlockIds.filter((id) => byId.has(id));
-        const subtreeOf = (id) => {
-            const block = byId.get(id);
-            if (!block)
-                return [];
-            const out = [block];
-            for (const child of childrenOf(block))
-                out.push(...subtreeOf(child));
-            return out;
-        };
-        const batches = [];
-        let current = [];
-        let currentTops = [];
-        for (const top of tops) {
-            const subtree = subtreeOf(top);
-            if (current.length && current.length + subtree.length > MAX_DESCENDANTS_PER_CALL) {
-                batches.push({ blocks: current, tops: currentTops });
-                current = [];
-                currentTops = [];
-            }
-            current.push(...subtree);
-            currentTops.push(top);
-        }
-        if (current.length)
-            batches.push({ blocks: current, tops: currentTops });
-        // A conversion that produced blocks but no first-level list is a shape this client does not
-        // understand; sending the blocks as their own top level is better than sending nothing.
-        if (!batches.length)
-            batches.push({ blocks: blocks.slice(0, MAX_DESCENDANTS_PER_CALL), tops: [] });
-        let revision;
-        for (const batch of batches) {
-            const data = await this.request("POST", `/open-apis/docx/v1/documents/${encodeURIComponent(documentId)}/blocks/${encodeURIComponent(documentId)}/descendant`, { children_id: batch.tops.length ? batch.tops : batch.blocks.map((block) => block.block_id), descendants: batch.blocks, index }, { write: true });
-            revision = data?.document_revision_id ?? revision;
-        }
-        return revision;
-    }
-    /** Deletes a range of the page block's children. The range is left-closed and right-open. */
-    async deleteChildren(documentId, startIndex, endIndex) {
-        if (endIndex <= startIndex)
-            return undefined;
-        const data = await this.request("DELETE", `/open-apis/docx/v1/documents/${encodeURIComponent(documentId)}/blocks/${encodeURIComponent(documentId)}/children/batch_delete`, { start_index: startIndex, end_index: endIndex }, { write: true });
-        return data?.document_revision_id;
-    }
-}
-/**
- * Removes the read-only merge information from a table block.
- *
- * The API rejects a table block that carries `merge_info`, and the conversion endpoint hands it
- * back with that field on it. The documentation says to strip it, so it is stripped.
- */
-export function stripTableMergeInfo(block) {
-    if (block.block_type !== 31)
-        return block;
-    const table = block.table;
-    if (!table || table.merge_info === undefined)
-        return block;
-    const { merge_info: _ignored, ...rest } = table;
-    return { ...block, table: rest };
-}