@ganglion/xacpx-channel-feishu 0.4.0

package/README.md

@@ -0,0 +1,91 @@
+# @ganglion/weacpx-channel-feishu
+
+Feishu channel plugin for `weacpx`.
+
+```bash
+weacpx plugin add @ganglion/weacpx-channel-feishu
+weacpx channel add feishu
+weacpx restart
+```
+
+The channel requires a Feishu self-built app `appId` and `appSecret`.
+
+## Reply rendering: `replyMode`
+
+| Mode | Behaviour |
+|------|-----------|
+| `"auto"` (default) | Streaming for direct (p2p) chats, static for groups. Groups already serialize visually around a thread, so the multi-message static path stays simpler there. |
+| `"streaming"` | The channel creates one CardKit v2 interactive card per turn and updates it in place — thinking → streaming → complete (or aborted/error). User sees output appear progressively in one message slot. |
+| `"static"` | Every `reply()` chunk + the final agent response are sent as separate text messages, replying to the user's incoming message. |
+
+While streaming, the card uses two CardKit endpoints intelligently:
+- `cardElement.content` for pure-text deltas — smaller payload, native typewriter animation.
+- Full `card.update` on state transitions, image-key arrival, reasoning panel toggles, and the final state.
+
+Final-state cards include the elapsed turn time in the footer (e.g. `已完成 · 3.4s`). Live streaming cards (thinking/streaming states) also show a ticking elapsed footer (`⏳ 处理中... 8.2s`) so long-running tasks give the user a continuous time signal. Models that emit `<think>...</think>` / `<thinking>...</thinking>` (or a `Reasoning:\n_…_` prefix) get the reasoning rendered above the answer in a separate notation-sized block, with a horizontal divider before the answer body. Markdown image URLs (`![alt](https://...)`) are resolved to Feishu `image_key` references on the fly so the card renders the image inline; URLs that don't resolve within the configurable timeout are stripped.
+
+When `channel.replyMode: "verbose"` (the default) is paired with streaming mode, tool calls are rendered as a collapsible **🔧 工具调用 (N)** panel above the answer body instead of inline text segments. Each step shows status (✅/⏳/❌), a kind icon (📖 read · 🔍 search · 💻 execute · ✏️ edit · 🧠 think · 🔧 other), the tool name, a one-line summary derived from the call's input (e.g. file path, command, search pattern), and the duration once finished. Static mode keeps the legacy inline behavior — each tool call lands as its own text bubble.
+
+The streaming card consumes the structured tool-use side-channel by registering an `onToolEvent` callback. The transport defaults to `toolEventMode: "structured"` whenever a handler is provided, so events flow into the collapsible card panel instead of the legacy text bubbles.
+
+The card terminates gracefully on daemon shutdown: SIGINT/SIGTERM/`beforeExit` drives every in-flight card to its "已停止" state before the process exits, so a killed `weacpx` daemon no longer leaves cards stuck at "处理中..." in the user's Feishu chat.
+
+Streaming mode requires the bot to have **`cardkit:card:write`** plus **`im:message:send_as_bot`** scopes. If the initial `cardkit.v1.card.create` call fails (most commonly: missing scope), the channel logs `feishu.streaming.fallback` and falls back to the static path for that turn. When the failure is a Feishu permission error (code `99991672`) the grant URL is also sent to the user once per 5-minute cooldown.
+
+Set globally:
+
+```jsonc
+{
+  "channels": [
+    {
+      "id": "feishu",
+      "type": "feishu",
+      "options": {
+        "appId": "cli_xxx",
+        "appSecret": "yyy",
+        "replyMode": "streaming"
+      }
+    }
+  ]
+}
+```
+
+Or per account:
+
+```jsonc
+{
+  "options": {
+    "replyMode": "streaming",
+    "accounts": {
+      "main":   { "appId": "...", "appSecret": "...", "replyMode": "streaming" },
+      "legacy": { "appId": "...", "appSecret": "...", "replyMode": "static" }
+    }
+  }
+}
+```
+
+## Cancelling the in-flight turn
+
+While the agent is processing, the user can send `stop`, `/stop`, `abort`, `停止`, `取消`, etc. The channel:
+
+1. Aborts the per-turn `AbortController` (which the router forwards to `transport.cancel()` so the underlying `acpx` process is interrupted).
+2. Renders an "已停止" final state on the streaming card, or sends a "已停止当前任务。" reply in static mode.
+3. Removes the typing reaction added to the user's original message.
+
+## Real-time session switching & background execution
+
+Each inbound prompt is **bound at dispatch time** to whatever session the chat is currently on, then runs on a **per-session lane**:
+
+- **Different sessions run concurrently.** Switching to another session (`/use`/`/ss`) while a task is in flight lets you use the new session immediately — turns on different sessions don't block each other.
+- **Same-session turns serialize**, preserving order within a session.
+- **Switch and cancel commands preempt.** `/use`, `/ss`, `/cancel`, `/stop` run on a **control lane**, so they take effect right away even while a prompt is running (the running prompt keeps going in the background — see below).
+
+When you switch away from a running session, its turn keeps executing in the background. Feishu uses **"B-semantics"**, which differs from the WeChat channel:
+
+- The backgrounded session has its **own streaming card** that keeps refreshing **to completion in the chat timeline** — it is *not* gated/suppressed. The result simply stays on that card.
+- On completion, a short ping is sent to the chat: `✅ <alias> 已完成` (or `⚠️ <alias> 失败`). Unlike WeChat, there is **no `/use 查看结果`** suffix — there is nothing to replay, because the card already holds the result.
+- Switching **back** to that session does **not** re-send the result.
+- `/sessions` marks sessions with an unfinished/unread background completion using `●`.
+
+`/cancel <alias>` (and `/stop <alias>`) target a specific session's in-flight turn by alias — fuzzy alias resolution applies, the same as `/use`.
+

