dsh-connect 0.7.2 → 0.8.0

package/lib/channels/dingtalk/stream.js

@@ -0,0 +1,199 @@
+/**
+ * DingTalk stream-mode gateway client: STOMP over WebSocket, zero third-party
+ * dependencies (Node ≥ 22 global `WebSocket`; older Node needs a polyfill —
+ * the constructor is looked up lazily on `globalThis` so the module loads
+ * fine on Node 20, it only fails at connect time).
+ *
+ * This file is the live network boundary: it is intentionally thin and every
+ * protocol detail it depends on lives in the pure modules (stomp.ts,
+ * message.ts) that carry the unit tests. Actual connectivity requires real
+ * app credentials and an outbound connection to the DingTalk gateway, so it
+ * cannot be exercised in CI here.
+ * @module dsh-connect/channels/dingtalk/stream
+ */
+import { decodeFrames, encodeFrame } from "./stomp.js";
+import { buildConnectBody, INBOUND_DESTINATION, INBOUND_SUBSCRIPTION, REPLY_DESTINATION, } from "./message.js";
+export const DEFAULT_STREAM_URL = "wss://api.dingtalk.com/connect";
+/** STOMP heartbeat interval (client → gateway), ms. */
+const HEARTBEAT_MS = 10_000;
+const RECONNECT_BASE_MS = 1_000;
+const RECONNECT_MAX_MS = 30_000;
+function lazyWebSocketCtor() {
+    return globalThis.WebSocket;
+}
+/**
+ * STOMP-over-WebSocket gateway client. Usage:
+ * ```ts
+ * const client = new DingtalkStreamClient({ clientId, clientSecret });
+ * client.onInbound((raw) => console.log(raw.conversationId, raw.text?.content));
+ * await client.connect();
+ * await client.sendReply(msgId, buildTextReplyBody(msgId, "hi"));
+ * ```
+ */
+export class DingtalkStreamClient {
+    clientId;
+    clientSecret;
+    url;
+    logger;
+    ws;
+    rest = "";
+    heartbeat;
+    reconnectTimer;
+    backoffMs = RECONNECT_BASE_MS;
+    closedByUs = false;
+    messageHandler;
+    constructor(options) {
+        this.clientId = options.clientId;
+        this.clientSecret = options.clientSecret;
+        this.url = options.url ?? DEFAULT_STREAM_URL;
+        this.logger = options.logger;
+    }
+    /** Register the inbound-message handler (called for every gateway push). */
+    onInbound(handler) {
+        this.messageHandler = handler;
+    }
+    /** Open the socket, perform the STOMP handshake and subscribe. Reconnect-safe. */
+    async connect() {
+        const Ctor = lazyWebSocketCtor();
+        if (Ctor === undefined) {
+            throw new Error("connect-dingtalk: WebSocket is not available on this runtime (Node ≥ 22 or a polyfill required)");
+        }
+        if (this.closedByUs)
+            return;
+        this.logger?.info?.(`connect-dingtalk: connecting to ${this.url}`);
+        const ws = new Ctor(this.url);
+        this.ws = ws;
+        await new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                cleanup();
+                reject(new Error("connect-dingtalk: WebSocket handshake timed out"));
+            }, 15_000);
+            const cleanup = () => {
+                clearTimeout(timer);
+                ws.onopen = null;
+                ws.onerror = null;
+            };
+            ws.onopen = () => {
+                cleanup();
+                this.onSocketOpen();
+                resolve();
+            };
+            ws.onerror = () => {
+                // onclose fires next; the close handler owns reconnect scheduling.
+            };
+        });
+        ws.onmessage = (ev) => this.onSocketMessage(String(ev.data ?? ""));
+        ws.onclose = (ev) => this.onSocketClose(ev.code, ev.reason);
+    }
+    /** Send a reply to an inbound message (SEND frame to the reply topic). */
+    async sendReply(msgId, body) {
+        const ws = this.ws;
+        if (ws === undefined || ws.readyState !== 1 /* OPEN */) {
+            throw new Error("connect-dingtalk: stream not connected");
+        }
+        ws.send(encodeFrame("SEND", { destination: REPLY_DESTINATION }, body));
+    }
+    /** Stop the client and cancel any scheduled reconnect. */
+    close() {
+        this.closedByUs = true;
+        if (this.reconnectTimer !== undefined) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = undefined;
+        }
+        this.stopHeartbeat();
+        this.ws?.close(1000, "bye");
+        this.ws = undefined;
+    }
+    onSocketOpen() {
+        this.logger?.info?.("connect-dingtalk: socket open, sending CONNECT");
+        this.sendFrame("CONNECT", {
+            "accept-version": "1.2",
+            host: "api.dingtalk.com",
+            "heart-beat": `${HEARTBEAT_MS},${HEARTBEAT_MS}`,
+        }, buildConnectBody(this.clientId, this.clientSecret));
+    }
+    onSocketMessage(data) {
+        const { frames, rest } = decodeFrames(this.rest + data);
+        this.rest = rest;
+        for (const frame of frames)
+            this.handleFrame(frame);
+    }
+    onSocketClose(code, reason) {
+        this.stopHeartbeat();
+        this.ws = undefined;
+        if (this.closedByUs)
+            return;
+        this.logger?.warn?.(`connect-dingtalk: socket closed (code=${String(code)} reason=${String(reason)}), reconnecting in ${this.backoffMs}ms`);
+        this.scheduleReconnect();
+    }
+    scheduleReconnect() {
+        if (this.closedByUs || this.reconnectTimer !== undefined)
+            return;
+        const delay = this.backoffMs;
+        this.backoffMs = Math.min(this.backoffMs * 2, RECONNECT_MAX_MS);
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = undefined;
+            void this.connect().catch((error) => {
+                this.logger?.error?.(`connect-dingtalk: reconnect attempt failed: ${String(error)}`);
+                this.scheduleReconnect();
+            });
+        }, delay);
+    }
+    handleFrame(frame) {
+        switch (frame.command) {
+            case "CONNECTED": {
+                this.backoffMs = RECONNECT_BASE_MS;
+                this.logger?.info?.("connect-dingtalk: CONNECTED, subscribing");
+                this.sendFrame("SUBSCRIBE", { id: INBOUND_SUBSCRIPTION, destination: INBOUND_DESTINATION });
+                this.startHeartbeat();
+                break;
+            }
+            case "MESSAGE": {
+                if (this.messageHandler === undefined)
+                    break;
+                try {
+                    const raw = JSON.parse(frame.body);
+                    void Promise.resolve(this.messageHandler(raw)).catch((error) => {
+                        this.logger?.warn?.(`connect-dingtalk: inbound handler failed: ${String(error)}`);
+                    });
+                }
+                catch (error) {
+                    this.logger?.warn?.(`connect-dingtalk: malformed gateway payload: ${String(error)}`);
+                }
+                break;
+            }
+            case "ERROR": {
+                this.logger?.error?.(`connect-dingtalk: gateway ERROR: ${frame.body || frame.headers.message || "no detail"}`);
+                break;
+            }
+            case "RECEIPT": {
+                this.logger?.info?.("connect-dingtalk: gateway receipt received");
+                break;
+            }
+            default:
+                this.logger?.warn?.(`connect-dingtalk: unhandled STOMP frame ${frame.command}`);
+        }
+    }
+    sendFrame(command, headers, body = "") {
+        const ws = this.ws;
+        if (ws === undefined || ws.readyState !== 1)
+            return;
+        ws.send(encodeFrame(command, headers, body));
+    }
+    startHeartbeat() {
+        this.stopHeartbeat();
+        this.heartbeat = setInterval(() => {
+            const ws = this.ws;
+            if (ws !== undefined && ws.readyState === 1)
+                ws.send("\n");
+        }, HEARTBEAT_MS);
+        this.heartbeat.unref?.();
+    }
+    stopHeartbeat() {
+        if (this.heartbeat !== undefined) {
+            clearInterval(this.heartbeat);
+            this.heartbeat = undefined;
+        }
+    }
+}
+//# sourceMappingURL=stream.js.map

