@larksuiteoapi/node-sdk 1.61.0 → 1.62.0

package/types/index.d.ts

@@ -110,6 +110,8 @@ interface IClientParams {
     helpDeskId?: string;
     helpDeskToken?: string;
     httpInstance?: HttpInstance;
+    /** Caller tag appended to User-Agent as `source/<name>`. */
+    source?: string;
 }
 interface IPayload {
     params?: Record<string, any>;
@@ -5923,7 +5925,7 @@ declare abstract class Client$12 extends Client$13 {
                         } | undefined;
                         recommend_item_infos?: {
                             item_id?: string | undefined;
-                            item_type?: "application" | "link" | undefined;
+                            item_type?: "link" | "application" | undefined;
                             name?: string | undefined;
                             description?: string | undefined;
                             link_url?: string | undefined;
@@ -5940,7 +5942,7 @@ declare abstract class Client$12 extends Client$13 {
                         }[] | undefined;
                         distributed_recommend_item_infos?: {
                             item_id?: string | undefined;
-                            item_type?: "application" | "link" | undefined;
+                            item_type?: "link" | "application" | undefined;
                             name?: string | undefined;
                             description?: string | undefined;
                             link_url?: string | undefined;
@@ -5989,7 +5991,7 @@ declare abstract class Client$12 extends Client$13 {
                         } | undefined;
                         recommend_item_infos?: {
                             item_id?: string | undefined;
-                            item_type?: "application" | "link" | undefined;
+                            item_type?: "link" | "application" | undefined;
                             name?: string | undefined;
                             description?: string | undefined;
                             link_url?: string | undefined;
@@ -6006,7 +6008,7 @@ declare abstract class Client$12 extends Client$13 {
                         }[] | undefined;
                         distributed_recommend_item_infos?: {
                             item_id?: string | undefined;
-                            item_type?: "application" | "link" | undefined;
+                            item_type?: "link" | "application" | undefined;
                             name?: string | undefined;
                             description?: string | undefined;
                             link_url?: string | undefined;
@@ -6769,7 +6771,7 @@ declare abstract class Client$12 extends Client$13 {
                         status?: number | undefined;
                         scene_type?: number | undefined;
                         payment_type?: number | undefined;
-                        create_source?: "developer_console" | "base" | "app_engine" | "bot_builder" | "aily" | "unknown" | undefined;
+                        create_source?: "unknown" | "developer_console" | "base" | "app_engine" | "bot_builder" | "aily" | undefined;
                         redirect_urls?: string[] | undefined;
                         online_version_id?: string | undefined;
                         unaudit_version_id?: string | undefined;
@@ -6846,7 +6848,7 @@ declare abstract class Client$12 extends Client$13 {
                         status?: number | undefined;
                         scene_type?: number | undefined;
                         payment_type?: number | undefined;
-                        create_source?: "developer_console" | "base" | "app_engine" | "bot_builder" | "aily" | "unknown" | undefined;
+                        create_source?: "unknown" | "developer_console" | "base" | "app_engine" | "bot_builder" | "aily" | undefined;
                         redirect_urls?: string[] | undefined;
                         online_version_id?: string | undefined;
                         unaudit_version_id?: string | undefined;
@@ -6935,7 +6937,7 @@ declare abstract class Client$12 extends Client$13 {
                         status?: number | undefined;
                         scene_type?: number | undefined;
                         payment_type?: number | undefined;
-                        create_source?: "developer_console" | "base" | "app_engine" | "bot_builder" | "aily" | "unknown" | undefined;
+                        create_source?: "unknown" | "developer_console" | "base" | "app_engine" | "bot_builder" | "aily" | undefined;
                         redirect_urls?: string[] | undefined;
                         online_version_id?: string | undefined;
                         unaudit_version_id?: string | undefined;
@@ -7444,7 +7446,7 @@ declare abstract class Client$12 extends Client$13 {
                             } | undefined;
                             recommend_item_infos?: {
                                 item_id?: string | undefined;
-                                item_type?: "application" | "link" | undefined;
+                                item_type?: "link" | "application" | undefined;
                                 name?: string | undefined;
                                 description?: string | undefined;
                                 link_url?: string | undefined;
@@ -7461,7 +7463,7 @@ declare abstract class Client$12 extends Client$13 {
                             }[] | undefined;
                             distributed_recommend_item_infos?: {
                                 item_id?: string | undefined;
-                                item_type?: "application" | "link" | undefined;
+                                item_type?: "link" | "application" | undefined;
                                 name?: string | undefined;
                                 description?: string | undefined;
                                 link_url?: string | undefined;
@@ -7510,7 +7512,7 @@ declare abstract class Client$12 extends Client$13 {
                             } | undefined;
                             recommend_item_infos?: {
                                 item_id?: string | undefined;
-                                item_type?: "application" | "link" | undefined;
+                                item_type?: "link" | "application" | undefined;
                                 name?: string | undefined;
                                 description?: string | undefined;
                                 link_url?: string | undefined;
@@ -7527,7 +7529,7 @@ declare abstract class Client$12 extends Client$13 {
                             }[] | undefined;
                             distributed_recommend_item_infos?: {
                                 item_id?: string | undefined;
-                                item_type?: "application" | "link" | undefined;
+                                item_type?: "link" | "application" | undefined;
                                 name?: string | undefined;
                                 description?: string | undefined;
                                 link_url?: string | undefined;
@@ -8290,7 +8292,7 @@ declare abstract class Client$12 extends Client$13 {
                             status?: number | undefined;
                             scene_type?: number | undefined;
                             payment_type?: number | undefined;
-                            create_source?: "developer_console" | "base" | "app_engine" | "bot_builder" | "aily" | "unknown" | undefined;
+                            create_source?: "unknown" | "developer_console" | "base" | "app_engine" | "bot_builder" | "aily" | undefined;
                             redirect_urls?: string[] | undefined;
                             online_version_id?: string | undefined;
                             unaudit_version_id?: string | undefined;
@@ -8367,7 +8369,7 @@ declare abstract class Client$12 extends Client$13 {
                             status?: number | undefined;
                             scene_type?: number | undefined;
                             payment_type?: number | undefined;
-                            create_source?: "developer_console" | "base" | "app_engine" | "bot_builder" | "aily" | "unknown" | undefined;
+                            create_source?: "unknown" | "developer_console" | "base" | "app_engine" | "bot_builder" | "aily" | undefined;
                             redirect_urls?: string[] | undefined;
                             online_version_id?: string | undefined;
                             unaudit_version_id?: string | undefined;
@@ -8456,7 +8458,7 @@ declare abstract class Client$12 extends Client$13 {
                             status?: number | undefined;
                             scene_type?: number | undefined;
                             payment_type?: number | undefined;
-                            create_source?: "developer_console" | "base" | "app_engine" | "bot_builder" | "aily" | "unknown" | undefined;
+                            create_source?: "unknown" | "developer_console" | "base" | "app_engine" | "bot_builder" | "aily" | undefined;
                             redirect_urls?: string[] | undefined;
                             online_version_id?: string | undefined;
                             unaudit_version_id?: string | undefined;
@@ -27583,7 +27585,7 @@ declare abstract class Client$U extends Client$V {
                             height?: number | undefined;
                             text?: {
                                 text?: string | undefined;
-                                font_weight?: "regular" | "bold" | undefined;
+                                font_weight?: "bold" | "regular" | undefined;
                                 font_size?: number | undefined;
                                 horizontal_align?: "left" | "center" | "right" | undefined;
                                 vertical_align?: "top" | "mid" | "bottom" | undefined;
@@ -27749,7 +27751,7 @@ declare abstract class Client$U extends Client$V {
                                 captions?: {
                                     data?: {
                                         text?: string | undefined;
-                                        font_weight?: "regular" | "bold" | undefined;
+                                        font_weight?: "bold" | "regular" | undefined;
                                         font_size?: number | undefined;
                                         horizontal_align?: "left" | "center" | "right" | undefined;
                                         vertical_align?: "top" | "mid" | "bottom" | undefined;
@@ -27948,7 +27950,7 @@ declare abstract class Client$U extends Client$V {
                                     children?: string[] | undefined;
                                     text?: {
                                         text?: string | undefined;
-                                        font_weight?: "regular" | "bold" | undefined;
+                                        font_weight?: "bold" | "regular" | undefined;
                                         font_size?: number | undefined;
                                         horizontal_align?: "left" | "center" | "right" | undefined;
                                         vertical_align?: "top" | "mid" | "bottom" | undefined;
@@ -284507,6 +284509,7 @@ declare class Client extends Client$1 {
     domain: string;
     httpInstance: HttpInstance;
     userAccessToken: UserAccessToken;
+    private readonly userAgent;
     constructor(params: IClientParams);
     formatPayload(payload?: IPayload, options?: IRequestOptions): Promise<Required<IPayload>>;
     request<T = any>(payload: AxiosRequestConfig, options?: IRequestOptions): Promise<T>;
@@ -293047,6 +293050,20 @@ interface IConstructorParams {
     httpInstance?: HttpInstance;
     autoReconnect?: boolean;
     agent?: any;
+    /** Caller tag appended to User-Agent as `source/<name>`. */
+    source?: string;
+    /** Fires once when the first WebSocket handshake succeeds. */
+    onReady?: () => void;
+    /**
+     * Fires when the initial connect fails and the client either cannot retry
+     * (autoReconnect=false) or exhausts `reconnectCount` retries. The callback
+     * receives an Error describing the final failure.
+     */
+    onError?: (err: Error) => void;
+    /** Fires when the client enters the reconnect loop (i.e., after a disconnect). */
+    onReconnecting?: () => void;
+    /** Fires after the reconnect loop successfully re-establishes the connection. */
+    onReconnected?: () => void;
 }
 declare class WSClient {
     private wsConfig;
@@ -293060,7 +293077,21 @@ declare class WSClient {
     private isConnecting;
     private reconnectInfo;
     private agent?;
+    /** User-supplied state-transition callbacks. All optional. */
+    private onReady?;
+    private onError?;
+    private onReconnecting?;
+    private onReconnected?;
+    private readonly userAgent;
+    /** True if the WS has ever connected successfully in this client's
+     *  lifetime — used to distinguish first-connect from reconnect. */
+    private hasEverConnected;
     constructor(params: IConstructorParams);
+    /**
+     * Invoke a user-supplied callback safely: no-op if undefined, swallow any
+     * exception to avoid breaking the WS state machine.
+     */
+    private safeInvoke;
     private pullConnectConfig;
     private connect;
     private reConnect;
@@ -293224,4 +293255,547 @@ interface RegisterAppResult {
 
 declare function registerApp(options: RegisterAppOptions): Promise<RegisterAppResult>;
 
-export { AESCipher, Aily, AppType, CAppTicket, CTenantAccessToken, Cache, CardActionHandler, Client, Domain, EventDispatcher, IHandles as EventHandles, HttpInstance, HttpRequestOptions, InteractiveCard, InteractiveCardActionEvent, InteractiveCardActionItem, InteractiveCardButtonActionItem, InteractiveCardDatePickerActionItem, InteractiveCardDivElement, InteractiveCardDividerElement, InteractiveCardElement, InteractiveCardField, InteractiveCardImageElement, InteractiveCardImageItem, InteractiveCardLarkMdItem, InteractiveCardMarkdownElement, InteractiveCardNoteElement, InteractiveCardOverflowActionItem, InteractiveCardPlainTextItem, InteractiveCardSelectMenuActionItem, InteractiveCardTextItem, InteractiveCardTitle, InteractiveCardUrlItem, InterfaceCardActionElement, LoggerLevel, WSClient, adaptDefault, adaptExpress, adaptKoa, adaptKoaRouter, defaultHttpInstance, generateChallenge, messageCard, registerApp, withAll, withHelpDeskCredential, withTenantKey, withTenantToken, withUserAccessToken };
+type ChatType = 'p2p' | 'group';
+interface NormalizedMessage {
+    messageId: string;
+    chatId: string;
+    chatType: ChatType;
+    senderId: string;
+    senderName?: string;
+    content: string;
+    rawContentType: string;
+    resources: ResourceDescriptor[];
+    mentions: MentionInfo[];
+    mentionAll: boolean;
+    mentionedBot: boolean;
+    rootId?: string;
+    threadId?: string;
+    replyToMessageId?: string;
+    createTime: number;
+    raw?: unknown;
+}
+interface ResourceDescriptor {
+    type: 'image' | 'file' | 'audio' | 'video' | 'sticker';
+    fileKey: string;
+    fileName?: string;
+    durationMs?: number;
+    coverImageKey?: string;
+}
+interface MentionInfo {
+    key: string;
+    openId?: string;
+    userId?: string;
+    name?: string;
+    isBot?: boolean;
+}
+interface BotIdentity {
+    openId: string;
+    userId?: string;
+    name: string;
+}
+type SendInput = {
+    markdown: string;
+} | {
+    text: string;
+} | {
+    post: object;
+} | {
+    image: {
+        source: string | Buffer;
+    };
+} | {
+    file: {
+        source: string | Buffer;
+        fileName: string;
+    };
+} | {
+    audio: {
+        source: string | Buffer;
+        duration?: number;
+    };
+} | {
+    video: {
+        source: string | Buffer;
+        duration?: number;
+        coverImageKey?: string;
+    };
+} | {
+    card: object;
+} | {
+    shareChat: {
+        chatId: string;
+    };
+} | {
+    shareUser: {
+        userId: string;
+    };
+} | {
+    sticker: {
+        fileKey: string;
+    };
+};
+interface MediaSource {
+    source: string | Buffer;
+}
+interface SendOptions {
+    replyTo?: string;
+    replyInThread?: boolean;
+    mentions?: MentionInfo[];
+}
+interface SendResult {
+    messageId: string;
+    chunkIds?: string[];
+}
+type StreamInput = {
+    markdown: MarkdownStreamProducer;
+} | {
+    card: {
+        initial: object;
+        producer: CardStreamProducer;
+    };
+};
+type MarkdownStreamProducer = (controller: MarkdownStreamController) => Promise<void>;
+type CardStreamProducer = (controller: CardStreamController) => Promise<void>;
+interface MarkdownStreamController {
+    append(chunk: string): Promise<void>;
+    setContent(full: string): Promise<void>;
+    readonly messageId: string;
+}
+interface CardStreamController {
+    update(next: object | ((current: object) => object)): Promise<void>;
+    readonly messageId: string;
+    readonly current: object;
+}
+interface EventMap {
+    message: (msg: NormalizedMessage) => void | Promise<void>;
+    reject: (evt: RejectEvent) => void;
+    cardAction: (evt: CardActionEvent) => void | Promise<void>;
+    reaction: (evt: ReactionEvent) => void;
+    botAdded: (evt: BotAddedEvent) => void;
+    comment: (evt: CommentEvent) => void | Promise<void>;
+    error: (err: LarkChannelError) => void;
+    reconnecting: () => void;
+    reconnected: () => void;
+}
+type EventName = keyof EventMap;
+/**
+ * Reason for a {@link RejectEvent}. These are the set of policy-level
+ * decisions that deliberately reject a message and inform the caller.
+ *
+ * Internal defenses (duplicate dedup, stale/expired timestamps, in-flight
+ * processing lock) silently drop their targets — they are not reject
+ * reasons, because the caller cannot act on them meaningfully.
+ */
+type RejectReason = 'group_not_allowed' | 'sender_not_allowed' | 'no_mention' | 'dm_disabled' | 'mention_all_blocked';
+interface RejectEvent {
+    messageId: string;
+    chatId: string;
+    senderId: string;
+    reason: RejectReason;
+}
+interface CardActionEvent {
+    messageId: string;
+    chatId: string;
+    operator: {
+        openId: string;
+        userId?: string;
+        name?: string;
+    };
+    action: {
+        value: unknown;
+        tag: string;
+        name?: string;
+        option?: string;
+    };
+}
+interface ReactionEvent {
+    messageId: string;
+    operator: {
+        openId: string;
+        userId?: string;
+    };
+    emojiType: string;
+    action: 'added' | 'removed';
+    actionTime?: number;
+}
+interface BotAddedEvent {
+    chatId: string;
+    operator: {
+        openId: string;
+        userId?: string;
+    };
+    /**
+     * The bot's own name as carried in the `name` field of the Feishu event.
+     * Not the chat's name — that requires a separate `getChatInfo(chatId)`
+     * call, which callers can do on demand.
+     */
+    botName?: string;
+    external?: boolean;
+    raw?: unknown;
+}
+interface CommentEvent {
+    fileToken: string;
+    fileType: string;
+    commentId: string;
+    replyId?: string;
+    operator: {
+        openId: string;
+        userId?: string;
+        unionId?: string;
+    };
+    mentionedBot: boolean;
+    timestamp: number;
+    raw?: unknown;
+}
+type LarkChannelErrorCode = 'format_error' | 'target_revoked' | 'rate_limited' | 'permission_denied' | 'upload_failed' | 'ssrf_blocked' | 'send_timeout' | 'not_connected' | 'unknown';
+declare class LarkChannelError extends Error {
+    code: LarkChannelErrorCode;
+    cause?: unknown;
+    context?: {
+        to?: string;
+        messageId?: string;
+        attempt?: number;
+    };
+    constructor(code: LarkChannelErrorCode, message: string, opts?: {
+        cause?: unknown;
+        context?: LarkChannelError['context'];
+    });
+}
+interface LarkChannelOptions {
+    appId: string;
+    appSecret: string;
+    transport?: 'websocket' | 'webhook';
+    webhook?: WebhookOptions;
+    safety?: SafetyConfig;
+    policy?: PolicyConfig;
+    outbound?: OutboundConfig;
+    logger?: Logger;
+    loggerLevel?: LoggerLevel;
+    cache?: Cache;
+    domain?: Domain | string;
+    httpInstance?: HttpInstance;
+    /** Caller tag appended to User-Agent as `source/<name>`. */
+    source?: string;
+    includeRawInMessage?: boolean;
+}
+interface WebhookOptions {
+    verificationToken?: string;
+    encryptKey?: string;
+    adapter?: 'express' | 'koa' | 'koa-router';
+}
+interface SafetyConfig {
+    dedup?: {
+        ttl?: number;
+        maxEntries?: number;
+        sweepIntervalMs?: number;
+    };
+    chatQueue?: {
+        enabled?: boolean;
+    };
+    batch?: {
+        text?: {
+            delayMs?: number;
+            longThresholdChars?: number;
+            longDelayMs?: number;
+            maxMessages?: number;
+            maxChars?: number;
+        };
+        media?: {
+            delayMs?: number;
+            maxItems?: number;
+        };
+    };
+    staleMessageWindowMs?: number;
+}
+interface PolicyConfig {
+    groupAllowlist?: string[];
+    dmMode?: 'open' | 'allowlist' | 'pair' | 'disabled';
+    dmAllowlist?: string[];
+    requireMention?: boolean;
+    respondToMentionAll?: boolean;
+}
+interface OutboundConfig {
+    textChunkLimit?: number;
+    markdownConverter?: 'builtin' | ((md: string) => object);
+    streamThrottleMs?: number;
+    streamThrottleChars?: number;
+    streamInitialText?: string;
+    ssrfGuard?: boolean | {
+        allowlist?: string[];
+    };
+    /**
+     * Restrict local file paths accepted by media `source` to the listed
+     * directories. When unset, only a POSIX blocklist (`/etc/`, `/proc/`,
+     * `/sys/`, `/dev/`) is enforced as a safety net; when set, every path
+     * must be inside one of these directories and symlink targets are
+     * re-checked after `realpath` resolution.
+     */
+    allowedFileDirs?: string[];
+    retry?: {
+        maxAttempts?: number;
+        baseDelayMs?: number;
+    };
+}
+interface ChatInfo {
+    chatId: string;
+    name?: string;
+    description?: string;
+    chatType: 'p2p' | 'group';
+    ownerId?: string;
+    memberCount?: number;
+}
+type ResourceType = 'image' | 'file';
+
+type Unsubscribe = () => void;
+declare class LarkChannel {
+    readonly rawClient: Client;
+    rawWsClient?: WSClient;
+    botIdentity?: BotIdentity;
+    private readonly opts;
+    private readonly logger;
+    private readonly dispatcher;
+    private readonly handlers;
+    private connectPromise?;
+    private connected;
+    private readonly sender;
+    private readonly safety;
+    constructor(opts: LarkChannelOptions);
+    connect(): Promise<void>;
+    private doConnect;
+    /**
+     * 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.
+     */
+    private connectWebSocket;
+    disconnect(): Promise<void>;
+    on<K extends EventName>(name: K, handler: EventMap[K]): Unsubscribe;
+    on(handlers: Partial<EventMap>): Unsubscribe;
+    private attachSingle;
+    send(to: string, input: SendInput, opts?: SendOptions): Promise<SendResult>;
+    stream(to: string, input: StreamInput, opts?: SendOptions): Promise<SendResult>;
+    updateCard(messageId: string, card: object): Promise<void>;
+    /**
+     * 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: string, text: string): Promise<void>;
+    recallMessage(messageId: string): Promise<void>;
+    /**
+     * 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: string, emojiType: string): Promise<string>;
+    /**
+     * 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: string, reactionId: string): Promise<void>;
+    /**
+     * 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: string, emojiType: string): Promise<boolean>;
+    downloadResource(fileKey: string, type: ResourceType): Promise<Buffer>;
+    getChatInfo(chatId: string): Promise<ChatInfo>;
+    updatePolicy(partial: Partial<PolicyConfig>): void;
+    getPolicy(): Readonly<PolicyConfig>;
+    private fetchBotIdentity;
+    private registerDispatcherHandlers;
+    private emitError;
+}
+declare function createLarkChannel(opts: LarkChannelOptions): LarkChannel;
+
+interface RawMessageEvent {
+    sender: {
+        sender_id: {
+            open_id?: string;
+            user_id?: string;
+            union_id?: string;
+        };
+        sender_type?: string;
+        tenant_key?: string;
+    };
+    message: {
+        message_id: string;
+        root_id?: string;
+        parent_id?: string;
+        create_time?: string;
+        update_time?: string;
+        chat_id: string;
+        thread_id?: string;
+        chat_type: 'p2p' | 'group';
+        message_type: string;
+        content: string;
+        mentions?: RawMention[];
+    };
+}
+interface RawMention {
+    key: string;
+    id: {
+        open_id?: string;
+        user_id?: string;
+        union_id?: string;
+    };
+    name?: string;
+    tenant_key?: string;
+}
+interface ApiMessageItem {
+    message_id?: string;
+    upper_message_id?: string;
+    msg_type?: string;
+    body?: {
+        content?: string;
+    };
+    mentions?: RawMention[];
+    sender?: {
+        id?: string;
+        id_type?: string;
+        sender_type?: string;
+    };
+    create_time?: string | number;
+}
+
+interface RawCardActionEvent {
+    /**
+     * Current shape (observed from `card.action.trigger` v2): message/chat ids
+     * are nested under `context`. Top-level variants kept as fallback in case
+     * older or alternate surfaces (webhook vs WS, older schema) still deliver
+     * them at the root.
+     */
+    context?: {
+        open_message_id?: string;
+        open_chat_id?: string;
+    };
+    open_message_id?: string;
+    open_chat_id?: string;
+    token?: string;
+    operator?: {
+        open_id?: string;
+        user_id?: string;
+        union_id?: string;
+        name?: string;
+    };
+    action?: {
+        value?: unknown;
+        tag?: string;
+        name?: string;
+        option?: string;
+        timezone?: string;
+    };
+}
+declare function normalizeCardAction(event: RawCardActionEvent): CardActionEvent | null;
+
+interface RawReactionEvent {
+    message_id?: string;
+    reaction_type?: {
+        emoji_type?: string;
+    };
+    operator_type?: string;
+    user_id?: {
+        open_id?: string;
+        user_id?: string | null;
+        union_id?: string;
+    };
+    action_time?: string;
+}
+declare function normalizeReaction(event: RawReactionEvent, action: 'added' | 'removed'): ReactionEvent | null;
+
+interface RawBotAddedEvent {
+    chat_id?: string;
+    operator_id?: {
+        open_id?: string;
+        user_id?: string | null;
+        union_id?: string;
+    };
+    external?: boolean;
+    /** The bot's name (NOT the chat's name). */
+    name?: string;
+    /** The bot's localized names. */
+    i18n_names?: {
+        zh_cn?: string;
+        en_us?: string;
+        ja_jp?: string;
+    };
+}
+declare function normalizeBotAdded(event: RawBotAddedEvent, opts?: {
+    includeRaw?: boolean;
+}): BotAddedEvent | null;
+
+interface RawCommentEvent {
+    app_id?: string;
+    file_token?: string;
+    file_type?: string;
+    comment_id?: string;
+    reply_id?: string;
+    /** Whether the bot was mentioned. Top-level in current payload. */
+    is_mentioned?: boolean;
+    /** Millisecond timestamp of the event. */
+    create_time?: string;
+    notice_meta?: {
+        from_user_id?: {
+            open_id?: string;
+            user_id?: string | null;
+            union_id?: string;
+        };
+        to_user_id?: {
+            open_id?: string;
+            user_id?: string | null;
+            union_id?: string;
+        };
+        file_token?: string;
+        file_type?: string;
+        timestamp?: string;
+        is_mentioned?: boolean;
+        notice_type?: string;
+    };
+    is_mention?: boolean;
+    user_id?: {
+        open_id?: string;
+        user_id?: string | null;
+        union_id?: string;
+    };
+    action_time?: string;
+}
+declare function normalizeComment(event: RawCommentEvent, opts?: {
+    includeRaw?: boolean;
+}): CommentEvent | null;
+
+interface NormalizeOptions {
+    botIdentity: BotIdentity;
+    stripBotMentions?: boolean;
+    includeRaw?: boolean;
+    fetchSubMessages?: (messageId: string) => Promise<ApiMessageItem[]>;
+    resolveUserName?: (openId: string) => string | undefined;
+    resolveSenderName?: (openId: string) => string | undefined;
+    batchResolveNames?: (openIds: string[]) => Promise<void>;
+}
+/**
+ * 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
+ */
+declare function normalize(event: RawMessageEvent, opts: NormalizeOptions): Promise<NormalizedMessage>;
+
+export { AESCipher, Aily, ApiMessageItem, AppType, BotAddedEvent, BotIdentity, CAppTicket, CTenantAccessToken, Cache, CardActionEvent, CardActionHandler, CardStreamController, CardStreamProducer, ChatInfo, ChatType, Client, CommentEvent, Domain, EventDispatcher, IHandles as EventHandles, EventMap, EventName, HttpInstance, HttpRequestOptions, InteractiveCard, InteractiveCardActionEvent, InteractiveCardActionItem, InteractiveCardButtonActionItem, InteractiveCardDatePickerActionItem, InteractiveCardDivElement, InteractiveCardDividerElement, InteractiveCardElement, InteractiveCardField, InteractiveCardImageElement, InteractiveCardImageItem, InteractiveCardLarkMdItem, InteractiveCardMarkdownElement, InteractiveCardNoteElement, InteractiveCardOverflowActionItem, InteractiveCardPlainTextItem, InteractiveCardSelectMenuActionItem, InteractiveCardTextItem, InteractiveCardTitle, InteractiveCardUrlItem, InterfaceCardActionElement, LarkChannel, LarkChannelError, LarkChannelErrorCode, LarkChannelOptions, LoggerLevel, MarkdownStreamController, MarkdownStreamProducer, MediaSource, MentionInfo, NormalizeOptions, NormalizedMessage, OutboundConfig, PolicyConfig, RawBotAddedEvent, RawCardActionEvent, RawCommentEvent, RawMessageEvent, RawReactionEvent, ReactionEvent, RejectEvent, RejectReason, ResourceDescriptor, ResourceType, SafetyConfig, SendInput, SendOptions, SendResult, StreamInput, WSClient, WebhookOptions, adaptDefault, adaptExpress, adaptKoa, adaptKoaRouter, createLarkChannel, defaultHttpInstance, generateChallenge, messageCard, normalize, normalizeBotAdded, normalizeCardAction, normalizeComment, normalizeReaction, registerApp, withAll, withHelpDeskCredential, withTenantKey, withTenantToken, withUserAccessToken };