@spaceflow/core 0.1.1

package/src/shared/feishu-sdk/feishu-sdk.service.ts

@@ -0,0 +1,130 @@
+import { Inject, Injectable, type OnModuleDestroy, type OnModuleInit } from "@nestjs/common";
+import { EventEmitter2 } from "@nestjs/event-emitter";
+import * as lark from "@larksuiteoapi/node-sdk";
+import {
+  FeishuModuleOptions,
+  FEISHU_MODULE_OPTIONS,
+  FeishuUser,
+  GetUserParams,
+  FEISHU_CARD_ACTION_TRIGGER,
+  type CardEvents,
+  type CardActionTriggerResponse,
+  type CardActionTriggerEvent,
+} from "./types";
+
+/**
+ * 飞书 API 服务
+ */
+@Injectable()
+export class FeishuSdkService implements OnModuleInit, OnModuleDestroy {
+  protected readonly client: lark.Client;
+
+  onModuleInit(): void {
+    const eventDispatcher = new lark.EventDispatcher({
+      encryptKey: "encrypt key",
+    }).register<CardEvents>({
+      [FEISHU_CARD_ACTION_TRIGGER]: async (data) => {
+        let done: (result: CardActionTriggerResponse) => void = () => null;
+        const p = new Promise<CardActionTriggerResponse>((resolve) => {
+          done = resolve;
+        });
+
+        // 转换为事件监听器友好的格式
+        const event: CardActionTriggerEvent = {
+          ...data,
+          done,
+        };
+
+        this.eventEmitter.emit(FEISHU_CARD_ACTION_TRIGGER, event);
+        return await p;
+      },
+    });
+  }
+
+  onModuleDestroy(): void {
+    this.eventEmitter.removeAllListeners();
+  }
+
+  constructor(
+    @Inject(FEISHU_MODULE_OPTIONS)
+    protected readonly options: FeishuModuleOptions,
+    protected readonly eventEmitter: EventEmitter2,
+  ) {
+    this.client = new lark.Client({
+      appId: options.appId,
+      appSecret: options.appSecret,
+      appType: options.appType === "store" ? lark.AppType.ISV : lark.AppType.SelfBuild,
+      domain: options.domain === "lark" ? lark.Domain.Lark : lark.Domain.Feishu,
+    });
+  }
+
+  /**
+   * 验证飞书配置
+   */
+  validateConfig(): void {
+    if (!this.options?.appId) {
+      throw new Error("缺少配置 feishu.appId (环境变量 FEISHU_APP_ID)");
+    }
+
+    if (!this.options?.appSecret) {
+      throw new Error("缺少配置 feishu.appSecret (环境变量 FEISHU_APP_SECRET)");
+    }
+  }
+
+  /**
+   * 获取原始 Lark Client 实例
+   * 用于调用 SDK 中未封装的 API
+   */
+  getClient(): lark.Client {
+    return this.client;
+  }
+
+  /**
+   * 获取用户信息
+   * @param params 获取用户信息的参数
+   * @returns 用户信息
+   */
+  async getUser(params: GetUserParams): Promise<FeishuUser | null> {
+    const { userId, userIdType = "open_id", departmentIdType } = params;
+
+    const response = await this.client.contact.user.get({
+      path: {
+        user_id: userId,
+      },
+      params: {
+        user_id_type: userIdType,
+        department_id_type: departmentIdType,
+      },
+    });
+
+    if (response.code !== 0) {
+      throw new Error(`飞书 API 错误: ${response.code} - ${response.msg}`);
+    }
+
+    return response.data?.user as FeishuUser | null;
+  }
+
+  /**
+   * 批量获取用户信息
+   * @param userIds 用户 ID 列表
+   * @param userIdType 用户 ID 类型
+   * @returns 用户信息列表
+   */
+  async batchGetUsers(
+    userIds: string[],
+    userIdType: "open_id" | "union_id" | "user_id" = "open_id",
+  ): Promise<FeishuUser[]> {
+    const response = await this.client.contact.user.batch({
+      params: {
+        user_ids: userIds,
+        user_id_type: userIdType,
+      },
+    });
+
+    if (response.code !== 0) {
+      throw new Error(`飞书 API 错误: ${response.code} - ${response.msg}`);
+    }
+
+    return (response.data?.items || []) as FeishuUser[];
+  }
+}

package/src/shared/feishu-sdk/fieshu-card.service.ts