package/dist/abort-detect.d.ts

@@ -0,0 +1,4 @@
+import type { FeishuMessageEvent } from "./types.js";
+export declare function isAbortTrigger(text: string): boolean;
+export declare function isLikelyAbortText(text: string): boolean;
+export declare function extractRawTextFromFeishuEvent(event: FeishuMessageEvent): string | undefined;

package/dist/card/card-builder.d.ts

@@ -0,0 +1,23 @@
+import type { ToolUseStep } from "./tool-use-types.js";
+export declare const STREAMING_ELEMENT_ID = "streaming_content";
+export declare const REASONING_ELEMENT_ID = "reasoning_content";
+export type CardState = "thinking" | "streaming" | "complete" | "aborted" | "error";
+export declare const CARD_BODY_MAX_CHARS = 28000;
+export declare function truncateForCardBody(text: string, maxChars?: number): string;
+export interface BuildCardInput {
+    state: CardState;
+    text: string;
+    elapsedMs?: number;
+    reasoningText?: string;
+    reasoningElapsedMs?: number;
+    toolSteps?: ToolUseStep[];
+    /** Per-call override of {@link CARD_BODY_MAX_CHARS}. */
+    maxBodyChars?: number;
+}
+export declare function buildCard(input: BuildCardInput): Record<string, unknown>;
+export declare function formatElapsedMs(ms: number): string;
+/**
+ * Builds the `content` string for `im.message.create({ msg_type: "interactive" })`
+ * that references a CardKit card instance by id.
+ */
+export declare function buildCardMessageContent(cardId: string): string;

package/dist/card/flush-controller.d.ts

