Lark/Feishu Node SDK

The Lark/Feishu Node SDK is the official server-side client for Lark Suite and Feishu’s Open Platform, the workplace collaboration suite used across bots, approval flows, document automation, and interactive messaging. It wraps the platform’s sprawling REST surface in a semantic, fully-typed client (client.im.message.create, client.contact.user.list, and hundreds more) so developers avoid hand-rolling token refresh, request signing, and pagination.

Beyond plain API calls, the SDK ships built-in event dispatching and card-action handling with adapters for Express, Koa, and generic HTTP, plus a WebSocket client for long-connection event delivery without exposing a public webhook endpoint. It is maintained directly by the Lark/Feishu team and tracks new platform capabilities closely, making it the default choice for any Node.js integration targeting the Lark/Feishu ecosystem.

What You Get

• A semantic client (client.<domain>.<resource>.<method>) covering messaging, contacts, approvals, calendar, docs, and more with full TypeScript type hints
• Automatic tenant/app access-token acquisition, caching, and refresh so callers never manage tokens manually
• Built-in event dispatcher and interactive-card handlers with ready-made adapters for Express, Koa, and Koa-router
• A WebSocket client (WSClient) for receiving platform events over a long connection instead of exposing a public webhook
• Iterator-based pagination helpers (*WithIterator) that eliminate manual page_token bookkeeping
• Encapsulated file upload/download handling, including streaming download via getReadableStream

Common Use Cases

• Building a self-built or ISV Lark/Feishu bot that sends interactive message cards and responds to card actions
• Automating enterprise workflows such as attendance, approvals, or contact/department management via server-side scripts
• Receiving platform events (message, approval, calendar) through a WebSocket connection in environments without public inbound webhooks
• Syncing organization contact/department data into an internal system using the paginated iterator APIs

Under The Hood

Architecture - The SDK centers on a Client class (client/client.ts) that extends a code-generated RequestTemplate base, giving every one of the hundreds of Feishu/Lark endpoints a typed method without hand-writing each one. A TokenManager handles app/tenant/user access-token acquisition, caching (pluggable Cache interface, defaulting to an in-memory store), and refresh transparently before each call. Separate modules handle concerns cleanly: dispatcher/ for event and card-action routing, adaptor/ for framework-specific HTTP glue (Express, Koa, Koa-router, or a generic default), and ws-client/ for a persistent WebSocket connection that receives platform events without a public webhook, using Protocol Buffers (ws-client/proto-buf) for the wire format.

Tech Stack - Written in TypeScript, built with Rollup into CommonJS and ESM outputs plus type declarations. Runtime dependencies are deliberately minimal: axios for HTTP, ws for the WebSocket client, protobufjs for binary event decoding, and small lodash.* helpers rather than the full lodash package. Dev tooling uses Jest for testing, ESLint (Airbnb base config) plus Prettier for style, and optional peer integrations with Express/Koa for the adapter layer.

Code Quality - The repo has 27+ __tests__ directories/files covering utilities, the channel/event layer, and logger internals, though core client request logic is comparatively thin on tests relative to its surface area. Code is organized by clear feature folders (client, dispatcher, adaptor, channel, ws-client) rather than one large file, naming is consistent with the domain model of the Feishu/Lark API, and TypeScript types are used throughout public interfaces, giving IDE-level safety for the very large generated API surface.

API Design - The semantic call pattern (client.im.message.create, client.contact.user.listWithIterator) closely mirrors the platform’s own documentation structure, which lowers the mental gap between reading Feishu’s API docs and writing code. Iterator-based pagination and encapsulated file upload/download remove common boilerplate, and the bilingual (English/Chinese) README plus linked official tutorials meaningfully shorten onboarding for a platform whose primary documentation is otherwise in Chinese.