@fastagent-sh/fastagent 0.12.0 → 0.13.0

package/dist/channels/feishu/feishu-api.js

@@ -0,0 +1,325 @@
+/**
+ * Feishu Open API transport, reused by the Lark compatibility profile. ONE pipeline (`call`) carries every JSON call — per-method wire code
+ * does not exist, so a transport rule can never be missing from one call site. The transport invariants
+ * live here and nowhere else:
+ *
+ *  1. Every call has a per-attempt timeout (API_TIMEOUT_MS; resource bytes DOWNLOAD_TIMEOUT_MS) — a
+ *     wedged connection cannot hang a turn or its session queue.
+ *  2. The tenant_access_token is fetched lazily, cached to its `expire` minus a refresh margin, and
+ *     invalidated + refetched ONCE when the platform says the token is bad (auth codes below) — no
+ *     other failure class is retried with a fresh token.
+ *  3. Only a rate-limit reject is retried (bounded attempts, linear backoff); nothing else — the
+ *     request may have been processed, and a retried send would double-deliver.
+ *  4. Success requires the body's own `code === 0` — an intermediary's HTTP 200 is not a sent message.
+ *  5. Every failure is a {@link FeishuApiError} naming the call; self-description is a property of the
+ *     error type, not per-call-site string assembly.
+ *
+ * On top of the pipeline sit thin typed methods (send/reply/edit/card/resource) — adding one is adding
+ * a wrapper, not wire code. SDK tripwire: if this surface ever needs WebSocket long-connection ingress
+ * or grows past ~a dozen methods, adopt @larksuiteoapi/node-sdk instead of growing it — the methods
+ * here are shape-compatible with the SDK's `client.im.*` style, so the policy layer survives that swap.
+ */
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { utf8Prefix } from "./text.js";
+/** Per-attempt timeout for a JSON API call — small JSON round-trips, so 30s is generous. */
+const API_TIMEOUT_MS = 30_000;
+/** Timeout for downloading resource bytes — sized for a slow link, not a JSON call. */
+const DOWNLOAD_TIMEOUT_MS = 120_000;
+/** How many rate-limit rejects one call absorbs before giving up. */
+const RETRIES = 3;
+/** Download sanity cap; a larger resource is rejected visibly (the engine resizes vision images
+ *  anyway, so this is a transport guard, not a model limit). */
+const MAX_DOWNLOAD_BYTES = 20 * 1024 * 1024;
+/** Refresh the cached tenant token this long before its stated expiry. */
+const TOKEN_REFRESH_MARGIN_S = 300;
+/** The platform's "this token is bad" codes: expired/invalid tenant token → invalidate + refetch once. */
+const AUTH_ERROR_CODES = new Set([99991661, 99991663, 99991664, 99991668]);
+/** The platform's frequency-limit code (arrives with HTTP 429 or 400). */
+const RATE_LIMIT_CODE = 99991400;
+/** A named Open API failure. `status` 0 = the transport itself failed (network error / timeout) before
+ *  any HTTP status existed; `code` is the platform's own error code (0 when none was readable).
+ *  Module-private: no external caller matches on the type; the pipeline's own retry logic reads `code`. */
+class FeishuApiError extends Error {
+    call;
+    status;
+    code;
+    description;
+    // No constructor parameter properties: the CLI runs source under Node's strip-only TS mode.
+    constructor(kind, call, status, code, description, options) {
+        super(status === 0
+            ? `${kind} ${call}: ${description}`
+            : `${kind} ${call} failed: ${status}${code ? ` code ${code}` : ""} ${description}`.trim(), options);
+        this.name = "FeishuApiError";
+        this.call = call;
+        this.status = status;
+        this.code = code;
+        this.description = description;
+    }
+}
+/** 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 function isCardStreamingClosed(e) {
+    return e instanceof FeishuApiError && (e.code === 200850 || e.code === 300309);
+}
+/** 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 function isFeishuConfigApiMissing(e) {
+    return e instanceof FeishuApiError && e.status === 404;
+}
+/** 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 function isTransientFeishuRegistrationError(e) {
+    return /resolve host|getaddrinfo|ENOTFOUND|fetch failed|ECONNRESET|timeout|210042|request_url/i.test(String(e));
+}
+/** Sleep on the GLOBAL timer (not `node:timers/promises`) so tests can drive it with fake timers. */
+const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/** 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 const FEISHU_MAX_TEXT_BYTES = 100 * 1024;
+/** Split text into chunks whose UTF-8 size fits the message cap, preferring a newline boundary. */
+export function chunkFeishuText(text, maxBytes = FEISHU_MAX_TEXT_BYTES) {
+    if (!Number.isSafeInteger(maxBytes) || maxBytes <= 0)
+        throw new RangeError("maxBytes must be a positive integer");
+    if (Buffer.byteLength(text, "utf8") <= maxBytes)
+        return [text];
+    const chunks = [];
+    let rest = text;
+    while (Buffer.byteLength(rest, "utf8") > maxBytes) {
+        // Find the largest CODE-POINT-aligned prefix under the cap, then prefer the last newline inside it.
+        // A cap smaller than one code point cannot satisfy both the byte limit and well-formed Unicode.
+        const prefix = utf8Prefix(rest, maxBytes);
+        if (prefix === "")
+            throw new RangeError("maxBytes is too small to contain the next Unicode code point");
+        let cut = prefix.lastIndexOf("\n");
+        if (cut <= 0)
+            cut = prefix.length;
+        chunks.push(rest.slice(0, cut));
+        rest = rest.slice(cut).replace(/^\n/, "");
+    }
+    if (rest.length > 0 || chunks.length === 0)
+        chunks.push(rest);
+    return chunks;
+}
+export function createFeishuApi(opts) {
+    const { kind = "feishu", baseUrl, appId, appSecret } = opts;
+    let cached;
+    /** Fetch (or reuse) the tenant_access_token — the one call that carries no Authorization header. */
+    const tenantToken = async () => {
+        if (cached && Date.now() < cached.expiresAt)
+            return cached.token;
+        const label = "tenant_access_token";
+        let res;
+        let raw;
+        try {
+            res = await fetch(`${baseUrl}/open-apis/auth/v3/tenant_access_token/internal`, {
+                method: "POST",
+                headers: { "content-type": "application/json; charset=utf-8" },
+                body: JSON.stringify({ app_id: appId, app_secret: appSecret }),
+                signal: AbortSignal.timeout(API_TIMEOUT_MS),
+            });
+            raw = await res.text();
+        }
+        catch (e) {
+            throw new FeishuApiError(kind, label, 0, 0, String(e), { cause: e });
+        }
+        let data;
+        try {
+            data = JSON.parse(raw);
+        }
+        catch {
+            data = {};
+        }
+        if (!res.ok || data.code !== 0 || typeof data.tenant_access_token !== "string") {
+            throw new FeishuApiError(kind, label, res.status, data.code ?? 0, data.msg ?? "response was not the expected JSON");
+        }
+        const ttlS = Math.max(60, (data.expire ?? 0) - TOKEN_REFRESH_MARGIN_S);
+        cached = { token: data.tenant_access_token, expiresAt: Date.now() + ttlS * 1000 };
+        return cached.token;
+    };
+    /** The pipeline: one JSON API call, carrying every transport invariant (module header). */
+    const call = async (label, method, path, body) => {
+        let refreshedAuth = false;
+        for (let attempt = 0;;) {
+            const token = await tenantToken();
+            let res;
+            let raw;
+            try {
+                res = await fetch(`${baseUrl}${path}`, {
+                    method,
+                    headers: {
+                        authorization: `Bearer ${token}`,
+                        "content-type": "application/json; charset=utf-8",
+                    },
+                    body: body === undefined ? undefined : JSON.stringify(body),
+                    signal: AbortSignal.timeout(API_TIMEOUT_MS),
+                });
+                raw = await res.text(); // the body read shares the timeout — a mid-body stall is a transport failure too
+            }
+            catch (e) {
+                throw new FeishuApiError(kind, label, 0, 0, String(e), { cause: e });
+            }
+            let data;
+            try {
+                data = JSON.parse(raw);
+            }
+            catch {
+                data = {}; // only the parse is forgiven — the code-gate below turns it into a named failure
+            }
+            if (res.ok && data.code === 0)
+                return data;
+            const code = data.code ?? 0;
+            if (AUTH_ERROR_CODES.has(code) && !refreshedAuth) {
+                // The platform says the token is bad (expired mid-cache-window, or revoked): refetch ONCE and
+                // retry. Auth is the one failure class where a retry cannot double-deliver — the request was
+                // rejected before it acted.
+                refreshedAuth = true;
+                cached = undefined;
+                continue;
+            }
+            if ((res.status === 429 || code === RATE_LIMIT_CODE) && attempt < RETRIES) {
+                attempt++;
+                await wait(attempt * 1000);
+                continue;
+            }
+            const exhausted = res.status === 429 || code === RATE_LIMIT_CODE ? ` (gave up after ${attempt} retries)` : "";
+            throw new FeishuApiError(kind, label, res.status, code, `${data.msg ?? "response was not the expected JSON"}${exhausted}`);
+        }
+    };
+    const api = {
+        async verifyCredentials() {
+            await tenantToken();
+        },
+        async botInfo() {
+            // bot/v3/info answers at the TOP LEVEL (`bot`), not under `data` — an older API family.
+            const data = await call("botInfo", "GET", "/open-apis/bot/v3/info");
+            return { openId: data.bot?.open_id, appName: data.bot?.app_name };
+        },
+        async sendMessage(chatId, msgType, content) {
+            const data = await call("sendMessage", "POST", "/open-apis/im/v1/messages?receive_id_type=chat_id", { receive_id: chatId, msg_type: msgType, content });
+            return data.data?.message_id;
+        },
+        async replyMessage(messageId, msgType, content, opts2) {
+            const data = await call("replyMessage", "POST", `/open-apis/im/v1/messages/${encodeURIComponent(messageId)}/reply`, { msg_type: msgType, content, ...(opts2?.replyInThread ? { reply_in_thread: true } : {}) });
+            return data.data?.message_id;
+        },
+        async sendText(target, text) {
+            const chunks = chunkFeishuText(text);
+            let firstId;
+            let first = true;
+            for (const chunk of chunks) {
+                const content = JSON.stringify({ text: chunk });
+                // A normal group quote-replies only the first chunk — N reply-quotes would be noise. A topic
+                // must reply_in_thread on EVERY chunk; a plain chat send would leak continuations to the main group.
+                const reply = target.replyTo !== undefined && (first || target.replyInThread === true);
+                const id = reply
+                    ? await api.replyMessage(target.replyTo, "text", content, {
+                        replyInThread: target.replyInThread,
+                    })
+                    : await api.sendMessage(target.chatId, "text", content);
+                if (first)
+                    firstId = id;
+                first = false;
+            }
+            return firstId;
+        },
+        async editTextMessage(messageId, text) {
+            await call("editTextMessage", "PUT", `/open-apis/im/v1/messages/${encodeURIComponent(messageId)}`, {
+                msg_type: "text",
+                content: JSON.stringify({ text }),
+            });
+        },
+        async deleteMessage(messageId) {
+            await call("deleteMessage", "DELETE", `/open-apis/im/v1/messages/${encodeURIComponent(messageId)}`);
+        },
+        async getMessage(messageId) {
+            const data = await call("getMessage", "GET", `/open-apis/im/v1/messages/${encodeURIComponent(messageId)}`);
+            return data.data?.items?.[0];
+        },
+        async downloadResource(messageId, fileKey, type) {
+            // The byte download is the one non-JSON call, so it cannot ride the pipeline — same token +
+            // timeout + naming discipline, applied here once.
+            const label = "downloadResource";
+            const token = await tenantToken();
+            let res;
+            let buf;
+            let errBody;
+            try {
+                res = await fetch(`${baseUrl}/open-apis/im/v1/messages/${encodeURIComponent(messageId)}/resources/${encodeURIComponent(fileKey)}?type=${type}`, { headers: { authorization: `Bearer ${token}` }, signal: AbortSignal.timeout(DOWNLOAD_TIMEOUT_MS) });
+                buf = res.ok ? await res.arrayBuffer() : undefined;
+                errBody = res.ok ? undefined : await res.text(); // the error body self-describes (expired key etc.)
+            }
+            catch (e) {
+                throw new FeishuApiError(kind, label, 0, 0, String(e), { cause: e });
+            }
+            if (!res.ok || buf === undefined) {
+                let description;
+                let code = 0;
+                try {
+                    const parsed = JSON.parse(errBody ?? "");
+                    description = parsed.msg;
+                    code = parsed.code ?? 0;
+                }
+                catch {
+                    /* non-JSON error body — fall through to the generic description */
+                }
+                throw new FeishuApiError(kind, label, res.status, code, description ?? "response was not the expected bytes");
+            }
+            const bytes = Buffer.from(buf);
+            if (bytes.byteLength > MAX_DOWNLOAD_BYTES)
+                throw new Error("resource is too large (max 20 MB)");
+            return { bytes, contentType: res.headers.get("content-type") ?? undefined };
+        },
+        async fetchImage(messageId, fileKey) {
+            const { bytes, contentType } = await api.downloadResource(messageId, fileKey, "image");
+            const mime = contentType?.split(";")[0]?.trim();
+            return { mimeType: mime?.startsWith("image/") ? mime : "image/jpeg", data: bytes.toString("base64") };
+        },
+        async fetchFile(messageId, fileKey, name, chatId, filesDir) {
+            const { bytes } = await api.downloadResource(messageId, fileKey, "file");
+            // The name is external input destined for a filesystem path — keep only its basename-safe core.
+            const safe = name.replace(/[/\\]/g, "_").replace(/^\.+/, "_") || "file";
+            const dir = join(filesDir, chatId);
+            await mkdir(dir, { recursive: true });
+            const dest = join(dir, safe);
+            await writeFile(dest, bytes);
+            return { path: dest, name: safe, size: bytes.byteLength };
+        },
+        async getAppConfig(appId) {
+            // v6 app detail — the one read surface that returns the event-security material (under data.app).
+            const data = await call("getAppConfig", "GET", `/open-apis/application/v6/applications/${encodeURIComponent(appId)}?lang=zh_cn`);
+            return {
+                verificationToken: data.data?.app?.encryption?.verification_token,
+                encryptionKey: data.data?.app?.encryption?.encryption_key,
+            };
+        },
+        async updateEventSubscription(appId, cfg) {
+            await call("updateEventSubscription", "PATCH", `/open-apis/application/v7/applications/${encodeURIComponent(appId)}/config`, {
+                event: { subscription_type: cfg.subscriptionType, request_url: cfg.requestUrl },
+            });
+        },
+        async createCard(cardJson) {
+            const data = await call("createCard", "POST", "/open-apis/cardkit/v1/cards", {
+                type: "card_json",
+                data: cardJson,
+            });
+            const id = data.data?.card_id;
+            if (!id)
+                throw new FeishuApiError(kind, "createCard", 200, 0, "response carried no card_id");
+            return id;
+        },
+        async updateCardElement(cardId, elementId, content, sequence) {
+            await call("updateCardElement", "PUT", `/open-apis/cardkit/v1/cards/${encodeURIComponent(cardId)}/elements/${encodeURIComponent(elementId)}/content`, { content, sequence });
+        },
+        async updateCard(cardId, cardJson, sequence) {
+            await call("updateCard", "PUT", `/open-apis/cardkit/v1/cards/${encodeURIComponent(cardId)}`, {
+                card: { type: "card_json", data: cardJson },
+                sequence,
+            });
+        },
+    };
+    return api;
+}

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