@@ -0,0 +1,48 @@
+export interface FlushControllerOptions {
+    minIntervalMs: number;
+    now?: () => number;
+    setTimer?: (cb: () => void, delayMs: number) => unknown;
+    clearTimer?: (handle: unknown) => void;
+    /**
+     * Called when {@link consecutiveFailures} reaches `failureThreshold`. The
+     * controller continues to accept flushes (so a recovery still works), but
+     * the owner can use this signal to fall back to a non-card delivery path.
+     * Fires once per crossing of the threshold; resets after any successful
+     * flush.
+     */
+    onFailureThreshold?: (consecutiveFailures: number) => void;
+    /** Default 3. */
+    failureThreshold?: number;
+}
+/**
+ * Throttled flush primitive.
+ *
+ * - `requestFlush(work)` honours the min-interval. Rapid calls coalesce to a
+ *   single trailing flush carrying the *latest* `work` callback.
+ * - `forceFlush(work)` runs ASAP, after any in-flight work completes,
+ *   and supersedes any queued throttled flush.
+ * - `waitIdle()` resolves once the chain plus any scheduled flush has drained.
+ */
+export declare class FlushController {
+    private readonly minIntervalMs;
+    private readonly now;
+    private readonly setTimer;
+    private readonly clearTimer;
+    private chain;
+    private deferredWork;
+    private timer;
+    private lastFlushAtMs;
+    private timerWaiters;
+    private consecutiveFailures;
+    private failureCallbackFired;
+    private readonly onFailureThreshold;
+    private readonly failureThreshold;
+    constructor(options?: Partial<FlushControllerOptions>);
+    /** Snapshot of the current consecutive-failure counter (for diagnostics). */
+    getConsecutiveFailures(): number;
+    requestFlush(work: () => Promise<void>): void;
+    private notifyTimerWaiters;
+    forceFlush(work: () => Promise<void>): Promise<void>;
+    waitIdle(): Promise<void>;
+    private appendToChain;
+}

package/dist/card/image-resolver.d.ts

@@ -0,0 +1,70 @@
+import { extractBufferFromFeishuResponse } from "../media.js";
+export interface ImageUploadClient {
+    im: {
+        image?: {
+            create(input: {
+                data: {
+                    image_type: "message";
+                    image: unknown;
+                };
+            }): Promise<unknown>;
+        };
+    };
+}
+export interface ImageResolverOptions {
+    client: ImageUploadClient;
+    /** Called whenever a previously-pending upload completes successfully. */
+    onImageResolved: () => void;
+    /**
+     * Optional override for fetching remote image bytes. Receives `maxBytes`
+     * so the implementation may stream-check the size *before* reading the
+     * full body. Defaults to global fetch which checks Content-Length.
+     */
+    fetchUrl?: (url: string, options?: {
+        maxBytes?: number;
+    }) => Promise<Buffer>;
+    /** Optional logger; receives string events for observability. */
+    log?: (event: string, context?: Record<string, unknown>) => void;
+    /** Max bytes per image. Defaults to 5 MiB. */
+    maxBytes?: number;
+    /**
+     * Max number of resolved/failed entries to retain. When exceeded, oldest
+     * entries are evicted in LRU order. Defaults to 256. Pending uploads are
+     * never evicted (they self-evict on completion).
+     */
+    cacheCap?: number;
+}
+/**
+ * Streams-friendly resolver that swaps `![alt](https://...)` references for
+ * `![alt](img_xxx)` Feishu image keys.
+ *
+ * - Synchronous `resolveImages` is safe to call on every flush; it never
+ *   blocks. Unknown URLs are stripped and queued for async upload.
+ * - `onImageResolved` fires when a URL finishes uploading, letting the
+ *   caller re-flush so the resolved image surfaces.
+ * - `resolveImagesAwait` is for terminal states (complete/abort) so the
+ *   final card carries all known image keys.
+ *
+ * The `resolved` and `failed` maps are LRU-bounded so a long-running
+ * controller (or one fed thousands of URLs) can't leak memory.
+ */
+export declare class ImageResolver {
+    private readonly resolved;
+    private readonly pending;
+    private readonly failed;
+    private readonly client;
+    private readonly onImageResolved;
+    private readonly fetchUrl;
+    private readonly log?;
+    private readonly maxBytes;
+    private readonly cacheCap;
+    constructor(options: ImageResolverOptions);
+    resolveImages(text: string): string;
+    resolveImagesAwait(text: string, timeoutMs: number): Promise<string>;
+    hasPending(): boolean;
+    private startUpload;
+    private doUpload;
+    private markResolved;
+    private markFailed;
+}
+export { extractBufferFromFeishuResponse };

