wechat_protocol/lib.rs
1//! Connect to WeChat, authenticate, synchronize and submit messages with [`NativeClient`].
2//!
3//! Most server operations are **methods on [`NativeClient`]**, rather than free
4//! functions in this crate's Functions list. [`AccountState`] holds accepted
5//! credentials; transfer it once into [`NativeClient::from_account`]. Account
6//! operations then share that owner. It is secret data, not an API access token.
7//!
8//! | Task | Start here |
9//! | --- | --- |
10//! | QR login | [`NativeClient::start_qr_login`], [`NativeClient::poll_login`], [`NativeClient::complete_login`] |
11//! | Receive a sync page | [`NativeClient::sync`], [`wire::decode_add_message`] |
12//! | Send text | [`NativeClient::send_text`], [`TextSendResult`] |
13//! | Contacts and rooms | [`NativeClient::lookup_contacts`], [`NativeClient::lookup_room`] |
14//! | Attachments | [`media`], [`media_send`], [`NativeClient::send_file`] |
15//! | Logout and shutdown | [`NativeClient::logout`], [`NativeClient::shutdown`], and `_blocking` forms of both |
16//! | Classify a failure | [`ServiceRejected`], [`is_session_rejected`], [`AccountInterrupted`], [`NativeRequestNotSubmitted`] |
17//! | Low-level encoding | [`wire`], [`protobuf`] |
18//!
19//! # Send one text message
20//!
21//! After an approved login, call the client method with the recipient's exact
22//! WeChat username. Persist the task ID, timestamp and intended operation in your
23//! application's recovery record before submission. A client ID is not a server
24//! guarantee against duplicate sends.
25//!
26//! ```no_run
27//! use wechat_protocol::{wire, NativeClient, TextSendOptions, TextSendResult};
28//!
29//! async fn send_once(
30//! client: &NativeClient,
31//! recipient: &str,
32//! text: &str,
33//! task_id: &str,
34//! created_at: u32,
35//! ) -> anyhow::Result<TextSendResult> {
36//! let client_id = wire::client_message_id(task_id.as_bytes());
37//! anyhow::ensure!(client_id != 0, "Choose another task ID");
38//! client.send_text(recipient, text, TextSendOptions {
39//! created_at,
40//! client_message_id: client_id,
41//! source: None,
42//! }).await
43//! }
44//! ```
45//!
46//! The source package includes runnable `qr_login`, `send_text` and `sync_once`
47//! examples. They keep credentials in memory and perform no profile writes.
48//!
49//! # Application responsibilities
50//!
51//! The crate implements supported wire operations, transport authentication and
52//! response decoding. The embedding application owns credential storage, send
53//! intents, uncertainty handling, sync recovery and official-profile writeback.
54//! An accepted receipt establishes server acceptance, not recipient playback or
55//! completed local history. An error after submission must not cause a blind resend.
56//!
57//! This library does not launch or load the official client. Peer responses pass
58//! pinned MMTLS signature and record authentication before business decode.
59//! Account-owned requests run blocking transport work on Tokio's blocking pool.
60//! Login bootstrap and remaining low-level operations
61//! are blocking and require a blocking worker in async applications.
62//!
63//! # Errors
64//!
65//! Functions return `anyhow::Error`. Branch on the types it carries rather than
66//! on message text:
67//!
68//! - [`ServiceRejected`] holds the [`Service`] and the non-zero code of a
69//! verified response. [`is_session_rejected`] is true when the account needs
70//! a new login or renewal.
71//! - [`AccountInterrupted`] says why the account owner ended a request or a
72//! notification wait: stopped, transferred, or superseded by a renewal.
73//! - [`NativeRequestNotSubmitted`] says nothing was handed to transport. An
74//! interruption without it has an unknown outcome.
75//!
76//! # Blocking embedders
77//!
78//! Applications that run their own blocking workers need no Tokio runtime:
79//! use [`NativeClient::request_blocking`],
80//! [`NativeClient::open_push_connection_blocking`],
81//! [`NativeClient::renew_session_blocking`], [`NativeClient::logout_blocking`],
82//! [`PendingLogout::submit_blocking`] and [`NativeClient::shutdown_blocking`].
83pub mod business;
84
85pub mod calls;
86mod client;
87mod errors;
88pub use errors::{is_session_rejected, AccountInterrupted, Service, ServiceRejected};
89mod lan_login;
90pub use lan_login::login_lan_error_reason;
91pub mod contact_sync;
92pub mod crypto;
93pub mod file_upload;
94pub mod media;
95pub mod media_send;
96pub mod mmtls;
97mod notice;
98pub mod openim;
99pub use openim::{OpenImContact, OpenImServiceError};
100pub mod protobuf;
101pub mod push;
102pub mod quote_send;
103pub mod silk;
104pub mod wire;
105pub use client::*;
106
107pub const MAX_MESSAGE_BYTES: usize = 16 * 1024 * 1024;