@@ -0,0 +1,36 @@
+import type { ChannelModule } from "../../host/node.ts";
+import { type FeishuCloudProfile } from "./cloud.ts";
+import { type FeishuMessage, type FeishuMessageEvent, type FeishuRoute, defaultFeishuRoute, feishuEnvelope } from "./parse.ts";
+import { type FeishuFailure } from "./preview.ts";
+export { defaultFeishuRoute, feishuEnvelope };
+export type { FeishuFailure, FeishuMessage, FeishuMessageEvent, FeishuRoute };
+export interface FeishuChannelOptions {
+    /** App ID (developer console → Credentials & Basic Info). */
+    appId: string;
+    /** App Secret (same page) — drives the tenant_access_token the replies ride on. */
+    appSecret: string;
+    /** Verification Token (console → Events & Callbacks) — authenticates PLAINTEXT events. */
+    verificationToken: string;
+    /** Encrypt Key (same page, optional there — recommended): when set, ordinary events arrive encrypted
+     *  and signed; this channel then REFUSES plaintext events (fail closed — accepting both would let a
+     *  forger skip the stronger check). Feishu explicitly excludes the encrypted `url_verification`
+     *  handshake from event signature verification; that narrow path is authenticated after decryption
+     *  by the Verification Token. Must match the console exactly. */
+    encryptKey?: string;
+    /** Policy: whether/where to answer an event (return null to ignore). Defaults to {@link defaultFeishuRoute}. */
+    route?: (event: FeishuMessageEvent) => FeishuRoute | null;
+    /** Customer-facing failure text for the chat (the dev-facing full `details` always go to the operator
+     *  log). Return a string to send it, or undefined/"" to stay silent. Default: a neutral message keyed
+     *  on `retryable`. A developer's own bot can surface the raw details, e.g. `(f) => `⚠️ ${f.details}``. */
+    onError?: (failed: FeishuFailure) => string | undefined;
+    /** API origin override (tests / self-hosted gateways). The kind fixes the default —
+     *  `feishuChannel` → `https://open.feishu.cn`, `larkChannel` → `https://open.larksuite.com`. */
+    baseUrl?: string;
+    /** How long (ms) a turn waits before its reply-quoted "⏳ Queued" card mounts. Defaults to 0
+     *  (immediate); the same card is later taken over by the live preview/final answer. */
+    queueNoticeDelayMs?: number;
+}
+/** Build the canonical Feishu channel. Lark calls the internal profile-bound builder below. */
+export declare function feishuChannel(opts: FeishuChannelOptions): ChannelModule;
+/** Internal compatibility seam: protocol behavior comes from Feishu; the profile binds cloud edges. */
+export declare function buildFeishuChannel(profile: FeishuCloudProfile, { appId, appSecret, verificationToken, encryptKey, route, onError, baseUrl, queueNoticeDelayMs, }: FeishuChannelOptions, factoryName: string): ChannelModule;