@satorijs/adapter-lark 3.1.4 → 3.1.6

package/src/http.ts

@@ -0,0 +1,157 @@
+import internal from 'stream'
+import { Adapter, Context, Logger, Schema } from '@satorijs/satori'
+import {} from '@satorijs/router'
+
+import { FeishuBot } from './bot'
+import { AllEvents } from './types'
+import { adaptSession, Cipher } from './utils'
+
+export class HttpServer<C extends Context = Context> extends Adapter<C, FeishuBot<C>> {
+  static inject = ['router']
+
+  private logger: Logger
+  private ciphers: Record<string, Cipher> = {}
+
+  constructor(ctx: C, bot: FeishuBot<C>) {
+    super(ctx)
+    this.logger = ctx.logger('lark')
+  }
+
+  fork(ctx: C, bot: FeishuBot<C>) {
+    super.fork(ctx, bot)
+
+    this._refreshCipher()
+    return bot.initialize()
+  }
+
+  async connect(bot: FeishuBot) {
+    const { path } = bot.config
+    bot.ctx.router.post(path, (ctx) => {
+      this._refreshCipher()
+
+      // compare signature if encryptKey is set
+      // But not every message contains signature
+      // https://open.larksuite.com/document/ukTMukTMukTM/uYDNxYjL2QTM24iN0EjN/event-subscription-configure-/encrypt-key-encryption-configuration-case#d41e8916
+      const signature = ctx.get('X-Lark-Signature')
+      const enabledSignatureVerify = this.bots.filter((bot) => bot.config.verifySignature)
+      if (signature && enabledSignatureVerify.length) {
+        const result = enabledSignatureVerify.some((bot) => {
+          const timestamp = ctx.get('X-Lark-Request-Timestamp')
+          const nonce = ctx.get('X-Lark-Request-Nonce')
+          const body = ctx.request.rawBody
+          const actualSignature = this.ciphers[bot.config.appId]?.calculateSignature(timestamp, nonce, body)
+          if (actualSignature === signature) return true
+          else return false
+        })
+        if (!result) return (ctx.status = 403)
+      }
+
+      // try to decrypt message first if encryptKey is set
+      const body = this._tryDecryptBody(ctx.request.body)
+      // respond challenge message
+      // https://open.larksuite.com/document/ukTMukTMukTM/uYDNxYjL2QTM24iN0EjN/event-subscription-configure-/request-url-configuration-case
+      if (body?.type === 'url_verification' && body?.challenge && typeof body.challenge === 'string') {
+        ctx.response.body = { challenge: body.challenge }
+        return
+      }
+
+      // compare verification token
+      const enabledVerifyTokenVerify = this.bots.filter((bot) => bot.config.verifyToken && bot.config.verificationToken)
+      if (enabledVerifyTokenVerify.length) {
+        const token = ctx.request.body?.token
+        // only compare token if token exists
+        if (token) {
+          const result = enabledVerifyTokenVerify.some((bot) => {
+            if (token === bot.config.verificationToken) return true
+            else return false
+          })
+          if (!result) return (ctx.status = 403)
+        }
+      }
+
+      // dispatch message
+      bot.logger.debug('received decryped event: %o', body)
+      this.dispatchSession(body)
+
+      // Lark requires 200 OK response to make sure event is received
+      return ctx.status = 200
+    })
+
+    bot.ctx.router.get(path + '/assets/:type/:message_id/:key', async (ctx) => {
+      const type = ctx.params.type === 'image' ? 'image' : 'file'
+      const key = ctx.params.key
+      const messageId = ctx.params.message_id
+      const selfId = ctx.request.query.self_id
+      const bot = this.bots.find((bot) => bot.selfId === selfId)
+      if (!bot) return ctx.status = 404
+
+      const resp = await bot.http.axios<internal.Readable>(`/im/v1/messages/${messageId}/resources/${key}`, {
+        method: 'GET',
+        params: { type },
+        responseType: 'stream',
+      })
+
+      ctx.status = 200
+      ctx.response.headers['Content-Type'] = resp.headers['content-type']
+      ctx.response.body = resp.data
+    })
+  }
+
+  dispatchSession(body: AllEvents): void {
+    const { header } = body
+    if (!header) return
+    const { app_id, event_type } = header
+    body.type = event_type // add type to body to ease typescript type narrowing
+    const bot = this.bots.find((bot) => bot.selfId === app_id)
+    const session = adaptSession(bot, body)
+    bot.dispatch(session)
+  }
+
+  private _tryDecryptBody(body: any): any {
+    this._refreshCipher()
+    // try to decrypt message if encryptKey is set
+    // https://open.larksuite.com/document/ukTMukTMukTM/uYDNxYjL2QTM24iN0EjN/event-subscription-configure-/encrypt-key-encryption-configuration-case
+    const ciphers = Object.values(this.ciphers)
+    if (ciphers.length && typeof body.encrypt === 'string') {
+      for (const cipher of ciphers) {
+        try {
+          return JSON.parse(cipher.decrypt(body.encrypt))
+        } catch {}
+      }
+      this.logger.warn('failed to decrypt message: %o', body)
+    }
+
+    if (typeof body.encrypt === 'string' && !ciphers.length) {
+      this.logger.warn('encryptKey is not set, but received encrypted message: %o', body)
+    }
+
+    return body
+  }
+
+  private _refreshCipher(): void {
+    const ciphers = Object.keys(this.ciphers)
+    const bots = this.bots.map((bot) => bot.config.appId)
+    if (bots.length === ciphers.length && bots.every((bot) => ciphers.includes(bot))) return
+
+    this.ciphers = {}
+    for (const bot of this.bots) {
+      this.ciphers[bot.config.appId] = new Cipher(bot.config.encryptKey)
+    }
+  }
+}
+
+export namespace HttpServer {
+  export interface Config {
+    selfUrl?: string
+    path?: string
+    verifyToken?: boolean
+    verifySignature?: boolean
+  }
+
+  export const createConfig = (path: string): Schema<Config> => Schema.object({
+    path: Schema.string().role('url').description('要连接的服务器地址。').default(path),
+    selfUrl: Schema.string().role('link').description('服务器暴露在公网的地址。缺省时将使用全局配置。'),
+    verifyToken: Schema.boolean().description('是否验证令牌。'),
+    verifySignature: Schema.boolean().description('是否验证签名。'),
+  }).description('服务端设置')
+}

