deezchatz_sdk/lib.rs
1//! # DeezChatz SDK for Rust
2//!
3//! An asynchronous Rust SDK for the DeezChatz platform, providing end-to-end encryption
4//! via the Signal Protocol (X3DH and Double Ratchet), zero-trust REST authentication via
5//! VXEdDSA signatures and VRF proofs, and real-time messaging over MQTT.
6//!
7//! ## Core Architecture
8//!
9//! - **End-to-End Cryptography**: Deeply integrated with `libsignal-dezire` to manage Identity
10//! Keys, Signed Pre-Keys, One-Time Pre-Keys (OPKs), and active Double Ratchet sessions.
11//! - **Zero-Trust Stateless Authentication**: Authenticates every REST request using cryptographic
12//! VXEdDSA signatures (`X-User-Id`, `X-Timestamp`, `X-Signature`, `X-Vrf`).
13//! - **Real-Time MQTT Transport**: Connects to the DeezChatz MQTT broker with cryptographic password
14//! tokens, receiving events via an asynchronous `tokio::sync::mpsc::Receiver`.
15//! - **Bring-Your-Own-Storage (BYOS)**: Abstract async traits for key persistence ([`KeyStore`]),
16//! session state ([`SessionStore`]), incoming message queue ([`InboxStore`]), and outgoing
17//! queue ([`OutboxStore`]).
18//! - **Guaranteed Delivery & Crash Resilience**: Unprocessed inbound messages and pending outbound
19//! messages are safely persisted to disk to prevent data loss across crashes or network disruptions.
20//! - **Multi-Type Framed Payloads**: Native support for UTF-8 text, Opus voice notes, and JPEG image
21//! transfers with captions and timestamps.
22//!
23//! ## Quick Start
24//!
25//! ```no_run
26//! use std::sync::Arc;
27//! use deezchatz_sdk::{DeezChatzClient, ClientConfig, Event, decode_payload, DecodedPayload};
28//! # use deezchatz_sdk::{KeyStore, SessionStore, InboxStore, OutboxStore, SdkError};
29//! # use async_trait::async_trait;
30//! # struct DummyStore;
31//! # #[async_trait] impl KeyStore for DummyStore {
32//! # async fn save_identity_key(&self, _: &[u8; 32], _: &[u8; 33]) -> Result<(), SdkError> { Ok(()) }
33//! # async fn get_identity_key(&self) -> Result<Option<([u8; 32], [u8; 33])>, SdkError> { Ok(None) }
34//! # async fn save_signed_pre_key(&self, _: u32, _: &[u8; 32], _: &[u8; 33]) -> Result<(), SdkError> { Ok(()) }
35//! # async fn get_signed_pre_key(&self, _: u32) -> Result<Option<([u8; 32], [u8; 33])>, SdkError> { Ok(None) }
36//! # async fn save_one_time_pre_keys(&self, _: Vec<(u32, [u8; 32], [u8; 33])>) -> Result<(), SdkError> { Ok(()) }
37//! # async fn consume_one_time_pre_key(&self, _: u32) -> Result<Option<([u8; 32], [u8; 33])>, SdkError> { Ok(None) }
38//! # }
39//! # #[async_trait] impl SessionStore for DummyStore {
40//! # async fn save_session(&self, _: &str, _: &[u8]) -> Result<(), SdkError> { Ok(()) }
41//! # async fn get_session(&self, _: &str) -> Result<Option<Vec<u8>>, SdkError> { Ok(None) }
42//! # async fn delete_session(&self, _: &str) -> Result<(), SdkError> { Ok(()) }
43//! # }
44//! # #[async_trait] impl InboxStore for DummyStore {
45//! # async fn save_to_inbox(&self, _: &str, _: &[u8]) -> Result<i64, SdkError> { Ok(1) }
46//! # async fn mark_inbox_processed(&self, _: i64) -> Result<(), SdkError> { Ok(()) }
47//! # async fn mark_inbox_failed(&self, _: i64, _: &str) -> Result<(), SdkError> { Ok(()) }
48//! # async fn get_pending_inbox(&self) -> Result<Vec<deezchatz_sdk::InboxEntry>, SdkError> { Ok(vec![]) }
49//! # }
50//! # #[async_trait] impl OutboxStore for DummyStore {
51//! # async fn save_to_outbox(&self, _: &str, _: &str, _: &str, _: &[u8]) -> Result<i64, SdkError> { Ok(1) }
52//! # async fn mark_outbox_sent(&self, _: i64) -> Result<(), SdkError> { Ok(()) }
53//! # async fn mark_outbox_failed(&self, _: i64, _: &str) -> Result<(), SdkError> { Ok(()) }
54//! # async fn get_pending_outbox(&self) -> Result<Vec<deezchatz_sdk::OutboxEntry>, SdkError> { Ok(vec![]) }
55//! # }
56//!
57//! #[tokio::main]
58//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
59//! let config = ClientConfig::production();
60//! let store = Arc::new(DummyStore);
61//!
62//! let mut client = DeezChatzClient::new(
63//! config,
64//! store.clone(),
65//! store.clone(),
66//! store.clone(),
67//! store.clone(),
68//! );
69//!
70//! // Connect to the real-time MQTT broker
71//! let mut event_rx = client.connect("my-user-id", "my-device-id").await?;
72//!
73//! // Process incoming messages
74//! tokio::spawn(async move {
75//! while let Some(event) = event_rx.recv().await {
76//! if let Event::MessageReceived { sender, plaintext } = event {
77//! if let Ok(payload) = decode_payload(&plaintext) {
78//! match payload {
79//! DecodedPayload::Text { text } => println!("{}: {}", sender, text),
80//! DecodedPayload::Voice { audio_bytes } => println!("Voice note ({} bytes)", audio_bytes.len()),
81//! DecodedPayload::Image { caption, image_bytes, .. } => println!("Image '{}' ({} bytes)", caption, image_bytes.len()),
82//! }
83//! }
84//! }
85//! }
86//! });
87//!
88//! // Send an encrypted text message
89//! let sent = client.send_text_message("recipient-id", "Hello!").await?;
90//! println!("Message sent with ID: {}", sent.message_id);
91//!
92//! client.disconnect().await?;
93//! Ok(())
94//! }
95//! ```
96
97pub mod client;
98pub mod crypto;
99pub mod error;
100pub mod messaging;
101pub mod oauth;
102pub mod transport;
103
104pub use client::{ClientConfig, DeezChatzClient, SentMessage};
105pub use error::SdkError;
106pub use messaging::{
107 decode_payload, encode_image_payload, encode_text_payload, encode_voice_payload,
108 DecodedPayload, InboxEntry, InboxStore, KeyStore, MessageStatus, OutboxEntry, OutboxStore,
109 PayloadError, SessionStore, PAYLOAD_TYPE_IMAGE, PAYLOAD_TYPE_TEXT, PAYLOAD_TYPE_VOICE,
110};
111pub use transport::Event;
112pub use transport::SyncBundleResponse;
113
114pub use base64;
115pub use libsignal_dezire;