@@ -0,0 +1,139 @@
+import { Injectable } from "@nestjs/common";
+import { FeishuSdkService } from "./feishu-sdk.service";
+import {
+  SendCardParams,
+  ReplyCardParams,
+  UpdateCardParams,
+  SendMessageResponse,
+  CardContent,
+  type CardActionTriggerCallback,
+} from "./types";
+import { OnEvent, type EventEmitter2 } from "@nestjs/event-emitter";
+import { FEISHU_CARD_ACTION_TRIGGER } from "./types";
+
+/**
+ * 飞书卡片消息服务
+ * 提供卡片消息的发送、回复、更新功能
+ */
+@Injectable()
+export class FeishuCardService {
+  constructor(
+    protected readonly feishuSdkService: FeishuSdkService,
+    protected readonly eventEmitter: EventEmitter2,
+  ) {}
+
+  @OnEvent(FEISHU_CARD_ACTION_TRIGGER)
+  async handleCardActionTrigger(event: CardActionTriggerCallback) {
+    const event_hook = event.header.event_type ?? event.event.action.tag;
+
+    // console.log(event_hook);
+  }
+
+  /**
+   * 将卡片内容转换为字符串
+   */
+  protected serializeCard(card: CardContent): string {
+    return typeof card === "string" ? card : JSON.stringify(card);
+  }
+
+  /**
+   * 转换 API 响应为统一格式
+   */
+  protected transformMessageResponse(data: any): SendMessageResponse {
+    return {
+      messageId: data.message_id,
+      rootId: data.root_id,
+      parentId: data.parent_id,
+      msgType: data.msg_type,
+      createTime: data.create_time,
+      updateTime: data.update_time,
+      deleted: data.deleted,
+      updated: data.updated,
+      chatId: data.chat_id,
+      sender: {
+        id: data.sender?.id,
+        idType: data.sender?.id_type,
+        senderType: data.sender?.sender_type,
+        tenantKey: data.sender?.tenant_key,
+      },
+    };
+  }
+
+  /**
+   * 发送卡片消息
+   * @param params 发送卡片消息的参数
+   * @returns 发送结果
+   */
+  async sendCard(params: SendCardParams): Promise<SendMessageResponse> {
+    const { receiveId, receiveIdType, card, uuid } = params;
+    const client = this.feishuSdkService.getClient();
+
+    const response = await client.im.message.create({
+      params: {
+        receive_id_type: receiveIdType,
+      },
+      data: {
+        receive_id: receiveId,
+        msg_type: "interactive",
+        content: this.serializeCard(card),
+        uuid,
+      },
+    });
+
+    if (response.code !== 0) {
+      throw new Error(`飞书发送卡片失败: ${response.code} - ${response.msg}`);
+    }
+
+    return this.transformMessageResponse(response.data);
+  }
+
+  /**
+   * 回复卡片消息
+   * @param params 回复卡片消息的参数
+   * @returns 回复结果
+   */
+  async replyCard(params: ReplyCardParams): Promise<SendMessageResponse> {
+    const { messageId, card, uuid } = params;
+    const client = this.feishuSdkService.getClient();
+
+    const response = await client.im.message.reply({
+      path: {
+        message_id: messageId,
+      },
+      data: {
+        msg_type: "interactive",
+        content: this.serializeCard(card),
+        uuid,
+      },
+    });
+
+    if (response.code !== 0) {
+      throw new Error(`飞书回复卡片失败: ${response.code} - ${response.msg}`);
+    }
+
+    return this.transformMessageResponse(response.data);
+  }
+
+  /**
+   * 更新卡片消息
+   * @param params 更新卡片消息的参数
+   * @returns 更新是否成功
+   */
+  async updateCard(params: UpdateCardParams): Promise<void> {
+    const { messageId, card } = params;
+    const client = this.feishuSdkService.getClient();
+
+    const response = await client.im.message.patch({
+      path: {
+        message_id: messageId,
+      },
+      data: {
+        content: this.serializeCard(card),
+      },
+    });
+
+    if (response.code !== 0) {
+      throw new Error(`飞书更新卡片失败: ${response.code} - ${response.msg}`);
+    }
+  }
+}

package/src/shared/feishu-sdk/index.ts

@@ -0,0 +1,4 @@
+export * from "./feishu-sdk.module";
+export * from "./feishu-sdk.service";
+export * from "./fieshu-card.service";
+export * from "./types/index";

