API Reference
Complete reference for the Celeris client and server packages, in JavaScript and Python: every export, option and type.
Reference overview
The API is deliberately small. Two packages, one job each, in each language.
| Reference | Covers |
|---|---|
| Client API | @useceleris/client — connecting, messaging, presence, payload helpers, errors |
| Server API | @useceleris/server — signing credentials, and connecting from a backend |
| Python Client API | useceleris-client — the same client surface for Python's asyncio |
| Python Server API | useceleris-server — signing credentials on a trusted Python server |
The Python packages follow the JavaScript ones with Python names (segment_id, presence_list) and asyncio idioms; the behaviour, limits and error codes are the same.
Client versus server
@useceleris/client runs in browsers, Node.js, Bun and Deno. It opens the connection, subscribes to segments, sends and receives messages, and reports presence. It contains no signing code, and it cannot mint credentials.
@useceleris/server belongs only on a trusted backend. It signs fresh credentials from claims your code decides. It depends on the client package for types only; the client package contains no signing facility. Never import the server package into an end-user bundle.
The credential flow
1. Your browser code needs a connection
2. The SDK calls your credentialProvider
3. Your provider asks your backend
4. Your backend authenticates the user, decides their claims, and signs them
5. The signed { payload, signature } goes back to the browser
6. The SDK connects with them
Step 4 is where authorization happens. The browser tells you which channel it wants; your backend decides whether that is allowed. Repeat for every connection attempt, including reconnects — the SDK calls your provider fresh each time, so you never manage token refresh.
See Authentication for how to scope claims and handle credentials. Reconnection and Recovery explains which failures retry, what subscriptions are restored, and why your application must still reconcile data.