package/dist/card/markdown-style.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Markdown style optimizer for Feishu rendering.
+ *
+ * Adapted from openclaw-lark's `card/markdown-style.ts`. Goals:
+ * - Demote H1–H3 to H4–H5 so card headers don't dwarf the bot's reply
+ * - Pad tables and code blocks with `<br>` so they don't collide with surrounding paragraphs
+ * - Normalise list/cell spacing
+ * - Protect fenced code block content from any of the above edits
+ * - As a safety net, strip `![alt](non-image-key)` references that would
+ *   trigger CardKit error 200570 if a stray URL escapes the image resolver.
+ *
+ * The function is fail-safe: if any rewrite throws, it returns the original text.
+ */
+export declare function optimizeMarkdownStyle(text: string, cardVersion?: number): string;

package/dist/card/reasoning.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Reasoning text splitting for `<think>...</think>` / `<thinking>...</thinking>` /
+ * `<thought>...</thought>` blocks and the `Reasoning:\n_…_` prefix format.
+ *
+ * Mirrors openclaw-lark's `splitReasoningText` / `stripReasoningTags` so cards
+ * can render a separate reasoning area above the answer body.
+ */
+export interface ReasoningSplit {
+    reasoningText?: string;
+    answerText?: string;
+}
+export declare function splitReasoningText(text?: string): ReasoningSplit;
+export declare function stripReasoningTags(text: string): string;

package/dist/card/shutdown-hooks.d.ts

@@ -0,0 +1,15 @@
+type ShutdownHandler = () => Promise<void> | void;
+/**
+ * Register a shutdown handler. Returns a dispose function.
+ *
+ * Restriction: handlers MUST NOT call `registerShutdownHook` from inside
+ * their own execution during shutdown. New registrations made while
+ * `runAll` is in flight are silently dropped because `firing` blocks
+ * subsequent fire requests.
+ */
+export declare function registerShutdownHook(name: string, handler: ShutdownHandler): () => void;
+export declare function fireShutdownHooksForTests(opts?: {
+    perHandlerTimeoutMs?: number;
+}): Promise<void>;
+export declare function __resetShutdownHooksForTests(): void;
+export {};

package/dist/card/streaming-card-controller.d.ts

