@larksuiteoapi/node-sdk 1.61.0 → 1.62.0

package/es/index.js

@@ -11,14 +11,19 @@
  */
 
 import axios, { AxiosError } from 'axios';
+import fs from 'fs';
+import path from 'path';
 import crypto from 'crypto';
 import { stringify } from 'qs';
 import identity from 'lodash.identity';
 import pickBy from 'lodash.pickby';
-import fs from 'fs';
 import merge from 'lodash.merge';
 import qs from 'querystring';
 import WebSocket from 'ws';
+import http from 'http';
+import https from 'https';
+import { promises } from 'dns';
+import { isIP } from 'net';
 
 /******************************************************************************
 Copyright (c) Microsoft Corporation.
@@ -98,10 +103,72 @@ typeof SuppressedError === "function" ? SuppressedError : function (error, suppr
     return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
 };
 
+/**
+ * Resolve the SDK's own version from `package.json`. The source lives at
+ * `utils/user-agent.ts`; the published bundle lives at `lib/index.js` or
+ * `es/index.js`. In both shapes the package.json sits exactly one level
+ * above the code, so `__dirname/..` is the primary candidate. A second
+ * candidate (two levels up) covers downstream bundlers that re-emit this
+ * module at a deeper path.
+ *
+ * We sanity-check `name === '@larksuiteoapi/node-sdk'` so we don't
+ * accidentally read an unrelated package.json that happens to sit in a
+ * parent directory during local development.
+ */
+let cachedVersion;
+function getSdkVersion() {
+    if (cachedVersion !== undefined)
+        return cachedVersion;
+    const candidates = [
+        path.resolve(__dirname, '..', 'package.json'),
+        path.resolve(__dirname, '..', '..', 'package.json'),
+    ];
+    for (const p of candidates) {
+        try {
+            const pkg = JSON.parse(fs.readFileSync(p, 'utf-8'));
+            if (pkg.name === '@larksuiteoapi/node-sdk' && typeof pkg.version === 'string') {
+                cachedVersion = pkg.version;
+                return pkg.version;
+            }
+        }
+        catch (_a) {
+            // try next candidate
+        }
+    }
+    cachedVersion = 'unknown';
+    return 'unknown';
+}
+/**
+ * Sanitize a caller-supplied `source` tag so it can be safely concatenated
+ * into a User-Agent header. Non-token characters are replaced with '_'
+ * and the result is clamped to 64 characters. Never throws.
+ */
+function sanitizeSource(raw) {
+    return raw.replace(/[^a-zA-Z0-9._-]/g, '_').slice(0, 64);
+}
+/**
+ * Build the User-Agent value. When `source` is provided it appends a
+ * `source/<sanitized>` product token, e.g.
+ *     oapi-node-sdk/1.62.0 source/cursor-bot
+ * Falsy or all-invalid-char `source` values produce the base UA without
+ * the extra token.
+ */
+function buildUserAgent(source) {
+    const base = `oapi-node-sdk/${getSdkVersion()}`;
+    if (!source)
+        return base;
+    const clean = sanitizeSource(source);
+    return clean ? `${base} source/${clean}` : base;
+}
+
 const defaultHttpInstance = axios.create();
