jmap-chat-client

What it is

JMAP Chat extension client methods (draft-atwood-jmap-chat-00) — typed bindings on top of jmap-base-client.

Typed client methods for the JMAP Chat extension (draft-atwood-jmap-chat).

Implements an extension trait on jmap-base-client::JmapClient that adds all JMAP Chat method calls as typed async methods, following the same session-bound SessionClient pattern used by jmap-mail-client.

What it's for

Implements draft-atwood-jmap-chat-00 method bindings (Chat/*, Message/*, Space/*, SpaceInvite/*, SpaceBan/*, ChatContact/*, CustomEmoji/*, ReadPosition/*, PresenceStatus/*, and push-subscription methods) on top of jmap-base-client. Depends on jmap-base-client for transport and session, and on jmap-chat-types for the wire types. Sibling of jmap-mail-client in the extension-client family; mirrors that crate's shape.

How to use

use jmap_base_client::{BearerAuth, ClientConfig, JmapClient};
use jmap_chat_client::{JmapChatExt, GetResponse};
use jmap_chat_types::Chat;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let auth = BearerAuth::new("my-token")?;
    let client = JmapClient::new_plain(auth, "https://jmap.example.com", ClientConfig::default())?;

    let session = client.fetch_session().await?;
    let chat = client.with_chat_session(session);

    // Fetch all chats for the primary account.
    let resp: GetResponse<Chat> = chat.chat_get(None, None).await?;
    for c in &resp.list {
        println!("{}: {:?}", c.id, c.name);
    }
    Ok(())
}

Registered methods

All JMAP Chat methods are available as typed async methods on SessionClient:

Chat/*

Message/*

Space/*

SpaceInvite/*

SpaceBan/*

ChatContact/*

CustomEmoji/*

ReadPosition/* and PresenceStatus/*

Push subscriptions

Push transport

Two real-time push transports are supported, both layered on top of the jmap-base-client HTTP client. They expose typed Chat-specific event types without forcing the application to parse raw JSON.

Modules

ChatWsExt is an extension trait on JmapClient that opens a WebSocket connection to the URL advertised in the JMAP Session's webSocketUrl capability. parse_chat_sse_block consumes a single SSE event block and returns a typed ChatSseEvent (or an error if the block is malformed).

Usage sketch

use jmap_base_client::{connect_ws, Session};
use jmap_chat_client::{ChatSessionExt, ChatWsExt};

async fn drive_chat_ws(session: &Session) -> Result<(), Box<dyn std::error::Error>> {
    // 1. Discover whether the server advertises JMAP WebSocket transport
    //    AND that the Chat capability rides on it.
    if !session.supports_chat_websocket() {
        return Ok(());
    }

    // 2. Read the WebSocket URL from the RFC 8887 capability object.
    let ws_cap = session.websocket_capability()?
        .expect("supports_chat_websocket implies WebSocketCapability is present");

    // 3. Open the WsSession (auth header tuple is built by your auth code).
    let mut ws = connect_ws(&ws_cap.url, /* auth_header = */ None).await?;

    // 4. Drive it via ChatWsExt — each yielded frame is a typed ChatWsFrame:
    //    StateChange, ChatTyping, ChatPresence, ResponseFrame, RequestError,
    //    Unknown { type_name, .. }, etc.
    while let Some(frame) = ws.next_chat_frame().await {
        let _frame = frame?;
    }
    Ok(())
}

For SSE, use the base-client event-source loop (JmapClient::subscribe_events) and feed each raw event block to parse_chat_sse_block, which returns a ChatSseFrame carrying the typed ChatSseEvent payload. The same Chat event variants are delivered over both transports; choose based on what the server advertises (see ChatSessionExt::supports_chat_websocket and chat_push_capability) and the deployment's network constraints (proxies, long-lived connections, etc.).

Examples

The crate ships two runnable examples under examples/. Both spin up an in-process tokio listener, emit synthetic JMAP push frames, and drive the client read loop. Useful as starting points for integration tests and as a demonstration of the public push API.

• examples/sse_listen.rs — consume a synthetic Server-Sent Events stream via JmapClient::subscribe_events. Two event: state frames per RFC 8620 §7.3 / JMAP Chat draft §StateChange. Run: cargo run --example sse_listen -p jmap-chat-client.
• examples/ws_loop.rs — drive a synthetic JMAP WebSocket via connect_ws + ChatWsExt::next_chat_frame. Emits one Response frame and one StateChange push frame per RFC 8887 / JMAP Chat WSS draft. Run: cargo run --example ws_loop -p jmap-chat-client.

NOT FOR PRODUCTION — single-shot, no retry, no auth, no TLS. Demonstrates the consume-side API only.

How it works

Each method on SessionClient runs the same pipeline:

1. Validate arguments (typed &Id / &[Id] makes invalid Ids unrepresentable; empty-state defence-in-depth guards return InvalidArgument before any I/O).
2. Resolve (api_url, account_id) from the bound session for urn:ietf:params:jmap:chat.
3. Build the method-arguments JSON.
4. Wrap it into a JmapRequest via JmapRequestBuilder with using = ["urn:ietf:params:jmap:core", "urn:ietf:params:jmap:chat"].
5. POST it via jmap_base_client::JmapClient::call.
6. extract_response::<T> finds the typed result for call ID "r1".

The Jmap*Ext extension trait (JmapChatExt) adds the with_chat_session(session) accessor to JmapClient. The returned SessionClient carries the session and exposes every JMAP Chat method as a typed async fn. The push-transport modules (ws, sse, session) layer typed Chat-specific event types on top of the base-client transports.

Gotchas

• space_join is non-standard. Space/join is a JMAP Chat extension method that does not follow the standard /set request shape. It takes a SpaceJoinInput struct (not a create/update/destroy map) and returns a SpaceJoinResponse (not a SetResponse). It cannot be used with JmapRequestBuilder::add_call in combination with other /set invocations in a multi-method request — use it as a standalone call.

References

• draft-atwood-jmap-chat — JMAP Chat extension (all sub-drafts: core objects, push, WebSocket events, federation, FileNode, CID scheme) — https://github.com/MarkAtwood/jmap-chat-spec
• RFC 8620 — JMAP Core (request/response envelope, /set and /query shapes, push subscription, SSE, WebSocket)