@@ -0,0 +1,196 @@
+import type { ToolUseEvent } from "./tool-use-types.js";
+export interface StreamingCardClient {
+    cardkit: {
+        v1: {
+            card: {
+                create(input: {
+                    data: {
+                        type: "card_json";
+                        data: string;
+                    };
+                }): Promise<{
+                    data?: {
+                        card_id?: string;
+                    };
+                }>;
+                update(input: {
+                    path: {
+                        card_id: string;
+                    };
+                    data: {
+                        card: {
+                            type: "card_json";
+                            data: string;
+                        };
+                        sequence: number;
+                    };
+                }): Promise<unknown>;
+            };
+            cardElement?: {
+                content(input: {
+                    path: {
+                        card_id: string;
+                        element_id: string;
+                    };
+                    data: {
+                        content: string;
+                        sequence: number;
+                    };
+                }): Promise<unknown>;
+            };
+        };
+    };
+    im: {
+        message: {
+            reply(input: {
+                path: {
+                    message_id: string;
+                };
+                data: {
+                    msg_type: "interactive";
+                    content: string;
+                };
+            }): Promise<{
+                data?: {
+                    message_id?: string;
+                    chat_id?: string;
+                };
+            }>;
+            create(input: {
+                params: {
+                    receive_id_type: "chat_id" | "open_id" | "user_id";
+                };
+                data: {
+                    receive_id: string;
+                    msg_type: "interactive";
+                    content: string;
+                };
+            }): Promise<{
+                data?: {
+                    message_id?: string;
+                    chat_id?: string;
+                };
+            }>;
+        };
+        image?: {
+            create(input: {
+                data: {
+                    image_type: "message";
+                    image: unknown;
+                };
+            }): Promise<unknown>;
+        };
+    };
+}
+export interface StreamingCardSeedInput {
+    to: string;
+    replyToMessageId?: string;
+}
+export interface StreamingCardSeedResult {
+    cardId: string;
+    messageId: string;
+}
+export interface StreamingCardControllerOptions {
+    client: StreamingCardClient;
+    flushIntervalMs?: number;
+    now?: () => number;
+    /** Set false to skip the markdown image-URL → image_key resolver. */
+    resolveImages?: boolean;
+    /** Max ms to wait for in-flight image uploads at terminal states. */
+    imageResolveTimeoutMs?: number;
+    /** Override HTTP fetch (used by the image resolver). Defaults to global fetch. */
+    fetchUrl?: (url: string, options?: {
+        maxBytes?: number;
+    }) => Promise<Buffer>;
+    /** Max bytes per uploaded image (forwarded to {@link ImageResolver}). */
+    imageMaxBytes?: number;
+    /** LRU cap for the image resolver's resolved/failed cache. */
+    imageCacheCap?: number;
+    /** Account scope for the message-unavailable cache. */
+    accountId?: string;
+    /**
+     * Called once when card updates have failed N consecutive times (default 3).
+     * Receives the latest text buffer so the channel can deliver the answer via
+     * a non-card path (plain reply) without losing the user's response.
+     * After firing, the controller still attempts further updates so a
+     * recovering Feishu can resume the card — but the channel should treat the
+     * answer as delivered out-of-band.
+     */
+    onCardDegraded?: (input: {
+        buffer: string;
+        consecutiveFailures: number;
+    }) => void;
+    /** Default 3. */
+    failureThreshold?: number;
+    /** Max chars for the card body before truncation; default 28000. */
+    cardBodyMaxChars?: number;
+    /** Interval for live elapsed-footer refresh while the card is non-terminal. Default 1000ms. */
+    liveFooterTickMs?: number;
+    setTimer?: (cb: () => void, delayMs: number) => unknown;
+    clearTimer?: (handle: unknown) => void;
+}
+export declare class StreamingCardController {
+    private readonly client;
+    private readonly flush;
+    private readonly now;
+    private readonly imageResolver;
+    private readonly imageResolveTimeoutMs;
+    private readonly accountId;
+    private readonly cardBodyMaxChars;
+    private cardId;
+    private messageId;
+    private streamedText;
+    private appendedFinal;
+    private sequence;
+    private state;
+    private lastPushedState;
+    private lastPushedReasoning;
+    private reasoningBuffer;
+    private reasoningStartedAt;
+    private reasoningLastAt;
+    private lastFooterText;
+    private readonly toolUseStore;
+    private lastPushedToolRevision;
+    private terminated;
+    private seededAtMs;
+    private degraded;
+    private disposeShutdownHook;
+    private terminalUpdateDelivered;
+    private readonly liveFooterTickMs;
+    private readonly setTimer;
+    private readonly clearTimer;
+    private liveFooterTimer;
+    private readonly onCardDegraded;
+    constructor(options: StreamingCardControllerOptions);
+    isTerminated(): boolean;
+    isDegraded(): boolean;
+    seed(input: StreamingCardSeedInput): Promise<StreamingCardSeedResult>;
+    appendStream(chunk: string): void;
+    recordToolEvent(event: ToolUseEvent): void;
+    appendReasoning(chunk: string): void;
+    complete(finalText?: string): Promise<void>;
+    abort(message?: string): Promise<void>;
+    private abortForShutdown;
+    fail(errorMessage: string): Promise<void>;
+    /**
+     * Compose the card body from the two-state text model. streamedText holds
+     * everything pushed during the turn; appendedFinal is the optional tail from
+     * complete(). When both are present we join with a blank line so the final
+     * tail visually separates from the progress.
+     */
+    private buildDisplayText;
+    /**
+     * Atomically advance the state machine. Returns false (no-op) when the
+     * transition isn't legal — protects against complete/abort/fail racing each
+     * other, and prevents stray appendStream calls from resurrecting a closed
+     * card. Sets terminal state synchronously so concurrent callers can't both
+     * pass through; the actual `terminated` flag flips after async work.
+     */
+    private transitionTo;
+    private markTerminalUpdateDelivered;
+    private scheduleLiveFooterTick;
+    private clearLiveFooterTick;
+    private awaitImageUploads;
+    waitIdle(): Promise<void>;
+    private pushUpdate;
+}