+// Fallback UA for callers that bypass Client/WSClient and hit
+// `defaultHttpInstance` directly. Client.formatPayload overrides this with
+// a source-enriched UA when a `source` option is configured.
+const FALLBACK_UA = buildUserAgent();
 defaultHttpInstance.interceptors.request.use((req) => {
-    if (req.headers) {
-        req.headers['User-Agent'] = 'oapi-node-sdk/1.0.0';
+    if (req.headers && !req.headers['User-Agent']) {
+        req.headers['User-Agent'] = FALLBACK_UA;
     }
     return req;
 }, undefined, { synchronous: true });
@@ -83926,6 +83993,7 @@ class Client extends Client$1 {
         this.appId = params.appId;
         this.appSecret = params.appSecret;
         this.disableTokenCache = params.disableTokenCache;
+        this.userAgent = buildUserAgent(params.source);
         assert(!this.appId, () => this.logger.error('appId is needed'));
         assert(!this.appSecret, () => this.logger.error('appSecret is needed'));
         this.helpDeskId = params.helpDeskId;
@@ -83985,7 +84053,7 @@ class Client extends Client$1 {
             }
             return {
                 params: Object.assign(Object.assign({}, ((payload === null || payload === void 0 ? void 0 : payload.params) || {})), targetOptions.params),
-                headers: Object.assign(Object.assign({ 'User-Agent': 'oapi-node-sdk/1.0.0' }, ((payload === null || payload === void 0 ? void 0 : payload.headers) || {})), targetOptions.headers),
+                headers: Object.assign(Object.assign({ 'User-Agent': this.userAgent }, ((payload === null || payload === void 0 ? void 0 : payload.headers) || {})), targetOptions.headers),
                 data: Object.assign(Object.assign({}, ((payload === null || payload === void 0 ? void 0 : payload.data) || {})), targetOptions.data),
                 path: Object.assign(Object.assign({}, ((payload === null || payload === void 0 ? void 0 : payload.path) || {})), targetOptions.path),
             };
@@ -85291,7 +85359,11 @@ class WSClient {
             lastConnectTime: 0,
             nextConnectTime: 0,
         };
-        const { appId, appSecret, agent, domain = Domain.Feishu, httpInstance = defaultHttpInstance, loggerLevel = LoggerLevel.info, logger = defaultLogger, autoReconnect = true } = params;
+        /** True if the WS has ever connected successfully in this client's
+         *  lifetime — used to distinguish first-connect from reconnect. */
+        this.hasEverConnected = false;
+        const { appId, appSecret, agent, domain = Domain.Feishu, httpInstance = defaultHttpInstance, loggerLevel = LoggerLevel.info, logger = defaultLogger, autoReconnect = true, source, onReady, onError, onReconnecting, onReconnected, } = params;
+        this.userAgent = buildUserAgent(source);
         this.logger = new LoggerProxy(loggerLevel, logger);
         assert(!appId, () => this.logger.error('appId is needed'));
         assert(!appSecret, () => this.logger.error('appSecret is needed'));
@@ -85306,6 +85378,24 @@ class WSClient {
         this.wsConfig.updateWs({
             autoReconnect
         });
+        this.onReady = onReady;
+        this.onError = onError;
+        this.onReconnecting = onReconnecting;
+        this.onReconnected = onReconnected;
+    }
+    /**
+     * Invoke a user-supplied callback safely: no-op if undefined, swallow any
+     * exception to avoid breaking the WS state machine.
+     */
+    safeInvoke(label, fn, ...args) {
+        if (!fn)
+            return;
+        try {
+            fn(...args);
+        }
+        catch (e) {
+            this.logger.error(`[ws] ${label} callback threw`, e);
+        }
     }
     pullConnectConfig() {
         return __awaiter(this, void 0, void 0, function* () {
@@ -85321,6 +85411,7 @@ class WSClient {
                     // consumed by gateway
                     headers: {
                         "locale": "zh",
+                        "User-Agent": this.userAgent,
                     },
                     timeout: 15000,
                 });
@@ -85414,7 +85505,11 @@ class WSClient {
                 finally {
                     this.isConnecting = false;
                 }
-                if (!isSuccess) {
+                if (isSuccess) {
+                    this.hasEverConnected = true;
+                    this.safeInvoke('onReady', this.onReady);
+                }
+                else {
                     this.logger.error('[ws]', 'connect failed');
                     yield this.reConnect();
                 }
@@ -85423,9 +85518,15 @@ class WSClient {
             }
             const { autoReconnect, reconnectNonce, reconnectCount, reconnectInterval } = this.wsConfig.getWS();
             if (!autoReconnect) {
+                if (!this.hasEverConnected) {
+                    this.safeInvoke('onError', this.onError, new Error('WebSocket connect failed and autoReconnect is disabled'));
+                }
                 return;
             }
             this.logger.info('[ws]', 'reconnect');
+            if (this.hasEverConnected) {
+                this.safeInvoke('onReconnecting', this.onReconnecting);
+            }
             if (wsInstance) {
                 wsInstance === null || wsInstance === void 0 ? void 0 : wsInstance.terminate();
             }
@@ -85447,12 +85548,20 @@ class WSClient {
                         // if reconnectCount < 0, the reconnect time is infinite
                         if (isSuccess) {
                             this.logger.debug('[ws]', 'reconnect success');
+                            if (this.hasEverConnected) {
+                                this.safeInvoke('onReconnected', this.onReconnected);
+                            }
+                            else {
+                                this.hasEverConnected = true;
+                                this.safeInvoke('onReady', this.onReady);
+                            }
                             this.isConnecting = false;
                             return;
                         }
                         this.logger.info('ws', `unable to connect to the server after trying ${count} times")`);
                         if (reconnectCount >= 0 && count >= reconnectCount) {
                             this.isConnecting = false;
+                            this.safeInvoke('onError', this.onError, new Error(`WebSocket reconnect exhausted after ${count} attempts`));
                             return;
                         }
                         this.reconnectInterval = setTimeout(() => {
@@ -86029,13 +86138,13 @@ function registerApp(options) {
         qrCodeUrl.searchParams.set('tp', 'sdk');
         onQRCodeReady({
             url: qrCodeUrl.toString(),
-            expireIn: (_a = beginRes.expire_in) !== null && _a !== void 0 ? _a : 600,
+            expireIn: (_a = beginRes.expires_in) !== null && _a !== void 0 ? _a : 600,
         });
         return startPolling({
             baseUrl,
             deviceCode: beginRes.device_code,
             interval: ((_b = beginRes.interval) !== null && _b !== void 0 ? _b : 5) * 1000,
-            expireIn: ((_c = beginRes.expire_in) !== null && _c !== void 0 ? _c : 600) * 1000,
+            expireIn: ((_c = beginRes.expires_in) !== null && _c !== void 0 ? _c : 600) * 1000,
             larkBaseUrl: `https://${(_d = options.larkDomain) !== null && _d !== void 0 ? _d : DEFAULT_LARK_DOMAIN}`,
             signal,
             onStatusChange,
@@ -86043,4 +86152,3652 @@ function registerApp(options) {
     });
 }
 
-export { AESCipher, Aily, AppType, CAppTicket, CTenantAccessToken, CardActionHandler, Client, Domain, EventDispatcher, LoggerLevel, WSClient, adaptDefault, adaptExpress, adaptKoa, adaptKoaRouter, defaultHttpInstance, generateChallenge, messageCard, registerApp, withAll, withHelpDeskCredential, withTenantKey, withTenantToken, withUserAccessToken };
+class LarkChannelError extends Error {
+    constructor(code, message, opts) {
+        super(message);
+        this.name = 'LarkChannelError';
+        this.code = code;
+        this.cause = opts === null || opts === void 0 ? void 0 : opts.cause;
+        this.context = opts === null || opts === void 0 ? void 0 : opts.context;
+    }
+}
+
+/**
+ * Dual-threshold throttle: fires `flush` either when `ms` have elapsed
+ * since the last fire OR when `chars` characters have accumulated.
+ *
+ * Usage inside a stream controller:
+ *   const t = new Throttle({ ms: 100, chars: 50 }, () => doPatch(buffer));
+ *   await t.note(deltaLen);       // may or may not fire, schedule the rest
+ *   await t.flushNow();           // end-of-stream force flush
+ */
+class Throttle {
+    constructor(opts, fire) {
+        this.opts = opts;
+        this.fire = fire;
+        this.pendingChars = 0;
+        this.lastFireAt = 0;
+    }
+    /**
+     * Accumulate bytes and decide whether to fire now, schedule a timer,
+     * or do nothing (a fire is already scheduled).
+     */
+    note(deltaChars) {
+        this.pendingChars += deltaChars;
+        if (this.pendingChars >= this.opts.chars) {
+            this.fireSoon(0);
+            return;
+        }
+        if (!this.timer) {
+            const elapsed = Date.now() - this.lastFireAt;
+            const wait = Math.max(0, this.opts.ms - elapsed);
+            this.fireSoon(wait);
+        }
+    }
+    fireSoon(delay) {
+        if (this.timer)
+            clearTimeout(this.timer);
+        this.timer = setTimeout(() => {
+            this.timer = undefined;
+            void this.doFire();
+        }, delay);
+    }
+    /**
+     * Force-flush everything accumulated so far, including any content that
+     * arrived during an in-flight fire. Waits for the in-flight fire to
+     * complete, then fires once more to capture the final state — without
+     * this second fire, the last chunk of appended content would be missed
+     * (the in-flight fire captured a snapshot BEFORE those chunks arrived).
+     */
+    flushNow() {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (this.timer) {
+                clearTimeout(this.timer);
+                this.timer = undefined;
+            }
+            if (this.inFlight) {
+                yield this.inFlight;
+            }
+            yield this.doFire();
+        });
+    }
+    doFire() {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (this.inFlight) {
+                // Someone else is firing; schedule a follow-up so the latest
+                // accumulated chars get captured after the in-flight fire ends.
+                this.fireSoon(this.opts.ms);
+                return;
+            }
+            const p = (() => __awaiter(this, void 0, void 0, function* () {
+                this.pendingChars = 0;
+                this.lastFireAt = Date.now();
+                yield this.fire();
+            }))();
+            this.inFlight = p;
+            try {
+                yield p;
+            }
+            finally {
+                this.inFlight = undefined;
+            }
+        });
+    }
+    dispose() {
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = undefined;
+        }
+    }
+}
+
+/**
+ * A per-stream FIFO queue that serializes async updates, so that concurrent
+ * calls to `append()` / `update()` always result in PATCH operations
+ * happening in submission order.
+ */
+class UpdateQueue {
+    constructor() {
+        this.tail = Promise.resolve();
+    }
+    enqueue(task) {
+        const next = this.tail.then(task, task);
+        this.tail = next.then(() => undefined, () => undefined);
+        return next;
+    }
+    drain() {
+        return this.tail;
+    }
+}
+
+/**
+ * Merge a streaming text chunk into an accumulator, handling both "delta"
+ * and "accumulated" producers transparently.
+ *
+ * Rules:
+ * - If `next` starts with `prev`, it's an accumulated stream → use `next`
+ * - If `prev` starts with `next`, the stream rewound or overlapped → keep `prev`
+ * - Otherwise, find the longest overlap between `prev`'s tail and `next`'s
+ *   head, and concatenate
+ */
+function mergeStreamingText(prev, next) {
+    if (!prev)
+        return next;
+    if (!next)
+        return prev;
+    if (next.startsWith(prev))
+        return next;
+    if (prev.startsWith(next))
+        return prev;
+    const maxOverlap = Math.min(prev.length, next.length);
+    for (let len = maxOverlap; len > 0; len--) {
+        if (prev.endsWith(next.substring(0, len))) {
+            return prev + next.substring(len);
+        }
+    }
+    return prev + next;
+}
+
+const DEFAULT_THROTTLE_MS$1 = 100;
+const DEFAULT_THROTTLE_CHARS$1 = 50;
+const DEFAULT_INITIAL = 'Thinking...';
+const DEFAULT_EMPTY = '(no content)';
+const INITIAL_SUMMARY = '[Generating...]';
+const SUMMARY_MAX_CHARS = 50;
+const ERROR_FOOTER = '\n\n— _(Generation interrupted)_';
+const ELEMENT_ID = 'stream_md';
+/**
+ * Shorten a markdown content string into a single-line preview suitable for
+ * the card's `summary.content` — shown in chat lists / message previews.
+ */
+function truncateSummary(text, max = SUMMARY_MAX_CHARS) {
+    if (!text)
+        return '';
+    const cleaned = text.replace(/\s+/g, ' ').trim();
+    return cleaned.length <= max ? cleaned : cleaned.slice(0, max - 1) + '…';
+}
+/**
+ * Build the initial card JSON for a streaming markdown reply.
+ *
+ * `streaming_mode: true` tells Feishu client to render incremental updates
+ * (via the cardElement.content API) as a native typewriter animation.
+ *
+ * `print_strategy: 'fast'` means: when a new full-content update arrives,
+ * immediately show any already-buffered-but-not-yet-animated text, so the
+ * display doesn't lag behind the upstream token rate.
+ */
+function buildStreamingCard(initialText) {
+    return {
+        schema: '2.0',
+        config: {
+            streaming_mode: true,
+            summary: { content: INITIAL_SUMMARY },
+            streaming_config: {
+                print_frequency_ms: { default: 70 },
+                print_step: { default: 1 },
+                print_strategy: 'fast',
+            },
+        },
+        body: {
+            elements: [
+                {
+                    tag: 'markdown',
+                    element_id: ELEMENT_ID,
+                    content: initialText,
+                },
+            ],
+        },
+    };
+}
+/**
+ * Streaming markdown reply that uses Feishu's native typewriter effect
+ * (cardkit.v1.cardElement.content).
+ *
+ * Flow:
+ *   1. ensureStarted(): create a card instance with streaming_mode=true,
+ *      send it as an interactive message referencing the card_id.
+ *   2. append(chunk) / setContent(full): accumulate locally, throttle.
+ *   3. throttle fires: updateCardElementContent(content, sequence++)
+ *      Feishu client renders typewriter animation based on the diff.
+ *   4. completeTerminal(): drain queue + finishStreamingCard to disable
+ *      streaming_mode (removes the typing cursor).
+ *   5. producer throws → append ERROR_FOOTER + finish stream → rethrow.
+ *
+ * The controller keeps its public shape (`append / setContent / run /
+ * messageId`) — callers don't see the implementation change.
+ */
+class MarkdownStreamControllerImpl {
+    constructor(sender, to, idType, opts) {
+        var _a, _b;
+        this.sender = sender;
+        this.to = to;
+        this.idType = idType;
+        this.opts = opts;
+        this.content = '';
+        this._messageId = '';
+        this.cardId = '';
+        this.sequence = 0;
+        this.queue = new UpdateQueue();
+        this.started = false;
+        const cfg = this.sender.config;
+        this.throttle = new Throttle({
+            ms: (_a = cfg.streamThrottleMs) !== null && _a !== void 0 ? _a : DEFAULT_THROTTLE_MS$1,
+            chars: (_b = cfg.streamThrottleChars) !== null && _b !== void 0 ? _b : DEFAULT_THROTTLE_CHARS$1,
+        }, () => this.pushContent());
+    }
+    get messageId() {
+        return this._messageId;
+    }
+    append(chunk) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!chunk)
+                return;
+            yield this.ensureStarted();
+            this.content = mergeStreamingText(this.content, chunk);
+            this.throttle.note(chunk.length);
+        });
+    }
+    setContent(full) {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this.ensureStarted();
+            this.content = full !== null && full !== void 0 ? full : '';
+            this.throttle.note(Number.MAX_SAFE_INTEGER);
+        });
+    }
+    run(producer) {
+        return __awaiter(this, void 0, void 0, function* () {
+            // Eagerly send the placeholder card so `run()` always returns a real
+            // messageId, and so that failTerminal / completeTerminal have a card
+            // to PATCH even if the producer never appends anything.
+            yield this.ensureStarted();
+            try {
+                yield producer(this);
+            }
+            catch (e) {
+                yield this.failTerminal(e);
+                throw e;
+            }
+            yield this.completeTerminal();
+            return { messageId: this._messageId };
+        });
+    }
+    // ─── internals ─────────────────────────────────────────
+    ensureStarted() {
+        var _a;
+        return __awaiter(this, void 0, void 0, function* () {
+            if (this.started)
+                return;
+            this.started = true;
+            const initialText = (_a = this.sender.config.streamInitialText) !== null && _a !== void 0 ? _a : DEFAULT_INITIAL;
+            const cardSpec = buildStreamingCard(initialText || '...');
+            this.cardId = yield this.sender.createCardInstance(cardSpec);
+            this._messageId = yield this.sender.sendCardByReference(this.to, this.idType, this.cardId, this.opts);
+        });
+    }
+    pushContent() {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!this.cardId)
+                return;
+            const snapshot = this.content || '...';
+            const seq = ++this.sequence;
+            yield this.queue.enqueue(() => __awaiter(this, void 0, void 0, function* () {
+                yield this.sender.updateCardElementContent(this.cardId, ELEMENT_ID, snapshot, seq);
+            }));
+        });
+    }
+    completeTerminal() {
+        var _a, _b;
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this.throttle.flushNow();
+            yield this.queue.drain();
+            if (!this.cardId)
+                return;
+            // If the producer never appended anything, PATCH the card to a
+            // neutral terminal state so the user sees the response is finalized
+            // rather than a stuck "Thinking..." placeholder.
+            if (!this.content) {
+                const seq = ++this.sequence;
+                yield this.queue.enqueue(() => __awaiter(this, void 0, void 0, function* () {
+                    try {
+                        yield this.sender.updateCardElementContent(this.cardId, ELEMENT_ID, DEFAULT_EMPTY, seq);
+                    }
+                    catch (_c) {
+                        // best effort
+                    }
+                }));
+                yield this.queue.drain();
+            }
+            try {
+                yield this.sender.finishStreamingCard(this.cardId, ++this.sequence, truncateSummary(this.content || DEFAULT_EMPTY));
+            }
+            catch (e) {
+                // best effort — Feishu auto-closes after 10min anyway
+                (_b = (_a = this.sender.logger).warn) === null || _b === void 0 ? void 0 : _b.call(_a, '[stream] finishStreamingCard failed', e);
+            }
+        });
+    }
+    failTerminal(_err) {
+        return __awaiter(this, void 0, void 0, function* () {
+            this.throttle.dispose();
+            if (!this.cardId)
+                return;
+            this.content = (this.content || '') + ERROR_FOOTER;
+            const seq = ++this.sequence;
+            yield this.queue.enqueue(() => __awaiter(this, void 0, void 0, function* () {
+                try {
+                    yield this.sender.updateCardElementContent(this.cardId, ELEMENT_ID, this.content, seq);
+                }
+                catch (_b) {
+                    // best effort
+                }
+            }));
+            yield this.queue.drain();
+            try {
+                yield this.sender.finishStreamingCard(this.cardId, ++this.sequence, truncateSummary(this.content));
+            }
+            catch (_a) {
+                // best effort
+            }
+        });
+    }
+}
+class MarkdownStreamController {
+    constructor(sender, to, idType, opts) {
+        this.impl = new MarkdownStreamControllerImpl(sender, to, idType, opts);
+    }
+    run(producer) {
+        return this.impl.run(producer);
+    }
+}
+
+const DEFAULT_THROTTLE_MS = 100;
+const DEFAULT_THROTTLE_CHARS = 50;
+/**
+ * Streaming card reply — the caller provides an initial card JSON and a
+ * producer that drives incremental `update()` calls with full or partial
+ * new card state.
+ *
+ * Updates are throttled + serialized. On producer exception, the last
+ * known state is kept and an error footer element is appended.
+ */
+class CardStreamControllerImpl {
+    constructor(sender, to, idType, opts, initial) {
+        var _a, _b;
+        this.sender = sender;
+        this.to = to;
+        this.idType = idType;
+        this.opts = opts;
+        this._messageId = '';
+        this.queue = new UpdateQueue();
+        this._current = initial;
+        const cfg = sender.config;
+        this.throttle = new Throttle({
+            ms: (_a = cfg.streamThrottleMs) !== null && _a !== void 0 ? _a : DEFAULT_THROTTLE_MS,
+            chars: (_b = cfg.streamThrottleChars) !== null && _b !== void 0 ? _b : DEFAULT_THROTTLE_CHARS,
+        }, () => this.patch());
+    }
+    get messageId() {
+        return this._messageId;
+    }
+    get current() {
+        return this._current;
+    }
+    update(next) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const nextCard = typeof next === 'function' ? next(this._current) : next;
+            this._current = nextCard;
+            this.throttle.note(JSON.stringify(nextCard).length);
+        });
+    }
+    run(producer) {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this.sendInitial();
+            try {
+                yield producer(this);
+            }
+            catch (e) {
+                yield this.failTerminal(e);
+                throw e;
+            }
+            yield this.completeTerminal();
+            return { messageId: this._messageId };
+        });
+    }
+    // ─── internals ─────────────────────────────────────────
+    sendInitial() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const id = yield this.sender.sendOneWithFallback({
+                to: this.to,
+                idType: this.idType,
+                msgType: 'interactive',
+                content: this._current,
+                replyTo: this.opts.replyTo,
+                replyInThread: this.opts.replyInThread,
+            });
+            this._messageId = id;
+        });
+    }
+    patch() {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!this._messageId)
+                return;
+            const snapshot = this._current;
+            yield this.queue.enqueue(() => __awaiter(this, void 0, void 0, function* () {
+                yield this.sender.patchCard(this._messageId, snapshot);
+            }));
+        });
+    }
+    completeTerminal() {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this.throttle.flushNow();
+            yield this.queue.drain();
+        });
+    }
+    failTerminal(_err) {
+        return __awaiter(this, void 0, void 0, function* () {
+            this.throttle.dispose();
+            const withFooter = appendErrorFooter(this._current);
+            yield this.queue.enqueue(() => __awaiter(this, void 0, void 0, function* () {
+                try {
+                    yield this.sender.patchCard(this._messageId, withFooter);
+                }
+                catch (_a) {
+                    // best effort
+                }
+            }));
+            yield this.queue.drain();
+        });
+    }
+}
+function appendErrorFooter(card) {
+    const cardObj = card;
+    const elements = Array.isArray(cardObj === null || cardObj === void 0 ? void 0 : cardObj.elements) ? [...cardObj.elements] : [];
+    elements.push({
+        tag: 'note',
+        elements: [{ tag: 'plain_text', content: '⚠️ 生成中断' }],
+    });
+    return Object.assign(Object.assign({}, card), { elements });
+}
+class CardStreamController {
+    constructor(sender, to, idType, opts, initial) {
+        this.impl = new CardStreamControllerImpl(sender, to, idType, opts, initial);
+    }
+    run(producer) {
+        return this.impl.run(producer);
+    }
+}
+
+/**
+ * Parse Opus/OGG audio duration (ms) from a buffer.
+ *
+ * Scans backward for the last "OggS" page capture pattern (0x4f676753) and
+ * reads its granule_position (64-bit LE at offset +6 from magic). For Opus,
+ * granule_position is the number of decoded samples at 48 kHz — divide by
+ * 48 (samples per ms) to get milliseconds.
+ *
+ * Returns undefined if the buffer doesn't contain a valid Ogg stream or if
+ * the granule position is obviously invalid.
+ */
+function parseOpusDuration(buf) {
+    if (!buf || buf.length < 27)
+        return undefined;
+    for (let i = buf.length - 27; i >= 0; i--) {
+        // "OggS" = 0x4f 67 67 53
+        if (buf[i] === 0x4f &&
+            buf[i + 1] === 0x67 &&
+            buf[i + 2] === 0x67 &&
+            buf[i + 3] === 0x53) {
+            const granule = buf.readBigInt64LE(i + 6);
+            if (granule < BigInt(0))
+                return undefined;
+            const ms = Number(granule) / 48;
+            if (!Number.isFinite(ms) || ms < 0)
+                return undefined;
+            return Math.round(ms);
+        }
+    }
+    return undefined;
+}
+
+/**
+ * Parse MP4 video duration (ms) from a buffer by walking the ISO BMFF box
+ * hierarchy and finding `moov → mvhd`.
+ *
+ * The `mvhd` box version determines field widths:
+ * - version 0: creation/modification/timescale/duration = 4 bytes each
+ * - version 1: creation/modification = 8 bytes, timescale = 4 bytes,
+ *              duration = 8 bytes
+ *
+ * Returns undefined if the stream is not parseable or duration is unknown.
+ */
+function parseMp4Duration(buf) {
+    if (!buf || buf.length < 16)
+        return undefined;
+    const moov = findBoxPayload(buf, 0, buf.length, 'moov');
+    if (!moov)
+        return undefined;
+    const mvhd = findBoxPayload(buf, moov.start, moov.end, 'mvhd');
+    if (!mvhd)
+        return undefined;
+    const p = mvhd.start;
+    if (p + 4 > buf.length)
+        return undefined;
+    const version = buf.readUInt8(p);
+    // skip flags (3 bytes)
+    const base = p + 4;
+    let timescale;
+    let duration;
+    if (version === 1) {
+        // creation(8) + modification(8) + timescale(4) + duration(8)
+        if (base + 28 > buf.length)
+            return undefined;
+        timescale = buf.readUInt32BE(base + 16);
+        duration = Number(buf.readBigUInt64BE(base + 20));
+    }
+    else {
+        // creation(4) + modification(4) + timescale(4) + duration(4)
+        if (base + 16 > buf.length)
+            return undefined;
+        timescale = buf.readUInt32BE(base + 8);
+        duration = buf.readUInt32BE(base + 12);
+    }
+    if (!timescale || !Number.isFinite(timescale) || !Number.isFinite(duration)) {
+        return undefined;
+    }
+    return Math.round((duration / timescale) * 1000);
+}
+/**
+ * Walk the boxes from [begin, end) looking for one whose type matches
+ * `name`. Returns the payload range (excluding the 8-byte header).
+ */
+function findBoxPayload(buf, begin, end, name) {
+    let p = begin;
+    while (p + 8 <= end && p + 8 <= buf.length) {
+        const size = buf.readUInt32BE(p);
+        const type = buf.slice(p + 4, p + 8).toString('ascii');
+        const boxEnd = size === 1
+            ? p + Number(buf.readBigUInt64BE(p + 8))
+            : size === 0
+                ? end // box extends to end-of-file
+                : p + size;
+        if (boxEnd <= p || boxEnd > end)
+            return undefined;
+        if (type === name) {
+            const payloadStart = size === 1 ? p + 16 : p + 8;
+            return { start: payloadStart, end: boxEnd };
+        }
+        p = boxEnd;
+    }
+    return undefined;
+}
+
+/**
+ * CIDR blocks that must not be reached from a URL fetch triggered by the
+ * SDK. Covers loopback, link-local, private ranges, CGNAT, documentation.
+ */
+const BLOCKED_V4 = [
+    [0x00000000, 8],
+    [0x0a000000, 8],
+    [0x7f000000, 8],
+    [0xa9fe0000, 16],
+    [0xac100000, 12],
+    [0xc0a80000, 16],
+    [0x64400000, 10],
+    [0xc0000000, 24],
+    [0xc0000200, 24],
+    [0xc6120000, 15],
+    [0xc6336400, 24],
+    [0xcb007100, 24],
+    [0xe0000000, 4],
+    [0xf0000000, 4], // 240.0.0.0/4 (reserved)
+];
+/**
+ * Validate that `url` does not resolve to an internal / reserved IP, and
+ * return the single IP that downstream fetching should pin to. Pinning is
+ * essential to close the DNS-rebinding TOCTOU gap: the attacker's DNS
+ * server could otherwise return a public IP to this check and a private
+ * IP (e.g. cloud metadata `169.254.169.254`) to the subsequent fetch.
+ *
+ * Allowlisted hostnames skip the public-IP check but still pin — pinning
+ * is only about consistency between check-time and use-time, and is
+ * harmless when the caller trusts the host.
+ */
+function assertPublicUrl(url, opts = {}) {
+    var _a, _b;
+    return __awaiter(this, void 0, void 0, function* () {
+        const u = new URL(url);
+        if (u.protocol !== 'http:' && u.protocol !== 'https:') {
+            throw new Error(`ssrf_blocked: protocol ${u.protocol}`);
+        }
+        // URL keeps IPv6 literals wrapped in brackets (`[::1]`) — strip them so
+        // `isIP()` recognizes the literal and we don't fall through to DNS.
+        const rawHost = u.hostname;
+        const host = rawHost.startsWith('[') && rawHost.endsWith(']')
+            ? rawHost.slice(1, -1)
+            : rawHost;
+        const allowlisted = (_b = (_a = opts.allowlist) === null || _a === void 0 ? void 0 : _a.includes(host)) !== null && _b !== void 0 ? _b : false;
+        let resolvedIp;
+        if (isIP(host)) {
+            resolvedIp = host;
+            if (!allowlisted)
+                assertIpPublic(resolvedIp);
+        }
+        else {
+            const records = yield promises.lookup(host, { all: true });
+            if (records.length === 0) {
+                throw new Error(`ssrf_blocked: no DNS records for ${host}`);
+            }
+            if (!allowlisted) {
+                // Reject if ANY record is private — we can't trust DNS
+                // round-robin to "win the lottery" and only return public IPs.
+                for (const r of records)
+                    assertIpPublic(r.address);
+            }
+            resolvedIp = records[0].address;
+        }
+        return { resolvedIp, originalHost: host };
+    });
+}
+function assertIpPublic(ip) {
+    const v = isIP(ip);
+    if (v === 4 && ipv4Blocked(ip)) {
+        throw new Error(`ssrf_blocked: ${ip}`);
+    }
+    if (v === 6 && ipv6Blocked(ip)) {
+        throw new Error(`ssrf_blocked: ${ip}`);
+    }
+    if (v === 0) {
+        throw new Error(`ssrf_blocked: not a valid IP: ${ip}`);
+    }
+}
+function ipv4Blocked(ip) {
+    const parts = ip.split('.').map(Number);
+    if (parts.length !== 4 || parts.some((p) => p < 0 || p > 255))
+        return true;
+    const n = ((parts[0] << 24) | (parts[1] << 16) | (parts[2] << 8) | parts[3]) >>> 0;
+    return BLOCKED_V4.some(([net, bits]) => {
+        const mask = bits === 0 ? 0 : ((-1) << (32 - bits)) >>> 0;
+        return (n & mask) === (net & mask);
+    });
+}
+/**
+ * Hardcoded IPv6 CIDR blocks rejected outright (not delegated to v4).
+ * Each tuple is [network address as 128-bit bigint, prefix length].
+ *
+ * Note: `BigInt('0x...')` is used (instead of `0x...n` literals) so the
+ * code compiles under TypeScript `target: es6` — bigint literals need
+ * es2020. Semantically identical.
+ */
+const BLOCKED_V6 = [
+    [BigInt('0xfe800000000000000000000000000000'), 10],
+    [BigInt('0xfc000000000000000000000000000000'), 7],
+    [BigInt('0xff000000000000000000000000000000'), 8],
+    [BigInt('0x01000000000000000000000000000000'), 64],
+    [BigInt('0x20010db8000000000000000000000000'), 32],
+    [BigInt('0x20010000000000000000000000000000'), 32], // 2001::/32      Teredo
+];
+// Top-96-bit prefixes that identify "an IPv4 address carried inside IPv6".
+// When these match, the low 32 bits are the actual IPv4 and we delegate
+// the decision to `ipv4Blocked` — so e.g. NAT64 around a public IPv4
+// passes, NAT64 around a private IPv4 is rejected.
+const HIGH96_MASK = BigInt('0xffffffffffffffffffffffff00000000');
+const PREFIX_V4_MAPPED = BigInt('0x00000000000000000000ffff00000000'); // ::ffff:0:0/96
+const PREFIX_V4_COMPAT = BigInt(0); // ::/96
+const PREFIX_NAT64 = BigInt('0x0064ff9b000000000000000000000000'); // 64:ff9b::/96
+const LOW32_MASK = BigInt('0xffffffff');
+function ipv6Blocked(ip) {
+    let n;
+    try {
+        n = parseIPv6(ip);
+    }
+    catch (_a) {
+        // Unparseable — fail-closed: treat as internal / suspicious.
+        return true;
+    }
+    // If the address carries an IPv4 in its low 32 bits, check that IPv4.
+    const high96 = n & HIGH96_MASK;
+    if (high96 === PREFIX_V4_MAPPED ||
+        high96 === PREFIX_NAT64 ||
+        high96 === PREFIX_V4_COMPAT) {
+        const v4 = Number(n & LOW32_MASK);
+        const v4Str = [
+            (v4 >>> 24) & 0xff,
+            (v4 >>> 16) & 0xff,
+            (v4 >>> 8) & 0xff,
+            v4 & 0xff,
+        ].join('.');
+        return ipv4Blocked(v4Str);
+    }
+    // Standalone blocked CIDRs via numeric comparison — handles all
+    // equivalent string representations (compressed, expanded, mixed).
+    return BLOCKED_V6.some(([net, bits]) => {
+        const shift = BigInt(128 - bits);
+        const allOnes = (BigInt(1) << BigInt(128)) - BigInt(1);
+        const mask = (allOnes >> shift) << shift;
+        return (n & mask) === (net & mask);
+    });
+}
+/**
+ * Parse any representation of an IPv6 address into a 128-bit bigint.
+ * Handles:
+ *   - `::` compression (`::1`, `fe80::1`, `::`)
+ *   - fully expanded form (`0:0:0:0:0:0:0:1`)
+ *   - IPv4-in-IPv6 mixed notation (`::ffff:127.0.0.1`, `64:ff9b::10.0.0.1`)
+ *   - Zone ID suffix (`fe80::1%eth0` — the suffix is ignored)
+ * Throws on any malformed input; the caller treats a throw as
+ * fail-closed.
+ */
+function parseIPv6(ip) {
+    let addr = ip.split('%')[0].toLowerCase(); // strip Zone ID
+    // Convert IPv4 suffix (dotted decimal) to two 16-bit hex groups so the
+    // rest of the parser only sees hex groups.
+    const v4Suffix = addr.match(/:(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/);
+    if (v4Suffix) {
+        const parts = v4Suffix[1].split('.').map(Number);
+        if (parts.length !== 4 || parts.some((p) => !Number.isFinite(p) || p < 0 || p > 255)) {
+            throw new Error('bad v4 suffix');
+        }
+        const hex1 = ((parts[0] << 8) | parts[1]).toString(16);
+        const hex2 = ((parts[2] << 8) | parts[3]).toString(16);
+        addr = addr.slice(0, addr.length - v4Suffix[1].length) + `${hex1}:${hex2}`;
+    }
+    // Expand `::`.
+    const halves = addr.split('::');
+    if (halves.length > 2)
+        throw new Error('multiple "::"');
+    let groups;
+    if (halves.length === 2) {
+        const left = halves[0] ? halves[0].split(':') : [];
+        const right = halves[1] ? halves[1].split(':') : [];
+        const fill = 8 - left.length - right.length;
+        if (fill < 0)
+            throw new Error('too many groups');
+        groups = [...left, ...Array(fill).fill('0'), ...right];
+    }
+    else {
+        groups = addr.split(':');
+    }
+    if (groups.length !== 8)
+        throw new Error('wrong group count');
+    let n = BigInt(0);
+    for (const g of groups) {
+        if (!/^[0-9a-f]{0,4}$/.test(g))
+            throw new Error('bad group');
+        n = (n << BigInt(16)) | BigInt(`0x${g || '0'}`);
+    }
+    return n;
+}
+
+/**
+ * POSIX directory prefixes that can never be a legitimate media source.
+ * Skipped on Windows (no equivalent single-prefix set exists there; a
+ * downstream allowlist is the right tool for Windows deployments).
+ */
+const POSIX_BLOCKED_PREFIXES = ['/etc/', '/proc/', '/sys/', '/dev/'];
+/** Max bytes accepted from a URL-based media source. Protects against
+ *  memory DoS when a malicious URL tries to return gigabytes. */
+const URL_MAX_BYTES = 50 * 1024 * 1024;
+class MediaUploader {
+    constructor(client, config) {
+        this.client = client;
+        this.config = config;
+    }
+    upload(input) {
+        var _a, _b, _c;
+        return __awaiter(this, void 0, void 0, function* () {
+            const buffer = yield this.toBuffer(input.source);
+            if (input.kind === 'image') {
+                return this.uploadImage(buffer);
+            }
+            if (input.kind === 'audio') {
+                const duration = this.resolveDuration(input, buffer);
+                return this.uploadFile(buffer, 'opus', (_a = input.fileName) !== null && _a !== void 0 ? _a : 'voice.opus', duration);
+            }
+            if (input.kind === 'video') {
+                const duration = this.resolveDuration(input, buffer);
+                return this.uploadFile(buffer, 'mp4', (_b = input.fileName) !== null && _b !== void 0 ? _b : 'video.mp4', duration);
+            }
+            // generic file — no duration required
+            return this.uploadFile(buffer, 'stream', (_c = input.fileName) !== null && _c !== void 0 ? _c : 'upload.bin');
+        });
+    }
+    /**
+     * Materialize `source` into a Buffer. A string is treated as:
+     *   • `http://` / `https://` URL — fetch with SSRF guard
+     *   • anything else — local filesystem path, read directly
+     */
+    toBuffer(source) {
+        var _a, _b;
+        return __awaiter(this, void 0, void 0, function* () {
+            if (Buffer.isBuffer(source))
+                return source;
+            if (!/^https?:\/\//i.test(source)) {
+                const allowedDirs = (_a = this.config) === null || _a === void 0 ? void 0 : _a.allowedFileDirs;
+                const resolved = path.resolve(source);
+                // Pre-I/O POSIX blocklist check: catches `/etc/passwd` etc.
+                // before touching the filesystem. Path-traversal variants like
+                // `/tmp/../etc/passwd` are collapsed by `path.resolve`.
+                this.assertNotOnPosixBlocklist(resolved);
+                try {
+                    // Follow symlinks so that:
+                    //   • a symlink inside an allowed dir pointing outside
+                    //     is caught (allowlist containment is on real target);
+                    //   • macOS `/etc` → `/private/etc` alias is also blocked.
+                    const realPath = yield fs.promises.realpath(resolved);
+                    this.assertNotOnPosixBlocklist(realPath);
+                    if (allowedDirs && allowedDirs.length > 0) {
+                        // Realpath the allowed dirs too — otherwise macOS
+                        // `/var` → `/private/var` alias would reject all
+                        // tmpdir-based paths.
+                        const canonicalDirs = yield Promise.all(allowedDirs.map((d) => __awaiter(this, void 0, void 0, function* () {
+                            const r = path.resolve(d);
+                            try {
+                                return yield fs.promises.realpath(r);
+                            }
+                            catch (_c) {
+                                return r;
+                            }
+                        })));
+                        const inAllowed = canonicalDirs.some((d) => realPath === d || realPath.startsWith(d + path.sep));
+                        if (!inAllowed) {
+                            throw new LarkChannelError('upload_failed', `file path is outside allowed directories: ${realPath}`);
+                        }
+                    }
+                    return yield fs.promises.readFile(realPath);
+                }
+                catch (e) {
+                    if (e instanceof LarkChannelError)
+                        throw e;
+                    throw new LarkChannelError('upload_failed', `source is neither an http(s) URL nor a readable local file: ${source}`, { cause: e });
+                }
+            }
+            const ssrf = (_b = this.config) === null || _b === void 0 ? void 0 : _b.ssrfGuard;
+            const guardEnabled = ssrf !== false;
+            let resolvedIp;
+            if (guardEnabled) {
+                const ssrfOpts = typeof ssrf === 'object' && ssrf ? { allowlist: ssrf.allowlist } : {};
+                try {
+                    ({ resolvedIp } = yield assertPublicUrl(source, ssrfOpts));
+                }
+                catch (e) {
+                    throw new LarkChannelError('ssrf_blocked', `URL blocked: ${String(e)}`, {
+                        cause: e,
+                    });
+                }
+            }
+            try {
+                // Pin the TCP connect target to the IP we just validated so the
+                // attacker can't swap in a private IP between the DNS check and
+                // the fetch (DNS rebinding / TOCTOU). We inject a custom `lookup`
+                // into a per-request agent; the URL itself stays intact so TLS
+                // SNI and certificate verification continue to use the original
+                // hostname.
+                const requestOpts = {
+                    url: source,
+                    method: 'GET',
+                    responseType: 'arraybuffer',
+                    timeout: 15000,
+                    maxContentLength: URL_MAX_BYTES,
+                    maxBodyLength: URL_MAX_BYTES,
+                };
+                if (resolvedIp) {
+                    const agent = makePinnedAgent(source, resolvedIp);
+                    requestOpts.httpAgent = agent;
+                    requestOpts.httpsAgent = agent;
+                }
+                const res = yield this.client.httpInstance.request(requestOpts);
+                return Buffer.from(res);
+            }
+            catch (e) {
+                throw new LarkChannelError('upload_failed', `fetch source URL failed`, {
+                    cause: e,
+                });
+            }
+        });
+    }
+    /**
+     * Reject paths pointing at POSIX system directories (`/etc`, `/proc`,
+     * `/sys`, `/dev`). Called twice by the caller — once on the resolved
+     * path pre-I/O, again on the realpath — so both direct hits
+     * (`/etc/passwd`) and macOS alias hits (`/etc` → `/private/etc`) are
+     * caught.
+     */
+    assertNotOnPosixBlocklist(p) {
+        if (process.platform === 'win32')
+            return;
+        if (POSIX_BLOCKED_PREFIXES.some((pre) => p === pre.slice(0, -1) || p.startsWith(pre))) {
+            throw new LarkChannelError('upload_failed', `file path is not allowed: ${p}`);
+        }
+    }
+    resolveDuration(input, buffer) {
+        if (input.duration != null && input.duration > 0)
+            return input.duration;
+        const parsed = input.kind === 'audio'
+            ? parseOpusDuration(buffer)
+            : input.kind === 'video'
+                ? parseMp4Duration(buffer)
+                : undefined;
+        if (parsed != null)
+            return parsed;
+        throw new LarkChannelError('upload_failed', `duration could not be determined for ${input.kind}; pass it explicitly`);
+    }
+    uploadImage(buffer) {
+        var _a, _b;
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                const r = yield this.client.im.v1.image.create({
+                    data: { image_type: 'message', image: buffer },
+                });
+                // The code-gen client already strips the outer envelope and returns
+                // `res?.data` directly, so `image_key` sits at the top level. Keep
+                // the nested `.data.image_key` path as a defensive fallback in case
+                // a caller plugs in a different HttpInstance that preserves the
+                // envelope.
+                const key = (_a = r === null || r === void 0 ? void 0 : r.image_key) !== null && _a !== void 0 ? _a : (_b = r === null || r === void 0 ? void 0 : r.data) === null || _b === void 0 ? void 0 : _b.image_key;
+                if (!key)
+                    throw new Error('image_key missing in upload response');
+                return { kind: 'image', fileKey: key };
+            }
+            catch (e) {
+                throw new LarkChannelError('upload_failed', `image upload failed`, {
+                    cause: e,
+                });
+            }
+        });
+    }
+    uploadFile(buffer, fileType, fileName, durationMs) {
+        var _a, _b;
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                const data = {
+                    file_type: fileType,
+                    file_name: fileName,
+                    file: buffer,
+                };
+                if (durationMs != null)
+                    data.duration = durationMs;
+                const r = yield this.client.im.v1.file.create({
+                    data: data,
+                });
+                const key = (_a = r === null || r === void 0 ? void 0 : r.file_key) !== null && _a !== void 0 ? _a : (_b = r === null || r === void 0 ? void 0 : r.data) === null || _b === void 0 ? void 0 : _b.file_key;
+                if (!key)
+                    throw new Error('file_key missing in upload response');
+                const kind = fileType === 'opus' ? 'audio' : fileType === 'mp4' ? 'video' : 'file';
+                return { kind, fileKey: key, durationMs };
+            }
+            catch (e) {
+                if (e instanceof LarkChannelError)
+                    throw e;
+                throw new LarkChannelError('upload_failed', `file upload failed`, {
+                    cause: e,
+                });
+            }
+        });
+    }
+}
+/**
+ * Build a per-request http(s) Agent whose DNS lookup always returns
+ * `pinnedIp`, regardless of what hostname Node would otherwise resolve.
+ * The URL's original hostname is preserved on the wire, which keeps TLS
+ * SNI and certificate verification working. This closes the window where
+ * a malicious DNS server could return a different (private) IP on the
+ * second resolution triggered by the actual fetch.
+ */
+function makePinnedAgent(url, pinnedIp) {
+    const AgentClass = url.startsWith('https:') ? https.Agent : http.Agent;
+    const agent = new AgentClass();
+    const family = pinnedIp.includes(':') ? 6 : 4;
+    const lookup = (_hostname, _opts, cb) => {
+        cb(null, pinnedIp, family);
+    };
+    // Node's Agent doesn't accept `lookup` in its constructor options, so we
+    // wrap `createConnection` to fold `lookup` into every outgoing socket.
+    const origCreateConnection = agent.createConnection.bind(agent);
+    agent.createConnection = (opts, cb) => origCreateConnection(Object.assign(Object.assign({}, opts), { lookup }), cb);
+    return agent;
+}
+
+/**
+ * Build a text prefix that renders as real Feishu mentions when prepended
+ * to a text-type outbound message (the <at …> tag form).
+ *
+ * For post-type messages, the mentions should be injected as `at` elements
+ * at the beginning of the post body — use `composePostMentionElements`
+ * instead.
+ */
+function composeMentionsTextPrefix(mentions) {
+    var _a;
+    if (!(mentions === null || mentions === void 0 ? void 0 : mentions.length))
+        return '';
+    const parts = [];
+    for (const m of mentions) {
+        if (!m.openId)
+            continue;
+        const name = (_a = m.name) !== null && _a !== void 0 ? _a : '';
+        parts.push(`<at user_id="${m.openId}">${name}</at>`);
+    }
+    return parts.length > 0 ? parts.join(' ') + ' ' : '';
+}
+/**
+ * Produce `at` elements to prepend to the first paragraph of a post body.
+ */
+function composePostMentionElements(mentions) {
+    if (!(mentions === null || mentions === void 0 ? void 0 : mentions.length))
+        return [];
+    const out = [];
+    for (const m of mentions) {
+        if (!m.openId)
+            continue;
+        out.push({ tag: 'at', user_id: m.openId, user_name: m.name });
+    }
+    return out;
+}
+
+/**
+ * Convert a Markdown string to Feishu post JSON.
+ *
+ * Coverage (the subset Agent frameworks realistically produce):
+ *   - Headings (rendered as bold text; Feishu post has no heading element)
+ *   - Paragraphs with inline **bold**, *italic*, `code`, [text](url)
+ *   - Fenced code blocks (```lang\n...\n```)
+ *   - Hard rules (---)
+ *   - Unordered / ordered list items (rendered as plain text with bullets)
+ *   - Blockquotes (rendered as "> " prefix preserved)
+ *
+ * Returns a post body keyed by `zh_cn` (Feishu's default locale).
+ */
+function markdownToPost(md, opts) {
+    var _a, _b;
+    const lines = md.replace(/\r\n/g, '\n').split('\n');
+    const paragraphs = [];
+    let fenceLang = null;
+    let fenceBuf = [];
+    const flushFence = () => {
+        if (fenceLang !== null) {
+            paragraphs.push([
+                {
+                    tag: 'text',
+                    text: fenceBuf.join('\n'),
+                    un_escape: true,
+                },
+            ]);
+            fenceBuf = [];
+            fenceLang = null;
+        }
+    };
+    for (const line of lines) {
+        const fenceMatch = line.match(/^```(\w*)\s*$/);
+        if (fenceMatch) {
+            if (fenceLang !== null) {
+                flushFence();
+            }
+            else {
+                fenceLang = fenceMatch[1] || '';
+            }
+            continue;
+        }
+        if (fenceLang !== null) {
+            fenceBuf.push(line);
+            continue;
+        }
+        if (/^\s*$/.test(line)) {
+            paragraphs.push([{ tag: 'text', text: '' }]);
+            continue;
+        }
+        if (/^(-{3,}|_{3,}|\*{3,})\s*$/.test(line)) {
+            paragraphs.push([{ tag: 'text', text: '———' }]);
+            continue;
+        }
+        paragraphs.push(parseInline(line));
+    }
+    flushFence();
+    // Prepend explicit mentions as `at` elements at the very top.
+    if ((_a = opts === null || opts === void 0 ? void 0 : opts.mentions) === null || _a === void 0 ? void 0 : _a.length) {
+        const atElements = composePostMentionElements(opts.mentions).map((el) => el);
+        if (atElements.length > 0) {
+            // Insert as a new first paragraph with at elements + a space
+            const first = [];
+            for (const el of atElements) {
+                first.push(el);
+                first.push({ tag: 'text', text: ' ' });
+            }
+            paragraphs.unshift(first);
+        }
+    }
+    return {
+        zh_cn: {
+            title: (_b = opts === null || opts === void 0 ? void 0 : opts.title) !== null && _b !== void 0 ? _b : '',
+            content: paragraphs,
+        },
+    };
+}
+/**
+ * Parse a single line of inline markdown into a list of post elements.
+ *
+ * Handles (in order):
+ *   ```inline code```, [text](url), **bold**, *italic*, __bold__, _italic_
+ *
+ * Headings (leading `#` sequence) render as bold text. List bullets and
+ * blockquote markers pass through as plain text prefix.
+ */
+function parseInline(line) {
+    // Normalize headings to bold
+    const headingMatch = line.match(/^(#{1,6})\s+(.*)$/);
+    if (headingMatch) {
+        const boldText = headingMatch[2];
+        return [{ tag: 'text', text: boldText, style: ['bold'] }];
+    }
+    const out = [];
+    // Token regex: inline code, link, bold, italic
+    const pattern = /(`[^`\n]+`)|(\[([^\]]+)\]\(([^)]+)\))|(\*\*[^*\n]+\*\*)|(__[^_\n]+__)|(\*[^*\n]+\*)|(_[^_\n]+_)/g;
+    let last = 0;
+    let m;
+    while ((m = pattern.exec(line))) {
+        if (m.index > last) {
+            out.push({ tag: 'text', text: line.slice(last, m.index) });
+        }
+        if (m[1]) {
+            // inline code
+            out.push({ tag: 'text', text: m[1].slice(1, -1), style: ['code'] });
+        }
+        else if (m[2]) {
+            // link
+            out.push({ tag: 'a', text: m[3], href: m[4] });
+        }
+        else if (m[5]) {
+            out.push({ tag: 'text', text: m[5].slice(2, -2), style: ['bold'] });
+        }
+        else if (m[6]) {
+            out.push({ tag: 'text', text: m[6].slice(2, -2), style: ['bold'] });
+        }
+        else if (m[7]) {
+            out.push({ tag: 'text', text: m[7].slice(1, -1), style: ['italic'] });
+        }
+        else if (m[8]) {
+            out.push({ tag: 'text', text: m[8].slice(1, -1), style: ['italic'] });
+        }
+        last = pattern.lastIndex;
+    }
+    if (last < line.length) {
+        out.push({ tag: 'text', text: line.slice(last) });
+    }
+    return out.length > 0 ? out : [{ tag: 'text', text: line }];
+}
+/**
+ * Extract the plain text body from a post JSON (recover flatted text for
+ * fallback-to-text paths).
+ */
+function postToPlainText(post) {
+    var _a;
+    const body = post === null || post === void 0 ? void 0 : post.zh_cn;
+    if (!(body === null || body === void 0 ? void 0 : body.content))
+        return '';
+    const lines = [];
+    for (const paragraph of body.content) {
+        if (!Array.isArray(paragraph))
+            continue;
+        const parts = [];
+        for (const el of paragraph) {
+            switch (el.tag) {
+                case 'text':
+                case 'a':
+                    parts.push((_a = el.text) !== null && _a !== void 0 ? _a : '');
+                    break;
+                case 'at':
+                    parts.push(el.user_name ? `@${el.user_name}` : '');
+                    break;
+                case 'img':
+                    parts.push(el.image_key ? `[image]` : '');
+                    break;
+            }
+        }
+        lines.push(parts.join(''));
+    }
+    return lines.join('\n').trim();
+}
+
+/**
+ * Split a long markdown string into chunks under `limit` characters.
+ *
+ * Preserves code block integrity — if a chunk boundary would fall inside a
+ * fenced code block, the current chunk closes the fence and the next chunk
+ * reopens it with the same language tag.
+ *
+ * Prefers breaking before headings when possible.
+ */
+function splitWithCodeFences(text, limit) {
+    if (text.length <= limit)
+        return [text];
+    const lines = text.split('\n');
+    const out = [];
+    let buf = [];
+    let bufLen = 0;
+    let fenceLang = null;
+    const flush = () => {
+        if (buf.length === 0)
+            return;
+        let chunk = buf.join('\n');
+        if (fenceLang !== null)
+            chunk += '\n```';
+        out.push(chunk);
+        buf = [];
+        bufLen = 0;
+        if (fenceLang !== null) {
+            // reopen fence in the next chunk
+            buf.push('```' + fenceLang);
+            bufLen = buf[0].length;
+        }
+    };
+    for (const line of lines) {
+        const m = line.match(/^```(\w*)$/);
+        const lineLen = line.length + (buf.length > 0 ? 1 : 0); // +1 for \n
+        // If this line is a heading and we already have content that's near
+        // the limit, prefer breaking here.
+        const isHeading = /^#{1,6}\s/.test(line);
+        const nearFull = bufLen > limit * 0.75;
+        if (bufLen + lineLen > limit || (isHeading && nearFull && buf.length > 0)) {
+            flush();
+        }
+        buf.push(line);
+        bufLen += lineLen;
+        if (m) {
+            // entering or leaving a fence
+            fenceLang = fenceLang === null ? m[1] || '' : null;
+        }
+    }
+    flush();
+    return out;
+}
+
+/**
+ * Infer Feishu's `receive_id_type` from the prefix of a target id.
+ *
+ *   oc_*          → chat_id
+ *   ou_*          → open_id
+ *   on_*          → union_id
+ *   contains '@'  → email
+ *   fallback      → user_id
+ */
+function detectReceiveIdType(to) {
+    if (!to)
+        throw new Error('empty receive_id');
+    if (to.startsWith('oc_'))
+        return 'chat_id';
+    if (to.startsWith('ou_'))
+        return 'open_id';
+    if (to.startsWith('on_'))
+        return 'union_id';
+    if (to.includes('@'))
+        return 'email';
+    return 'user_id';
+}
+
+/**
+ * Classify a raw error (typically from axios/fetch or a Feishu API response)
+ * into a LarkChannelError with a stable code.
+ */
+function classifyError(err, context) {
+    if (err instanceof LarkChannelError)
+        return err;
+    const code = inferCode(err);
+    const message = extractMessage(err);
+    return new LarkChannelError(code, message, { cause: err, context });
+}
+function inferCode(err) {
+    var _a, _b, _c, _d, _e, _f, _g, _h;
+    const raw = err;
+    const status = (_b = (_a = raw === null || raw === void 0 ? void 0 : raw.response) === null || _a === void 0 ? void 0 : _a.status) !== null && _b !== void 0 ? _b : raw === null || raw === void 0 ? void 0 : raw.status;
+    const feishuCode = (_g = (_e = (_d = (_c = raw === null || raw === void 0 ? void 0 : raw.response) === null || _c === void 0 ? void 0 : _c.data) === null || _d === void 0 ? void 0 : _d.code) !== null && _e !== void 0 ? _e : (_f = raw === null || raw === void 0 ? void 0 : raw.data) === null || _f === void 0 ? void 0 : _f.code) !== null && _g !== void 0 ? _g : raw === null || raw === void 0 ? void 0 : raw.code;
+    const msg = String((_h = raw === null || raw === void 0 ? void 0 : raw.message) !== null && _h !== void 0 ? _h : '').toLowerCase();
+    if (typeof feishuCode === 'number') {
+        if (feishuCode === 230020 || feishuCode === 230017)
+            return 'target_revoked';
+        if (feishuCode === 99991400 || feishuCode === 99991401)
+            return 'permission_denied';
+        if (feishuCode === 230002 || feishuCode === 230001)
+            return 'format_error';
+    }
+    if (status === 429)
+        return 'rate_limited';
+    if (status === 401 || status === 403)
+        return 'permission_denied';
+    if (status === 400)
+        return 'format_error';
+    if (status === 404)
+        return 'target_revoked';
+    if (msg.startsWith('ssrf_blocked'))
+        return 'ssrf_blocked';
+    if (msg.includes('timeout') || (raw === null || raw === void 0 ? void 0 : raw.code) === 'ETIMEDOUT' || (raw === null || raw === void 0 ? void 0 : raw.code) === 'ECONNABORTED') {
+        return 'send_timeout';
+    }
+    return 'unknown';
+}
+function extractMessage(err) {
+    var _a, _b, _c, _d;
+    const raw = err;
+    return (((_b = (_a = raw === null || raw === void 0 ? void 0 : raw.response) === null || _a === void 0 ? void 0 : _a.data) === null || _b === void 0 ? void 0 : _b.msg) ||
+        ((_d = (_c = raw === null || raw === void 0 ? void 0 : raw.response) === null || _c === void 0 ? void 0 : _c.data) === null || _d === void 0 ? void 0 : _d.message) ||
+        (raw === null || raw === void 0 ? void 0 : raw.message) ||
+        String(err));
+}
+function isRetryable(err) {
+    return err.code === 'rate_limited' || err.code === 'unknown';
+}
+function isFormatError(err) {
+    return err.code === 'format_error';
+}
+function isReplyTargetGone(err) {
+    return err.code === 'target_revoked';
+}
+
+/**
+ * Execute `op` with exponential backoff. Only retries errors classified as
+ * retryable (rate_limited / unknown). Business errors (format / revoked /
+ * permission / timeout) fail fast and bubble up.
+ */
+function retry(op, opts = {}) {
+    var _a, _b;
+    return __awaiter(this, void 0, void 0, function* () {
+        const max = (_a = opts.maxAttempts) !== null && _a !== void 0 ? _a : 3;
+        const base = (_b = opts.baseDelayMs) !== null && _b !== void 0 ? _b : 500;
+        let lastErr;
+        for (let attempt = 1; attempt <= max; attempt++) {
+            try {
+                return yield op(attempt);
+            }
+            catch (raw) {
+                const err = classifyError(raw, { attempt });
+                lastErr = err;
+                if (attempt >= max || !isRetryable(err)) {
+                    throw err;
+                }
+                const delay = base * Math.pow(3, attempt - 1);
+                yield sleep(delay);
+            }
+        }
+        throw lastErr;
+    });
+}
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+
+const DEFAULT_CHUNK_LIMIT = 3500;
+class OutboundSender {
+    constructor(client, config, logger) {
+        var _a;
+        this.client = client;
+        this.config = config;
+        this.logger = logger;
+        this.uploader = new MediaUploader(client, config);
+        this.chunkLimit = (_a = config.textChunkLimit) !== null && _a !== void 0 ? _a : DEFAULT_CHUNK_LIMIT;
+    }
+    send(to, input, opts = {}) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const idType = detectReceiveIdType(to);
+            if ('markdown' in input)
+                return this.sendMarkdown(to, idType, input.markdown, opts);
+            if ('text' in input)
+                return this.sendText(to, idType, input.text, opts);
+            if ('post' in input)
+                return this.sendPost(to, idType, input.post, opts);
+            if ('image' in input)
+                return this.sendImage(to, idType, input.image, opts);
+            if ('file' in input)
+                return this.sendFile(to, idType, input.file, opts);
+            if ('audio' in input)
+                return this.sendAudio(to, idType, input.audio, opts);
+            if ('video' in input)
+                return this.sendVideo(to, idType, input.video, opts);
+            if ('card' in input)
+                return this.sendCard(to, idType, input.card, opts);
+            if ('shareChat' in input)
+                return this.sendShareChat(to, idType, input.shareChat.chatId, opts);
+            if ('shareUser' in input)
+                return this.sendShareUser(to, idType, input.shareUser.userId, opts);
+            if ('sticker' in input)
+                return this.sendSticker(to, idType, input.sticker.fileKey, opts);
+            throw new LarkChannelError('format_error', 'unrecognized SendInput shape');
+        });
+    }
+    stream(to, input, opts = {}) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const idType = detectReceiveIdType(to);
+            if ('markdown' in input) {
+                const controller = new MarkdownStreamController(this, to, idType, opts);
+                return controller.run(input.markdown);
+            }
+            if ('card' in input) {
+                const controller = new CardStreamController(this, to, idType, opts, input.card.initial);
+                return controller.run(input.card.producer);
+            }
+            throw new LarkChannelError('format_error', 'unrecognized StreamInput shape');
+        });
+    }
+    // ─── text / markdown / post ───────────────────────────
+    sendMarkdown(to, idType, md, opts) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const chunks = splitWithCodeFences(md, this.chunkLimit);
+            const ids = [];
+            for (let i = 0; i < chunks.length; i++) {
+                const post = this.convertMarkdown(chunks[i], i === 0 ? opts.mentions : undefined);
+                const id = yield this.sendOneWithFallback({
+                    to, idType,
+                    msgType: 'post', content: post,
+                    replyTo: i === 0 ? opts.replyTo : undefined,
+                    replyInThread: opts.replyInThread,
+                });
+                ids.push(id);
+            }
+            return this.makeResult(ids);
+        });
+    }
+    sendText(to, idType, text, opts) {
+        var _a;
+        return __awaiter(this, void 0, void 0, function* () {
+            const prefix = composeMentionsTextPrefix((_a = opts.mentions) !== null && _a !== void 0 ? _a : []);
+            const body = prefix + text;
+            const chunks = splitPlain(body, this.chunkLimit);
+            const ids = [];
+            for (let i = 0; i < chunks.length; i++) {
+                const id = yield this.sendOneWithFallback({
+                    to, idType,
+                    msgType: 'text',
+                    content: { text: chunks[i] },
+                    replyTo: i === 0 ? opts.replyTo : undefined,
+                    replyInThread: opts.replyInThread,
+                });
+                ids.push(id);
+            }
+            return this.makeResult(ids);
+        });
+    }
+    sendPost(to, idType, post, opts) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const id = yield this.sendOneWithFallback({
+                to, idType,
+                msgType: 'post',
+                content: post,
+                replyTo: opts.replyTo,
+                replyInThread: opts.replyInThread,
+            });
+            return { messageId: id };
+        });
+    }
+    convertMarkdown(md, mentions) {
+        const conv = this.config.markdownConverter;
+        if (typeof conv === 'function')
+            return conv(md);
+        return markdownToPost(md, { mentions });
+    }
+    // ─── media ────────────────────────────────────────────
+    sendImage(to, idType, input, opts) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const up = yield this.uploader.upload({ kind: 'image', source: input.source });
+            const id = yield this.sendOneWithFallback({
+                to, idType,
+                msgType: 'image',
+                content: { image_key: up.fileKey },
+                replyTo: opts.replyTo,
+                replyInThread: opts.replyInThread,
+            });
+            return { messageId: id };
+        });
+    }
+    sendFile(to, idType, input, opts) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const up = yield this.uploader.upload({
+                kind: 'file', source: input.source, fileName: input.fileName,
+            });
+            const id = yield this.sendOneWithFallback({
+                to, idType,
+                msgType: 'file',
+                content: { file_key: up.fileKey },
+                replyTo: opts.replyTo,
+                replyInThread: opts.replyInThread,
+            });
+            return { messageId: id };
+        });
+    }
+    sendAudio(to, idType, input, opts) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const up = yield this.uploader.upload({
+                kind: 'audio', source: input.source, duration: input.duration,
+            });
+            const id = yield this.sendOneWithFallback({
+                to, idType,
+                msgType: 'audio',
+                content: { file_key: up.fileKey },
+                replyTo: opts.replyTo,
+                replyInThread: opts.replyInThread,
+            });
+            return { messageId: id };
+        });
+    }
+    sendVideo(to, idType, input, opts) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const up = yield this.uploader.upload({
+                kind: 'video', source: input.source, duration: input.duration,
+            });
+            const content = { file_key: up.fileKey };
+            if (input.coverImageKey)
+                content.image_key = input.coverImageKey;
+            const id = yield this.sendOneWithFallback({
+                to, idType,
+                msgType: 'media',
+                content,
+                replyTo: opts.replyTo,
+                replyInThread: opts.replyInThread,
+            });
+            return { messageId: id };
+        });
+    }
+    // ─── card ─────────────────────────────────────────────
+    sendCard(to, idType, card, opts) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const id = yield this.sendOneWithFallback({
+                to, idType,
+                msgType: 'interactive',
+                content: card,
+                replyTo: opts.replyTo,
+                replyInThread: opts.replyInThread,
+            });
+            return { messageId: id };
+        });
+    }
+    // ─── share / sticker ──────────────────────────────────
+    sendShareChat(to, idType, chatId, opts) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const id = yield this.sendOneWithFallback({
+                to, idType,
+                msgType: 'share_chat',
+                content: { chat_id: chatId },
+                replyTo: opts.replyTo,
+                replyInThread: opts.replyInThread,
+            });
+            return { messageId: id };
+        });
+    }
+    sendShareUser(to, idType, userId, opts) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const id = yield this.sendOneWithFallback({
+                to, idType,
+                msgType: 'share_user',
+                content: { user_id: userId },
+                replyTo: opts.replyTo,
+                replyInThread: opts.replyInThread,
+            });
+            return { messageId: id };
+        });
+    }
+    sendSticker(to, idType, fileKey, opts) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const id = yield this.sendOneWithFallback({
+                to, idType,
+                msgType: 'sticker',
+                content: { file_key: fileKey },
+                replyTo: opts.replyTo,
+                replyInThread: opts.replyInThread,
+            });
+            return { messageId: id };
+        });
+    }
+    // ─── low-level raw send with fallback & retry ─────────
+    /**
+     * Send once with fallback for format errors (post → text) and for
+     * vanished reply targets (reply → create).
+     */
+    sendOneWithFallback(args) {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                return yield this.rawSendWithRetry(args);
+            }
+            catch (e) {
+                const err = classifyError(e, { to: args.to });
+                if (isReplyTargetGone(err) && args.replyTo) {
+                    return this.rawSendWithRetry(Object.assign(Object.assign({}, args), { replyTo: undefined }));
+                }
+                if (isFormatError(err) && args.msgType === 'post') {
+                    const plain = postToPlainText(args.content);
+                    return this.rawSendWithRetry(Object.assign(Object.assign({}, args), { msgType: 'text', content: { text: plain || '[message]' } }));
+                }
+                throw err;
+            }
+        });
+    }
+    rawSendWithRetry(args) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return retry(() => this.rawSend(args), this.config.retry);
+        });
+    }
+    rawSend(args) {
+        var _a, _b;
+        return __awaiter(this, void 0, void 0, function* () {
+            const payload = {
+                receive_id: args.to,
+                msg_type: args.msgType,
+                content: JSON.stringify(args.content),
+            };
+            if (args.replyTo) {
+                const r = yield this.client.im.v1.message.reply({
+                    path: { message_id: args.replyTo },
+                    data: {
+                        content: payload.content,
+                        msg_type: args.msgType,
+                        reply_in_thread: args.replyInThread,
+                    },
+                });
+                const id = (_a = r.data) === null || _a === void 0 ? void 0 : _a.message_id;
+                if (!id)
+                    throw new LarkChannelError('unknown', 'message_id missing from reply response');
+                return id;
+            }
+            const r = yield this.client.im.v1.message.create({
+                params: { receive_id_type: args.idType },
+                data: payload,
+            });
+            const id = (_b = r.data) === null || _b === void 0 ? void 0 : _b.message_id;
+            if (!id)
+                throw new LarkChannelError('unknown', 'message_id missing from create response');
+            return id;
+        });
+    }
+    // ─── helpers used by streaming ────────────────────────
+    /**
+     * Full card replace via im.v1.message.patch — used by CardStreamController
+     * and the public `channel.updateCard()` low-level API. Not suitable for
+     * text streaming (use native cardkit streaming below for that).
+     */
+    patchCard(messageId, card) {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this.client.im.v1.message.patch({
+                path: { message_id: messageId },
+                data: { content: JSON.stringify(card) },
+            });
+        });
+    }
+    /**
+     * Create a card instance via cardkit.v1.card.create. Used to get a
+     * `card_id` that can be referenced from messages AND updated with
+     * native streaming APIs (cardElement.content for typewriter effect).
+     */
+    createCardInstance(spec) {
+        var _a;
+        return __awaiter(this, void 0, void 0, function* () {
+            const r = yield this.client.cardkit.v1.card.create({
+                data: { type: 'card_json', data: JSON.stringify(spec) },
+            });
+            const cardId = (_a = r.data) === null || _a === void 0 ? void 0 : _a.card_id;
+            if (!cardId) {
+                throw new LarkChannelError('unknown', 'cardkit.card.create returned no card_id');
+            }
+            return cardId;
+        });
+    }
+    /**
+     * Send an interactive message that references a pre-created card instance
+     * by card_id. Returns the resulting message_id.
+     */
+    sendCardByReference(to, idType, cardId, opts) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.rawSendWithRetry({
+                to, idType,
+                msgType: 'interactive',
+                content: { type: 'card', data: { card_id: cardId } },
+                replyTo: opts.replyTo,
+                replyInThread: opts.replyInThread,
+            });
+        });
+    }
+    /**
+     * Stream update: replace a card element's content and let Feishu render
+     * the incremental diff as a typewriter animation. `sequence` must be
+     * monotonically increasing per card (duplicates/out-of-order → rejected
+     * server-side). `uuid` is required for idempotency — we compose it from
+     * cardId + sequence so two concurrent calls with the same seq would
+     * dedupe rather than both take effect.
+     */
+    updateCardElementContent(cardId, elementId, content, sequence) {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this.client.cardkit.v1.cardElement.content({
+                path: { card_id: cardId, element_id: elementId },
+                data: {
+                    content,
+                    sequence,
+                    uuid: `c_${cardId}_${sequence}`,
+                },
+            });
+        });
+    }
+    /**
+     * Switch a streaming card to finalized state (streaming_mode: false).
+     * Feishu auto-closes after 10min regardless, but callers should close
+     * explicitly when producer completes.
+     *
+     * `summary` is optional; when provided, also updates the card's preview
+     * text (the one shown in message lists / chat previews). Without it, the
+     * preview stays at whatever was set during streaming (typically the
+     * default "[Generating...]"), which looks stuck.
+     */
+    finishStreamingCard(cardId, sequence, summary) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const config = { streaming_mode: false };
+            if (summary !== undefined) {
+                config.summary = { content: summary };
+            }
+            yield this.client.cardkit.v1.card.settings({
+                path: { card_id: cardId },
+                data: {
+                    settings: JSON.stringify({ config }),
+                    sequence,
+                    uuid: `s_${cardId}_${sequence}`,
+                },
+            });
+        });
+    }
+    makeResult(ids) {
+        return {
+            messageId: ids[0],
+            chunkIds: ids.length > 1 ? ids : undefined,
+        };
+    }
+}
+function splitPlain(text, limit) {
+    if (text.length <= limit)
+        return [text];
+    const out = [];
+    for (let i = 0; i < text.length; i += limit) {
+        out.push(text.slice(i, i + limit));
+    }
+    return out;
+}
+
+/**
+ * Per-scope pipeline that does two things at once:
+ *   - Debounce-based batch aggregation (for IM messages)
+ *   - Strict serialization of all work (both batched flushes and direct
+ *     `run()` tasks) via a promise chain
+ *
+ * Supports two entry points:
+ *   - push(msg, handler):  enqueue for batched dispatch
+ *   - run(task):           run a one-shot async task serialized after any
+ *                          pending batch and previous tasks
+ */
+class ChatPipeline {
+    constructor(config, serialOnly) {
+        this.config = config;
+        this.serialOnly = serialOnly;
+        this.buffer = [];
+        this.bufferChars = 0;
+        this.tail = Promise.resolve();
+    }
+    push(msg, handler) {
+        var _a;
+        this.buffer.push(msg);
+        this.bufferChars += msg.content.length;
+        (_a = this.pendingHandler) !== null && _a !== void 0 ? _a : (this.pendingHandler = handler);
+        // Force flush when caps reached.
+        if (this.buffer.length >= this.config.maxMessages
+            || this.bufferChars >= this.config.maxChars) {
+            this.clearTimer();
+            this.enqueueFlush();
+            return;
+        }
+        // Pure-serial mode (debounce disabled).
+        if (this.config.delayMs <= 0 || this.serialOnly) {
+            this.clearTimer();
+            this.enqueueFlush();
+            return;
+        }
+        // Debounced flush.
+        this.clearTimer();
+        const delay = this.bufferChars >= this.config.longThresholdChars
+            ? this.config.longDelayMs
+            : this.config.delayMs;
+        this.timer = setTimeout(() => {
+            this.timer = undefined;
+            this.enqueueFlush();
+        }, delay);
+    }
+    run(task) {
+        // Any pending batch flushes first so a follow-on action-like task
+        // runs after its chat's in-flight message work.
+        if (this.buffer.length > 0) {
+            this.clearTimer();
+            this.enqueueFlush();
+        }
+        const next = this.tail.then(task, task);
+        this.tail = next.then(() => undefined, () => undefined);
+        return next;
+    }
+    flushNow() {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (this.buffer.length > 0) {
+                this.clearTimer();
+                this.enqueueFlush();
+            }
+            yield this.tail;
+        });
+    }
+    isIdle() {
+        return this.buffer.length === 0 && !this.timer;
+    }
+    dispose() {
+        this.clearTimer();
+        this.buffer = [];
+        this.pendingHandler = undefined;
+    }
+    clearTimer() {
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = undefined;
+        }
+    }
+    enqueueFlush() {
+        if (this.buffer.length === 0)
+            return;
+        const batch = this.buffer;
+        const handler = this.pendingHandler;
+        this.buffer = [];
+        this.bufferChars = 0;
+        this.pendingHandler = undefined;
+        if (!handler)
+            return;
+        const dispatch = {
+            message: mergeBatch(batch),
+            sourceIds: batch.map((m) => m.messageId),
+        };
+        const task = () => handler(dispatch);
+        const next = this.tail.then(task, task);
+        this.tail = next.then(() => undefined, () => undefined);
+    }
+}
+class ChatPipelineManager {
+    constructor(config) {
+        this.config = config;
+        this.pipelines = new Map();
+    }
+    push(scope, msg, handler) {
+        this.getOrCreate(scope, false).push(msg, handler);
+    }
+    run(scope, task) {
+        return this.getOrCreate(scope, true).run(task);
+    }
+    getOrCreate(scope, serialOnly) {
+        let p = this.pipelines.get(scope);
+        if (!p) {
+            p = new ChatPipeline(this.config, serialOnly);
+            this.pipelines.set(scope, p);
+        }
+        return p;
+    }
+    flushAll() {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield Promise.all([...this.pipelines.values()].map((p) => p.flushNow()));
+        });
+    }
+    dispose() {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this.flushAll();
+            for (const p of this.pipelines.values())
+                p.dispose();
+            this.pipelines.clear();
+        });
+    }
+}
+/**
+ * Merge a batch of NormalizedMessages (all from the same chat) into a
+ * single representative message. Keeps the latest-arrival metadata and
+ * unions content / resources / mentions.
+ */
+function mergeBatch(batch) {
+    if (batch.length === 1)
+        return batch[0];
+    const last = batch[batch.length - 1];
+    const content = batch
+        .map((m) => m.content)
+        .filter((c) => c && c.length > 0)
+        .join('\n\n');
+    const resources = dedupBy(batch.flatMap((m) => m.resources), (r) => r.fileKey);
+    const mentions = dedupBy(batch.flatMap((m) => m.mentions), (m) => { var _a; return (_a = m.openId) !== null && _a !== void 0 ? _a : m.key; });
+    return Object.assign(Object.assign({}, last), { content,
+        resources,
+        mentions, mentionAll: batch.some((m) => m.mentionAll), mentionedBot: batch.some((m) => m.mentionedBot) });
+}
+function dedupBy(items, key) {
+    const seen = new Set();
+    const out = [];
+    for (const item of items) {
+        const k = key(item);
+        if (k == null) {
+            out.push(item);
+            continue;
+        }
+        if (seen.has(k))
+            continue;
+        seen.add(k);
+        out.push(item);
+    }
+    return out;
+}
+
+const DEFAULT_BATCH = {
+    delayMs: 600,
+    longThresholdChars: 1000,
+    longDelayMs: 2000,
+    maxMessages: 8,
+    maxChars: 4000,
+};
+const DEFAULT_DEDUP = {
+    ttl: 12 * 3600000,
+    maxEntries: 5000,
+    sweepIntervalMs: 5 * 60000,
+    namespace: 'channel:seen',
+};
+const DEFAULT_STALE_MS = 30 * 60000;
+const DEFAULT_LOCK_TTL_MS = 5 * 60000;
+function resolveBatchConfig(cfg) {
+    var _a, _b, _c, _d, _e, _f, _g;
+    const t = (_b = (_a = cfg === null || cfg === void 0 ? void 0 : cfg.batch) === null || _a === void 0 ? void 0 : _a.text) !== null && _b !== void 0 ? _b : {};
+    return {
+        delayMs: (_c = t.delayMs) !== null && _c !== void 0 ? _c : DEFAULT_BATCH.delayMs,
+        longThresholdChars: (_d = t.longThresholdChars) !== null && _d !== void 0 ? _d : DEFAULT_BATCH.longThresholdChars,
+        longDelayMs: (_e = t.longDelayMs) !== null && _e !== void 0 ? _e : DEFAULT_BATCH.longDelayMs,
+        maxMessages: (_f = t.maxMessages) !== null && _f !== void 0 ? _f : DEFAULT_BATCH.maxMessages,
+        maxChars: (_g = t.maxChars) !== null && _g !== void 0 ? _g : DEFAULT_BATCH.maxChars,
+    };
+}
+
+/**
+ * Two-tier dedup cache: hot in-memory LRU + injectable long-term Cache.
+ * Memory tier serves 99% of queries sub-millisecond; long-term tier
+ * survives process restarts when a persistent Cache implementation is
+ * provided. Default node-sdk `internalCache` is memory-only — callers
+ * wanting cross-restart persistence inject their own Cache (e.g., Redis).
+ */
+class SeenCache {
+    constructor(cache, opts = {}) {
+        var _a, _b, _c, _d, _e, _f;
+        this.cache = cache;
+        this.memory = new Map(); // id → expireAt
+        this.ttlMs = (_a = opts.ttlMs) !== null && _a !== void 0 ? _a : DEFAULT_DEDUP.ttl;
+        this.maxMem = (_b = opts.maxMemEntries) !== null && _b !== void 0 ? _b : DEFAULT_DEDUP.maxEntries;
+        this.ns = (_c = opts.namespace) !== null && _c !== void 0 ? _c : DEFAULT_DEDUP.namespace;
+        const sweepMs = (_d = opts.sweepMs) !== null && _d !== void 0 ? _d : DEFAULT_DEDUP.sweepIntervalMs;
+        this.sweeper = setInterval(() => this.sweep(), sweepMs);
+        (_f = (_e = this.sweeper).unref) === null || _f === void 0 ? void 0 : _f.call(_e);
+    }
+    has(id) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const now = Date.now();
+            const exp = this.memory.get(id);
+            if (exp && exp > now) {
+                // refresh LRU position
+                this.memory.delete(id);
+                this.memory.set(id, exp);
+                return true;
+            }
+            // fall through to long-term tier
+            const hit = yield this.cache.get(id, { namespace: this.ns });
+            if (hit) {
+                this.memory.set(id, now + this.ttlMs);
+                this.evictIfNeeded();
+                return true;
+            }
+            return false;
+        });
+    }
+    add(id) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const expireAt = Date.now() + this.ttlMs;
+            this.memory.set(id, expireAt);
+            this.evictIfNeeded();
+            // best-effort write to long-term; ignore failures
+            try {
+                yield this.cache.set(id, '1', expireAt, { namespace: this.ns });
+            }
+            catch (_a) {
+                // tolerated — memory tier remains authoritative during the session
+            }
+        });
+    }
+    evictIfNeeded() {
+        while (this.memory.size > this.maxMem) {
+            const first = this.memory.keys().next().value;
+            if (first === undefined)
+                break;
+            this.memory.delete(first);
+        }
+    }
+    sweep() {
+        const now = Date.now();
+        for (const [k, v] of this.memory) {
+            if (v <= now)
+                this.memory.delete(k);
+        }
+    }
+    dispose() {
+        clearInterval(this.sweeper);
+        this.memory.clear();
+    }
+}
+
+class PolicyGate {
+    constructor(cfg, bot) {
+        this.cfg = Object.assign({}, (cfg !== null && cfg !== void 0 ? cfg : {}));
+        this.bot = bot;
+    }
+    evaluate(msg) {
+        if (msg.chatType === 'group')
+            return this.evaluateGroup(msg);
+        return this.evaluateDm(msg);
+    }
+    evaluateGroup(msg) {
+        var _a, _b;
+        const allow = this.cfg.groupAllowlist;
+        if (allow && allow.length > 0 && !allow.includes(msg.chatId)) {
+            return { allowed: false, reason: 'group_not_allowed' };
+        }
+        const requireMention = (_a = this.cfg.requireMention) !== null && _a !== void 0 ? _a : true;
+        if (requireMention && !msg.mentionedBot) {
+            return { allowed: false, reason: 'no_mention' };
+        }
+        if (msg.mentionAll && !((_b = this.cfg.respondToMentionAll) !== null && _b !== void 0 ? _b : false)) {
+            return { allowed: false, reason: 'mention_all_blocked' };
+        }
+        return { allowed: true };
+    }
+    evaluateDm(msg) {
+        var _a, _b;
+        const mode = (_a = this.cfg.dmMode) !== null && _a !== void 0 ? _a : 'open';
+        if (mode === 'disabled') {
+            return { allowed: false, reason: 'dm_disabled' };
+        }
+        if (mode === 'allowlist') {
+            const allow = (_b = this.cfg.dmAllowlist) !== null && _b !== void 0 ? _b : [];
+            if (!allow.includes(msg.senderId)) {
+                return { allowed: false, reason: 'sender_not_allowed' };
+            }
+        }
+        // 'pair' mode is reserved for a future iteration; treat as open for now.
+        return { allowed: true };
+    }
+    updateConfig(partial) {
+        this.cfg = Object.assign(Object.assign({}, this.cfg), partial);
+    }
+    getConfig() {
+        return this.cfg;
+    }
+    setBotIdentity(bot) {
+        this.bot = bot;
+    }
+    getBotIdentity() {
+        return this.bot;
+    }
+}
+
+/**
+ * Short-TTL in-memory lock to prevent concurrent processing of the same
+ * event — complements SeenCache by covering the "currently in flight"
+ * window, during which the event is not yet committed to SeenCache.
+ */
+class ProcessingLock {
+    constructor(ttlMs = DEFAULT_LOCK_TTL_MS, sweepMs = 60000) {
+        var _a, _b;
+        this.ttlMs = ttlMs;
+        this.locks = new Map(); // id → expireAt (ms)
+        this.sweeper = setInterval(() => this.sweep(), sweepMs);
+        (_b = (_a = this.sweeper).unref) === null || _b === void 0 ? void 0 : _b.call(_a);
+    }
+    /** Returns true if the lock is acquired; false if already held. */
+    acquire(id) {
+        const now = Date.now();
+        const exp = this.locks.get(id);
+        if (exp && exp > now)
+            return false;
+        this.locks.set(id, now + this.ttlMs);
+        return true;
+    }
+    release(id) {
+        this.locks.delete(id);
+    }
+    sweep() {
+        const now = Date.now();
+        for (const [k, v] of this.locks) {
+            if (v <= now)
+                this.locks.delete(k);
+        }
+    }
+    dispose() {
+        clearInterval(this.sweeper);
+        this.locks.clear();
+    }
+}
+
+function isStale(createTimeMs, windowMs = DEFAULT_STALE_MS) {
+    if (!createTimeMs || !Number.isFinite(createTimeMs))
+        return false;
+    return Date.now() - createTimeMs > windowMs;
+}
+
+/**
+ * Pipeline entry facade for the channel's safety layer.
+ *
+ * Three tiers of protection, each targeting different event shapes:
+ *   - pushMessage: full pipeline (stale + dedup + policy + lock + batch + queue)
+ *   - pushAction:  dedup + lock + queue — for card button clicks and doc comments
+ *   - pushLight:   dedup only — for reactions
+ */
+class SafetyPipeline {
+    constructor(opts) {
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l;
+        this.logger = opts.logger;
+        this.onReject = opts.onReject;
+        this.onMessage = opts.onMessage;
+        this.staleWindow = (_b = (_a = opts.config) === null || _a === void 0 ? void 0 : _a.staleMessageWindowMs) !== null && _b !== void 0 ? _b : DEFAULT_STALE_MS;
+        this.queueEnabled = (_e = (_d = (_c = opts.config) === null || _c === void 0 ? void 0 : _c.chatQueue) === null || _d === void 0 ? void 0 : _d.enabled) !== null && _e !== void 0 ? _e : true;
+        this.seenCache = new SeenCache(opts.cache, {
+            ttlMs: (_g = (_f = opts.config) === null || _f === void 0 ? void 0 : _f.dedup) === null || _g === void 0 ? void 0 : _g.ttl,
+            maxMemEntries: (_j = (_h = opts.config) === null || _h === void 0 ? void 0 : _h.dedup) === null || _j === void 0 ? void 0 : _j.maxEntries,
+            sweepMs: (_l = (_k = opts.config) === null || _k === void 0 ? void 0 : _k.dedup) === null || _l === void 0 ? void 0 : _l.sweepIntervalMs,
+        });
+        this.lock = new ProcessingLock();
+        this.policy = new PolicyGate(opts.policy, opts.botIdentity);
+        this.manager = new ChatPipelineManager(resolveBatchConfig(opts.config));
+    }
+    // ─── tier 1: full pipeline for IM messages ─────────────
+    pushMessage(msg) {
+        var _a, _b, _c, _d, _e, _f, _g;
+        return __awaiter(this, void 0, void 0, function* () {
+            if (isStale(msg.createTime, this.staleWindow)) {
+                (_b = (_a = this.logger).debug) === null || _b === void 0 ? void 0 : _b.call(_a, `safety: drop stale message ${msg.messageId}`);
+                return;
+            }
+            if (yield this.seenCache.has(msg.messageId)) {
+                (_d = (_c = this.logger).debug) === null || _d === void 0 ? void 0 : _d.call(_c, `safety: drop duplicate message ${msg.messageId}`);
+                return;
+            }
+            const decision = this.policy.evaluate(msg);
+            if (!decision.allowed) {
+                this.onReject({
+                    messageId: msg.messageId,
+                    chatId: msg.chatId,
+                    senderId: msg.senderId,
+                    reason: (_e = decision.reason) !== null && _e !== void 0 ? _e : 'group_not_allowed',
+                });
+                return;
+            }
+            if (!this.lock.acquire(msg.messageId)) {
+                (_g = (_f = this.logger).debug) === null || _g === void 0 ? void 0 : _g.call(_f, `safety: drop in-flight message ${msg.messageId}`);
+                return;
+            }
+            const dispatchHandler = (batch) => __awaiter(this, void 0, void 0, function* () {
+                var _h, _j;
+                try {
+                    yield this.onMessage(batch.message);
+                }
+                catch (e) {
+                    (_j = (_h = this.logger).error) === null || _j === void 0 ? void 0 : _j.call(_h, `safety: message handler threw`, e);
+                }
+                finally {
+                    for (const id of batch.sourceIds) {
+                        try {
+                            yield this.seenCache.add(id);
+                        }
+                        catch ( /* best effort */_k) { /* best effort */ }
+                        this.lock.release(id);
+                    }
+                }
+            });
+            if (this.queueEnabled) {
+                this.manager.push(msg.chatId, msg, dispatchHandler);
+            }
+            else {
+                // queueing disabled: fire-and-forget, no batch either
+                void dispatchHandler({ message: msg, sourceIds: [msg.messageId] });
+            }
+        });
+    }
+    // ─── tier 2: dedup + lock + queue for cardAction & comment ─────
+    pushAction(eventId, queueScope, handler) {
+        var _a, _b, _c, _d;
+        return __awaiter(this, void 0, void 0, function* () {
+            if (yield this.seenCache.has(eventId)) {
+                (_b = (_a = this.logger).debug) === null || _b === void 0 ? void 0 : _b.call(_a, `safety: drop duplicate action ${eventId}`);
+                return;
+            }
+            if (!this.lock.acquire(eventId)) {
+                (_d = (_c = this.logger).debug) === null || _d === void 0 ? void 0 : _d.call(_c, `safety: drop in-flight action ${eventId}`);
+                return;
+            }
+            const task = () => __awaiter(this, void 0, void 0, function* () {
+                var _e, _f;
+                try {
+                    yield handler();
+                }
+                catch (e) {
+                    (_f = (_e = this.logger).error) === null || _f === void 0 ? void 0 : _f.call(_e, `safety: action handler threw`, e);
+                }
+                finally {
+                    try {
+                        yield this.seenCache.add(eventId);
+                    }
+                    catch ( /* best effort */_g) { /* best effort */ }
+                    this.lock.release(eventId);
+                }
+            });
+            if (this.queueEnabled) {
+                yield this.manager.run(queueScope, task);
+            }
+            else {
+                yield task();
+            }
+        });
+    }
+    // ─── tier 3: dedup only (reactions) ────────────────────
+    pushLight(eventId, handler) {
+        var _a, _b;
+        return __awaiter(this, void 0, void 0, function* () {
+            if (yield this.seenCache.has(eventId))
+                return;
+            yield this.seenCache.add(eventId);
+            try {
+                yield handler();
+            }
+            catch (e) {
+                (_b = (_a = this.logger).warn) === null || _b === void 0 ? void 0 : _b.call(_a, `safety: light handler threw`, e);
+            }
+        });
+    }
+    // ─── runtime config ────────────────────────────────────
+    updatePolicy(partial) {
+        this.policy.updateConfig(partial);
+    }
+    getPolicy() {
+        return this.policy.getConfig();
+    }
+    setBotIdentity(bot) {
+        this.policy.setBotIdentity(bot);
+    }
+    dispose() {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this.manager.dispose();
+            this.seenCache.dispose();
+            this.lock.dispose();
+        });
+    }
+}
+
+function isMentionAll(m) {
+    return m.key === '@_all';
+}
+function extractMentions(raw, botOpenId) {
+    var _a, _b, _c;
+    const mentions = new Map();
+    const mentionsByOpenId = new Map();
+    const mentionList = [];
+    let mentionAll = false;
+    let mentionedBot = false;
+    for (const m of raw !== null && raw !== void 0 ? raw : []) {
+        if (isMentionAll(m)) {
+            mentionAll = true;
+            mentions.set(m.key, { key: m.key, name: m.name, isBot: false });
+            continue;
+        }
+        const openId = (_b = (_a = m.id) === null || _a === void 0 ? void 0 : _a.open_id) !== null && _b !== void 0 ? _b : '';
+        const userId = (_c = m.id) === null || _c === void 0 ? void 0 : _c.user_id;
+        const isBot = Boolean(botOpenId && openId === botOpenId);
+        if (isBot)
+            mentionedBot = true;
+        const info = {
+            key: m.key,
+            openId: openId || undefined,
+            userId,
+            name: m.name,
+            isBot,
+        };
+        mentions.set(m.key, info);
+        if (openId)
+            mentionsByOpenId.set(openId, info);
+        mentionList.push(info);
+    }
+    return { mentions, mentionsByOpenId, mentionList, mentionAll, mentionedBot };
+}
+/**
+ * Second-pass: replace placeholder keys in `content` with human-readable names
+ * (or strip bot mentions if configured).
+ *
+ * Must run AFTER all converters have done their work, because converters use
+ * placeholder keys to defer resolution to this single point.
+ */
+function resolveMentions(content, ctx) {
+    if (!content || ctx.mentions.size === 0)
+        return content;
+    let out = content;
+    for (const [key, info] of ctx.mentions) {
+        if (info.isBot && ctx.stripBotMentions) {
+            // Remove key plus one surrounding whitespace on either side.
+            const re = new RegExp(`\\s?${escapeRegex(key)}\\s?`, 'g');
+            out = out.replace(re, ' ');
+            continue;
+        }
+        const replacement = info.name ? `@${info.name}` : key;
+        out = out.split(key).join(replacement);
+    }
+    // Collapse any double-spaces introduced by bot-mention stripping.
+    return out.replace(/[ \t]{2,}/g, ' ').trim();
+}
+function escapeRegex(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function safeParse(raw) {
+    if (!raw)
+        return undefined;
+    try {
+        return JSON.parse(raw);
+    }
+    catch (_a) {
+        return undefined;
+    }
+}
+function applyStyle(text, style) {
+    if (!style || style.length === 0)
+        return text;
+    let out = text;
+    if (style.includes('bold'))
+        out = `**${out}**`;
+    if (style.includes('italic'))
+        out = `*${out}*`;
+    if (style.includes('underline'))
+        out = `<u>${out}</u>`;
+    if (style.includes('lineThrough') || style.includes('strikethrough'))
+        out = `~~${out}~~`;
+    if (style.includes('codeInline') || style.includes('code'))
+        out = `\`${out}\``;
+    return out;
+}
+const LOCALE_PRIORITY = ['zh_cn', 'en_us', 'ja_jp'];
+function unwrapLocale(parsed) {
+    if ('title' in parsed || 'content' in parsed) {
+        return parsed;
+    }
+    for (const loc of LOCALE_PRIORITY) {
+        const hit = parsed[loc];
+        if (hit != null && typeof hit === 'object')
+            return hit;
+    }
+    const firstKey = Object.keys(parsed)[0];
+    if (firstKey) {
+        const first = parsed[firstKey];
+        if (first != null && typeof first === 'object')
+            return first;
+    }
+    return undefined;
+}
+function formatDuration(ms) {
+    if (ms == null || !Number.isFinite(ms) || ms < 0)
+        return undefined;
+    if (ms < 1000)
+        return `${Math.round(ms)}ms`;
+    if (ms % 1000 === 0)
+        return `${ms / 1000}s`;
+    return `${(ms / 1000).toFixed(1)}s`;
+}
+function millisToDatetime(ms) {
+    if (ms == null)
+        return undefined;
+    const n = typeof ms === 'string' ? parseInt(ms, 10) : ms;
+    if (!Number.isFinite(n) || n <= 0)
+        return undefined;
+    const d = new Date(n + 8 * 3600000);
+    const y = d.getUTCFullYear();
+    const mo = String(d.getUTCMonth() + 1).padStart(2, '0');
+    const day = String(d.getUTCDate()).padStart(2, '0');
+    const h = String(d.getUTCHours()).padStart(2, '0');
+    const mi = String(d.getUTCMinutes()).padStart(2, '0');
+    return `${y}-${mo}-${day} ${h}:${mi}`;
+}
+function formatRFC3339Beijing(ms) {
+    const d = new Date(ms + 8 * 3600000);
+    const y = d.getUTCFullYear();
+    const mo = String(d.getUTCMonth() + 1).padStart(2, '0');
+    const day = String(d.getUTCDate()).padStart(2, '0');
+    const h = String(d.getUTCHours()).padStart(2, '0');
+    const mi = String(d.getUTCMinutes()).padStart(2, '0');
+    const s = String(d.getUTCSeconds()).padStart(2, '0');
+    return `${y}-${mo}-${day}T${h}:${mi}:${s}+08:00`;
+}
+function indentLines(text, indent) {
+    return text
+        .split('\n')
+        .map((line) => `${indent}${line}`)
+        .join('\n');
+}
+function escapeAttr(s) {
+    return s.replace(/"/g, '&quot;');
+}
+
+const convertAudio = (raw, _ctx) => __awaiter(void 0, void 0, void 0, function* () {
+    const parsed = safeParse(raw);
+    const fileKey = parsed === null || parsed === void 0 ? void 0 : parsed.file_key;
+    if (!fileKey)
+        return { content: '[audio]', resources: [] };
+    const duration = parsed === null || parsed === void 0 ? void 0 : parsed.duration;
+    const durAttr = formatDuration(duration);
+    const attr = durAttr ? ` duration="${durAttr}"` : '';
+    const content = `<audio key="${fileKey}"${attr}/>`;
+    const resources = [
+        { type: 'audio', fileKey, durationMs: duration },
+    ];
+    return { content, resources };
+});
+
+function formatCalendarInner(raw) {
+    const parsed = safeParse(raw);
+    if (!parsed)
+        return '[calendar event]';
+    const lines = [];
+    if (parsed.summary)
+        lines.push(`📅 ${parsed.summary}`);
+    const start = millisToDatetime(parsed.start_time);
+    const end = millisToDatetime(parsed.end_time);
+    if (start && end)
+        lines.push(`🕙 ${start} ~ ${end}`);
+    else if (start)
+        lines.push(`🕙 ${start}`);
+    return lines.length > 0 ? lines.join('\n') : '[calendar event]';
+}
+const convertCalendar = (raw, _ctx) => __awaiter(void 0, void 0, void 0, function* () {
+    return ({
+        content: `<calendar_invite>\n${formatCalendarInner(raw)}\n</calendar_invite>`,
+        resources: [],
+    });
+});
+const convertGeneralCalendar = (raw, _ctx) => __awaiter(void 0, void 0, void 0, function* () {
+    return ({
+        content: `<calendar>\n${formatCalendarInner(raw)}\n</calendar>`,
+        resources: [],
+    });
+});
+const convertShareCalendarEvent = (raw, _ctx) => __awaiter(void 0, void 0, void 0, function* () {
+    return ({
+        content: `<calendar_share>\n${formatCalendarInner(raw)}\n</calendar_share>`,
+        resources: [],
+    });
+});
+
+const convertFile = (raw, _ctx) => __awaiter(void 0, void 0, void 0, function* () {
+    const parsed = safeParse(raw);
+    const fileKey = parsed === null || parsed === void 0 ? void 0 : parsed.file_key;
+    if (!fileKey)
+        return { content: '[file]', resources: [] };
+    const fileName = parsed === null || parsed === void 0 ? void 0 : parsed.file_name;
+    const nameAttr = fileName ? ` name="${escapeAttr(fileName)}"` : '';
+    const content = `<file key="${fileKey}"${nameAttr}/>`;
+    const resources = [{ type: 'file', fileKey, fileName }];
+    return { content, resources };
+});
+
+const convertFolder = (raw, _ctx) => __awaiter(void 0, void 0, void 0, function* () {
+    const parsed = safeParse(raw);
+    const fileKey = parsed === null || parsed === void 0 ? void 0 : parsed.file_key;
+    if (!fileKey)
+        return { content: '[folder]', resources: [] };
+    const nameAttr = (parsed === null || parsed === void 0 ? void 0 : parsed.file_name) ? ` name="${escapeAttr(parsed.file_name)}"` : '';
+    return { content: `<folder key="${fileKey}"${nameAttr}/>`, resources: [] };
+});
+
+const convertHongbao = (raw, _ctx) => __awaiter(void 0, void 0, void 0, function* () {
+    const parsed = safeParse(raw);
+    const textAttr = (parsed === null || parsed === void 0 ? void 0 : parsed.text) ? ` text="${escapeAttr(parsed.text)}"` : '';
+    return { content: `<hongbao${textAttr}/>`, resources: [] };
+});
+
+const convertImage = (raw, _ctx) => __awaiter(void 0, void 0, void 0, function* () {
+    const parsed = safeParse(raw);
+    const imageKey = parsed === null || parsed === void 0 ? void 0 : parsed.image_key;
+    if (!imageKey)
+        return { content: '[image]', resources: [] };
+    const resources = [{ type: 'image', fileKey: imageKey }];
+    return { content: `![image](${imageKey})`, resources };
+});
+
+/**
+ * Recursive walker that extracts human-readable text from a Feishu
+ * interactive card JSON tree. Covers header titles, plain_text / lark_md
+ * elements, button labels, form fields, notes, and commonly used nested
+ * element types.
+ */
+function walkCard(node) {
+    const out = [];
+    visit(node, out);
+    // de-duplicate adjacent empties and collapse
+    return out.filter((s) => s && s.trim().length > 0);
+}
+function visit(node, out) {
+    if (node == null)
+        return;
+    if (typeof node === 'string' || typeof node === 'number' || typeof node === 'boolean')
+        return;
+    if (Array.isArray(node)) {
+        for (const child of node)
+            visit(child, out);
+        return;
+    }
+    if (typeof node !== 'object')
+        return;
+    const obj = node;
+    // tag: plain_text / lark_md / markdown → push content
+    const tag = obj.tag;
+    if (typeof tag === 'string' && (tag === 'plain_text' || tag === 'lark_md' || tag === 'markdown')) {
+        if (typeof obj.content === 'string')
+            out.push(obj.content);
+        return;
+    }
+    // header.title
+    if (obj.header && typeof obj.header === 'object') {
+        const header = obj.header;
+        if (header.title)
+            visit(header.title, out);
+    }
+    // text / content on common elements (div, button, note, etc.)
+    if (obj.text)
+        visit(obj.text, out);
+    // button / select option label (typed as button)
+    if (typeof tag === 'string' && tag === 'button') {
+        const text = obj.text;
+        if (text)
+            visit(text, out);
+    }
+    // form fields: label, placeholder, options
+    if (obj.label)
+        visit(obj.label, out);
+    if (obj.placeholder)
+        visit(obj.placeholder, out);
+    if (Array.isArray(obj.options)) {
+        for (const opt of obj.options) {
+            const o = opt;
+            if (o === null || o === void 0 ? void 0 : o.text)
+                visit(o.text, out);
+        }
+    }
+    // column / row containers
+    if (Array.isArray(obj.elements))
+        for (const el of obj.elements)
+            visit(el, out);
+    if (Array.isArray(obj.fields))
+        for (const f of obj.fields)
+            visit(f, out);
+    if (Array.isArray(obj.actions))
+        for (const a of obj.actions)
+            visit(a, out);
+    if (Array.isArray(obj.columns))
+        for (const c of obj.columns)
+            visit(c, out);
+    // common nested shapes for v2 card body
+    if (obj.body)
+        visit(obj.body, out);
+}
+
+const convertInteractive = (raw, _ctx) => __awaiter(void 0, void 0, void 0, function* () {
+    const parsed = safeParse(raw);
+    if (parsed == null || typeof parsed !== 'object') {
+        return { content: '[interactive card]', resources: [] };
+    }
+    const pieces = walkCard(parsed);
+    if (pieces.length === 0) {
+        return { content: '[interactive card]', resources: [] };
+    }
+    // Dedup adjacent duplicates while preserving order
+    const seen = new Set();
+    const out = [];
+    for (const p of pieces) {
+        const key = p.trim();
+        if (!key || seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(key);
+    }
+    return { content: out.join('\n'), resources: [] };
+});
+
+const convertLocation = (raw, _ctx) => __awaiter(void 0, void 0, void 0, function* () {
+    const parsed = safeParse(raw);
+    const name = parsed === null || parsed === void 0 ? void 0 : parsed.name;
+    const lat = parsed === null || parsed === void 0 ? void 0 : parsed.latitude;
+    const lng = parsed === null || parsed === void 0 ? void 0 : parsed.longitude;
+    const nameAttr = name ? ` name="${escapeAttr(name)}"` : '';
+    const coordsAttr = lat && lng ? ` coords="lat:${lat},lng:${lng}"` : '';
+    return { content: `<location${nameAttr}${coordsAttr}/>`, resources: [] };
+});
+
+const MAX_ITEMS = 50;
+const convertMergeForward = (_raw, ctx) => __awaiter(void 0, void 0, void 0, function* () {
+    var _a;
+    const { messageId, fetchSubMessages, dispatch } = ctx;
+    if (!fetchSubMessages || !dispatch) {
+        return { content: '<forwarded_messages/>', resources: [] };
+    }
+    let items;
+    try {
+        items = yield fetchSubMessages(messageId);
+    }
+    catch (_b) {
+        return { content: '<forwarded_messages/>', resources: [] };
+    }
+    if (!items || items.length === 0) {
+        return { content: '<forwarded_messages/>', resources: [] };
+    }
+    const capped = items.slice(0, MAX_ITEMS);
+    const truncated = items.length > MAX_ITEMS;
+    // Pre-warm sender name cache in one batch call.
+    if (ctx.batchResolveNames) {
+        const senderIds = new Set();
+        for (const it of capped) {
+            const sid = (_a = it.sender) === null || _a === void 0 ? void 0 : _a.id;
+            if (sid && it.message_id !== messageId)
+                senderIds.add(sid);
+        }
+        if (senderIds.size > 0) {
+            try {
+                yield ctx.batchResolveNames([...senderIds]);
+            }
+            catch (_c) {
+                // best effort
+            }
+        }
+    }
+    const childrenMap = buildChildrenMap(capped, messageId);
+    const content = yield formatSubTree(messageId, childrenMap, ctx, truncated);
+    return { content, resources: [] };
+});
+function buildChildrenMap(items, rootId) {
+    var _a;
+    const map = new Map();
+    for (const it of items) {
+        if (it.message_id === rootId && !it.upper_message_id)
+            continue;
+        const pid = (_a = it.upper_message_id) !== null && _a !== void 0 ? _a : rootId;
+        let arr = map.get(pid);
+        if (!arr) {
+            arr = [];
+            map.set(pid, arr);
+        }
+        arr.push(it);
+    }
+    for (const arr of map.values()) {
+        arr.sort((a, b) => {
+            var _a, _b;
+            const ta = parseInt(String((_a = a.create_time) !== null && _a !== void 0 ? _a : '0'), 10);
+            const tb = parseInt(String((_b = b.create_time) !== null && _b !== void 0 ? _b : '0'), 10);
+            return ta - tb;
+        });
+    }
+    return map;
+}
+function formatSubTree(parentId, map, ctx, truncated = false) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const children = map.get(parentId);
+        if (!children || children.length === 0)
+            return '<forwarded_messages/>';
+        const parts = [];
+        for (const item of children) {
+            try {
+                const sub = yield renderItem(item, map, ctx);
+                if (sub)
+                    parts.push(sub);
+            }
+            catch (_a) {
+                // skip bad item
+            }
+        }
+        if (parts.length === 0)
+            return '<forwarded_messages/>';
+        const body = parts.join('\n');
+        const footer = truncated ? '\n... (truncated)' : '';
+        return `<forwarded_messages>\n${body}${footer}\n</forwarded_messages>`;
+    });
+}
+function renderItem(item, map, ctx) {
+    var _a, _b, _c, _d, _e, _f, _g, _h;
+    return __awaiter(this, void 0, void 0, function* () {
+        const msgType = (_a = item.msg_type) !== null && _a !== void 0 ? _a : 'text';
+        const senderId = (_c = (_b = item.sender) === null || _b === void 0 ? void 0 : _b.id) !== null && _c !== void 0 ? _c : 'unknown';
+        const createMs = parseInt(String((_d = item.create_time) !== null && _d !== void 0 ? _d : '0'), 10);
+        const timestamp = createMs > 0 ? formatRFC3339Beijing(createMs) : 'unknown';
+        const displayName = (_f = (_e = ctx.resolveUserName) === null || _e === void 0 ? void 0 : _e.call(ctx, senderId)) !== null && _f !== void 0 ? _f : senderId;
+        let content;
+        if (msgType === 'merge_forward') {
+            // Nested forward — recurse locally without another API call.
+            const nestedId = item.message_id;
+            content = nestedId ? yield formatSubTree(nestedId, map, ctx) : '<forwarded_messages/>';
+        }
+        else {
+            const rawContent = (_h = (_g = item.body) === null || _g === void 0 ? void 0 : _g.content) !== null && _h !== void 0 ? _h : '{}';
+            if (!ctx.dispatch) {
+                content = rawContent;
+            }
+            else {
+                const r = yield ctx.dispatch(rawContent, msgType, ctx);
+                content = r.content;
+            }
+        }
+        const indented = indentLines(content, '    ');
+        return `[${timestamp}] ${displayName}:\n${indented}`;
+    });
+}
+
+const convertPost = (raw, ctx) => __awaiter(void 0, void 0, void 0, function* () {
+    var _a;
+    const rawParsed = safeParse(raw);
+    if (rawParsed == null || typeof rawParsed !== 'object') {
+        return { content: '[rich text message]', resources: [] };
+    }
+    const body = unwrapLocale(rawParsed);
+    if (!body)
+        return { content: '[rich text message]', resources: [] };
+    const resources = [];
+    const lines = [];
+    if (body.title) {
+        lines.push(`**${body.title}**`);
+        lines.push('');
+    }
+    for (const paragraph of (_a = body.content) !== null && _a !== void 0 ? _a : []) {
+        if (!Array.isArray(paragraph))
+            continue;
+        let line = '';
+        for (const el of paragraph) {
+            line += renderElement(el, ctx, resources);
+        }
+        lines.push(line);
+    }
+    const content = lines.join('\n').trim() || '[rich text message]';
+    return { content, resources };
+});
+function renderElement(el, ctx, resources) {
+    var _a, _b, _c, _d, _e, _f, _g;
+    switch (el.tag) {
+        case 'text':
+            return applyStyle((_a = el.text) !== null && _a !== void 0 ? _a : '', el.style);
+        case 'a': {
+            const label = (_c = (_b = el.text) !== null && _b !== void 0 ? _b : el.href) !== null && _c !== void 0 ? _c : '';
+            return el.href ? `[${label}](${el.href})` : label;
+        }
+        case 'at': {
+            const userId = (_d = el.user_id) !== null && _d !== void 0 ? _d : '';
+            if (userId === 'all' || userId === 'all_members')
+                return '@all';
+            // Prefer placeholder key so resolveMentions handles it uniformly
+            const info = ctx.mentionsByOpenId.get(userId);
+            if (info)
+                return info.key;
+            return el.user_name ? `@${el.user_name}` : `@${userId}`;
+        }
+        case 'img': {
+            if (el.image_key) {
+                resources.push({ type: 'image', fileKey: el.image_key });
+                return `![image](${el.image_key})`;
+            }
+            return '';
+        }
+        case 'media': {
+            if (el.file_key) {
+                resources.push({ type: 'file', fileKey: el.file_key });
+                return `<file key="${el.file_key}"/>`;
+            }
+            return '';
+        }
+        case 'code_block': {
+            const lang = (_e = el.language) !== null && _e !== void 0 ? _e : '';
+            const code = (_f = el.text) !== null && _f !== void 0 ? _f : '';
+            return `\n\`\`\`${lang}\n${code}\n\`\`\`\n`;
+        }
+        case 'hr':
+            return '\n---\n';
+        default:
+            return (_g = el.text) !== null && _g !== void 0 ? _g : '';
+    }
+}
+
+const convertShareChat = (raw, _ctx) => __awaiter(void 0, void 0, void 0, function* () {
+    var _a;
+    const parsed = safeParse(raw);
+    return {
+        content: `<group_card id="${(_a = parsed === null || parsed === void 0 ? void 0 : parsed.chat_id) !== null && _a !== void 0 ? _a : ''}"/>`,
+        resources: [],
+    };
+});
+const convertShareUser = (raw, _ctx) => __awaiter(void 0, void 0, void 0, function* () {
+    var _b;
+    const parsed = safeParse(raw);
+    return {
+        content: `<contact_card id="${(_b = parsed === null || parsed === void 0 ? void 0 : parsed.user_id) !== null && _b !== void 0 ? _b : ''}"/>`,
+        resources: [],
+    };
+});
+
+const convertSticker = (raw, _ctx) => __awaiter(void 0, void 0, void 0, function* () {
+    const parsed = safeParse(raw);
+    const fileKey = parsed === null || parsed === void 0 ? void 0 : parsed.file_key;
+    if (!fileKey)
+        return { content: '[sticker]', resources: [] };
+    const resources = [{ type: 'sticker', fileKey }];
+    return { content: `<sticker key="${fileKey}"/>`, resources };
+});
+
+const convertSystem = (raw, _ctx) => __awaiter(void 0, void 0, void 0, function* () {
+    const parsed = safeParse(raw);
+    if (!parsed || !parsed.template) {
+        return { content: '[system message]', resources: [] };
+    }
+    const out = parsed.template.replace(/\{([a-z_]+)\}/g, (match, name) => {
+        const val = parsed[name];
+        if (Array.isArray(val))
+            return val.join(', ');
+        if (typeof val === 'string')
+            return val;
+        if (val == null)
+            return '';
+        return match;
+    });
+    return { content: out.trim() || '[system message]', resources: [] };
+});
+
+const convertText = (raw, _ctx) => __awaiter(void 0, void 0, void 0, function* () {
+    var _a;
+    const parsed = safeParse(raw);
+    return { content: (_a = parsed === null || parsed === void 0 ? void 0 : parsed.text) !== null && _a !== void 0 ? _a : '', resources: [] };
+});
+
+const convertTodo = (raw, _ctx) => __awaiter(void 0, void 0, void 0, function* () {
+    const parsed = safeParse(raw);
+    if (!(parsed === null || parsed === void 0 ? void 0 : parsed.summary))
+        return { content: '<todo>\n[todo]\n</todo>', resources: [] };
+    const lines = [];
+    if (parsed.summary.title)
+        lines.push(parsed.summary.title);
+    const bodyText = extractPostPlainText(parsed.summary.content);
+    if (bodyText)
+        lines.push(bodyText);
+    const due = millisToDatetime(parsed.due_time);
+    if (due)
+        lines.push(`Due: ${due}`);
+    if (lines.length === 0)
+        return { content: '<todo>\n[todo]\n</todo>', resources: [] };
+    return { content: `<todo>\n${lines.join('\n')}\n</todo>`, resources: [] };
+});
+function extractPostPlainText(blocks) {
+    if (!blocks)
+        return '';
+    const lines = [];
+    for (const paragraph of blocks) {
+        if (!Array.isArray(paragraph))
+            continue;
+        const parts = [];
+        for (const el of paragraph) {
+            if (el.tag === 'text' && el.text)
+                parts.push(el.text);
+            else if (el.tag === 'a' && el.text)
+                parts.push(el.text);
+        }
+        if (parts.length > 0)
+            lines.push(parts.join(''));
+    }
+    return lines.join('\n');
+}
+
+const convertUnknown = (raw, _ctx) => __awaiter(void 0, void 0, void 0, function* () {
+    const parsed = safeParse(raw);
+    if (parsed && typeof parsed.text === 'string') {
+        return { content: parsed.text, resources: [] };
+    }
+    return { content: '[unsupported message]', resources: [] };
+});
+
+const convertVideo = (raw, _ctx) => __awaiter(void 0, void 0, void 0, function* () {
+    const parsed = safeParse(raw);
+    const fileKey = parsed === null || parsed === void 0 ? void 0 : parsed.file_key;
+    if (!fileKey)
+        return { content: '[video]', resources: [] };
+    const nameAttr = (parsed === null || parsed === void 0 ? void 0 : parsed.file_name) ? ` name="${escapeAttr(parsed.file_name)}"` : '';
+    const durStr = formatDuration(parsed === null || parsed === void 0 ? void 0 : parsed.duration);
+    const durAttr = durStr ? ` duration="${durStr}"` : '';
+    const content = `<video key="${fileKey}"${nameAttr}${durAttr}/>`;
+    const resources = [
+        {
+            type: 'video',
+            fileKey,
+            fileName: parsed === null || parsed === void 0 ? void 0 : parsed.file_name,
+            durationMs: parsed === null || parsed === void 0 ? void 0 : parsed.duration,
+            coverImageKey: parsed === null || parsed === void 0 ? void 0 : parsed.image_key,
+        },
+    ];
+    return { content, resources };
+});
+
+const convertVideoChat = (raw, _ctx) => __awaiter(void 0, void 0, void 0, function* () {
+    const parsed = safeParse(raw);
+    if (!parsed) {
+        return { content: '<meeting>\n[video chat]\n</meeting>', resources: [] };
+    }
+    const lines = [];
+    if (parsed.topic)
+        lines.push(`📹 ${parsed.topic}`);
+    const start = millisToDatetime(parsed.start_time);
+    if (start)
+        lines.push(`🕙 ${start}`);
+    const inner = lines.length > 0 ? lines.join('\n') : '[video chat]';
+    return { content: `<meeting>\n${inner}\n</meeting>`, resources: [] };
+});
+
+const convertVote = (raw, _ctx) => __awaiter(void 0, void 0, void 0, function* () {
+    var _a, _b;
+    const parsed = safeParse(raw);
+    if (!parsed || (!parsed.topic && !((_a = parsed.options) === null || _a === void 0 ? void 0 : _a.length))) {
+        return { content: '<vote>\n[vote]\n</vote>', resources: [] };
+    }
+    const lines = [];
+    if (parsed.topic)
+        lines.push(parsed.topic);
+    for (const opt of (_b = parsed.options) !== null && _b !== void 0 ? _b : [])
+        lines.push(`• ${opt}`);
+    return { content: `<vote>\n${lines.join('\n')}\n</vote>`, resources: [] };
+});
+
+const converters = new Map([
+    ['text', convertText],
+    ['post', convertPost],
+    ['image', convertImage],
+    ['file', convertFile],
+    ['audio', convertAudio],
+    ['video', convertVideo],
+    ['media', convertVideo],
+    ['sticker', convertSticker],
+    ['interactive', convertInteractive],
+    ['merge_forward', convertMergeForward],
+    ['share_chat', convertShareChat],
+    ['share_user', convertShareUser],
+    ['location', convertLocation],
+    ['system', convertSystem],
+    ['vote', convertVote],
+    ['todo', convertTodo],
+    ['calendar', convertCalendar],
+    ['general_calendar', convertGeneralCalendar],
+    ['share_calendar_event', convertShareCalendarEvent],
+    ['folder', convertFolder],
+    ['hongbao', convertHongbao],
+    ['video_chat', convertVideoChat],
+]);
+/**
+ * Dispatch a message content to the matching converter, with uniform error
+ * containment — any thrown error is trapped and the fallback converter is
+ * invoked instead so that normalization never fails catastrophically.
+ */
+function dispatchConvert(raw, msgType, ctx) {
+    var _a;
+    return __awaiter(this, void 0, void 0, function* () {
+        const fn = (_a = converters.get(msgType)) !== null && _a !== void 0 ? _a : convertUnknown;
+        try {
+            return yield fn(raw, ctx);
+        }
+        catch (_b) {
+            return convertUnknown(raw);
+        }
+    });
+}
+
+function normalizeCardAction(event) {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m;
+    const messageId = (_b = (_a = event.context) === null || _a === void 0 ? void 0 : _a.open_message_id) !== null && _b !== void 0 ? _b : event.open_message_id;
+    const chatId = (_d = (_c = event.context) === null || _c === void 0 ? void 0 : _c.open_chat_id) !== null && _d !== void 0 ? _d : event.open_chat_id;
+    const operatorOpenId = (_e = event.operator) === null || _e === void 0 ? void 0 : _e.open_id;
+    if (!messageId || !chatId || !operatorOpenId)
+        return null;
+    return {
+        messageId,
+        chatId,
+        operator: {
+            openId: operatorOpenId,
+            userId: (_f = event.operator) === null || _f === void 0 ? void 0 : _f.user_id,
+            name: (_g = event.operator) === null || _g === void 0 ? void 0 : _g.name,
+        },
+        action: {
+            value: (_h = event.action) === null || _h === void 0 ? void 0 : _h.value,
+            tag: (_k = (_j = event.action) === null || _j === void 0 ? void 0 : _j.tag) !== null && _k !== void 0 ? _k : 'unknown',
+            name: (_l = event.action) === null || _l === void 0 ? void 0 : _l.name,
+            option: (_m = event.action) === null || _m === void 0 ? void 0 : _m.option,
+        },
+    };
+}
+
+function normalizeReaction(event, action) {
+    var _a, _b, _c, _d;
+    const messageId = event.message_id;
+    const emojiType = (_a = event.reaction_type) === null || _a === void 0 ? void 0 : _a.emoji_type;
+    const operatorOpenId = (_b = event.user_id) === null || _b === void 0 ? void 0 : _b.open_id;
+    if (!messageId || !emojiType || !operatorOpenId)
+        return null;
+    const actionTimeStr = event.action_time;
+    const actionTime = actionTimeStr ? parseInt(actionTimeStr, 10) : undefined;
+    return {
+        messageId,
+        operator: {
+            openId: operatorOpenId,
+            userId: (_d = (_c = event.user_id) === null || _c === void 0 ? void 0 : _c.user_id) !== null && _d !== void 0 ? _d : undefined,
+        },
+        emojiType,
+        action,
+        actionTime: actionTime != null && Number.isFinite(actionTime) ? actionTime : undefined,
+    };
+}
+
+function normalizeBotAdded(event, opts) {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j;
+    const chatId = event.chat_id;
+    const operatorOpenId = (_a = event.operator_id) === null || _a === void 0 ? void 0 : _a.open_id;
+    if (!chatId || !operatorOpenId)
+        return null;
+    const botName = (_f = (_d = (_b = event.name) !== null && _b !== void 0 ? _b : (_c = event.i18n_names) === null || _c === void 0 ? void 0 : _c.zh_cn) !== null && _d !== void 0 ? _d : (_e = event.i18n_names) === null || _e === void 0 ? void 0 : _e.en_us) !== null && _f !== void 0 ? _f : (_g = event.i18n_names) === null || _g === void 0 ? void 0 : _g.ja_jp;
+    return {
+        chatId,
+        operator: {
+            openId: operatorOpenId,
+            userId: (_j = (_h = event.operator_id) === null || _h === void 0 ? void 0 : _h.user_id) !== null && _j !== void 0 ? _j : undefined,
+        },
+        botName,
+        external: event.external,
+        raw: (opts === null || opts === void 0 ? void 0 : opts.includeRaw) ? event : undefined,
+    };
+}
+
+function normalizeComment(event, opts) {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o;
+    const fileToken = (_a = event.file_token) !== null && _a !== void 0 ? _a : (_b = event.notice_meta) === null || _b === void 0 ? void 0 : _b.file_token;
+    const fileType = (_c = event.file_type) !== null && _c !== void 0 ? _c : (_d = event.notice_meta) === null || _d === void 0 ? void 0 : _d.file_type;
+    const commentId = event.comment_id;
+    const userId = (_f = (_e = event.notice_meta) === null || _e === void 0 ? void 0 : _e.from_user_id) !== null && _f !== void 0 ? _f : event.user_id;
+    const operatorOpenId = userId === null || userId === void 0 ? void 0 : userId.open_id;
+    if (!fileToken || !fileType || !commentId || !operatorOpenId)
+        return null;
+    const tsStr = (_j = (_g = event.create_time) !== null && _g !== void 0 ? _g : (_h = event.notice_meta) === null || _h === void 0 ? void 0 : _h.timestamp) !== null && _j !== void 0 ? _j : event.action_time;
+    const timestamp = tsStr ? parseInt(tsStr, 10) : Date.now();
+    return {
+        fileToken,
+        fileType,
+        commentId,
+        replyId: event.reply_id,
+        operator: {
+            openId: operatorOpenId,
+            userId: (_k = userId === null || userId === void 0 ? void 0 : userId.user_id) !== null && _k !== void 0 ? _k : undefined,
+            unionId: userId === null || userId === void 0 ? void 0 : userId.union_id,
+        },
+        mentionedBot: Boolean((_o = (_l = event.is_mentioned) !== null && _l !== void 0 ? _l : (_m = event.notice_meta) === null || _m === void 0 ? void 0 : _m.is_mentioned) !== null && _o !== void 0 ? _o : event.is_mention),
+        timestamp: Number.isFinite(timestamp) ? timestamp : Date.now(),
+        raw: (opts === null || opts === void 0 ? void 0 : opts.includeRaw) ? event : undefined,
+    };
+}
+
+/**
+ * Normalize a raw Feishu message event into a NormalizedMessage.
+ *
+ * Pipeline:
+ *   1. Extract mentions → build key/openId maps + bot detection
+ *   2. For `interactive` type, fetch full v2 card content if capability available
+ *   3. Build ConvertContext with injected capabilities
+ *   4. Dispatch to the matching converter (uniform error containment inside)
+ *   5. Run resolveMentions second pass — replace placeholders with @name
+ *   6. Assemble and return NormalizedMessage
+ */
+function normalize(event, opts) {
+    var _a, _b, _c, _d, _e;
+    return __awaiter(this, void 0, void 0, function* () {
+        const msg = event.message;
+        const botOpenId = (_a = opts.botIdentity) === null || _a === void 0 ? void 0 : _a.openId;
+        const { mentions, mentionsByOpenId, mentionList, mentionAll: mentionAllFromRaw, mentionedBot } = extractMentions(msg.mentions, botOpenId);
+        // Feishu frequently omits the `mentions` array even when the message
+        // contains `@所有人` — the placeholder `@_all` stays inline in content.
+        // Fall back to a content-level scan so policy gating (respondToMentionAll)
+        // and downstream consumers see a truthy mentionAll in that case.
+        const mentionAll = mentionAllFromRaw || detectMentionAllInContent(msg.content);
+        const ctx = {
+            messageId: msg.message_id,
+            botOpenId,
+            mentions,
+            mentionsByOpenId,
+            stripBotMentions: (_b = opts.stripBotMentions) !== null && _b !== void 0 ? _b : true,
+            fetchSubMessages: opts.fetchSubMessages,
+            resolveUserName: opts.resolveUserName,
+            batchResolveNames: opts.batchResolveNames,
+            dispatch: dispatchConvert,
+        };
+        const { content: rawContent, resources } = yield dispatchConvert(msg.content, msg.message_type, ctx);
+        const content = resolveMentions(rawContent, ctx);
+        const senderOpenId = event.sender.sender_id.open_id;
+        const senderFallbackId = (_d = (_c = event.sender.sender_id.user_id) !== null && _c !== void 0 ? _c : event.sender.sender_id.union_id) !== null && _d !== void 0 ? _d : '';
+        const senderId = senderOpenId !== null && senderOpenId !== void 0 ? senderOpenId : senderFallbackId;
+        const senderName = senderOpenId ? (_e = opts.resolveSenderName) === null || _e === void 0 ? void 0 : _e.call(opts, senderOpenId) : undefined;
+        const createMs = msg.create_time ? parseInt(msg.create_time, 10) : 0;
+        return {
+            messageId: msg.message_id,
+            chatId: msg.chat_id,
+            chatType: msg.chat_type,
+            senderId,
+            senderName,
+            content,
+            rawContentType: msg.message_type,
+            resources,
+            mentions: mentionList,
+            mentionAll,
+            mentionedBot,
+            rootId: msg.root_id,
+            threadId: msg.thread_id,
+            replyToMessageId: msg.parent_id,
+            createTime: Number.isFinite(createMs) ? createMs : 0,
+            raw: opts.includeRaw ? event : undefined,
+        };
+    });
+}
+/**
+ * Detect `@_all` placeholder inside a raw Feishu content JSON string without
+ * parsing. We deliberately search the serialized form (not the parsed text),
+ * because the placeholder can appear in a `text` field (text/post) or inside
+ * nested content arrays (post). The placeholder is bounded by non-word chars
+ * on the right (whitespace, quote, punctuation) — on the left `@` is already
+ * a non-word char so no explicit boundary is needed.
+ */
+function detectMentionAllInContent(content) {
+    if (!content)
+        return false;
+    return /@_all\b/.test(content);
+}
+
+class LarkChannel {
+    constructor(opts) {
+        var _a, _b, _c, _d, _e, _f, _g;
+        this.handlers = {};
+        this.connected = false;
+        this.opts = opts;
+        this.logger = new LoggerProxy((_a = opts.loggerLevel) !== null && _a !== void 0 ? _a : LoggerLevel.info, (_b = opts.logger) !== null && _b !== void 0 ? _b : defaultLogger);
+        this.rawClient = new Client({
+            appId: opts.appId,
+            appSecret: opts.appSecret,
+            domain: (_c = opts.domain) !== null && _c !== void 0 ? _c : Domain.Feishu,
+            cache: opts.cache,
+            httpInstance: opts.httpInstance,
+            logger: opts.logger,
+            loggerLevel: opts.loggerLevel,
+            source: opts.source,
+        });
+        this.dispatcher = new EventDispatcher({
+            verificationToken: (_d = opts.webhook) === null || _d === void 0 ? void 0 : _d.verificationToken,
+            encryptKey: (_e = opts.webhook) === null || _e === void 0 ? void 0 : _e.encryptKey,
+            cache: opts.cache,
+            logger: opts.logger,
+            loggerLevel: opts.loggerLevel,
+        });
+        this.sender = new OutboundSender(this.rawClient, (_f = opts.outbound) !== null && _f !== void 0 ? _f : {}, this.logger);
+        this.safety = new SafetyPipeline({
+            config: opts.safety,
+            policy: opts.policy,
+            cache: (_g = opts.cache) !== null && _g !== void 0 ? _g : internalCache,
+            logger: this.logger,
+            onReject: (evt) => { var _a, _b; (_b = (_a = this.handlers).reject) === null || _b === void 0 ? void 0 : _b.call(_a, evt); },
+            onMessage: (merged) => __awaiter(this, void 0, void 0, function* () {
+                const handler = this.handlers.message;
+                if (handler)
+                    yield handler(merged);
+            }),
+        });
+    }
+    // ─── lifecycle ──────────────────────────────────────────
+    connect() {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (this.connectPromise)
+                return this.connectPromise;
+            this.connectPromise = this.doConnect().catch((err) => {
+                this.connectPromise = undefined;
+                throw err;
+            });
+            return this.connectPromise;
+        });
+    }
+    doConnect() {
+        var _a;
+        return __awaiter(this, void 0, void 0, function* () {
+            this.botIdentity = yield this.fetchBotIdentity();
+            this.safety.setBotIdentity(this.botIdentity);
+            this.registerDispatcherHandlers();
+            const transport = (_a = this.opts.transport) !== null && _a !== void 0 ? _a : 'websocket';
+            if (transport === 'websocket') {
+                yield this.connectWebSocket(15000);
+            }
+            // webhook transport wiring is external: user plugs this.dispatcher into
+            // their HTTP handler via the existing adaptor modules.
+            this.connected = true;
+        });
+    }
+    /**
+     * Construct the underlying WSClient and wait for its `onReady` callback —
+     * so `connect()` only resolves after the first WebSocket handshake
+     * actually succeeds. Rejects on `onError` or if the handshake doesn't
+     * complete within `timeoutMs`.
+     *
+     * Also wires `onReconnecting` / `onReconnected` callbacks to emit the
+     * corresponding public events.
+     */
+    connectWebSocket(timeoutMs) {
+        return new Promise((resolve, reject) => {
+            var _a;
+            let settled = false;
+            const timer = setTimeout(() => {
+                if (settled)
+                    return;
+                settled = true;
+                reject(new LarkChannelError('not_connected', `WebSocket handshake did not complete within ${timeoutMs}ms`));
+            }, timeoutMs);
+            this.rawWsClient = new WSClient({
+                appId: this.opts.appId,
+                appSecret: this.opts.appSecret,
+                domain: (_a = this.opts.domain) !== null && _a !== void 0 ? _a : Domain.Feishu,
+                logger: this.opts.logger,
+                loggerLevel: this.opts.loggerLevel,
+                httpInstance: this.opts.httpInstance,
+                autoReconnect: true,
+                source: this.opts.source,
+                onReady: () => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    clearTimeout(timer);
+                    resolve();
+                },
+                onError: (err) => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    clearTimeout(timer);
+                    reject(new LarkChannelError('not_connected', `WebSocket connect failed: ${err.message}`, { cause: err }));
+                },
+                onReconnecting: () => { var _a, _b; return (_b = (_a = this.handlers).reconnecting) === null || _b === void 0 ? void 0 : _b.call(_a); },
+                onReconnected: () => { var _a, _b; return (_b = (_a = this.handlers).reconnected) === null || _b === void 0 ? void 0 : _b.call(_a); },
+            });
+            this.rawWsClient.start({ eventDispatcher: this.dispatcher });
+        });
+    }
+    disconnect() {
+        var _a;
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!this.connected)
+                return;
+            try {
+                (_a = this.rawWsClient) === null || _a === void 0 ? void 0 : _a.close({});
+            }
+            catch ( /* best effort */_b) { /* best effort */ }
+            try {
+                yield this.safety.dispose();
+            }
+            catch ( /* best effort */_c) { /* best effort */ }
+            this.connected = false;
+            this.connectPromise = undefined;
+        });
+    }
+    on(nameOrMap, handler) {
+        if (typeof nameOrMap === 'string') {
+            return this.attachSingle(nameOrMap, handler);
+        }
+        const unsubs = [];
+        Object.keys(nameOrMap).forEach((k) => {
+            const fn = nameOrMap[k];
+            if (fn)
+                unsubs.push(this.attachSingle(k, fn));
+        });
+        return () => unsubs.forEach((u) => u());
+    }
+    attachSingle(name, handler) {
+        if (this.handlers[name]) {
+            this.logger.warn(`channel: handler for "${name}" is being overwritten`);
+        }
+        this.handlers[name] = handler;
+        return () => {
+            if (this.handlers[name] === handler)
+                delete this.handlers[name];
+        };
+    }
+    // ─── outbound ──────────────────────────────────────────
+    send(to, input, opts) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.sender.send(to, input, opts);
+        });
+    }
+    stream(to, input, opts) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.sender.stream(to, input, opts);
+        });
+    }
+    // ─── low-level ─────────────────────────────────────────
+    updateCard(messageId, card) {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this.sender.patchCard(messageId, card);
+        });
+    }
+    /**
+     * Edit an already-sent message's text/post content. Uses `im.v1.message.update`
+     * which (per Feishu docs) only supports editing text and rich-text (post)
+     * messages. For cards, use {@link updateCard} instead — a wrong attempt to
+     * use this on a card would hit the same API and fail with a clearer
+     * Feishu-side error.
+     */
+    editMessage(messageId, text) {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this.rawClient.im.v1.message.update({
+                path: { message_id: messageId },
+                data: {
+                    msg_type: 'text',
+                    content: JSON.stringify({ text }),
+                },
+            });
+        });
+    }
+    recallMessage(messageId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this.rawClient.im.v1.message.delete({
+                path: { message_id: messageId },
+            });
+        });
+    }
+    /**
+     * Add an emoji reaction to a message. Returns the `reaction_id` Feishu
+     * assigned — stash it if you want to {@link removeReaction} later,
+     * since the raw `im.message.reaction.*_v1` events don't carry the id.
+     * Only the bot's own reactions can be removed.
+     */
+    addReaction(messageId, emojiType) {
+        var _a, _b;
+        return __awaiter(this, void 0, void 0, function* () {
+            const r = yield this.rawClient.im.v1.messageReaction.create({
+                path: { message_id: messageId },
+                data: { reaction_type: { emoji_type: emojiType } },
+            });
+            const rid = (_b = (_a = r === null || r === void 0 ? void 0 : r.data) === null || _a === void 0 ? void 0 : _a.reaction_id) !== null && _b !== void 0 ? _b : r === null || r === void 0 ? void 0 : r.reaction_id;
+            if (!rid) {
+                throw new LarkChannelError('unknown', 'messageReaction.create returned no reaction_id');
+            }
+            return rid;
+        });
+    }
+    /**
+     * Remove a reaction by its `reaction_id` (the value returned from
+     * {@link addReaction}). Only the bot's own reactions can be removed —
+     * removing a user-added reaction will fail with a Feishu permission
+     * error.
+     */
+    removeReaction(messageId, reactionId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this.rawClient.im.v1.messageReaction.delete({
+                path: { message_id: messageId, reaction_id: reactionId },
+            });
+        });
+    }
+    /**
+     * Convenience: remove the bot's reaction on `messageId` matching
+     * `emojiType`, without needing the `reaction_id`. Lists the message's
+     * reactions filtered by emoji, picks the one added by this bot
+     * (operator_type === 'app'), and deletes it. Returns `true` if a
+     * matching reaction was found and deleted, `false` otherwise (including
+     * the case where the bot never added that emoji).
+     */
+    removeReactionByEmoji(messageId, emojiType) {
+        var _a, _b;
+        return __awaiter(this, void 0, void 0, function* () {
+            const r = yield this.rawClient.im.v1.messageReaction.list({
+                path: { message_id: messageId },
+                params: { reaction_type: emojiType, page_size: 50 },
+            });
+            const items = (_b = (_a = r === null || r === void 0 ? void 0 : r.data) === null || _a === void 0 ? void 0 : _a.items) !== null && _b !== void 0 ? _b : [];
+            const mine = items.find((it) => { var _a; return ((_a = it.operator) === null || _a === void 0 ? void 0 : _a.operator_type) === 'app'; });
+            if (!(mine === null || mine === void 0 ? void 0 : mine.reaction_id))
+                return false;
+            yield this.removeReaction(messageId, mine.reaction_id);
+            return true;
+        });
+    }
+    downloadResource(fileKey, type) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (type === 'image') {
+                const r = yield this.rawClient.im.v1.image.get({
+                    path: { image_key: fileKey },
+                });
+                return yield bufferFromStream(r);
+            }
+            const r = yield this.rawClient.im.v1.file.get({
+                path: { file_key: fileKey },
+            });
+            return yield bufferFromStream(r);
+        });
+    }
+    getChatInfo(chatId) {
+        var _a, _b;
+        return __awaiter(this, void 0, void 0, function* () {
+            const r = yield this.rawClient.im.v1.chat.get({
+                path: { chat_id: chatId },
+            });
+            const d = (_a = r.data) !== null && _a !== void 0 ? _a : {};
+            return {
+                chatId,
+                name: d.name,
+                description: d.description,
+                chatType: (_b = d.chat_mode) !== null && _b !== void 0 ? _b : 'group',
+                ownerId: d.owner_id,
+                memberCount: d.user_count,
+            };
+        });
+    }
+    // ─── runtime config ────────────────────────────────────
+    updatePolicy(partial) {
+        this.safety.updatePolicy(partial);
+    }
+    getPolicy() {
+        return this.safety.getPolicy();
+    }
+    // ─── internals: bot identity & dispatch wiring ────────
+    fetchBotIdentity() {
+        var _a;
+        return __awaiter(this, void 0, void 0, function* () {
+            // Standard Feishu API: GET /open-apis/bot/v3/info
+            // Returns: { code, msg, bot: { open_id, app_name, avatar_url, ... } }
+            let lastError;
+            try {
+                const r = yield this.rawClient.request({
+                    url: '/open-apis/bot/v3/info',
+                    method: 'GET',
+                });
+                const bot = r.bot;
+                if (bot === null || bot === void 0 ? void 0 : bot.open_id) {
+                    return { openId: bot.open_id, name: (_a = bot.app_name) !== null && _a !== void 0 ? _a : 'bot' };
+                }
+                lastError = new Error(`bot/v3/info response missing open_id: ${JSON.stringify(r).slice(0, 200)}`);
+            }
+            catch (e) {
+                lastError = e;
+            }
+            // Let the shared error classifier decide: 401/403 / feishu auth codes
+            // → permission_denied; rate_limited / send_timeout pass through;
+            // everything else falls back to `not_connected` (the genuine
+            // "couldn't reach the API" bucket). Without this, all connect
+            // failures collapse to `not_connected`, making auth errors
+            // indistinguishable from network errors.
+            const classified = classifyError(lastError);
+            const code = classified.code === 'unknown' ? 'not_connected' : classified.code;
+            throw new LarkChannelError(code, 'could not resolve bot identity via /open-apis/bot/v3/info — required for channel to function', { cause: lastError });
+        });
+    }
+    registerDispatcherHandlers() {
+        // `im.v1.message.get(mid)` on a merge_forward message returns
+        // `data.items[]` as a flat list: the parent message first (no
+        // `upper_message_id`) followed by every descendant, each with
+        // `upper_message_id` pointing at its direct parent. That is
+        // exactly what `convertMergeForward` / `buildChildrenMap` consume,
+        // so the converter tree-builds correctly without further work.
+        // (Earlier attempts used `message.list` with
+        // `container_id_type: 'message'`, which Feishu rejects — 'message'
+        // isn't a valid container type.)
+        const fetchSubMessages = (mid) => __awaiter(this, void 0, void 0, function* () {
+            var _a, _b, _c, _d;
+            try {
+                const r = yield this.rawClient.im.v1.message.get({
+                    path: { message_id: mid },
+                });
+                const items = (_b = (_a = r.data) === null || _a === void 0 ? void 0 : _a.items) !== null && _b !== void 0 ? _b : [];
+                return items;
+            }
+            catch (e) {
+                (_d = (_c = this.logger).warn) === null || _d === void 0 ? void 0 : _d.call(_c, 'channel: fetchSubMessages failed', e);
+                return [];
+            }
+        });
+        const normalizeOpts = {
+            botIdentity: this.botIdentity,
+            stripBotMentions: true,
+            includeRaw: this.opts.includeRawInMessage,
+            fetchSubMessages,
+        };
+        this.dispatcher.register({
+            // IM message — full safety pipeline
+            'im.message.receive_v1': (raw) => __awaiter(this, void 0, void 0, function* () {
+                try {
+                    const msg = yield normalize(raw, normalizeOpts);
+                    yield this.safety.pushMessage(msg);
+                }
+                catch (e) {
+                    this.emitError(e);
+                }
+            }),
+            // Card button click — dedup + lock + queue (by chatId).
+            // The key includes the action's identity (tag + value) so that
+            // different buttons on the same card by the same user are NOT
+            // collapsed by the dedup cache. A genuine Feishu re-delivery
+            // of the same click still hashes to the same key.
+            'card.action.trigger': (raw) => __awaiter(this, void 0, void 0, function* () {
+                const evt = normalizeCardAction(raw);
+                if (!evt)
+                    return;
+                const actionId = cardActionId(evt.action);
+                yield this.safety.pushAction(`card:${evt.messageId}:${evt.operator.openId}:${actionId}`, evt.chatId, () => __awaiter(this, void 0, void 0, function* () {
+                    const h = this.handlers.cardAction;
+                    if (h)
+                        yield h(evt);
+                }));
+            }),
+            // Reactions — dedup only
+            'im.message.reaction.created_v1': (raw) => __awaiter(this, void 0, void 0, function* () {
+                const evt = normalizeReaction(raw, 'added');
+                if (!evt)
+                    return;
+                const key = reactionKey(evt);
+                yield this.safety.pushLight(key, () => { var _a, _b; return (_b = (_a = this.handlers).reaction) === null || _b === void 0 ? void 0 : _b.call(_a, evt); });
+            }),
+            'im.message.reaction.deleted_v1': (raw) => __awaiter(this, void 0, void 0, function* () {
+                const evt = normalizeReaction(raw, 'removed');
+                if (!evt)
+                    return;
+                const key = reactionKey(evt);
+                yield this.safety.pushLight(key, () => { var _a, _b; return (_b = (_a = this.handlers).reaction) === null || _b === void 0 ? void 0 : _b.call(_a, evt); });
+            }),
+            // Bot added — direct fire, no safety
+            'im.chat.member.bot.added_v1': (raw) => {
+                var _a, _b;
+                const evt = normalizeBotAdded(raw, {
+                    includeRaw: this.opts.includeRawInMessage,
+                });
+                if (!evt)
+                    return;
+                try {
+                    (_b = (_a = this.handlers).botAdded) === null || _b === void 0 ? void 0 : _b.call(_a, evt);
+                }
+                catch (e) {
+                    this.emitError(e);
+                }
+            },
+            // Drive comments — dedup + lock + queue (by fileToken)
+            'drive.notice.comment_add_v1': (raw) => __awaiter(this, void 0, void 0, function* () {
+                const evt = normalizeComment(raw, {
+                    includeRaw: this.opts.includeRawInMessage,
+                });
+                if (!evt)
+                    return;
+                yield this.safety.pushAction(`comment:${evt.fileToken}:${evt.commentId}`, evt.fileToken, () => __awaiter(this, void 0, void 0, function* () {
+                    const h = this.handlers.comment;
+                    if (h)
+                        yield h(evt);
+                }));
+            }),
+        });
+    }
+    emitError(e) {
+        var _a, _b, _c;
+        const err = e instanceof LarkChannelError
+            ? e
+            : new LarkChannelError('unknown', String((_a = e === null || e === void 0 ? void 0 : e.message) !== null && _a !== void 0 ? _a : e), { cause: e });
+        const handler = this.handlers.error;
+        if (handler)
+            handler(err);
+        else
+            (_c = (_b = this.logger).error) === null || _c === void 0 ? void 0 : _c.call(_b, 'channel: unhandled error', err);
+    }
+}
+function createLarkChannel(opts) {
+    return new LarkChannel(opts);
+}
+function bufferFromStream(raw) {
+    return __awaiter(this, void 0, void 0, function* () {
+        if (Buffer.isBuffer(raw))
+            return raw;
+        if (raw instanceof Uint8Array)
+            return Buffer.from(raw);
+        if (typeof raw === 'object' && raw !== null) {
+            const r = raw;
+            // The code-gen download endpoints (im.v1.image.get / im.v1.file.get)
+            // return a wrapper object `{ writeFile, getReadableStream, headers }`
+            // where the body is exposed as a stream. Consume it into a Buffer.
+            if (typeof r.getReadableStream === 'function') {
+                return yield readableToBuffer(r.getReadableStream());
+            }
+            if (Buffer.isBuffer(r.data))
+                return r.data;
+            if (r.data instanceof Uint8Array)
+                return Buffer.from(r.data);
+        }
+        throw new LarkChannelError('unknown', 'unexpected download response type');
+    });
+}
+function readableToBuffer(stream) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        stream.on('data', (chunk) => {
+            chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+        });
+        stream.on('end', () => resolve(Buffer.concat(chunks)));
+        stream.on('error', reject);
+    });
+}
+function reactionKey(evt) {
+    var _a;
+    return `rx:${evt.messageId}:${evt.operator.openId}:${evt.emojiType}:${evt.action}:${(_a = evt.actionTime) !== null && _a !== void 0 ? _a : 0}`;
+}
+/**
+ * Build a stable identity for a card action event's button/element, so that
+ * different clicks on the same card by the same user dedup independently.
+ * `tag` plus serialized `value` is enough to tell buttons apart; `name` and
+ * `option` are rolled in for form-style interactions where the same value
+ * may repeat but the triggering element differs. The serialized payload is
+ * length-clamped to keep cache keys small.
+ */
+function cardActionId(action) {
+    var _a, _b, _c;
+    const serialized = typeof action.value === 'string' ? action.value : JSON.stringify((_a = action.value) !== null && _a !== void 0 ? _a : '');
+    const valuePart = serialized.length > 128 ? serialized.slice(0, 128) : serialized;
+    return `${action.tag}|${(_b = action.name) !== null && _b !== void 0 ? _b : ''}|${(_c = action.option) !== null && _c !== void 0 ? _c : ''}|${valuePart}`;
+}
+
+export { AESCipher, Aily, AppType, CAppTicket, CTenantAccessToken, CardActionHandler, Client, Domain, EventDispatcher, LarkChannel, LarkChannelError, LoggerLevel, WSClient, adaptDefault, adaptExpress, adaptKoa, adaptKoaRouter, createLarkChannel, defaultHttpInstance, generateChallenge, messageCard, normalize, normalizeBotAdded, normalizeCardAction, normalizeComment, normalizeReaction, registerApp, withAll, withHelpDeskCredential, withTenantKey, withTenantToken, withUserAccessToken };