220 lines
11 KiB
Markdown
220 lines
11 KiB
Markdown
# larksuite-oapi-sdk-rs
|
|
|
|
[](https://crates.io/crates/larksuite-oapi-sdk-rs)
|
|
[](https://docs.rs/larksuite-oapi-sdk-rs)
|
|
[](https://github.com/adamcavendish/larksuite-oapi-sdk-rs/actions/workflows/ci.yml)
|
|
[](./LICENSE)
|
|
|
|
Non-official, Tokio-native Rust SDK for Lark / Feishu (飞书) Open Platform
|
|
APIs, bots, events, WebSockets, and interactive cards. It follows the official
|
|
[Go SDK](https://github.com/larksuite/oapi-sdk-go) closely while providing
|
|
idiomatic Rust configuration, typed REST resources, event handling, and optional
|
|
WebSocket, Axum, and channel integration.
|
|
|
|
## Build with Lark / Feishu
|
|
|
|
- **Build a bot:** receive typed message events and reply through the IM API.
|
|
- **Receive events:** use WebSocket long connections without a public callback
|
|
URL, or verify and dispatch HTTP webhooks.
|
|
- **Automate Open Platform workflows:** use typed REST resources for messages,
|
|
calendars, documents, Base, approvals, and more.
|
|
|
|
New to the platform? Start with the
|
|
[build a Lark / Feishu bot tutorial](docs/tutorial-build-a-feishu-bot.md). It
|
|
creates a bot that replies to received messages over a WebSocket long
|
|
connection.
|
|
|
|
## Highlights
|
|
|
|
- Tenant, user, app, and marketplace token acquisition with configurable
|
|
caching and retry behavior.
|
|
- Typed REST resources with query inputs, upload/download helpers, and lazy
|
|
iterators for supported paginated endpoints.
|
|
- Raw requests and a Go-compatibility bridge for endpoints not yet promoted to
|
|
dedicated Rust resources.
|
|
- Webhook event dispatch with signature verification and encrypted payload
|
|
decryption.
|
|
- Optional WebSocket long connections, Axum handlers, and higher-level channel
|
|
message helpers.
|
|
|
|
## Install
|
|
|
|
```toml
|
|
[dependencies]
|
|
larksuite-oapi-sdk-rs = "0.3.12"
|
|
```
|
|
|
|
The minimum supported Rust version is 1.95.0.
|
|
|
|
## Quick Start
|
|
|
|
Build a client once, then call a typed resource. The SDK handles tenant-token
|
|
acquisition and request authentication for this endpoint.
|
|
|
|
```rust,no_run
|
|
use larksuite_oapi_sdk_rs::service::im::v1::CreateMessageReqBody;
|
|
use larksuite_oapi_sdk_rs::{LarkClient, RequestOption};
|
|
|
|
#[tokio::main]
|
|
async fn main() -> Result<(), Box<dyn std::error::Error>> {
|
|
let client = LarkClient::builder("APP_ID", "APP_SECRET").build()?;
|
|
let body = CreateMessageReqBody {
|
|
receive_id: Some("CHAT_ID".to_string()),
|
|
msg_type: Some("text".to_string()),
|
|
content: Some(r#"{"text":"Hello from Rust"}"#.to_string()),
|
|
uuid: None,
|
|
};
|
|
|
|
let response = client
|
|
.im()
|
|
.message
|
|
.create("chat_id", &body, &RequestOption::default())
|
|
.await?;
|
|
|
|
println!("success: {}", response.success());
|
|
Ok(())
|
|
}
|
|
```
|
|
|
|
Use `LarkClient::builder` to set a base URL, timeout, retry limit, token cache,
|
|
custom headers, marketplace mode, helpdesk credentials, or a JWT client
|
|
assertion provider. See [`examples/client_config.rs`](examples/client_config.rs)
|
|
for the complete setup.
|
|
|
|
## Common Flows
|
|
|
|
| Need | Start here |
|
|
| --- | --- |
|
|
| Build a first Lark / Feishu bot | [Tutorial: build a Lark / Feishu bot](docs/tutorial-build-a-feishu-bot.md) |
|
|
| Call a typed REST endpoint | [`examples/send_message.rs`](examples/send_message.rs) or [generated examples](examples/README.md) |
|
|
| Call an uncovered endpoint | [`examples/raw_api.rs`](examples/raw_api.rs) |
|
|
| Control VC meeting bots | [VC meeting bots](docs/vc-bots.md) |
|
|
| Export Spark app source | [Spark app export](docs/spark-app-export.md) |
|
|
| Preview or apply Spark database schema changes | [Spark database migration](docs/spark-db-migration.md) |
|
|
| Read or modify Mail conversations | [Mail user-mailbox threads](docs/mail-v1-threads.md) |
|
|
| Resolve Drive object metadata by token | [Drive token lookup](docs/drive-token-lookup.md) |
|
|
| Manage Unified KMS autonomous keys | [Unified KMS](docs/unified-kms.md) |
|
|
| Discover or manage BaseApps | [`examples/base_v3_app_read.rs`](examples/base_v3_app_read.rs) and [Base v3 application mode](docs/base-v3-apps.md) |
|
|
| Manage Base dashboards or dashboard blocks | [Base v3 dashboards](docs/base-v3-dashboards.md) |
|
|
| Read or update Base dashboard or form sharing | [Base v3 sharing](docs/base-v3-sharing.md) |
|
|
| Manage Base v3 forms and questions | [Base v3 forms](docs/base-v3-forms.md) |
|
|
| Manage Base workflows or visible fields | [Base workflows](docs/base-v3-workflows.md) and [Base visible fields](docs/base-visible-fields.md) |
|
|
| Configure a Base field extension or share records | [Base v3 field extensions and record share links](docs/base-v3-field-extensions.md) |
|
|
| Read or update modern Docx content | [`examples/docs_ai_fetch.rs`](examples/docs_ai_fetch.rs) and [Docs AI document content](docs/docs-ai.md) |
|
|
| Read, edit, or render Slides AI presentations | [`examples/slides_ai_read.rs`](examples/slides_ai_read.rs), [`examples/slides_ai_render.rs`](examples/slides_ai_render.rs), and [Slides AI presentation content](docs/slides-ai.md) |
|
|
| Exchange or refresh OAuth tokens | [`examples/authen_oauth.rs`](examples/authen_oauth.rs) and [OAuth SSO guide](docs/oauth-sso.md) |
|
|
| Join a shared calendar event | [Events, WebSockets, and channels](docs/events-and-channels.md#calendar-share-token-joins) |
|
|
| Receive webhook events | [`examples/event_handler.rs`](examples/event_handler.rs) |
|
|
| Send a validated interactive card | [`examples/card_send.rs`](examples/card_send.rs) and [Cards guide](docs/cards.md) |
|
|
| Stream a CardKit document | [`examples/cardkit_stream.rs`](examples/cardkit_stream.rs) and [Cards guide](docs/cards.md) |
|
|
| Send a published Card Builder template | [`examples/card_template_send.rs`](examples/card_template_send.rs) and [Cards guide](docs/cards.md) |
|
|
| Handle interactive card callbacks | [`examples/card_action_handler.rs`](examples/card_action_handler.rs) |
|
|
| Run a WebSocket event client | [`examples/ws_client.rs`](examples/ws_client.rs) with `ws` enabled |
|
|
| Send channel messages | [`examples/channel_send.rs`](examples/channel_send.rs) with `messaging` enabled |
|
|
| Normalize channel messages | [`examples/channel_normalize.rs`](examples/channel_normalize.rs) with `channel` enabled |
|
|
| Search bots or work with OKRs | [`examples/bot_search.rs`](examples/bot_search.rs) and [`examples/okr_v2.rs`](examples/okr_v2.rs) |
|
|
|
|
## Guides
|
|
|
|
- [Tutorial: build a Lark / Feishu bot](docs/tutorial-build-a-feishu-bot.md):
|
|
create a WebSocket-connected bot that receives and replies to messages.
|
|
- [Go service and event compatibility](docs/go-compatibility.md): raw
|
|
requests, the compatibility bridge, and deterministic Go-to-Rust checks.
|
|
- [Cards](docs/cards.md): versioned Card JSON, CardKit streaming, published
|
|
Card Builder templates, and callbacks.
|
|
- [Card protocol alignment](docs/card-protocol.md): source hierarchy and
|
|
verification workflow for Card JSON and card callbacks.
|
|
- [Events, WebSockets, and channels](docs/events-and-channels.md): webhook
|
|
dispatch, long connections, trusted user channels, replies, and updates.
|
|
- [OAuth SSO](docs/oauth-sso.md): Feishu and Lark browser login, PKCE, token
|
|
refresh, and application-owned session handling.
|
|
- [VC meeting bots](docs/vc-bots.md): event queries and outbound meeting join,
|
|
leave, message, countdown, and active-meeting operations.
|
|
- [Spark app export](docs/spark-app-export.md): streaming source archives,
|
|
response validation, and app-type-dependent source snapshots.
|
|
- [Spark database migration](docs/spark-db-migration.md): explicit preview,
|
|
irreversible apply, and caller-owned asynchronous status polling.
|
|
- [Mail user-mailbox threads](docs/mail-v1-threads.md): conversation reads
|
|
and batch label, folder, and Trash operations.
|
|
- [Drive token lookup](docs/drive-token-lookup.md): underlying object metadata
|
|
resolution without implicit download or export.
|
|
- [Unified KMS](docs/unified-kms.md): tenant-scoped autonomous-key lifecycle,
|
|
deletion plans, recovery, and import material.
|
|
- [Base v3 application mode](docs/base-v3-apps.md): user-token workspace,
|
|
BaseApp, page, and block operations.
|
|
- [Base v3 dashboards](docs/base-v3-dashboards.md): dashboard and dashboard
|
|
block lifecycle, chart data, and layout operations.
|
|
- [Base v3 sharing](docs/base-v3-sharing.md): dashboard and form sharing
|
|
reads and partial updates with user or tenant credentials.
|
|
- [Base v3 forms](docs/base-v3-forms.md): form lifecycle and form-question
|
|
operations, including explicit destructive-delete semantics.
|
|
- [Base v3 workflows](docs/base-v3-workflows.md): workflow lifecycle with
|
|
caller-owned definition bodies.
|
|
- [Base visible fields](docs/base-visible-fields.md): full-list view and form
|
|
field visibility and ordering.
|
|
- [Base v3 field extensions and record share links](docs/base-v3-field-extensions.md):
|
|
typed extension configuration, cell updates, and batch record links.
|
|
- [Docs AI document content](docs/docs-ai.md): modern Docx content fetches,
|
|
updates, asynchronous-task reads, and version-history operations.
|
|
- [Slides AI presentation content](docs/slides-ai.md): XML presentation and
|
|
slide operations with version-history support.
|
|
- [Documentation index](docs/README.md): detailed guides and runnable examples.
|
|
|
|
## Migration from 0.2
|
|
|
|
Version 0.3 makes API-breaking corrections so the public Rust surface matches
|
|
the upstream Lark contracts more closely.
|
|
|
|
- Replace `Client` with `LarkClient` and `ClientBuilder` with
|
|
`LarkClientBuilder`.
|
|
- Replace `client.wiki()` with `client.wiki_v1()` or `client.wiki_v2()`.
|
|
- Replace `do_req`, `do_req_typed`, and verb helpers with `raw_request*` and an
|
|
`ApiReq` when a dedicated typed resource is unavailable.
|
|
- Treat Hire v1 `IdNameObject.name` as `Option<I18n>` with `zh_cn` and `en_us`
|
|
fields.
|
|
- Handle JSON construction failures as `LarkError::Json`; legacy card element
|
|
helpers are fallible for the same reason.
|
|
- Use `JsonValue` for intentionally dynamic API data instead of public
|
|
`serde_json::Value` model fields.
|
|
|
|
Typed REST responses and incoming event payloads are `#[non_exhaustive]`.
|
|
Deserialize them and read their public fields as before, but do not use struct
|
|
literals to create server-owned values.
|
|
|
|
## Cargo Features
|
|
|
|
| Feature | Description |
|
|
| --- | --- |
|
|
| `ws` | WebSocket long-connection event client with protobuf framing. |
|
|
| `messaging` | High-level outbound messaging and resource operations without WebSocket dependencies. |
|
|
| `channel` | Inbound normalization and runtime policy helpers; enables `messaging` and `ws`. |
|
|
| `axum` | Axum adapters for webhook and card-action handlers. |
|
|
|
|
Cargo unifies enabled features across the dependency graph. Enabling `channel`
|
|
therefore enables both `messaging` and `ws`; enabling `messaging` and `ws`
|
|
separately does not enable the `channel` runtime API.
|
|
|
|
```toml
|
|
[dependencies]
|
|
larksuite-oapi-sdk-rs = { version = "0.3.12", features = ["ws", "axum"] }
|
|
```
|
|
|
|
## API Coverage
|
|
|
|
The SDK provides dedicated resources across IM, Calendar, Drive, Docs, Sheets,
|
|
Bitable, Contacts, Approval, VC, Wiki, Hire, and the broader Lark/Feishu
|
|
OpenAPI surface. Generated smoke tests verify request paths, query inputs,
|
|
bodies, uploads, downloads, and response handling. See the
|
|
[changelog](CHANGELOG.md) for release detail and the
|
|
[examples index](examples/README.md) for runnable calls.
|
|
|
|
## Requirements
|
|
|
|
- Rust 1.95.0 or newer
|
|
- Rust edition 2024
|
|
|
|
## License
|
|
|
|
Licensed under [MIT](LICENSE).
|
|
|