package/src/index.ts

@@ -0,0 +1,15 @@
+import { FeishuBot } from './bot'
+import * as Lark from './types'
+
+export * from './bot'
+
+export { Lark, Lark as Feishu }
+
+export default FeishuBot
+
+declare module '@satorijs/core' {
+  interface Session {
+    feishu: Lark.Internal
+    lark: Lark.Internal
+  }
+}

package/src/message.ts

@@ -0,0 +1,185 @@
+import { createReadStream } from 'fs'
+import internal from 'stream'
+
+import { Context, h, MessageEncoder, Quester } from '@satorijs/satori'
+import FormData from 'form-data'
+
+import { LarkBot } from './bot'
+import { BaseResponse, Message, MessageContent, MessageType } from './types'
+import { extractIdType } from './utils'
+
+export interface Addition {
+  file: MessageContent.MediaContents
+  type: MessageType
+}
+
+export class LarkMessageEncoder<C extends Context = Context> extends MessageEncoder<C, LarkBot<C>> {
+  private quote: string | undefined
+  private content = ''
+  private addition: Addition
+  // TODO: currently not used, would be supported in the future
+  private richText: MessageContent.RichText[string]
+
+  async post(data?: any) {
+    try {
+      let resp: BaseResponse & { data: Message }
+      if (this.quote) {
+        resp = await this.bot.internal?.replyMessage(this.quote, data)
+      } else {
+        data.receive_id = this.channelId
+        resp = await this.bot.internal?.sendMessage(extractIdType(this.channelId), data)
+      }
+      const session = this.bot.session()
+      session.messageId = resp.data.message_id
+      session.timestamp = Number(resp.data.create_time) * 1000
+      session.userId = resp.data.sender.id
+      session.app.emit(session, 'send', session)
+      this.results.push(session.event.message)
+    } catch (e) {
+      // try to extract error message from Lark API
+      if (Quester.isAxiosError(e)) {
+        if (e.response?.data?.code) {
+          const generalErrorMsg = `Check error code at https://open.larksuite.com/document/server-docs/getting-started/server-error-codes`
+          e.message += ` (Lark error code ${e.response.data.code}: ${e.response.data.msg ?? generalErrorMsg})`
+        }
+      }
+      this.errors.push(e)
+    }
+  }
+
+  async flush() {
+    if (this.content === '' && !this.addition && !this.richText) return
+
+    let message: MessageContent.Contents
+    if (this.addition) {
+      message = {
+        ...message,
+        ...this.addition.file,
+      }
+    }
+    if (this.richText) {
+      message = { zh_cn: this.richText }
+    }
+    if (this.content) {
+      message = { text: this.content }
+    }
+    await this.post({
+      msg_type: this.richText ? 'post' : this.addition ? this.addition.type : 'text',
+      content: JSON.stringify(message),
+    })
+
+    // reset cached content
+    this.quote = undefined
+    this.content = ''
+    this.addition = undefined
+    this.richText = undefined
+  }
+
+  async sendFile(type: 'image' | 'video' | 'audio' | 'file', url: string): Promise<Addition> {
+    const payload = new FormData()
+
+    const assetKey = type === 'image' ? 'image' : 'file'
+    const [schema, file] = url.split('://')
+    const filename = schema === 'base64' ? 'unknown' : new URL(url).pathname.split('/').pop()
+    if (schema === 'file') {
+      payload.append(assetKey, createReadStream(file))
+    } else if (schema === 'base64') {
+      payload.append(assetKey, Buffer.from(file, 'base64'))
+    } else {
+      const resp = await this.bot.assetsQuester.get<internal.Readable>(url, { responseType: 'stream' })
+      payload.append(assetKey, resp)
+    }
+
+    if (type === 'image') {
+      payload.append('image_type', 'message')
+      const { data } = await this.bot.internal.uploadImage(payload)
+      return {
+        type: 'image',
+        file: {
+          image_key: data.image_key,
+        },
+      }
+    } else {
+      let msgType: MessageType = 'file'
+      if (type === 'audio') {
+        // FIXME: only support opus
+        payload.append('file_type', 'opus')
+        msgType = 'audio'
+      } else if (type === 'video') {
+        // FIXME: only support mp4
+        payload.append('file_type', 'mp4')
+        msgType = 'media'
+      } else {
+        const ext = filename.split('.').pop()
+        if (['xls', 'ppt', 'pdf'].includes(ext)) {
+          payload.append('file_type', ext)
+        } else {
+          payload.append('file_type', 'stream')
+        }
+      }
+      payload.append('file_name', filename)
+      const { data } = await this.bot.internal.uploadFile(payload)
+      return {
+        type: msgType,
+        file: {
+          file_key: data.file_key,
+        },
+      }
+    }
+  }
+
+  async visit(element: h) {
+    const { type, attrs, children } = element
+
+    switch (type) {
+      case 'text':
+        this.content += attrs.content
+        break
+      case 'at': {
+        if (attrs.type === 'all') {
+          this.content += `<at user_id="all">${attrs.name ?? '所有人'}</at>`
+        } else {
+          this.content += `<at user_id="${attrs.id}">${attrs.name}</at>`
+        }
+        break
+      }
+      case 'a':
+        await this.render(children)
+        if (attrs.href) this.content += ` (${attrs.href})`
+        break
+      case 'p':
+        if (!this.content.endsWith('\n')) this.content += '\n'
+        await this.render(children)
+        if (!this.content.endsWith('\n')) this.content += '\n'
+        break
+      case 'br':
+        this.content += '\n'
+        break
+      case 'sharp':
+        // platform does not support sharp
+        break
+      case 'quote':
+        await this.flush()
+        this.quote = attrs.id
+        break
+      case 'image':
+      case 'video':
+      case 'audio':
+      case 'file':
+        if (attrs.url) {
+          await this.flush()
+          this.addition = await this.sendFile(type, attrs.url)
+        }
+        break
+      case 'figure': // FIXME: treat as message element for now
+      case 'message':
+        await this.flush()
+        await this.render(children, true)
+        break
+      default:
+        await this.render(children)
+    }
+  }
+}
+
+export { LarkMessageEncoder as FeishuMessageEncoder }