package/lib/channels/dingtalk/stream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream.js","sourceRoot":"","sources":["../../../src/channels/dingtalk/stream.ts"],"names":[],"mappings":"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"}

package/lib/channels/dingtalk/webhook.d.ts

@@ -0,0 +1,84 @@
+/** DingTalk webhook configuration. */
+export interface DingtalkWebhookConfig {
+    /** Full webhook URL, e.g. `https://oapi.dingtalk.com/robot/send?access_token=xxx`. */
+    webhookUrl: string;
+    /** Optional signing secret (`SEC...`) — when set, requests are signed. */
+    secret?: string;
+    /** HTTP timeout in ms (default 10s). */
+    timeoutMs?: number;
+    /** Backoff delays between retries for transient network errors (default 1s/2s/4s). */
+    retryDelaysMs?: readonly number[];
+    /** Extra delay for the 130101 frequency-limit retry (default 10s). */
+    rateLimitDelayMs?: number;
+}
+/** Body shape accepted by the DingTalk robot API. */
+export type DingtalkBody = {
+    msgtype: "text";
+    text: {
+        content: string;
+    };
+    at?: {
+        atMobiles?: string[];
+        atUserIds?: string[];
+        isAtAll?: boolean;
+    };
+} | {
+    msgtype: "markdown";
+    markdown: {
+        title: string;
+        text: string;
+    };
+    at?: {
+        atMobiles?: string[];
+        atUserIds?: string[];
+        isAtAll?: boolean;
+    };
+};
+/** Response of the DingTalk robot API. */
+export interface DingtalkResponse {
+    errcode: number;
+    errmsg: string;
+}
+/** How to address people in a DingTalk group. */
+export interface DingtalkAt {
+    /** Phone numbers — required by DingTalk for `atMobiles` (robots can't resolve names). */
+    mobiles?: readonly string[];
+    /** User ids (unionid/`userId` when known). */
+    userIds?: readonly string[];
+    /** @everyone. */
+    all?: boolean;
+}
+/** DingTalk caps markdown body text at 20000 chars. */
+export declare const MARKDOWN_LIMIT = 20000;
+/**
+ * Compute the DingTalk webhook signature. The SDK expects
+ * `timestamp + "\n" + secret` signed with HMAC-SHA256, base64-encoded, then
+ * URL-encoded as the `sign` query param.
+ */
+export declare function signDingtalk(secret: string, timestampMs: number): string;
+/**
+ * Verify an incoming signature against a secret (used by webhook receivers, if
+ * ever needed). Both sides are compared after URL-decoding, so a sender that
+ * encoded `+` as `%2B` (or vice versa) still verifies, and the timestamp must
+ * be fresh (default: ±5 minutes) to be replay-resistant.
+ */
+export declare function verifyDingtalkSignature(secret: string, timestampMs: string, sign: string, nowMs?: number, maxAgeMs?: number): boolean;
+/**
+ * Minimal DingTalk group-robot webhook client built on the global `fetch`
+ * (Node ≥ 18 / ≥ 20 — no third-party HTTP dependency). Transient failures
+ * (network errors, the 20/min frequency limit) are retried with backoff.
+ */
+export declare class DingtalkWebhook {
+    readonly config: DingtalkWebhookConfig;
+    constructor(config: DingtalkWebhookConfig);
+    /**
+     * Send a markdown message. `title` is shown as the message's card title in
+     * DingTalk; `text` is the markdown body (truncated to 20000 chars, the API
+     * limit). Optionally @-mention people.
+     */
+    sendMarkdown(title: string, text: string, at?: DingtalkAt): Promise<DingtalkResponse>;
+    /** Send a plain-text message (content shown verbatim, `\n` newlines allowed). */
+    sendText(content: string, at?: DingtalkAt): Promise<DingtalkResponse>;
+    private send;
+}
+//# sourceMappingURL=webhook.d.ts.map

