onwardz 0.1.0

Server-side SDK for managing Onwardz rooms (create rooms, issue join tokens, manage settings).
Documentation

onwardz

Server-side SDK for managing Onwardz rooms. Use this in your Rust backend to create rooms, issue join tokens, and manage room settings. Pairs with @onwardz/js for browser clients.

Never use this crate in client-side code. It requires your API key, which must stay on the server.

Installation

[dependencies]
onwardz = "0.1"

Async, runtime-agnostic (built on reqwest). The examples below use tokio.

Quick start

use onwardz::{OnwardzClient, CreateRoomOptions};

# async fn run() -> Result<(), onwardz::OnwardzError> {
let onwardz = OnwardzClient::new(std::env::var("ONWARDZ_API_KEY").unwrap());

// Create a room
let room = onwardz
    .create_room(CreateRoomOptions { max_participants: Some(10), ..Default::default() })
    .await?;

// Issue a short-lived token for a browser client
let token = onwardz.issue_token(&room.room_id, None).await?;

// Pass room.room_id + token.token to the browser — the client joins with
// @onwardz/js, no API key needed in the browser.
# Ok(())
# }

The token flow

The recommended pattern for production:

Your backend (Rust)               Browser (@onwardz/js)
──────────────────                ────────────────────
create_room()         ──room_id──►
issue_token(room_id)  ───token───►  new OnwardzRoom({ roomId, token })
                                    room.join()

Tokens expire after 1 hour by default (issue_token(&id, None)). Generate one per user session.

API reference

OnwardzClient

use onwardz::OnwardzClient;

// Default endpoint (https://api.onwardz.com/rpc)
let onwardz = OnwardzClient::new(api_key);

// Self-hosted deployment
let onwardz = OnwardzClient::builder(api_key)
    .server_url("https://api.your-domain.com/rpc")
    .build();

OnwardzClient is cheap to clone and safe to share across tasks.

create_room(opts) -> CreateRoomResponse

# use onwardz::{OnwardzClient, CreateRoomOptions};
# async fn f(onwardz: OnwardzClient) -> Result<(), onwardz::OnwardzError> {
let room = onwardz.create_room(CreateRoomOptions {
    max_participants: Some(10),                       // optional cap
    expires_at: Some("2026-12-31T23:59:59Z".into()),  // optional ISO 8601 expiry
}).await?;
// room.room_id, room.peer_id, room.show_branding, room.theme
# Ok(()) }

list_rooms() -> Vec<Room>

# use onwardz::OnwardzClient;
# async fn f(onwardz: OnwardzClient) -> Result<(), onwardz::OnwardzError> {
for room in onwardz.list_rooms().await? {
    println!("{} (created {})", room.id, room.created_at);
}
# Ok(()) }

delete_room(room_id)

Soft-delete a room. Active participants are not forcibly disconnected, but no new peers can join.

# use onwardz::OnwardzClient;
# async fn f(onwardz: OnwardzClient) -> Result<(), onwardz::OnwardzError> {
onwardz.delete_room("room_abc123").await?;
# Ok(()) }

configure_room(room_id, opts)

Update room settings. Only the fields you set are changed; use the builder to express set vs clear.

# use onwardz::{OnwardzClient, ConfigureRoomOptions, Theme};
# async fn f(onwardz: OnwardzClient) -> Result<(), onwardz::OnwardzError> {
onwardz.configure_room("room_abc123", ConfigureRoomOptions::new()
    .max_participants(20)
    .allowed_origins(vec!["https://app.your-domain.com".into()])
    .theme(Theme { accent: Some("#5E6AD2".into()), ..Default::default() })
).await?;

// Clear a field (send an explicit null):
onwardz.configure_room("room_abc123", ConfigureRoomOptions::new().clear_max_participants()).await?;
# Ok(()) }
Setter Clears with Description
max_participants(n) clear_max_participants() Participant cap
expires_at(ts) clear_expiry() ISO 8601 expiry
metadata(v) — Arbitrary JSON attached to the room
allowed_origins(v) — Origin allow-list for browser clients
theme(t) clear_theme() Curated look for <onwardz-room>

issue_token(room_id, ttl_seconds) -> IssueTokenResponse

Issue a signed JWT that lets a browser client join room_id without the API key. None uses the default 1-hour TTL.

# use onwardz::OnwardzClient;
# async fn f(onwardz: OnwardzClient) -> Result<(), onwardz::OnwardzError> {
let t = onwardz.issue_token("room_abc123", None).await?;       // 1 hour
let t = onwardz.issue_token("room_abc123", Some(300)).await?;  // 5 minutes
# Ok(()) }

Error handling

Calls return OnwardzError. Match rpc_code() against RpcErrorCode to handle known server conditions by name:

use onwardz::{OnwardzClient, RpcErrorCode};

# async fn f(onwardz: OnwardzClient, room_id: &str) {
match onwardz.delete_room(room_id).await {
    Ok(()) => {}
    Err(e) if e.rpc_code() == Some(RpcErrorCode::RoomNotFound) => { /* already gone */ }
    Err(e) => eprintln!("{e}"),
}
# }
Variant Code Meaning
RoomNotFound -32000 Room does not exist or was deleted
PeerNotFound -32001 Peer ID not in signaling state
Forbidden -32003 Invalid or missing API key
RoomFull -32004 Room has reached its participant cap
RoomExpired -32005 Room's expiry timestamp has passed
CapReached -32006 Account monthly minute quota exhausted

License

MIT