package/src/types/.eslintrc.yml

@@ -0,0 +1,2 @@
+rules:
+  max-len: off

package/src/types/auth.ts

@@ -0,0 +1,54 @@
+import { BaseResponse, Internal } from '.'
+
+/**
+ * Lark defines three types of token:
+ * - app_access_token: to access the API in an app (published on App Store).
+ * - tenant_access_token: to access the API as an enterprise or a team (tenant).
+ *   *We commonly use this one*
+ * - user_access_token: to access the API as the specific user.
+ *
+ * @see https://open.larksuite.com/document/ukTMukTMukTM/uMTNz4yM1MjLzUzM
+ */
+
+export interface AppCredentials {
+  app_id: string
+  app_secret: string
+}
+
+export interface AppAccessToken extends BaseResponse {
+  /** access token */
+  app_access_token: string
+  /** expire time in seconds. e.g: 7140 (119 minutes) */
+  expire: number
+}
+
+export interface TenantAccessToken extends BaseResponse {
+  /** access token */
+  tenant_access_token: string
+  /** expire time in seconds. e.g: 7140 (119 minutes) */
+  expire: number
+}
+
+declare module './internal' {
+  export interface Internal {
+    /**
+     * Returns the app_access_token for the bot.
+     * @see https://open.larksuite.com/document/ukTMukTMukTM/ukDNz4SO0MjL5QzM/auth-v3/auth/app_access_token_internal
+     */
+    getAppAccessToken(data: AppCredentials): Promise<AppAccessToken>
+    /**
+     * Returns the tenant_access_token for the bot.
+     * @see https://open.larksuite.com/document/ukTMukTMukTM/ukDNz4SO0MjL5QzM/auth-v3/auth/tenant_access_token_internal
+     */
+    getTenantAccessToken(data: AppCredentials): Promise<TenantAccessToken>
+  }
+}
+
+Internal.define({
+  '/auth/v3/app_access_token/internal': {
+    POST: 'getAppAccessToken',
+  },
+  '/auth/v3/tenant_access_token/internal': {
+    POST: 'getTenantAccessToken',
+  },
+})