package/lib/channels/dingtalk/webhook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook.d.ts","sourceRoot":"","sources":["../../../src/channels/dingtalk/webhook.ts"],"names":[],"mappings":"AAYA,sCAAsC;AACtC,MAAM,WAAW,qBAAqB;IACpC,sFAAsF;IACtF,UAAU,EAAE,MAAM,CAAC;IACnB,0EAA0E;IAC1E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wCAAwC;IACxC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sFAAsF;IACtF,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,sEAAsE;IACtE,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,qDAAqD;AACrD,MAAM,MAAM,YAAY,GAAG;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1B,EAAE,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;CACxE,GAAG;IACF,OAAO,EAAE,UAAU,CAAC;IACpB,QAAQ,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1C,EAAE,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;CACxE,CAAC;AAEF,0CAA0C;AAC1C,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,iDAAiD;AACjD,MAAM,WAAW,UAAU;IACzB,yFAAyF;IACzF,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,8CAA8C;IAC9C,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,iBAAiB;IACjB,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAED,uDAAuD;AACvD,eAAO,MAAM,cAAc,QAAS,CAAC;AAIrC;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAIxE;AAUD;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,MAAM,EACZ,KAAK,GAAE,MAAmB,EAC1B,QAAQ,GAAE,MAAmB,GAC5B,OAAO,CAOT;AA2BD;;;;GAIG;AACH,qBAAa,eAAe;IAC1B,QAAQ,CAAC,MAAM,EAAE,qBAAqB,CAAC;gBAE3B,MAAM,EAAE,qBAAqB;IAOzC;;;;OAIG;IACG,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAK3F,iFAAiF;IAC3E,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,gBAAgB,CAAC;YAI7D,IAAI;CAiCnB"}