package/dist/card/tool-use-store.d.ts

@@ -0,0 +1,19 @@
+import type { ToolUseEvent, ToolUseStep } from "./tool-use-types.js";
+/**
+ * Per-controller accumulator for structured tool events. Each unique
+ * `toolCallId` gets a single ToolUseStep that is mutated as later events
+ * (start → update → end) for the same id arrive. Steps preserve
+ * insertion order so the rendered panel reads top-to-bottom in the
+ * order tools were invoked.
+ */
+export declare class ToolUseStore {
+    private readonly stepsById;
+    private readonly order;
+    private readonly now;
+    private revision;
+    constructor(now?: () => number);
+    record(event: ToolUseEvent): void;
+    steps(): ToolUseStep[];
+    isEmpty(): boolean;
+    getRevision(): number;
+}

package/dist/card/tool-use-types.d.ts

@@ -0,0 +1,11 @@
+import type { ToolUseEvent, ToolUseKind, ToolUseStatus } from "xacpx/plugin-api";
+export type { ToolUseEvent, ToolUseKind, ToolUseStatus };
+export interface ToolUseStep {
+    toolCallId: string;
+    toolName: string;
+    kind: ToolUseKind;
+    summary?: string;
+    status: ToolUseStatus;
+    startedAt: number;
+    durationMs?: number;
+}

package/dist/channel.d.ts

@@ -0,0 +1,65 @@
+import type { ChannelStartInput, CoordinatorMessageInput, CreateChannelDeps, ScheduledChannelMessageInput, MessageChannelRuntime, OrchestrationDeliveryCallbacks } from "xacpx/plugin-api";
+import type { FeishuResolvedAccountConfig } from "./config.js";
+import { type FeishuLarkClient } from "./lark-client.js";
+type OrchestrationTaskRecord = Parameters<MessageChannelRuntime["notifyTaskCompletion"]>[0];
+interface FeishuChannelDeps extends CreateChannelDeps {
+    createClient?: (account: FeishuResolvedAccountConfig) => FeishuLarkClient;
+}
+export declare class FeishuChannel implements MessageChannelRuntime {
+    private readonly deps;
+    readonly id = "feishu";
+    private readonly accounts;
+    private dedup;
+    private markDelivered;
+    private markFailed;
+    private agent;
+    private quota;
+    private logger;
+    private sessions;
+    private activeTurns;
+    private readonly executor;
+    private readonly activeTasks;
+    private readonly permissionNotifier;
+    private readonly config;
+    constructor(options: Record<string, unknown> | undefined, deps?: FeishuChannelDeps);
+    isLoggedIn(): boolean;
+    login(): Promise<string>;
+    logout(): void;
+    configureOrchestration(callbacks: OrchestrationDeliveryCallbacks): void;
+    start(input: ChannelStartInput): Promise<void>;
+    notifyTaskCompletion(task: OrchestrationTaskRecord): Promise<void>;
+    notifyTaskProgress(task: OrchestrationTaskRecord, text: string): Promise<void>;
+    sendCoordinatorMessage(input: CoordinatorMessageInput): Promise<void>;
+    sendScheduledMessage(input: ScheduledChannelMessageInput): Promise<void>;
+    private sendRouteText;
+    private handleMessageEvent;
+    /**
+     * Detect a stop-word inbound and short-circuit to the abort fast-path.
+     * Returns true if the message was handled as an abort (caller should
+     * stop processing), false if the message should continue down the
+     * normal handling path.
+     *
+     * Authorization:
+     * - In a group with `requireMention`, the abort word must be addressed
+     *   to the bot. Without this, anyone in the group can drop "stop" and
+     *   cancel another user's turn.
+     * - The sender must own at least one live task in this chat/thread —
+     *   you can only stop your own work.
+     */
+    private tryHandleAbortTrigger;
+    /**
+     * Pre-register the active task BEFORE the chat-queue body runs so an
+     * abort message arriving while the turn is queued can still find it and
+     * mark it suppressed.
+     */
+    private registerActiveTask;
+    private sendBackgroundCompletionNotice;
+    private runTurn;
+    private trySeedStreamingCard;
+    private deliverResponse;
+    private downloadInboundAttachments;
+    private handleAbortFastPath;
+    private sendReplyWithGuard;
+    private maybeNotifyPermissionError;
+}
+export {};

