frankenstein

Frankenstein's data structures (structs and enums) map one-to-one with the Telegram Bot API. Optional fields in the API are represented as Option<T> in Rust.

To create parameters for API methods, use the associated builder pattern. Only required fields must be set; optional fields default to None.

use frankenstein::methods::SendMessageParams;

let send_message_params = SendMessageParams::builder()
    .chat_id(1337)
    .text("hello")
    .build();

To add Frankenstein to your Rust project, run cargo add frankenstein or manually add it to your Cargo.toml. By default, the crate only includes Telegram types. To perform actual API requests, you must enable either a blocking or an async client via features.

[dependencies]
frankenstein = { version = "0.51", features = [] }

The RichText enum is the core abstraction for text formatting. It can be a simple Text(String), a List(Vec<RichText>), or a Object(RichTextObject) which contains specific formatting like Bold, Italic, Code, Url, etc.

Convenience implementations allow you to convert String, &str, or Vec<RichText> directly into RichText using .into() or RichText::from().

use frankenstein::RichText;

// Simple text
let text = RichText::from("plain text");

// Nested list of text
let list = RichText::from(vec![RichText::from("item 1"), RichText::from("item 2")]);

To interact with the Telegram Bot API, you use the TelegramApi (synchronous) or AsyncTelegramApi (asynchronous) traits. These traits are provided by the trait-sync and trait-async features respectively.

• Use TelegramApi when working with the client-ureq feature.
• Use AsyncTelegramApi when working with the client-reqwest feature.

Frankenstein requires specific features to be enabled to provide HTTP clients:

Blocking (Synchronous) Clients

• client-ureq: Uses the ureq crate for blocking HTTP requests.
• trait-sync: Provides a blocking API trait, useful for implementing custom blocking clients.

Async Clients

• client-reqwest: Uses the reqwest crate for asynchronous HTTP requests. Note that file uploads are currently not supported on wasm32 targets.
• trait-async: Provides an async API trait, used by client-reqwest, useful for implementing custom async clients.

To use the async client, update your Cargo.toml as follows:

frankenstein = { version = "0.51", features = ["client-reqwest"] }

Frankenstein supports two different HTTP client backends via Cargo features. You must enable one of these features to access the corresponding client modules and API traits:

1. reqwest: Enable the client-reqwest feature. This provides an asynchronous client implementation using the reqwest crate.
2. ureq: Enable the client-ureq feature. This provides a synchronous client implementation using the ureq crate.

Note: The old AsyncApi and Api structs are deprecated. You should use the specialized client modules instead.

# For asynchronous reqwest-based client
frankenstein = { version = "0.51.0", features = ["client-reqwest", "trait-async"] }

# For synchronous ureq-based client
frankenstein = { version = "0.51.0", features = ["client-ureq", "trait-sync"] }

The Bot struct provides a synchronous implementation of the TelegramApi trait using the ureq HTTP client. You can initialize it using the API key or a custom URL.

Use Bot::new(api_key) for standard Telegram API URLs, or Bot::new_url(api_url) if you are using a custom endpoint or a local mock server.

// Using an API key
let bot = Bot::new("YOUR_API_KEY");

// Using a custom URL
let bot = Bot::new_url("https://my.custom.proxy/bot");

The Bot struct is the primary asynchronous entry point for interacting with the Telegram API using the reqwest HTTP client. You can initialize it in two ways:

1. Using an API Key: Use Bot::new(api_key) to create a bot instance configured with the default Telegram API base URL.
2. Using a Custom URL: Use Bot::new_url(api_url) if you are using a local Telegram Bot API server or a proxy.

You can also use the Bot::builder() pattern to provide a custom reqwest::Client (e.g., for custom timeouts or proxy settings) and a custom api_url.

// Using an API key
let bot = Bot::new("YOUR_API_KEY");

// Using a custom URL (e.g., for a local server)
let bot = Bot::new_url("http://localhost:8081/");

// Using the builder for advanced configuration
let bot = Bot::builder()
    .api_url("https://my-proxy.com/")
    .client(custom_reqwest_client)
    .build();

To make requests using the blocking client, use the Bot struct from frankenstein::client_ureq and the TelegramApi trait. Every method call returns a Result containing either the successful response or an error.

use frankenstein::TelegramApi;
use frankenstein::client_ureq::Bot;
use frankenstein::methods::{GetUpdatesParams, SendMessageParams};
use frankenstein::types::AllowedUpdate;

let token = "123:ABC";
let bot = Bot::new(token);

// Send a message
let send_message_params = SendMessageParams::builder()
    .chat_id(1337)
    .text("hello")
    .build();
let result = bot.send_message(&send_message_params);

// Get updates (interactions with the bot)
let update_params = GetUpdatesParams::builder()
    .allowed_updates(vec![AllowedUpdate::Message])
    .build();
let result = bot.get_updates(&update_params);

For methods that support file uploads, use the FileUpload enum. It has two variants:

1. FileUpload::String(String): Pass the ID of a file that has already been uploaded to Telegram.
2. FileUpload::InputFile(InputFile): Upload a new file from a local path using multipart upload.

The InputFile struct wraps a std::path::PathBuf.

// Example of the FileUpload enum structure
pub enum FileUpload {
    InputFile(InputFile),
    String(String),
}

pub struct InputFile {
    path: std::path::PathBuf
}