dingtalk-stream-sdk 0.2.2

# DingTalk Stream SDK for Rust

English | [简体中文](README.zh_cn.md)

A Rust implementation of the DingTalk Stream SDK.

## Features

- WebSocket connection with auto-reconnect
- `CALLBACK`, `EVENT`, and `SYSTEM` message handling
- Automatic ACK responses
- Async callback webhook replies (`WebhookMessage`)
- Proactive robot messaging (private and group)
- Callback file/image download (`DingtalkResource`)
- Media upload (`DingTalkMedia`)
- Access token caching and refresh
- Lifecycle hooks (`LifecycleListener`)

## Installation

```toml
[dependencies]
dingtalk-stream-sdk = "0.2"
```

Optional image decoding support:

```toml
[dependencies]
dingtalk-stream-sdk = { version = "0.2", features = ["image"] }
```

## Environment Variables

- `DINGTALK_CLIENT_ID`
- `DINGTALK_CLIENT_SECRET`

## Quick Start

```rust
use async_trait::async_trait;
use dingtalk_stream::frames::down_message::callback_message::{CallbackMessage, MessagePayload};
use dingtalk_stream::frames::down_message::MessageTopic;
use dingtalk_stream::frames::up_message::callback_message::WebhookMessage;
use dingtalk_stream::handlers::{CallbackHandler, Error, ErrorCode, Resp};
use dingtalk_stream::{Credential, DingTalkStream, TOPIC_ROBOT};
use std::sync::Arc;
use tokio::sync::mpsc::Sender;

struct RobotHandler(MessageTopic);

#[async_trait]
impl CallbackHandler for RobotHandler {
    async fn process(
        &self,
        _client: Arc<DingTalkStream>,
        message: &CallbackMessage,
        _cb_webhook_msg_sender: Option<Sender<WebhookMessage>>,
    ) -> Result<Resp, Error> {
        if let Some(data) = &message.data {
            if let Some(MessagePayload::Text { text }) = &data.payload {
                return Ok(Resp::Text(format!("echo: {}", text.content)));
            }
        }
        Err(Error {
            msg: "unsupported message".to_string(),
            code: ErrorCode::BadRequest,
        })
    }

    fn topic(&self) -> &MessageTopic {
        &self.0
    }
}

#[tokio::main]
async fn main() -> dingtalk_stream::Result<()> {
    let client = Arc::new(
        DingTalkStream::new(Credential::from_env())
            .register_callback_handler(Arc::new(RobotHandler(MessageTopic::Callback(
                TOPIC_ROBOT.to_string(),
            ))))
            .await,
    );

    let (_client, join_handle) = Arc::clone(&client).start().await?;
    join_handle.await??;
    Ok(())
}
```

See [examples/hello.rs](examples/hello.rs) for a full example.

## ClientConfig

```rust
use dingtalk_stream::{ClientConfig, Credential, DingTalkStream};
use std::time::Duration;

let config = ClientConfig {
    auto_reconnect: true,
    ua: "my-bot/1.0".to_string(),
    reconnect_interval: Duration::from_secs(10),
    keep_alive_interval: Duration::from_secs(60),
};

let client = DingTalkStream::with_config(Credential::from_env(), config);
```

## Topic Constants

- `TOPIC_ROBOT`: `/v1.0/im/bot/messages/get`
- `TOPIC_ROBOT_DELEGATE`: `/v1.0/im/bot/messages/delegate`
- `TOPIC_CARD`: `/v1.0/card/instances/callback`

## Send Robot Messages

```rust
use dingtalk_stream::frames::up_message::robot_message::{RobotMessage, RobotPrivateMessage};

client
    .send_message(
        RobotMessage::from(RobotPrivateMessage {
            user_ids: vec!["manager_userid".into()],
            content: "hello".into(),
        })
        .with_cb(|result| {
            println!("send result: {result:?}");
        }),
    )
    .await?;
```

## Download Callback Files/Images

`PayloadPicture` and `PayloadFile` implement `DingtalkResource`:

```rust
use dingtalk_stream::client::DingtalkResource;

let (path, _resource) = picture_payload.fetch(client.as_ref(), "/tmp".into()).await?;
println!("saved to: {}", path.display());
```

## Upload Media

```rust
use dingtalk_stream::client::{DingTalkMedia, MediaImage};
use std::path::PathBuf;

let media = MediaImage::from(PathBuf::from("./test_resources/img.png"));
let result = media.upload(client.as_ref()).await?;
println!("upload: errcode={}, errmsg={}", result.errcode, result.errmsg);
```

## Lifecycle Listener

Implement `LifecycleListener` and register it via `register_lifecycle_listener(...)` to observe events such as:

- `Start`
- `Connecting`
- `Connected`
- `WebsocketRead`
- `WebsocketWrite`
- `Disconnected`
- `Stopped`

## License

MIT