ably_chat/
lib.rs

1//! Unofficial, ergonomic Rust client for the Ably Chat REST API (v4).
2//!
3//! Not affiliated with or endorsed by Ably.
4//!
5//! # Overview
6//!
7//! Build a [`Client`] with an [`Auth`] credential, scope it to a room with
8//! [`Client::room`], then chain into [`Messages`], [`Reactions`], or
9//! [`OccupancyHandle`]. Each operation is a builder that terminates in a bare
10//! `.await` (via [`IntoFuture`]); every fallible call
11//! returns [`Result<T>`]. Handles are cheap to [`Clone`] (`Arc`-backed) and
12//! `Send + Sync`.
13//!
14//! History and versions are paginated: `.await` a query for the first
15//! [`Page`], or call `.into_stream()` to follow the `next` links to exhaustion.
16//!
17//! # Example
18//!
19//! ```no_run
20//! use ably_chat::prelude::*;
21//! use futures::StreamExt;
22//!
23//! # async fn run() -> ably_chat::Result<()> {
24//! // Build a client and scope it to a room (rooms are implicit — this creates
25//! // nothing server-side).
26//! let client = Client::builder(Auth::api_key("appId.keyId:keySecret")).build();
27//! let room = client.room("my-room");
28//!
29//! // Send a message.
30//! let sent = room.messages().send("hello, world").await?;
31//! println!("sent message {}", sent.serial);
32//!
33//! // Stream history (newest first by default), following pagination. The
34//! // stream is `!Unpin`, so pin it before polling with `.next()`.
35//! let mut history = std::pin::pin!(room.messages().history().into_stream());
36//! while let Some(message) = history.next().await {
37//!     let message = message?;
38//!     println!("{}: {}", message.client_id, message.text);
39//! }
40//! # Ok(())
41//! # }
42//! ```
43//!
44//! # Permissions & token issuance
45//!
46//! Build the capability string for a TokenRequest or JWT with `Capability`
47//! (feature `capabilities`), mint the JWT itself with `mint_ably_jwt`
48//! (feature `jwt`; **server-side only** — it signs with your API secret),
49//! and let the client refresh Bearer credentials automatically by building
50//! [`Auth`] with [`Auth::provider`] instead of a static token (ADR-0012,
51//! SPEC §13).
52//!
53//! Prefer not to sign requests yourself? `KeyTokenProvider` (feature
54//! `token-issuance`, off by default) mints Ably Tokens through the platform
55//! `requestToken` endpoint instead — also **server-side only**. Pair it with
56//! [`Auth::provider`] the same way (ADR-0012 item 5, SPEC §13).
57
58/// Low-level generated bindings. Escape hatch; NOT covered by the pre-1.0
59/// stability guarantee and may change on regeneration.
60pub mod raw {
61    pub use ably_chat_openapi::*;
62}
63
64pub mod prelude;
65
66// Ergonomic layer (filled in by later phases).
67mod error;
68pub use error::{Error, ErrorInfo, Result};
69
70mod types;
71pub use types::*;
72
73mod config;
74pub use config::*;
75
76#[cfg(feature = "capabilities")]
77mod capability;
78#[cfg(feature = "capabilities")]
79pub use capability::{Capability, Operation};
80
81#[cfg(feature = "jwt")]
82mod jwt;
83#[cfg(feature = "jwt")]
84pub use jwt::{SigningKey, TokenParams, mint_ably_jwt};
85
86#[cfg(feature = "token-issuance")]
87mod token_provider;
88#[cfg(feature = "token-issuance")]
89pub use token_provider::KeyTokenProvider;
90
91mod client;
92pub use client::{Client, ClientBuilder};
93
94mod dispatch;
95
96mod room;
97pub use room::Room;
98
99mod messages;
100pub use messages::{
101    DeleteMessage, GetMessage, History, Messages, SendMessage, UpdateMessage, Versions,
102};
103
104mod reactions;
105pub use reactions::{ClientReactions, DeleteReaction, Reactions, SendReaction};
106
107mod occupancy;
108pub use occupancy::{GetOccupancy, OccupancyHandle};
109
110mod pagination;
111pub use pagination::Page;
ably_chat/lib.rs

ably_chat/
lib.rs
