@fastagent-sh/fastagent 0.12.1 → 0.13.0

package/README.md

@@ -145,7 +145,7 @@ const agent = createPiAgent({
 | [Embedding](https://fastagent.sh/docs/embedding/) | Use FastAgent as a library inside your own app |
 | [Channels](https://fastagent.sh/docs/channels/) | Add webhook/bot channels |
 | [Deploy](https://fastagent.sh/docs/deploy/) | Ship the directory to Fly, Railway, or any Docker host |
-| [GitHub](https://fastagent.sh/docs/github/) / [Telegram](https://fastagent.sh/docs/telegram/) | First-party channel guides |
+| [GitHub](https://fastagent.sh/docs/github/) / [Telegram](https://fastagent.sh/docs/telegram/) / [Feishu and Lark](https://fastagent.sh/docs/feishu/) | First-party channel guides |
 | [Channel development](https://fastagent.sh/docs/channel-development/) | Build custom channel adapters |
 | [API reference](https://fastagent.sh/docs/api-reference/) | Public TypeScript API reference |
 | [Troubleshooting](https://fastagent.sh/docs/troubleshooting/) | Common setup/runtime issues |
@@ -170,7 +170,9 @@ Subpath exports:
 - `@fastagent-sh/fastagent/core` — engine-neutral contract, consumption helpers, channel/host kit, schedules;
 - `@fastagent-sh/fastagent/pi` — the pi reference implementation;
 - `@fastagent-sh/fastagent/github` — GitHub webhook channel;
-- `@fastagent-sh/fastagent/telegram` — Telegram bot channel.
+- `@fastagent-sh/fastagent/telegram` — Telegram bot channel;
+- `@fastagent-sh/fastagent/feishu` — canonical Feishu bot channel (飞书, open.feishu.cn);
+- `@fastagent-sh/fastagent/lark` — Lark-international compatibility profile over the Feishu engine.
 
 ## Repository layout
 

package/dist/channels/feishu/bootstrap-token.d.ts

@@ -0,0 +1,42 @@
+import type { FeishuCloudKind } from "./cloud.ts";
+/** What the bootstrap needs from the API pipeline (subset of FeishuApi; injectable in tests). */
+interface EventSubscriptionPatcher {
+    updateEventSubscription(appId: string, cfg: {
+        subscriptionType: "webhook";
+        requestUrl: string;
+    }): Promise<void>;
+}
+export interface FeishuBootstrapTokenOptions {
+    api: EventSubscriptionPatcher;
+    appId: string;
+    /** Canonical Feishu by default; Lark compatibility binds its own route explicitly. */
+    kind?: FeishuCloudKind;
+    /** Expose local `port` on a public URL (production: startCloudflareTunnel; tests: loopback). */
+    startTunnel: (port: number) => Promise<{
+        url: string;
+        close(): void;
+    } | undefined>;
+    /** Budget for the whole capture (the challenge normally lands within the PATCH round-trip). */
+    timeoutMs?: number;
+    /** PATCH attempts × delay — the PATCH is the one and only readiness probe (see below). */
+    patchAttempts?: number;
+    patchRetryMs?: number;
+    /** Retry classifier. Default: retry every PATCH failure (Feishu edge warm-up compatibility).
+     * Lark onboarding rejects a definitive config-route 404 immediately so it can fall back by hand. */
+    shouldRetryPatch?: (error: unknown) => boolean;
+    /** Progress hooks: production prints the assigned URL/retries; tests keep transport IO injected. */
+    onTunnelReady?: (url: string) => void;
+    onPatchRetry?: (info: {
+        error: unknown;
+        attempt: number;
+        attempts: number;
+        retryMs: number;
+    }) => void;
+}
+/**
+ * Run the bootstrap (module header). Resolves with the app's Verification Token; rejects with a
+ * plain, actionable Error (tunnel unavailable, PATCH refused, challenge never arrived) — the caller
+ * degrades to the manual console instruction.
+ */
+export declare function bootstrapFeishuVerificationToken(options: FeishuBootstrapTokenOptions): Promise<string>;
+export {};

package/dist/channels/feishu/bootstrap-token.js

@@ -0,0 +1,94 @@
+/**
+ * Verification-Token bootstrap — the token has NO read API (field-tested 2026-07: the v6 app detail
+ * never returns `encryption`, and the v7 config route only supports PATCH). The platform's only
+ * programmatic delivery is the `url_verification` challenge it POSTs to the request URL while an
+ * event-subscription PATCH is verified — the challenge body carries `token`, the app's Verification
+ * Token. So `add feishu`'s create flow finishes the job by: standing up a throwaway local responder,
+ * exposing it on an ephemeral quick tunnel, PATCHing the app's event subscription at it, capturing
+ * the token from the challenge, and tearing everything down. `dev --tunnel` / `deploy … --run`
+ * re-PATCH the request URL onto the real server later (the token is app-level and survives that).
+ *
+ * Security: the serving path keeps its strict non-empty-token requirement — no bootstrap mode there.
+ * The throwaway URL is random (unguessable), lives for seconds, and only the FIRST challenge is
+ * accepted, immediately after our own credential-authenticated PATCH.
+ */
+import { createServer } from "node:http";
+/**
+ * Run the bootstrap (module header). Resolves with the app's Verification Token; rejects with a
+ * plain, actionable Error (tunnel unavailable, PATCH refused, challenge never arrived) — the caller
+ * degrades to the manual console instruction.
+ */
+export async function bootstrapFeishuVerificationToken(options) {
+    let capturedToken;
+    const token = new Promise((resolve) => {
+        capturedToken = resolve;
+    });
+    // The throwaway responder: answers /health (diagnostics) and the url_verification challenge
+    // (echo `challenge` back), capturing `token` from the FIRST challenge only.
+    const server = createServer((req, res) => {
+        if (req.method === "GET") {
+            res.end("ok");
+            return;
+        }
+        let body = "";
+        req.on("data", (d) => {
+            body += String(d);
+        });
+        req.on("end", () => {
+            try {
+                const j = JSON.parse(body);
+                if (j.type === "url_verification" && typeof j.challenge === "string" && typeof j.token === "string") {
+                    capturedToken?.(j.token);
+                    capturedToken = undefined; // first challenge only
+                    res.setHeader("content-type", "application/json");
+                    res.end(JSON.stringify({ challenge: j.challenge }));
+                    return;
+                }
+            }
+            catch {
+                /* not the challenge — fall through to the empty ACK */
+            }
+            res.end("{}");
+        });
+    });
+    await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+    const address = server.address();
+    const port = typeof address === "object" && address !== null ? address.port : 0;
+    const tunnel = await options.startTunnel(port);
+    try {
+        if (!tunnel)
+            throw new Error("no tunnel came up (is cloudflared installed?)");
+        options.onTunnelReady?.(tunnel.url);
+        // Do NOT health-poll the edge here: "can WE reach it" says nothing about platform→edge, the path
+        // the challenge uses (field-tested: local negative-DNS caching failed while that path worked).
+        // PATCH immediately; it is the real probe because success requires the challenge round-trip.
+        const attempts = options.patchAttempts ?? 8;
+        for (let attempt = 1;; attempt++) {
+            try {
+                await options.api.updateEventSubscription(options.appId, {
+                    subscriptionType: "webhook",
+                    requestUrl: `${tunnel.url}/${options.kind ?? "feishu"}`,
+                });
+                break;
+            }
+            catch (e) {
+                if (attempt >= attempts || options.shouldRetryPatch?.(e) === false)
+                    throw e;
+                const retryMs = options.patchRetryMs ?? 10_000;
+                options.onPatchRetry?.({ error: e, attempt, attempts, retryMs });
+                await new Promise((resolve) => setTimeout(resolve, retryMs));
+            }
+        }
+        const winner = await Promise.race([
+            token,
+            new Promise((resolve) => setTimeout(() => resolve(undefined), options.timeoutMs ?? 30_000)),
+        ]);
+        if (winner === undefined)
+            throw new Error("the registration challenge never arrived");
+        return winner;
+    }
+    finally {
+        tunnel?.close();
+        server.close();
+    }
+}

package/dist/channels/feishu/card.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Card JSON builders — PURE: the streaming-card entity (JSON 2.0) the live preview creates, the settled
+ * final card, and the message content that mounts a card entity into a chat. Kept out of preview.ts so
+ * the card DSL is data-in → string-out and testable without the pump.
+ *
+ * The preview is ONE markdown element (`element_id` below) inside a card with `streaming_mode` on:
+ * the pump PUTs full-text snapshots at that element (feishu-api.ts `updateCardElement`) and the client
+ * renders the typewriter effect. Settling replaces the whole entity (`updateCard`) with the same
+ * element, `streaming_mode` off — one write flips content and mode together.
+ *
+ * Budget: a card entity is capped at 30 KB, so the final answer's card chunk (and the live view) stay
+ * well under it; longer answers overflow into follow-up messages (preview.ts owns that policy).
+ */
+/** The one streamed element's id — shared by create (card.ts) and update (preview.ts). */
+export declare const ANSWER_ELEMENT_ID = "answer";
+/** Byte budget for markdown carried by ONE card (entity cap 30 KB minus JSON envelope + escaping room). */
+export declare const CARD_MARKDOWN_MAX_BYTES: number;
+/**
+ * The answer's first line as plain text — what the chat list and the push notification show for the
+ * settled card (`config.summary.content`). Without it a card message previews as a generic "[Card]"
+ * placeholder: the user's notification would never carry the actual answer. Markdown is stripped
+ * lightly (this is a one-line teaser, not a renderer): fenced code dropped, links/images → their text,
+ * emphasis/heading/list markers removed.
+ */
+export declare function cardSummary(markdown: string): string;
+/** The live-preview card entity: streaming on, seeded with the placeholder/first view. */
+export declare function streamingCardJson(initial: string): string;
+/** The settled card: final markdown, streaming off (stops the client's streaming affordance), plus
+ *  the answer-derived summary so the chat list / notification shows the reply, not "[Card]". */
+export declare function finalCardJson(markdown: string): string;
+/** The `interactive` message content that mounts a card ENTITY (vs an inline static card). */
+export declare function cardEntityContent(cardId: string): string;

package/dist/channels/feishu/card.js

@@ -0,0 +1,66 @@
+/**
+ * Card JSON builders — PURE: the streaming-card entity (JSON 2.0) the live preview creates, the settled
+ * final card, and the message content that mounts a card entity into a chat. Kept out of preview.ts so
+ * the card DSL is data-in → string-out and testable without the pump.
+ *
+ * The preview is ONE markdown element (`element_id` below) inside a card with `streaming_mode` on:
+ * the pump PUTs full-text snapshots at that element (feishu-api.ts `updateCardElement`) and the client
+ * renders the typewriter effect. Settling replaces the whole entity (`updateCard`) with the same
+ * element, `streaming_mode` off — one write flips content and mode together.
+ *
+ * Budget: a card entity is capped at 30 KB, so the final answer's card chunk (and the live view) stay
+ * well under it; longer answers overflow into follow-up messages (preview.ts owns that policy).
+ */
+import { truncateCodePointPrefix } from "./text.js";
+/** The one streamed element's id — shared by create (card.ts) and update (preview.ts). */
+export const ANSWER_ELEMENT_ID = "answer";
+/** Byte budget for markdown carried by ONE card (entity cap 30 KB minus JSON envelope + escaping room). */
+export const CARD_MARKDOWN_MAX_BYTES = 20 * 1024;
+/** Character budget for the settled card's summary (the chat-list / push-notification preview). */
+const SUMMARY_MAX_CHARS = 60;
+/**
+ * The answer's first line as plain text — what the chat list and the push notification show for the
+ * settled card (`config.summary.content`). Without it a card message previews as a generic "[Card]"
+ * placeholder: the user's notification would never carry the actual answer. Markdown is stripped
+ * lightly (this is a one-line teaser, not a renderer): fenced code dropped, links/images → their text,
+ * emphasis/heading/list markers removed.
+ */
+export function cardSummary(markdown) {
+    const line = markdown
+        .replace(/```[\s\S]*?(```|$)/g, " ") // fenced code is never a readable one-line preview
+        .split("\n")
+        .map((l) => l
+        .replace(/^\s{0,3}(?:#{1,6}|>|[-*+]|\d+[.)])\s+/, "") // heading / quote / list markers
+        .replace(/!\[([^\]]*)\]\([^)]*\)/g, "$1") // images → alt text
+        .replace(/\[([^\]]*)\]\([^)]*\)/g, "$1") // links → link text
+        .replace(/[*_~`]/g, "")
+        .trim())
+        .find((l) => l !== "") ?? "";
+    return truncateCodePointPrefix(line, SUMMARY_MAX_CHARS);
+}
+function cardJson(markdown, streaming, summary) {
+    return JSON.stringify({
+        schema: "2.0",
+        config: {
+            streaming_mode: streaming,
+            update_multi: true,
+            // Only the settled card sets a summary — while streaming, the platform's default (a localized
+            // "[Generating…]") is better than any fixed text we could pin.
+            ...(summary ? { summary: { content: summary } } : {}),
+        },
+        body: { elements: [{ tag: "markdown", content: markdown, element_id: ANSWER_ELEMENT_ID }] },
+    });
+}
+/** The live-preview card entity: streaming on, seeded with the placeholder/first view. */
+export function streamingCardJson(initial) {
+    return cardJson(initial, true);
+}
+/** The settled card: final markdown, streaming off (stops the client's streaming affordance), plus
+ *  the answer-derived summary so the chat list / notification shows the reply, not "[Card]". */
+export function finalCardJson(markdown) {
+    return cardJson(markdown, false, cardSummary(markdown));
+}
+/** The `interactive` message content that mounts a card ENTITY (vs an inline static card). */
+export function cardEntityContent(cardId) {
+    return JSON.stringify({ type: "card", data: { card_id: cardId } });
+}

package/dist/channels/feishu/cloud.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Feishu is the canonical implementation. Lark international speaks the same protocol but trails the
+ * primary cloud in control-plane capabilities, so it binds the Feishu engine through this explicit
+ * compatibility profile instead of becoming the engine's naming/design center.
+ */
+export type FeishuCloudKind = "feishu" | "lark";
+export interface FeishuCloudProfile {
+    kind: FeishuCloudKind;
+    envPrefix: "FEISHU" | "LARK";
+    apiBase: string;
+    capabilities: {
+        appCreation: "scan-to-create" | "guided-console";
+    };
+}
+export declare const FEISHU_CLOUD: FeishuCloudProfile;
+export declare const LARK_COMPAT_CLOUD: FeishuCloudProfile;
+export declare function cloudFor(kind: FeishuCloudKind): FeishuCloudProfile;

package/dist/channels/feishu/cloud.js

@@ -0,0 +1,19 @@
+export const FEISHU_CLOUD = {
+    kind: "feishu",
+    envPrefix: "FEISHU",
+    apiBase: "https://open.feishu.cn",
+    capabilities: {
+        appCreation: "scan-to-create",
+    },
+};
+export const LARK_COMPAT_CLOUD = {
+    kind: "lark",
+    envPrefix: "LARK",
+    apiBase: "https://open.larksuite.com",
+    capabilities: {
+        appCreation: "guided-console",
+    },
+};
+export function cloudFor(kind) {
+    return kind === "feishu" ? FEISHU_CLOUD : LARK_COMPAT_CLOUD;
+}

package/dist/channels/feishu/crypto.d.ts

@@ -0,0 +1,13 @@
+/** Constant-time string equality (padded to equal length first — timingSafeEqual demands it). */
+export declare function timingSafeEqualStr(a: string, b: string): boolean;
+/** Decrypt an `{"encrypt": …}` event payload to its plaintext JSON string. Throws on malformed input
+ *  or a wrong key (bad padding) — the caller turns that into a 4xx, never a silent drop. */
+export declare function decryptEvent(encryptKey: string, encryptB64: string): string;
+/** The expected `X-Lark-Signature` for a request: sha256(timestamp + nonce + encryptKey + rawBody) hex. */
+export declare function eventSignature(encryptKey: string, timestamp: string, nonce: string, rawBody: string): string;
+/** Whether a request's signature headers verify against the raw body (constant-time). */
+export declare function verifySignature(encryptKey: string, headers: {
+    timestamp: string;
+    nonce: string;
+    signature: string;
+}, rawBody: string): boolean;

package/dist/channels/feishu/crypto.js

@@ -0,0 +1,41 @@
+/**
+ * Canonical Feishu webhook security (reused by Lark compatibility) — PURE: AES event decryption and request
+ * signature, exactly as the open platform defines them. When an Encrypt Key is configured in the
+ * developer console, every event arrives as `{"encrypt": "<base64>"}` with signature headers; without
+ * one, events arrive in plaintext and carry only the verification token in the body. feishu.ts owns the
+ * fail-closed policy (which checks run when); this module owns the math.
+ *
+ *  - Decryption: AES-256-CBC. The key is sha256(encryptKey); the base64 payload is IV (16 bytes) ‖
+ *    ciphertext; the plaintext is the event JSON (PKCS#7 padding handled by the cipher).
+ *  - Signature: `X-Lark-Signature = sha256(timestamp + nonce + encryptKey + rawBody)` hex, where
+ *    rawBody is the VERBATIM request body (the encrypted form) — computed over bytes, so the caller
+ *    must pass the raw text, never a re-serialization.
+ *
+ * Comparisons are constant-time (timingSafeEqual) so neither the signature check nor the verification-
+ * token check leaks a timing signal.
+ */
+import { createDecipheriv, createHash, timingSafeEqual } from "node:crypto";
+/** Constant-time string equality (padded to equal length first — timingSafeEqual demands it). */
+export function timingSafeEqualStr(a, b) {
+    const ab = Buffer.from(a);
+    const bb = Buffer.from(b);
+    return ab.length === bb.length && timingSafeEqual(ab, bb);
+}
+/** Decrypt an `{"encrypt": …}` event payload to its plaintext JSON string. Throws on malformed input
+ *  or a wrong key (bad padding) — the caller turns that into a 4xx, never a silent drop. */
+export function decryptEvent(encryptKey, encryptB64) {
+    const key = createHash("sha256").update(encryptKey, "utf8").digest();
+    const buf = Buffer.from(encryptB64, "base64");
+    if (buf.length <= 16)
+        throw new Error("encrypted event payload is too short to carry an IV + ciphertext");
+    const decipher = createDecipheriv("aes-256-cbc", key, buf.subarray(0, 16));
+    return Buffer.concat([decipher.update(buf.subarray(16)), decipher.final()]).toString("utf8");
+}
+/** The expected `X-Lark-Signature` for a request: sha256(timestamp + nonce + encryptKey + rawBody) hex. */
+export function eventSignature(encryptKey, timestamp, nonce, rawBody) {
+    return createHash("sha256").update(`${timestamp}${nonce}${encryptKey}${rawBody}`, "utf8").digest("hex");
+}
+/** Whether a request's signature headers verify against the raw body (constant-time). */
+export function verifySignature(encryptKey, headers, rawBody) {
+    return timingSafeEqualStr(eventSignature(encryptKey, headers.timestamp, headers.nonce, rawBody), headers.signature);
+}

package/dist/channels/feishu/feishu-api.d.ts

@@ -0,0 +1,108 @@
+import type { ImageRef } from "../../agent.ts";
+import type { FeishuCloudKind } from "./cloud.ts";
+/** Where a reply goes: a chat, optionally quote-replying a message (in-thread in topic groups). */
+export interface FeishuTarget {
+    chatId: string;
+    /** Message to reply to (the summoning message). Set in groups so the answer threads under the asker. */
+    replyTo?: string;
+    /** Reply into the message's topic thread (topic groups). */
+    replyInThread?: boolean;
+}
+/** A downloaded inbound file: an absolute local path the agent's tools (read/bash) can open. */
+export interface DownloadedFile {
+    path: string;
+    name: string;
+    size: number;
+}
+/** Whether an error is the platform's "card streaming closed/timed out" reject — preview.ts re-enables
+ *  streaming once when it sees this. A plain code check on the typed error, exported instead of the
+ *  class so no caller can construct/throw one. */
+export declare function isCardStreamingClosed(e: unknown): boolean;
+/** Whether the platform origin has no application-config route at all. Onboarding uses this narrow
+ * signal to fall back to a manual token/mode setup; auth/scope/network failures must remain visible. */
+export declare function isFeishuConfigApiMissing(e: unknown): boolean;
+/** Whether a registration-PATCH failure is transient weather worth retrying: network/DNS/timeouts, or
+ *  the platform's 210042 "request_url validation failed" while its own path to a fresh tunnel edge
+ *  warms up. Everything else (scope, auth, app under review, the config-route 404 above) is definitive
+ *  — the registrars and the token bootstrap share this one classifier. */
+export declare function isTransientFeishuRegistrationError(e: unknown): boolean;
+export interface FeishuApiOptions {
+    /** Branded diagnostics; defaults to the canonical Feishu cloud. */
+    kind?: FeishuCloudKind;
+    /** API origin: `https://open.feishu.cn` (Feishu) or `https://open.larksuite.com` (Lark intl). */
+    baseUrl: string;
+    appId: string;
+    appSecret: string;
+}
+/**
+ * The Feishu Open API client: one instance per channel, holding the token cache. Every method rides the
+ * single pipeline (module header). Throws {@link FeishuApiError} on any failure.
+ */
+export interface FeishuApi {
+    /** Validate appId/appSecret by acquiring the tenant token through this pipeline. Does not require
+     *  the bot capability (unlike botInfo), so guided onboarding can fail before persisting a typo. */
+    verifyCredentials(): Promise<void>;
+    /** GET /bot/v3/info — the bot's own identity (open_id drives @mention summon). */
+    botInfo(): Promise<{
+        openId?: string;
+        appName?: string;
+    }>;
+    /** Send a message to a chat; returns the new message_id (undefined if the body carried none). */
+    sendMessage(chatId: string, msgType: string, content: string): Promise<string | undefined>;
+    /** Reply to a message (quote; `replyInThread` stays inside a topic group's thread). */
+    replyMessage(messageId: string, msgType: string, content: string, opts?: {
+        replyInThread?: boolean;
+    }): Promise<string | undefined>;
+    /** Send `text`, split at the platform's size cap: ordinary groups quote only the first chunk; topic
+     *  groups reply_in_thread on every chunk. Returns the FIRST message_id. */
+    sendText(target: FeishuTarget, text: string): Promise<string | undefined>;
+    /** Edit a sent text message in place (PUT; the platform caps edits at 20 per message). */
+    editTextMessage(messageId: string, text: string): Promise<void>;
+    /** Recall (delete) a message the bot sent. */
+    deleteMessage(messageId: string): Promise<void>;
+    /** Fetch one message (the reply-referent path). Undefined when the API returns no item. */
+    getMessage(messageId: string): Promise<{
+        message_id?: string;
+        msg_type?: string;
+        body?: {
+            content?: string;
+        };
+        mentions?: unknown[];
+        sender?: unknown;
+    } | undefined>;
+    /** Download a message resource (image/file bytes). Caps at {@link MAX_DOWNLOAD_BYTES}. */
+    downloadResource(messageId: string, fileKey: string, type: "image" | "file"): Promise<{
+        bytes: Buffer;
+        contentType?: string;
+    }>;
+    /** Download an image resource as a vision ImageRef. */
+    fetchImage(messageId: string, fileKey: string): Promise<ImageRef>;
+    /** Download a file resource to `<filesDir>/<chat>/<name>`. */
+    fetchFile(messageId: string, fileKey: string, name: string, chatId: string, filesDir: string): Promise<DownloadedFile>;
+    /** Read the app's own event-security config (the platform-generated verification token / encrypt
+     *  key) — the scan-to-create flow copies these into .env so the operator never opens the console. */
+    getAppConfig(appId: string): Promise<{
+        verificationToken?: string;
+        encryptionKey?: string;
+    }>;
+    /** Update the app's own event subscription (application-v7 config PATCH — tenant token can only
+     *  operate on itself; the request-URL change takes effect immediately, no version publish). The
+     *  platform VERIFIES `requestUrl` with a url_verification challenge during this call, so the server
+     *  behind it must already be answering. */
+    updateEventSubscription(appId: string, cfg: {
+        subscriptionType: "webhook";
+        requestUrl: string;
+    }): Promise<void>;
+    /** Create a card entity (card JSON 2.0). Returns its card_id. */
+    createCard(cardJson: string): Promise<string>;
+    /** Stream-update a card element's text (full-content snapshot + strictly increasing sequence). */
+    updateCardElement(cardId: string, elementId: string, content: string, sequence: number): Promise<void>;
+    /** Replace a card entity's content (the settle write; also flips streaming_mode off via the JSON). */
+    updateCard(cardId: string, cardJson: string, sequence: number): Promise<void>;
+}
+/** The platform caps a text-message request body at 150 KB; stay well under it (the content is a JSON
+ *  envelope around the text, and multi-byte characters inflate the byte count). */
+export declare const FEISHU_MAX_TEXT_BYTES: number;
+/** Split text into chunks whose UTF-8 size fits the message cap, preferring a newline boundary. */
+export declare function chunkFeishuText(text: string, maxBytes?: number): string[];
+export declare function createFeishuApi(opts: FeishuApiOptions): FeishuApi;