oxidebot 0.1.7

# Oxidebot

**Oxidebot** is a lightweight yet powerful chatbot framework based on Rust and the Tokio runtime. It aims to provide developers with a flexible and extensible environment for bot development through modular design.

## Available Bots
- [onebot_v11_oxidebot](https://github.com/canxin121/onebot_v11_oxidebot)
- [telegram_bot_oxidebot](https://github.com/canxin121/telegram_bot_oxidebot)

## Available Handlers
- [china_unicom_oxidebot](https://github.com/canxin121/china_unicom_oxidebot)

## Example Usage
- [oxidebot_example](https://github.com/canxin121/oxidebot_example)

## Core Concepts

### Bot
`Bot` is the core component of the framework, responsible for providing `Event`s and offering basic API methods for developers to call. It serves as the bridge between the framework and external platforms (such as QQ, Telegram, etc.).

The common API is complemented by `PlatformApiRequest`. Every adapter can expose its complete native API through the same lossless JSON request, response, and multipart-file abstraction. This second layer deliberately retains platform-only capabilities even when no honest cross-platform semantic model exists. Unsupported adapters return a downcastable `UnsupportedPlatformApiError` by default, while callers can inspect `platform_api_methods` or `supports_platform_api_method` before calling a platform-only feature.

### Event
`Event` is the object that the framework processes, representing the various events received by the bot. Event types include:

- **MessageEvent**: Message events
- **NoticeEvent**: Notification events
- **RequestEvent**: Request events
- **MetaEvent**: Meta events
- **AnyEvent**: Generalized events

### Matcher
`Matcher` is an abstraction over `Bot` and `Event`, simplifying event handling and API calls. It provides convenient methods to extract key information from events (such as users, messages, groups) and easily call related APIs.

### Handler
`Handler` is the core component for event processing, divided into two types:

- **EventHandler**: Handles incoming `Event`s and is triggered only when an event occurs.
- **ActiveHandler**: Suitable for proactive processing scenarios, it can run continuously, execute scheduled tasks, or perform other background operations.

A `Handler` can include either an `EventHandler` or an `ActiveHandler`, or both.

### Filter
`Filter` is a global event filter used to process and intercept events before they reach the `Handler`. The `Filter` has a higher priority than the `Handler`.

### OxideBotManager
`OxideBotManager` is the manager of the framework, the entry point for starting and running the bot. Developers should call its `run_block` method at the end of the `main` function to launch the entire framework along with all registered `Bot`s, `Filter`s, and `Handler`s.

## Auxiliary Tools for Handler Writer

### Wait

Include a restricted `BroadcastSender` that can only use `subscribe` fn in your handler
```rust
use oxidebot::manager::BroadcastSender;

pub struct WaitHandler {
    pub broadcast_sender: BroadcastSender,
}
```

Then use `wait` in your `HandlerTrait` implementation.
You can find the provided `wait` methods in `utils::wait` or define your own.
```rust
use std::time::Duration;

use anyhow::Result;
use oxidebot::{manager::BroadcastSender, matcher::Matcher, wait_user_text_generic};

async fn wait_for_number(
    matcher: &Matcher,
    broadcast_sender: &BroadcastSender,
) -> Result<()> {
    let (number, matcher) = wait_user_text_generic::<u8>(
        matcher,
        broadcast_sender,
        Duration::from_secs(30),
        3,
        Some("Please send an unsigned 8-bit integer".to_string()),
    )
    .await?;
    # let _ = (number, matcher);
    Ok(())
}
```

## License
MIT OR Apache-2.0