package/src/types/event.ts

@@ -0,0 +1,22 @@
+export interface EventHeader<T extends string> {
+  event_id: string
+  event_type: T
+  create_time: string
+  token: string
+  app_id: string
+  tenant_key: string
+}
+
+export interface Events {}
+export type EventName = keyof Events
+
+// In fact, this is the 2.0 version of the event sent by Lark.
+// And only the 2.0 version has the `schema` field.
+export type EventSkeleton<T extends EventName, Event, Header = EventHeader<T>> = {
+  schema: '2.0'
+  type: T
+  header: Header
+  event: Event
+}
+
+export type AllEvents = Events[EventName]

package/src/types/guild.ts

@@ -0,0 +1,64 @@
+import { Dict } from '@satorijs/satori'
+
+import { Lark } from '.'
+import { Internal } from './internal'
+import { Paginated, Pagination } from './utils'
+
+declare module '.' {
+  export namespace Lark {
+    export interface Guild {
+      avatar: string
+      name: string
+      description: string
+      i18n_names: Dict<string>
+      add_member_permission: string
+      share_card_permission: string
+      at_all_permission: string
+      edit_permission: string
+      owner_id_type: string
+      owner_id: string
+      chat_id: string
+      chat_mode: string
+      chat_type: string
+      chat_tag: string
+      join_message_visibility: string
+      leave_message_visibility: string
+      membership_approval: string
+      moderation_permission: string
+      external: boolean
+      tenant_key: string
+      user_count: string
+      bot_count: string
+    }
+  }
+}
+
+export interface GuildMember {
+  member_id_type: Lark.UserIdType
+  member_id: string
+  name: string
+  tenant_key: string
+}
+
+declare module './internal' {
+  export interface Internal {
+    /** @see https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/chat/list */
+    getCurrentUserGuilds(params?: Pagination<{ user_id_type?: Lark.UserIdType }>): Promise<{ data: Paginated<Lark.Guild> }>
+    /** @see https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/chat/get */
+    getGuildInfo(chat_id: string, params?: { user_id_type?: string }): Promise<BaseResponse & { data: Lark.Guild }>
+    /** @see https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/chat-members/get */
+    getGuildMembers(chat_id: string, params?: Pagination<{ member_id_type?: Lark.UserIdType }>): Promise<{ data: Paginated<GuildMember> }>
+  }
+}
+
+Internal.define({
+  '/im/v1/chats': {
+    GET: 'getCurrentUserGuilds',
+  },
+  '/im/v1/chats/{chat_id}': {
+    GET: 'getGuildInfo',
+  },
+  '/im/v1/chats/{chat_id}/members': {
+    GET: 'getGuildMembers',
+  },
+})

package/src/types/index.ts