package/lib/channels/dingtalk/webhook.js

@@ -0,0 +1,143 @@
+/**
+ * DingTalk group-robot webhook transport. A webhook URL is created from a
+ * group's "custom robot" (群自定义机器人): the group owner adds a robot, gets
+ * an `access_token`, and optionally enables a signing secret. This transport
+ * only *pushes* — DingTalk custom webhooks cannot receive messages, so this
+ * package is a one-way notice channel (progress / results / alerts), not a
+ * bidirectional conversation adapter like the Feishu one.
+ *
+ * @module dsh-connect/channels/dingtalk/webhook
+ */
+import { createHmac, timingSafeEqual } from "node:crypto";
+/** DingTalk caps markdown body text at 20000 chars. */
+export const MARKDOWN_LIMIT = 20_000;
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * Compute the DingTalk webhook signature. The SDK expects
+ * `timestamp + "\n" + secret` signed with HMAC-SHA256, base64-encoded, then
+ * URL-encoded as the `sign` query param.
+ */
+export function signDingtalk(secret, timestampMs) {
+    const stringToSign = `${timestampMs}\n${secret}`;
+    const mac = createHmac("sha256", secret).update(stringToSign, "utf8").digest("base64");
+    return encodeURIComponent(mac);
+}
+function safeDecode(value) {
+    try {
+        return decodeURIComponent(value);
+    }
+    catch {
+        return value; // not URL-encoded — compare as-is
+    }
+}
+/**
+ * Verify an incoming signature against a secret (used by webhook receivers, if
+ * ever needed). Both sides are compared after URL-decoding, so a sender that
+ * encoded `+` as `%2B` (or vice versa) still verifies, and the timestamp must
+ * be fresh (default: ±5 minutes) to be replay-resistant.
+ */
+export function verifyDingtalkSignature(secret, timestampMs, sign, nowMs = Date.now(), maxAgeMs = 5 * 60_000) {
+    const ts = Number(timestampMs);
+    if (!Number.isFinite(ts) || Math.abs(nowMs - ts) > maxAgeMs)
+        return false;
+    const expected = signDingtalk(secret, ts);
+    const a = Buffer.from(safeDecode(sign));
+    const b = Buffer.from(safeDecode(expected));
+    return a.length === b.length && timingSafeEqual(a, b);
+}
+/** Replace non-url-safe chars in a DingTalk webhook URL's query (idempotent-safe). */
+function withSignature(url, secret, timestampMs) {
+    const sign = signDingtalk(secret, timestampMs);
+    const sep = url.includes("?") ? "&" : "?";
+    return `${url}${sep}timestamp=${timestampMs}&sign=${sign}`;
+}
+/** Errors that are safe to retry: transient network issues and the frequency limit. */
+function isRetryable(error) {
+    const errcode = error.errcode;
+    if (errcode === 130101)
+        return true; // 发送频率限制 (20/min per robot)
+    if (error instanceof TypeError)
+        return true; // fetch network failure
+    return false;
+}
+function delayFor(config, error, attempt) {
+    const errcode = error.errcode;
+    if (errcode === 130101)
+        return config.rateLimitDelayMs ?? 10_000; // rate limit: wait for the window to pass
+    const backoff = config.retryDelaysMs;
+    if (backoff !== undefined && backoff.length > 0)
+        return backoff[Math.min(attempt, backoff.length - 1)] ?? 1_000;
+    return 1_000 * 2 ** attempt; // 1s, 2s, 4s…
+}
+const MAX_ATTEMPTS = 3;
+/**
+ * Minimal DingTalk group-robot webhook client built on the global `fetch`
+ * (Node ≥ 18 / ≥ 20 — no third-party HTTP dependency). Transient failures
+ * (network errors, the 20/min frequency limit) are retried with backoff.
+ */
+export class DingtalkWebhook {
+    config;
+    constructor(config) {
+        if (!config.webhookUrl || !config.webhookUrl.startsWith("https://")) {
+            throw new Error("connect-dingtalk: webhookUrl must be a https:// DingTalk robot URL");
+        }
+        this.config = config;
+    }
+    /**
+     * Send a markdown message. `title` is shown as the message's card title in
+     * DingTalk; `text` is the markdown body (truncated to 20000 chars, the API
+     * limit). Optionally @-mention people.
+     */
+    async sendMarkdown(title, text, at) {
+        const body = text.length > MARKDOWN_LIMIT ? `${text.slice(0, MARKDOWN_LIMIT)}\n\n…(已截断)` : text;
+        return this.send({ msgtype: "markdown", markdown: { title, text: body }, at: atBody(at) });
+    }
+    /** Send a plain-text message (content shown verbatim, `\n` newlines allowed). */
+    async sendText(content, at) {
+        return this.send({ msgtype: "text", text: { content }, at: atBody(at) });
+    }
+    async send(body, attempt = 0) {
+        const { webhookUrl, secret, timeoutMs = 10_000 } = this.config;
+        const url = secret ? withSignature(webhookUrl, secret, Date.now()) : webhookUrl;
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        try {
+            const response = await fetch(url, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify(body),
+                signal: controller.signal,
+            });
+            if (!response.ok) {
+                throw new Error(`connect-dingtalk: HTTP ${response.status} ${response.statusText}`);
+            }
+            const parsed = (await response.json());
+            if (parsed.errcode !== 0) {
+                const error = new Error(`connect-dingtalk: DingTalk error ${parsed.errcode}: ${parsed.errmsg}`);
+                error.errcode = parsed.errcode;
+                throw error;
+            }
+            return parsed;
+        }
+        catch (error) {
+            if (isRetryable(error) && attempt < MAX_ATTEMPTS) {
+                await sleep(delayFor(this.config, error, attempt));
+                return this.send(body, attempt + 1);
+            }
+            throw error;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+}
+function atBody(at) {
+    if (at === undefined)
+        return undefined;
+    return {
+        ...(at.mobiles !== undefined && at.mobiles.length > 0 ? { atMobiles: [...at.mobiles] } : {}),
+        ...(at.userIds !== undefined && at.userIds.length > 0 ? { atUserIds: [...at.userIds] } : {}),
+        ...(at.all === true ? { isAtAll: true } : {}),
+    };
+}
+//# sourceMappingURL=webhook.js.map

package/lib/channels/dingtalk/webhook.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook.js","sourceRoot":"","sources":["../../../src/channels/dingtalk/webhook.ts"],"names":[],"mappings":"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"}

package/lib/channels/feishu/adapter.d.ts

@@ -0,0 +1,139 @@
+import type { ChannelAdapter, ChoiceOption, ChoicePrompt, ChoiceResult, InboundMessage, OutboundTarget, SummaryCard } from "../../types.js";
+import type { Language } from "../../i18n.js";
+/** Pad every label with trailing spaces up to the same display width. */
+export declare function padLabels(options: readonly ChoiceOption[]): ChoiceOption[];
+/**
+ * Render options as an equal-width button grid: 2 buttons per row via
+ * `column_set` (two weighted columns), padding the last row with empty
+ * columns so every row is a uniform 2-cell layout. Labels are padded to the
+ * same display width so the buttons themselves render uniformly. Destructive
+ * actions (labels starting with ❌) render as red danger buttons.
+ */
+export declare function buildButtonGrid(options: readonly ChoiceOption[], columnsPerRow?: number): unknown[];
+/**
+ * Render options as a single-select dropdown (`select_static`) inside an
+ * `action` container. Selecting an entry fires the card action with
+ * `action.tag === "select_static"` and the picked option id in `action.option`.
+ */
+export declare function buildSelectMenu(options: readonly ChoiceOption[], placeholder?: string, initial?: string): unknown[];
+/**
+ * Assemble the card elements for a choice prompt. When `sections` is given,
+ * the options are split into titled groups — each with a bold section caption
+ * and a divider before it — instead of one flat grid. Options not listed in
+ * any section (typically the trailing exit/back buttons) are rendered after
+ * the sections, separated by a divider.
+ *
+ * @param prompt - The choice prompt to render
+ * @param defaultColumns - Default number of columns per row (default: 2)
+ */
+export declare function buildChoiceElements(prompt: ChoicePrompt, defaultColumns?: number): unknown[];
+/**
+ * Encode a chatKey with an optional thread id. With `threadIsolation` on, a
+ * group message inside a thread gets `chatId:thread=<rootId>` as its chatKey,
+ * so each thread binds its own DSH session while outbound sends still target
+ * the base chat id (replies land in the thread via replyRef).
+ */
+export declare function encodeChatKey(chatId: string, threadId?: string): string;
+/** Decode a possibly thread-scoped chatKey back to its base chat id. */
+export declare function decodeChatKey(chatKey: string): {
+    chatId: string;
+    threadId?: string;
+};
+/** Classify a local file name for the Feishu upload API (image vs stream file). */
+export declare function classifyFeishuFile(filename: string): "image" | "file";
+/** Strip path separators / control chars from a downloaded file's name. */
+export declare function sanitizeFileName(name: string): string;
+/**
+ * Extract a human-readable error detail. Feishu business errors (missing
+ * permission, invalid resource, …) arrive as HTTP 200/400 with the real
+ * `{code, msg}` in the response body; prefer that over the axios fallback
+ * message like "Request failed with status code 400" that hides the cause.
+ */
+export declare function extractErrorDetail(error: unknown): string;
+export interface FeishuConfig {
+    appId?: string;
+    appSecret?: string;
+    transport?: "websocket" | "webhook";
+    verificationToken?: string;
+    encryptKey?: string;
+    /** HTTP port for `transport: "webhook"` (default 9000). */
+    webhookPort?: number;
+    /** HTTP path the Feishu event callback posts to (default "/"). */
+    webhookPath?: string;
+    /** Group messages must @-mention the bot (default true). */
+    requireMention?: boolean;
+    /** Single-chat policy (SDK values): open / allowlist / pair / disabled. */
+    dmMode?: "open" | "allowlist" | "pair" | "disabled";
+    /** Bind one DSH session per group thread instead of one per chat (default false). */
+    threadIsolation?: boolean;
+    /** User-facing message language: `zh` (default) or `en`. */
+    language?: Language;
+}
+export declare class FeishuAdapter implements ChannelAdapter {
+    private readonly logger?;
+    private readonly isChatAllowed?;
+    readonly id = "feishu";
+    private readonly channel;
+    private readonly pendingChoices;
+    /** Cards whose stale-button tap was already noticed (dedupe, self-clearing). */
+    private readonly staleNoticed;
+    private readonly staleTimers;
+    private readonly t;
+    private readonly transport;
+    private readonly webhookPort;
+    private readonly webhookPath;
+    private readonly threadIsolation;
+    private server?;
+    private handler?;
+    constructor(config: FeishuConfig, logger?: {
+        info?: (...args: unknown[]) => void;
+        warn?: (...args: unknown[]) => void;
+        error?: (...args: unknown[]) => void;
+    } | undefined, isChatAllowed?: ((channel: string, chatKey: string, senderKey: string) => boolean) | undefined);
+    onInbound(handler: (msg: InboundMessage) => void | Promise<void>): void;
+    /** Resource types downloadable via `im.v1.messageResource.get`. Stickers are not supported by the Feishu API. */
+    private static readonly DOWNLOADABLE_TYPES;
+    /** Download attached images / files into local temp dirs; return their paths (and any failures). */
+    private downloadResources;
+    /**
+     * Download a resource inside a user message.
+     *
+     * Note: do NOT use the SDK's `downloadResource(fileKey, type)` — it calls
+     * `im.v1.image.get` / `im.v1.file.get` (download image / download file), and
+     * per the Feishu docs those endpoints **can only download resources uploaded
+     * by the bot itself**. Resources inside user-sent messages must be fetched
+     * with "get resource file from message" `im.v1.messageResource.get` (with
+     * message_id + type=image/file/audio/video), otherwise it returns HTTP 400.
+     */
+    private downloadMessageResource;
+    /**
+     * Housekeeping for the per-channel temp dirs: remove downloads older than
+     * 24h so a busy bot doesn't fill the OS temp partition. Best-effort — a
+     * failure to clean is logged, never fatal.
+     */
+    private cleanupTempDirs;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    /** Base chat id for outbound sends (strips any `:thread=` suffix). */
+    private chatIdOf;
+    sendText(target: OutboundTarget, text: string): Promise<void>;
+    sendCard(target: OutboundTarget, card: SummaryCard): Promise<void>;
+    streamText(target: OutboundTarget, chunks: AsyncIterable<string>): Promise<void>;
+    /**
+     * Deliver a local file to the chat. The SDK uploads the source itself:
+     * images are sent inline, everything else as an attachment.
+     */
+    sendFile(target: OutboundTarget, filePath: string, options?: {
+        filename?: string;
+    }): Promise<void>;
+    /**
+     * Build the send options shared by text/markdown deliveries: an optional
+     * reply target and @-mentions (SDK renders `<at user_id=…>` prefixes for
+     * both text and post messages, so group completion cards can nudge the
+     * requester).
+     */
+    private sendOpts;
+    promptChoice(target: OutboundTarget, prompt: ChoicePrompt, updateMessageId?: string): Promise<ChoiceResult>;
+    closeMenu(messageId: string, summary: string): Promise<void>;
+}
+//# sourceMappingURL=adapter.d.ts.map

package/lib/channels/feishu/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../../src/channels/feishu/adapter.ts"],"names":[],"mappings":"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"}