package/dist/chat-queue.d.ts

@@ -0,0 +1,12 @@
+export declare function buildFeishuQueueKey(accountId: string, chatId: string, threadId?: string): string;
+export declare function enqueueFeishuChatTask(input: {
+    accountId: string;
+    chatId: string;
+    threadId?: string;
+    task: () => Promise<void>;
+}): {
+    status: "queued" | "immediate";
+    promise: Promise<void>;
+};
+export declare function clearFeishuQueueForAccount(accountId: string): void;
+export declare function resetFeishuChatQueueForTests(): void;

package/dist/completion-notice.d.ts

@@ -0,0 +1 @@
+export declare function buildFeishuCompletionNotice(displayAlias: string, status: "done" | "error"): string;

package/dist/config.d.ts

@@ -0,0 +1,39 @@
+import { type FeishuTuning } from "./tuning.js";
+export type FeishuDmPolicy = "open" | "allowlist" | "disabled";
+export type FeishuGroupPolicy = "open" | "allowlist" | "disabled";
+export type FeishuReplyMode = "static" | "streaming" | "auto";
+export interface FeishuAccountConfig {
+    name?: string;
+    enabled?: boolean;
+    appId?: string;
+    appSecret?: string;
+    domain?: string;
+    requireMention?: boolean;
+    dmPolicy?: FeishuDmPolicy;
+    groupPolicy?: FeishuGroupPolicy;
+    allowFrom?: string[];
+    replyMode?: FeishuReplyMode;
+}
+export interface FeishuResolvedAccountConfig {
+    accountId: string;
+    name?: string;
+    enabled: boolean;
+    configured: boolean;
+    appId: string;
+    appSecret: string;
+    domain: string;
+    requireMention: boolean;
+    dmPolicy: FeishuDmPolicy;
+    groupPolicy: FeishuGroupPolicy;
+    allowFrom: string[];
+    replyMode: FeishuReplyMode;
+}
+export interface FeishuChannelConfig extends FeishuAccountConfig {
+    defaultAccount: string;
+    textMessageFormat: "text";
+    dedupTtlMs: number;
+    dedupMaxEntries: number;
+    accounts: FeishuResolvedAccountConfig[];
+    tuning: FeishuTuning;
+}
+export declare function parseFeishuChannelConfig(raw: unknown): FeishuChannelConfig;

package/dist/content-converters.d.ts

@@ -0,0 +1,11 @@
+import type { FeishuMessageEvent, FeishuContentConversionResult } from "./types";
+interface ConvertInput {
+    messageType: string;
+    content: string;
+    messageId: string;
+    mentions?: FeishuMessageEvent["message"]["mentions"];
+    botOpenId?: string;
+    stripBotMentions?: boolean;
+}
+export declare function convertFeishuMessageContent(input: ConvertInput): Promise<FeishuContentConversionResult>;
+export {};

package/dist/errors.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Shared Feishu/Lark error helpers.
+ *
+ * Centralizes the `{ code, msg, response: { data: { code, msg } } }` shape
+ * the @larksuiteoapi/node-sdk throws so domain modules (message-unavailable,
+ * permission-error, future rate-limit handling) all parse the envelope the
+ * same way. New error codes go in {@link FeishuErrorCode}.
+ */
+export declare const FeishuErrorCode: {
+    /** Message has been recalled. */
+    readonly MessageRecalled: 230011;
+    /** Message has been deleted. */
+    readonly MessageDeleted: 231003;
+    /** App is missing one or more required API scopes. */
+    readonly AppScopeMissing: 99991672;
+};
+export type FeishuErrorCodeValue = (typeof FeishuErrorCode)[keyof typeof FeishuErrorCode];
+export declare function isTerminalMessageApiCode(code: unknown): code is number;
+export declare function extractFeishuApiCode(error: unknown): number | undefined;
+export declare function extractFeishuMessage(error: unknown): string;