@fastagent-sh/fastagent 0.24.4 → 0.26.0

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

@@ -26,7 +26,7 @@ const API_TIMEOUT_MS = 30_000;
 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
+/** Download sanity cap; a larger resource is rejected visibly (the harness 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. */
@@ -75,6 +75,11 @@ export function isTransientFeishuRegistrationError(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));
+/**
+ * How many pages of 100 a member-name read walks before giving up: each page is a serial round trip on a turn's path,
+ * so a chat of thousands is named up to here and the rest is said, not waited for.
+ */
+const MEMBER_PAGES = 10;
 /** 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). */
 const FEISHU_MAX_TEXT_BYTES = 100 * 1024;
@@ -188,155 +193,193 @@ export function createFeishuApi(opts) {
             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 thread
-                // must reply_in_thread on EVERY chunk; a plain chat send would leak continuations to main chat.
-                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", 
-            // Pin the id type: callers match mentions/sender against open_ids, so the response's id shape
-            // must not depend on the platform's default staying open_id.
-            `/open-apis/im/v1/messages/${encodeURIComponent(messageId)}?user_id_type=open_id`);
-            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;
+    return client(undefined);
+    function client(onSent) {
+        /** Every created message passes here, so `onSent` cannot miss one (sendText's chunks ride send/reply). */
+        const sent = (messageId) => {
+            if (messageId !== undefined)
+                onSent?.(messageId);
+            return messageId;
+        };
+        const api = {
+            recordingSends: (record) => client(record),
+            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 sent(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 sent(data.data?.message_id);
+            },
+            async listMessages(container, pageSize, endTime, opts) {
+                const query = new URLSearchParams({
+                    container_id_type: container.type,
+                    container_id: container.id,
+                    sort_type: "ByCreateTimeDesc",
+                    page_size: String(pageSize),
+                    user_id_type: "open_id",
+                    // A Card 2.0 (every streamed answer, a feishu-send digest) otherwise reads as "please upgrade the client".
+                    card_msg_content_type: "user_card_content",
+                });
+                if (endTime !== undefined)
+                    query.set("end_time", String(endTime));
+                const data = await call("listMessages", "GET", `/open-apis/im/v1/messages?${query}`, undefined, opts);
+                return { items: data.data?.items ?? [], hasMore: data.data?.has_more === true };
+            },
+            async chatMemberNames(chatId, wanted, opts) {
+                const names = new Map();
+                let pageToken;
+                for (let page = 0; page < MEMBER_PAGES; page++) {
+                    const query = new URLSearchParams({ member_id_type: "open_id", page_size: "100" });
+                    if (pageToken)
+                        query.set("page_token", pageToken);
+                    const data = await call("chatMemberNames", "GET", `/open-apis/im/v1/chats/${encodeURIComponent(chatId)}/members?${query}`, undefined, opts);
+                    for (const member of data.data?.items ?? []) {
+                        if (member.member_id && member.name && wanted.has(member.member_id))
+                            names.set(member.member_id, member.name);
+                    }
+                    if (data.data?.has_more !== true || !data.data.page_token)
+                        return { names, complete: true };
+                    if (names.size === wanted.size)
+                        return { names, complete: false };
+                    pageToken = data.data.page_token;
+                }
+                return { names, complete: false };
+            },
+            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 thread
+                    // must reply_in_thread on EVERY chunk; a plain chat send would leak continuations to main chat.
+                    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", 
+                // Pin the id type: callers match mentions/sender against open_ids, so the response's id shape
+                // must not depend on the platform's default staying open_id. And ask for a card as it was SENT:
+                // by default a Card 2.0 message (every answer this channel streams) comes back as the
+                // placeholder "please upgrade the client to view this", so a quoted answer was unreadable.
+                `/open-apis/im/v1/messages/${encodeURIComponent(messageId)}?user_id_type=open_id&card_msg_content_type=user_card_content`);
+                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 {
-                    const parsed = JSON.parse(errBody ?? "");
-                    description = parsed.msg;
-                    code = parsed.code ?? 0;
+                    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 {
-                    /* non-JSON error body — fall through to the generic description */
+                catch (e) {
+                    throw new FeishuApiError(kind, label, 0, 0, String(e), { cause: e });
                 }
-                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");
-            const dest = attachmentPath(filesDir, chatId, name);
-            await mkdir(dest.dir, { recursive: true });
-            await writeFile(dest.path, bytes);
-            return { path: dest.path, name: dest.name, 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 listAppScopes() {
-            const data = await call("listAppScopes", "GET", "/open-apis/application/v6/scopes");
-            return (data.data?.scopes ?? []).flatMap((scope) => {
-                if (typeof scope.scope_name !== "string" || typeof scope.grant_status !== "number")
-                    return [];
-                const type = scope.scope_type === "user" || scope.scope_type === "tenant" ? scope.scope_type : undefined;
-                return [{ name: scope.scope_name, grantStatus: scope.grant_status, type }];
-            });
-        },
-        async addAppScopes(appId, scopeNames) {
-            if (scopeNames.length === 0)
-                return;
-            await call("addAppScopes", "PATCH", `/open-apis/application/v7/applications/${encodeURIComponent(appId)}/config`, {
-                scope: {
-                    add_scopes: scopeNames.map((scopeName) => ({ scope_name: scopeName, token_type: "tenant" })),
-                },
-            });
-        },
-        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, opts) {
-            await call("updateCardElement", "PUT", `/open-apis/cardkit/v1/cards/${encodeURIComponent(cardId)}/elements/${encodeURIComponent(elementId)}/content`, { content, sequence }, opts);
-        },
-        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;
+                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");
+                const dest = attachmentPath(filesDir, chatId, name);
+                await mkdir(dest.dir, { recursive: true });
+                await writeFile(dest.path, bytes);
+                return { path: dest.path, name: dest.name, 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 listAppScopes() {
+                const data = await call("listAppScopes", "GET", "/open-apis/application/v6/scopes");
+                return (data.data?.scopes ?? []).flatMap((scope) => {
+                    if (typeof scope.scope_name !== "string" || typeof scope.grant_status !== "number")
+                        return [];
+                    const type = scope.scope_type === "user" || scope.scope_type === "tenant" ? scope.scope_type : undefined;
+                    return [{ name: scope.scope_name, grantStatus: scope.grant_status, type }];
+                });
+            },
+            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, opts) {
+                await call("updateCardElement", "PUT", `/open-apis/cardkit/v1/cards/${encodeURIComponent(cardId)}/elements/${encodeURIComponent(elementId)}/content`, { content, sequence }, opts);
+            },
+            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

@@ -1,5 +1,6 @@
 import type { ChannelModule, LongConnectionChannelModule } from "../../channel.ts";
 import { type FeishuCloudProfile } from "./cloud.ts";
+import { type FeishuSubscriptionMode } from "./setup-mode.ts";
 import { type FeishuMessage, type FeishuMessageEvent, type FeishuRoute, defaultFeishuRoute, feishuEnvelope } from "./parse.ts";
 import { type FeishuFailure } from "./preview.ts";
 import { connectFeishuWs } from "./ws-ingress.ts";
@@ -30,6 +31,8 @@ export type FeishuWebSocketChannelOptions = FeishuChannelBaseOptions & {
 };
 /** Build the canonical Feishu Request-URL webhook channel. */
 export declare function feishuChannel(opts: FeishuChannelOptions): ChannelModule;
+/** How this process receives the Feishu channel: `FEISHU_INGRESS`, else WebSocket under `dev` and webhook otherwise. */
+export declare function feishuIngress(): FeishuSubscriptionMode;
 /** Build the canonical Feishu WebSocket long-connection channel. */
 export declare function feishuWebSocketChannel(opts: FeishuWebSocketChannelOptions): LongConnectionChannelModule;
 /** Internal compatibility seams: protocol behavior comes from Feishu; the profile binds cloud edges. */