@minitool/feishu-bot 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,345 @@
+/** @-提醒参数 */
+export declare interface AtOptions {
+    /** @ 指定用户 open_id 列表 */
+    atUserIds?: string[];
+    /** @ 所有人 */
+    atAll?: boolean;
+}
+
+/**
+ * 构造 image 消息。
+ *
+ * 注意：自定义机器人直发 image 消息只认 image_key（形如 `img_xxx`）。
+ * 想要直接发送本地文件，请使用 FeishuBot.sendImage() 或 FeishuBot.uploadImage()。
+ */
+export declare function buildImage(imageKey: string): ImageMessage;
+
+/**
+ * 构造卡片（interactive）消息。
+ *
+ * 直接透传 card 结构。支持 card schema 2.0 或旧版 header/elements 格式：
+ *
+ *   buildInteractive({
+ *     schema: "2.0",
+ *     header: { title: { tag: "plain_text", content: "标题" } },
+ *     body: { elements: [...] },
+ *   });
+ *
+ *   // 或旧版：
+ *   buildInteractive({
+ *     config: { wide_screen_mode: true },
+ *     header: { template: "blue", title: { tag: "plain_text", content: "标题" } },
+ *     elements: [...],
+ *   });
+ */
+export declare function buildInteractive(card: InteractiveCard): InteractiveMessage;
+
+/**
+ * 构造富文本（post）消息。
+ *
+ * 用户构造 PostContent（支持 zh_cn/en_us/ja_jp 三语言），每个语言下是 `content: PostTag[][]` 的二维数组：
+ * 外层是段落（行），内层是行内的标签（text/a/at/img）。
+ *
+ * 示例：
+ *   buildPost({
+ *     zh_cn: {
+ *       title: "标题",
+ *       content: [
+ *         [{ tag: "text", text: "第一段: " }, { tag: "a", text: "点这里", href: "https://..." }],
+ *         [{ tag: "img", image_key: "img_xxx" }],
+ *       ],
+ *     },
+ *   });
+ */
+export declare function buildPost(post: PostContent): PostMessage;
+
+/**
+ * 构造分享群名片（share_chat）消息。
+ *
+ * @param shareChatId 群 chat_id（形如 `oc_xxx`）
+ */
+export declare function buildShareChat(shareChatId: string): ShareChatMessage;
+
+/**
+ * 构造 text 消息。
+ *
+ * @-提醒说明（来自飞书文档）：
+ * - @ 所有人：`<at user_id="all">所有人</at>`（仅群里能用，必须机器人所在群支持）
+ * - @ 指定用户（需已知 open_id）：`<at user_id="ou_xxx"></at>`
+ *
+ * 示例：
+ *   buildText("hello", { atAll: true })
+ *   // => { msg_type: "text", content: { text: "hello <at user_id=\"all\">所有人</at>" } }
+ */
+export declare function buildText(text: string, opts?: AtOptions): TextMessage;
+
+/**
+ * 获取当前 Unix 秒时间戳。
+ */
+export declare function currentTimestamp(): number;
+
+/**
+ * 调用飞书 OpenAPI 或 webhook 后，返回 code !== 0 或 HTTP 非 2xx 时抛出。
+ */
+export declare class FeishuApiError extends FeishuBotError {
+    readonly code: number;
+    readonly response: unknown;
+    constructor(message: string, code: number, response: unknown);
+}
+
+/** 飞书 OpenAPI 统一返回结构 */
+export declare interface FeishuApiResponse<T = unknown> {
+    code: number;
+    msg: string;
+    data?: T;
+}
+
+/**
+ * 飞书自定义机器人 SDK 主类。
+ *
+ * 构造期不会报错；缺失配置时延迟到 send/upload 调用时抛出 FeishuConfigError，
+ * 便于「先 new 再注入配置」的使用模式。
+ *
+ * 使用示例：
+ *   const bot = new FeishuBot(); // 从 env 读配置
+ *   await bot.sendText("hello", { atAll: true });
+ *   await bot.sendImage("./banner.png"); // 自动上传得到 image_key 再发送
+ */
+export declare class FeishuBot {
+    private readonly webhook?;
+    private readonly secret?;
+    private readonly appId?;
+    private readonly appSecret?;
+    private readonly fetchImpl?;
+    private readonly timeout?;
+    private readonly baseUrl;
+    private tokenManager;
+    private imageUploader;
+    constructor(options?: FeishuBotOptions);
+    /**
+     * 原子发送：接收已构造好的 payload，负责注入签名并 POST 到 webhook。
+     * code !== 0 时抛 FeishuApiError。
+     */
+    send<T = unknown>(payload: MessagePayload): Promise<FeishuApiResponse<T>>;
+    sendText(text: string, opts?: AtOptions): Promise<FeishuApiResponse>;
+    sendPost(post: PostContent): Promise<FeishuApiResponse>;
+    sendShareChat(shareChatId: string): Promise<FeishuApiResponse>;
+    sendInteractive(card: InteractiveCard): Promise<FeishuApiResponse>;
+    /**
+     * 发送图片。智能识别三种入参：
+     *   - string 且以 `img_` 开头 → 直接当 image_key 使用
+     *   - string 否则 → 视为本地文件路径，先上传再发送
+     *   - Buffer / Uint8Array → 直接上传再发送
+     */
+    sendImage(input: ImageSource): Promise<FeishuApiResponse>;
+    /**
+     * 暴露底层图片上传，便于调用方复用 image_key。
+     * 需要 appId / appSecret 配置。
+     */
+    uploadImage(file: ImageSource): Promise<string>;
+    private ensureWebhook;
+    private ensureAppCredentials;
+    private getTokenManager;
+    private getImageUploader;
+}
+
+/**
+ * 所有飞书机器人相关错误的基类。
+ */
+export declare class FeishuBotError extends Error {
+    constructor(message: string);
+}
+
+/**
+ * 飞书自定义机器人 SDK 的类型定义。
+ */
+/** SDK 构造配置 */
+export declare interface FeishuBotOptions {
+    /** 机器人 webhook URL。默认读 `process.env.FEISHU_BOT_WEBHOOK` */
+    webhook?: string;
+    /** 签名校验密钥。若设置，会在每次发送时自动附加 timestamp / sign */
+    secret?: string;
+    /** 应用 App ID，仅图片上传需要。默认读 `process.env.FEISHU_APP_ID` */
+    appId?: string;
+    /** 应用 App Secret，仅图片上传需要。默认读 `process.env.FEISHU_APP_SECRET` */
+    appSecret?: string;
+    /** 自定义 fetch 实现，用于测试注入。默认用 globalThis.fetch */
+    fetch?: typeof fetch;
+    /** 请求超时，单位毫秒。默认 10000 */
+    timeout?: number;
+    /** 飞书开放平台基础 URL，默认 https://open.feishu.cn */
+    baseUrl?: string;
+}
+
+/**
+ * 配置相关错误：如未提供 webhook、secret、appId、appSecret 等。
+ * 构造 FeishuBot 实例时不会抛；延迟到 send/upload 调用时才抛。
+ */
+export declare class FeishuConfigError extends FeishuBotError {
+    constructor(message: string);
+}
+
+/**
+ * 生成飞书自定义机器人签名。
+ *
+ * 算法（来自飞书官方文档，反直觉之处：HMAC 的 key 是 stringToSign 本身，data 是空字符串）：
+ *   stringToSign = `${timestamp}\n${secret}`
+ *   sign         = Base64(HmacSHA256(key = stringToSign, data = ''))
+ *
+ * @param timestamp  Unix 秒时间戳（飞书要求 ±1 小时窗口）
+ * @param secret     机器人「安全设置 → 签名校验」得到的 secret
+ */
+export declare function genSign(timestamp: number | string, secret: string): string;
+
+/** 图片消息 */
+export declare interface ImageMessage {
+    msg_type: 'image';
+    content: {
+        image_key: string;
+    };
+}
+
+/** 支持的图片源：文件路径字符串 / Buffer / Uint8Array */
+export declare type ImageSource = string | Buffer | Uint8Array;
+
+/**
+ * 图片上传器：调用 im/v1/images 接口，返回 image_key。
+ * - string: 作为文件路径用 fs/promises.readFile 读成 Buffer
+ * - Buffer/Uint8Array: 直接作为 Blob 数据
+ * 用 globalThis 的 FormData + Blob（Node 18+ 内置），不依赖 form-data 包。
+ */
+export declare class ImageUploader {
+    private readonly tokenManager;
+    private readonly fetchImpl?;
+    private readonly timeout?;
+    private readonly baseUrl;
+    constructor(options: ImageUploaderOptions);
+    /**
+     * 上传图片，返回 image_key。
+     */
+    uploadImage(file: ImageSource): Promise<string>;
+    private resolveSource;
+}
+
+declare interface ImageUploaderOptions {
+    tokenManager: TokenManager;
+    fetch?: typeof fetch;
+    timeout?: number;
+    baseUrl?: string;
+}
+
+/** 卡片消息（透传 card schema 2.0 或旧版） */
+export declare type InteractiveCard = Record<string, unknown>;
+
+export declare interface InteractiveMessage {
+    msg_type: 'interactive';
+    card: InteractiveCard;
+}
+
+/** 所有支持的消息类型联合 */
+export declare type MessagePayload = TextMessage | PostMessage | ImageMessage | ShareChatMessage | InteractiveMessage;
+
+/** 富文本多语言内容 */
+export declare interface PostContent {
+    zh_cn?: PostLocale;
+    en_us?: PostLocale;
+    ja_jp?: PostLocale;
+}
+
+/** 富文本单语言内容 */
+export declare interface PostLocale {
+    title?: string;
+    content: PostTag[][];
+}
+
+/** 富文本消息 */
+export declare interface PostMessage {
+    msg_type: 'post';
+    content: {
+        post: PostContent;
+    };
+}
+
+/** 富文本消息中的内容标签 */
+export declare type PostTag = {
+    tag: 'text';
+    text: string;
+    un_escape?: boolean;
+} | {
+    tag: 'a';
+    text: string;
+    href: string;
+} | {
+    tag: 'at';
+    user_id: string;
+    user_name?: string;
+} | {
+    tag: 'img';
+    image_key: string;
+};
+
+/** 分享群名片消息 */
+export declare interface ShareChatMessage {
+    msg_type: 'share_chat';
+    content: {
+        share_chat_id: string;
+    };
+}
+
+/** 带签名字段的最终 webhook 请求体 */
+export declare type SignedPayload = MessagePayload & {
+    timestamp?: string;
+    sign?: string;
+};
+
+/** 获取 tenant_access_token 的返回 */
+export declare interface TenantAccessTokenResponse {
+    code: number;
+    msg: string;
+    tenant_access_token?: string;
+    expire?: number;
+}
+
+/** 文本消息 */
+export declare interface TextMessage {
+    msg_type: 'text';
+    content: {
+        text: string;
+    };
+}
+
+/**
+ * tenant_access_token 缓存与自动刷新。
+ * 并发去重：多次 getToken() 在 in-flight 期间共享同一个 Promise，避免重复请求。
+ */
+export declare class TokenManager {
+    private readonly appId;
+    private readonly appSecret;
+    private readonly fetchImpl?;
+    private readonly timeout?;
+    private readonly baseUrl;
+    private cached;
+    private inflight;
+    constructor(options: TokenManagerOptions);
+    /**
+     * 获取有效 token。优先使用缓存；过期/即将过期时刷新。
+     */
+    getToken(): Promise<string>;
+    private isCacheFresh;
+    private fetchToken;
+}
+
+declare interface TokenManagerOptions {
+    appId: string;
+    appSecret: string;
+    fetch?: typeof fetch;
+    timeout?: number;
+    baseUrl?: string;
+}
+
+/** 上传图片返回数据 */
+export declare interface UploadImageResult {
+    image_key: string;
+}
+
+export { }