lark-node-sdk

用途

lark-node-sdk 是面向 @larksuiteoapi/node-sdk 的开发指南，帮助开发者在 Node.js 环境中接入飞书/Lark 开放平台。适用于调用开放平台 API、处理事件回调，以及构建消息卡片等场景。

主要能力

• 客户端初始化：支持自建应用与 ISV（商店应用）两种类型，可配置 appId、appSecret、domain（飞书/国际版 Lark/自定义 URL）、appType、disableTokenCache 等参数。
• API 调用：采用语义化链式结构 client.<domain>.<resource>.<method>，覆盖消息与群组（im）、通讯录（contact）、日历（calendar）、云文档（drive）、电子表格（sheets）、多维表格（bitable）、审批（approval）、考勤（attendance）等常用域。
• 消息发送：支持文本消息、交互式卡片、内置卡片辅助方法（defaultCard）以及卡片模板 ID 发送。
• 分页：提供 Async Iterator 形式的 listWithIterator，便于遍历分页数据。
• 文件上传/下载：支持上传文件（如 mp4）与下载文件（可写入本地或转为可读流）。
• 事件处理：支持 WebSocket（推荐，无需公网 IP 或隧道，适合本地开发）与 Webhook 两种方式，Webhook 提供 Express 与 Koa 适配器，并支持 autoChallenge。
• 卡片交互处理：通过 CardActionHandler 处理卡片回调，可返回新卡片以更新原卡片。
• 请求选项：支持传入 tenant_key、自定义请求头，以及组合多个选项（withAll）。

使用方式

1. 安装并引入 SDK：import * as lark from '@larksuiteoapi/node-sdk';
2. 使用 appId 与 appSecret 创建 lark.Client；ISV 应用需设置 appType: lark.AppType.ISV。
3. 通过链式调用发起 API 请求，例如 client.im.message.create(...) 发送消息。
4. 事件订阅可选择 WebSocket（new lark.WSClient(...) 并 start）或 Webhook（lark.EventDispatcher 配合 adaptExpress/adaptKoa）。
5. 卡片交互使用 lark.CardActionHandler 并挂载到 Webhook 路由。

适用场景

• 在 Node.js 服务中集成飞书消息通知、群机器人或交互式卡片。
• 需要读取或写入飞书通讯录、日历、云文档、多维表格、审批、考勤等数据。
• 本地开发阶段通过 WebSocket 接收事件，无需公网地址。
• ISV 商店应用需要按 tenant_key 调用接口的场景。

限制

资料未提供 SDK 的版本要求、Node.js 运行环境限制、速率限制、错误处理细节、收费或价格信息，以及各 API 的完整参数说明。具体能力与限制请以官方文档和 SDK 源码为准。