package/src/shared/feishu-sdk/types/card-action.ts

@@ -0,0 +1,132 @@
+/**
+ * 飞书 SDK 卡片交互回调相关类型
+ */
+
+import type { I18nLocale } from "./common";
+import type { CardData } from "./card";
+
+/** 卡片交互事件名称常量 */
+export const FEISHU_CARD_ACTION_TRIGGER = "card.action.trigger" as const;
+
+/** 回调基本信息 (header) */
+export interface CardActionHeader {
+  /** 回调的唯一标识 */
+  event_id: string;
+  /** 应用的 Verification Token */
+  token: string;
+  /** 回调发送的时间，微秒级时间戳 */
+  create_time: string;
+  /** 回调类型，固定为 "card.action.trigger" */
+  event_type: typeof FEISHU_CARD_ACTION_TRIGGER;
+  /** 应用归属的 tenant key */
+  tenant_key: string;
+  /** 应用的 App ID */
+  app_id: string;
+}
+
+/** 操作者信息 */
+export interface CardActionOperator {
+  /** 回调触发者的 tenant key */
+  tenant_key: string;
+  /** 回调触发者的 user_id (需开启权限) */
+  user_id?: string;
+  /** 回调触发者的 open_id */
+  open_id: string;
+  /** 回调触发者的 union_id */
+  union_id?: string;
+}
+
+/** 交互信息 */
+export interface CardActionInfo {
+  /** 交互组件绑定的开发者自定义回传数据 */
+  value?: Record<string, unknown> | string;
+  /** 交互组件的标签 */
+  tag: string;
+  /** 用户当前所在地区的时区 */
+  timezone?: string;
+  /** 组件的自定义唯一标识 */
+  name?: string;
+  /** 表单容器内用户提交的数据 */
+  form_value?: Record<string, unknown>;
+  /** 输入框组件提交的数据 (未内嵌在表单中时) */
+  input_value?: string;
+  /** 单选组件的选项回调值 */
+  option?: string;
+  /** 多选组件的选项回调值 */
+  options?: string[];
+  /** 勾选器组件的回调数据 */
+  checked?: boolean;
+}
+
+/** 展示场景上下文 */
+export interface CardActionContext {
+  /** 链接地址 (适用于链接预览场景) */
+  url?: string;
+  /** 链接预览的 token */
+  preview_token?: string;
+  /** 消息 ID */
+  open_message_id: string;
+  /** 会话 ID */
+  open_chat_id: string;
+}
+
+/** 回调详细信息 (event) */
+export interface CardActionEventData {
+  /** 回调触发者信息 */
+  operator: CardActionOperator;
+  /** 更新卡片用的凭证，有效期 30 分钟，最多可更新 2 次 */
+  token: string;
+  /** 交互信息 */
+  action: CardActionInfo;
+  /** 卡片展示场景 */
+  host?: string;
+  /** 卡片分发类型，链接预览卡片时为 url_preview */
+  delivery_type?: "url_preview";
+  /** 展示场景上下文 */
+  context: CardActionContext;
+}
+
+/** 回调结构体 (schema 2.0) */
+export interface CardActionTriggerCallback {
+  /** 回调版本，固定为 "2.0" */
+  schema: "2.0";
+  /** 回调基本信息 */
+  header: CardActionHeader;
+  /** 回调详细信息 */
+  event: CardActionEventData;
+}
+
+/** Toast 提示配置 */
+export interface CardActionToast {
+  /** 弹窗提示的类型 */
+  type?: "info" | "success" | "error" | "warning";
+  /** 单语言提示文案 */
+  content?: string;
+  /** 多语言提示文案 */
+  i18n?: Partial<Record<I18nLocale, string>>;
+}
+
+/** 响应回调的结构体 */
+export interface CardActionTriggerResponse {
+  /** Toast 弹窗提示 */
+  toast?: CardActionToast;
+  /** 卡片数据 (用于更新卡片) */
+  card?: CardData;
+}
+
+/** 交互事件回调接口 */
+export interface CardActionTriggerEventCallback {
+  /** 完成回调，返回响应结果 */
+  done: (result: CardActionTriggerResponse) => void;
+}
+
+/** 交互事件 (用于事件监听器)，包含回调数据和 done 方法 */
+export interface CardActionTriggerEvent
+  extends CardActionTriggerEventCallback, CardActionTriggerCallback {}
+
+/** 事件注册类型 */
+export interface CardEvents {
+  [FEISHU_CARD_ACTION_TRIGGER]: (
+    data: CardActionTriggerCallback,
+  ) => Promise<CardActionTriggerResponse>;
+}