@@ -0,0 +1,41 @@
+export * from './internal'
+export * from './auth'
+export * from './event'
+export * from './guild'
+export * from './message'
+
+export namespace Lark {
+  /**
+   * A user in Lark has several different IDs.
+   * @see https://open.larksuite.com/document/home/user-identity-introduction/introduction
+   */
+  export interface UserIds {
+    union_id: string
+    /** *user_id* only available when the app has permissions granted by the administrator */
+    user_id?: string
+    open_id: string
+  }
+
+  /**
+   * Identify a user in Lark.
+   * This behaves like {@link Lark.UserIds}, but it only contains *open_id*.
+   * (i.e. the id_type is always `open_id`)
+   */
+  export interface UserIdentifiers {
+    id: string
+    id_type: string
+  }
+
+  export type UserIdType = 'union_id' | 'user_id' | 'open_id'
+  /**
+   * The id type when specify a receiver, would be used in the request query.
+   *
+   * NOTE: we always use **open_id** to identify a user, use **chat_id** to identify a channel.
+   * @see https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/message/create
+   */
+  export type ReceiveIdType = UserIdType | 'email' | 'chat_id'
+
+  export type DepartmentIdType = 'department_id' | 'open_department_id'
+}
+
+export { Lark as Feishu }

package/src/types/internal.ts

@@ -0,0 +1,62 @@
+import FormData from 'form-data'
+import { Dict, makeArray, Quester } from '@satorijs/satori'
+import { LarkBot } from '../bot'
+
+export interface Internal {}
+
+export interface BaseResponse {
+  /** error code. would be 0 if success, and non-0 if failed. */
+  code: number
+  /** error message. would be 'success' if success. */
+  msg: string
+}
+
+type Method = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH'
+
+export class Internal {
+  constructor(private bot: LarkBot) {}
+
+  private processReponse(response: any): BaseResponse {
+    const { code, msg } = response
+    if (code === 0) {
+      return response
+    } else {
+      this.bot.logger.debug('response: %o', response)
+      throw new Error(`HTTP response with non-zero status (${code}) with message "${msg}"`)
+    }
+  }
+
+  static define(routes: Dict<Partial<Record<Method, string | string[]>>>) {
+    for (const path in routes) {
+      for (const key in routes[path]) {
+        const method = key as Method
+        for (const name of makeArray(routes[path][method])) {
+          Internal.prototype[name] = async function (this: Internal, ...args: any[]) {
+            const raw = args.join(', ')
+            const url = path.replace(/\{([^}]+)\}/g, () => {
+              if (!args.length) throw new Error(`too few arguments for ${path}, received ${raw}`)
+              return args.shift()
+            })
+            const config: Quester.AxiosRequestConfig = {}
+            if (args.length === 1) {
+              if (method === 'GET' || method === 'DELETE') {
+                config.params = args[0]
+              } else {
+                if (method === 'POST' && args[0] instanceof FormData) {
+                  config.headers = args[0].getHeaders()
+                }
+                config.data = args[0]
+              }
+            } else if (args.length === 2 && method !== 'GET' && method !== 'DELETE') {
+              config.data = args[0]
+              config.params = args[1]
+            } else if (args.length > 1) {
+              throw new Error(`too many arguments for ${path}, received ${raw}`)
+            }
+            return this.processReponse(await this.bot.http(method, url, config))
+          }
+        }
+      }
+    }
+  }
+}

package/src/types/message/asset.ts

@@ -0,0 +1,50 @@
+import FormData from 'form-data'
+
+import { BaseResponse, Internal } from '..'
+
+export interface Asset<T> extends BaseResponse {
+  data: T
+}
+
+export type Image = Asset<{ image_key: string }>
+export type File = Asset<{ file_key: string }>
+
+declare module '../internal' {
+  interface Internal {
+    /**
+     * Upload an image to obtain an `image_key` for use in sending messages or changing the avatar.
+     *
+     * The data should contain:
+     * - `image_type`: 'message' | 'avatar'
+     * - `image': Buffer
+     * @see https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/image/create
+     */
+    uploadImage(data: FormData): Promise<Image>
+    /**
+     * Upload a file to obtain a `file_key` for use in sending messages.
+     *
+     * The data should contain:
+     * - `file_type`: 'opus' | 'mp4' | 'pdf' | 'xls' | 'ppt' | 'stream'
+     *   - `opus`: Opus audio file
+     *   - `mp4`: MP4 video file
+     *   - `pdf`: PDF file
+     *   - `xls`: Excel file
+     *   - `ppt`: PowerPoint file
+     *   - `stream`: Stream file, or any other file not listed above
+     * - `file_name`: string, include extension
+     * - `duration`?: number, the duration of audio/video file in milliseconds
+     * - `file`: Buffer
+     * @see https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/file/create
+     */
+    uploadFile(data: FormData): Promise<File>
+  }
+}
+
+Internal.define({
+  '/im/v1/images': {
+    POST: 'uploadImage',
+  },
+  '/im/v1/files': {
+    POST: 'uploadFile',
+  },
+})