package/src/shared/feishu-sdk/types/card.ts

@@ -0,0 +1,64 @@
+/**
+ * 飞书 SDK 卡片消息相关类型
+ */
+
+import type { ReceiveIdType } from "./message";
+
+/** 卡片消息内容，可以是 JSON 对象或 JSON 字符串 */
+export type CardContent = Record<string, unknown> | string;
+
+/** 发送卡片消息参数 */
+export interface SendCardParams {
+  /** 接收者 ID */
+  receiveId: string;
+  /** 接收者 ID 类型 */
+  receiveIdType: ReceiveIdType;
+  /** 卡片内容 (JSON 对象或字符串) */
+  card: CardContent;
+  /** 可选的 UUID，用于幂等性控制 */
+  uuid?: string;
+}
+
+/** 回复卡片消息参数 */
+export interface ReplyCardParams {
+  /** 要回复的消息 ID */
+  messageId: string;
+  /** 卡片内容 (JSON 对象或字符串) */
+  card: CardContent;
+  /** 可选的 UUID，用于幂等性控制 */
+  uuid?: string;
+}
+
+/** 更新卡片消息参数 */
+export interface UpdateCardParams {
+  /** 要更新的消息 ID */
+  messageId: string;
+  /** 新的卡片内容 (JSON 对象或字符串) */
+  card: CardContent;
+}
+
+/** 卡片数据 - 使用 JSON 代码 */
+export interface CardDataRaw {
+  /** 卡片类型: raw 表示 JSON 构建的卡片 */
+  type: "raw";
+  /** 卡片的 JSON 数据 */
+  data: Record<string, unknown>;
+}
+
+/** 卡片数据 - 使用卡片模板 */
+export interface CardDataTemplate {
+  /** 卡片类型: template 表示卡片模板 */
+  type: "template";
+  /** 卡片模板数据 */
+  data: {
+    /** 卡片模板 ID */
+    template_id: string;
+    /** 卡片模板版本号 */
+    template_version_name?: string;
+    /** 卡片模板变量 */
+    template_variable?: Record<string, unknown>;
+  };
+}
+
+/** 卡片数据类型 */
+export type CardData = CardDataRaw | CardDataTemplate;

package/src/shared/feishu-sdk/types/common.ts

@@ -0,0 +1,22 @@
+/**
+ * 飞书 SDK 通用类型
+ */
+
+/** 支持的语言类型 */
+export type I18nLocale =
+  | "zh_cn"
+  | "en_us"
+  | "zh_hk"
+  | "zh_tw"
+  | "ja_jp"
+  | "id_id"
+  | "vi_vn"
+  | "th_th"
+  | "pt_br"
+  | "es_es"
+  | "ko_kr"
+  | "de_de"
+  | "fr_fr"
+  | "it_it"
+  | "ru_ru"
+  | "ms_my";

package/src/shared/feishu-sdk/types/index.ts

@@ -0,0 +1,46 @@
+/**
+ * 飞书 SDK 类型定义
+ */
+
+// Module - 模块配置
+export {
+  FEISHU_MODULE_OPTIONS,
+  type FeishuModuleOptions,
+  type FeishuModuleAsyncOptions,
+} from "./module";
+
+// Common - 通用类型
+export { type I18nLocale } from "./common";
+
+// User - 用户相关
+export { type UserIdType, type FeishuUser, type GetUserParams } from "./user";
+
+// Message - 消息相关
+export { type ReceiveIdType, type SendMessageResponse } from "./message";
+
+// Card - 卡片消息
+export {
+  type CardContent,
+  type SendCardParams,
+  type ReplyCardParams,
+  type UpdateCardParams,
+  type CardDataRaw,
+  type CardDataTemplate,
+  type CardData,
+} from "./card";
+
+// CardAction - 卡片交互回调
+export {
+  FEISHU_CARD_ACTION_TRIGGER,
+  type CardActionHeader,
+  type CardActionOperator,
+  type CardActionInfo,
+  type CardActionContext,
+  type CardActionEventData,
+  type CardActionTriggerCallback,
+  type CardActionToast,
+  type CardActionTriggerResponse,
+  type CardActionTriggerEventCallback,
+  type CardActionTriggerEvent,
+  type CardEvents,
+} from "./card-action";

package/src/shared/feishu-sdk/types/message.ts

@@ -0,0 +1,35 @@
+/**
+ * 飞书 SDK 消息相关类型
+ */
+
+/** 消息接收者类型 */
+export type ReceiveIdType = "open_id" | "user_id" | "union_id" | "email" | "chat_id";
+
+/** 发送/回复消息的响应 */
+export interface SendMessageResponse {
+  /** 消息 ID */
+  messageId: string;
+  /** 根消息 ID (用于消息链) */
+  rootId?: string;
+  /** 父消息 ID */
+  parentId?: string;
+  /** 消息类型 */
+  msgType: string;
+  /** 创建时间 (毫秒时间戳) */
+  createTime: string;
+  /** 更新时间 (毫秒时间戳) */
+  updateTime: string;
+  /** 是否被撤回 */
+  deleted: boolean;
+  /** 是否被更新 */
+  updated: boolean;
+  /** 会话 ID */
+  chatId: string;
+  /** 发送者信息 */
+  sender: {
+    id: string;
+    idType: string;
+    senderType: string;
+    tenantKey?: string;
+  };
+}

package/src/shared/feishu-sdk/types/module.ts

@@ -0,0 +1,21 @@
+/**
+ * 飞书 SDK 模块配置类型
+ */
+
+export const FEISHU_MODULE_OPTIONS = "FEISHU_MODULE_OPTIONS";
+
+export interface FeishuModuleOptions {
+  /** 应用 ID */
+  appId: string;
+  /** 应用密钥 */
+  appSecret: string;
+  /** 应用类型：自建应用或商店应用 */
+  appType?: "self_build" | "store";
+  /** 域名：飞书或 Lark */
+  domain?: "feishu" | "lark";
+}
+
+export interface FeishuModuleAsyncOptions {
+  useFactory: (...args: any[]) => Promise<FeishuModuleOptions> | FeishuModuleOptions;
+  inject?: any[];
+}

package/src/shared/feishu-sdk/types/user.ts

@@ -0,0 +1,77 @@
+/**
+ * 飞书 SDK 用户相关类型
+ */
+
+/** 用户 ID 类型 */
+export type UserIdType = "open_id" | "union_id" | "user_id";
+
+/** 用户信息 */
+export interface FeishuUser {
+  /** 用户的 union_id */
+  union_id?: string;
+  /** 用户的 user_id */
+  user_id?: string;
+  /** 用户的 open_id */
+  open_id?: string;
+  /** 用户名 */
+  name?: string;
+  /** 英文名 */
+  en_name?: string;
+  /** 昵称 */
+  nickname?: string;
+  /** 邮箱 */
+  email?: string;
+  /** 手机号 */
+  mobile?: string;
+  /** 手机号码可见性 */
+  mobile_visible?: boolean;
+  /** 性别 */
+  gender?: number;
+  /** 头像 */
+  avatar?: {
+    avatar_72?: string;
+    avatar_240?: string;
+    avatar_640?: string;
+    avatar_origin?: string;
+  };
+  /** 用户状态 */
+  status?: {
+    is_frozen?: boolean;
+    is_resigned?: boolean;
+    is_activated?: boolean;
+    is_exited?: boolean;
+    is_unjoin?: boolean;
+  };
+  /** 所属部门 ID 列表 */
+  department_ids?: string[];
+  /** 直属主管的用户 ID */
+  leader_user_id?: string;
+  /** 城市 */
+  city?: string;
+  /** 国家或地区 */
+  country?: string;
+  /** 工位 */
+  work_station?: string;
+  /** 入职时间 */
+  join_time?: number;
+  /** 是否是租户管理员 */
+  is_tenant_manager?: boolean;
+  /** 工号 */
+  employee_no?: string;
+  /** 员工类型 */
+  employee_type?: number;
+  /** 企业邮箱 */
+  enterprise_email?: string;
+  /** 职务 */
+  job_title?: string;
+}
+
+/** 获取用户信息的参数 */
+export interface GetUserParams {
+  /** 用户 ID */
+  userId: string;
+  /** 用户 ID 类型 */
+  userIdType?: UserIdType;
+  /** 部门 ID 类型 */
+  departmentIdType?: "department_id" | "open_department_id";
+}