SDKs
Which SDKs exist, what each one covers, and what to do from a language that has none yet.
What exists
| language | package | covers | runtimes |
|---|---|---|---|
| JavaScript / TypeScript | @blackevin/client | realtime and REST | Node, browser, Bun, Deno |
| Ruby | blackevin | REST | Ruby 3.0 and up — Rails, Sinatra, Hanami |
Realtime is the WebSocket client: subscribe, presence, connection state. REST is everything a backend does without holding a socket: sign a token for a browser, publish, read history and presence, manage queues.
That split is why a server-side SDK can be small. A Rails app never subscribes — its browsers do, with the JavaScript SDK — so the Ruby gem is the REST half, and the two are meant to be used together:
browser ── @blackevin/client ── Realtime, with authUrl pointing at your server
server ── blackevin (gem) ── signs the token, publishes from jobs and webhooksThe same contract
Every SDK is tested against one language-neutral contract: an OpenAPI file for the REST surface, and JSON fixtures that pin what a schema cannot — the exact bytes a token request is signed over, how a key splits, how a channel name goes into a path. The node's own verifier runs the same fixtures, so an SDK that passes produces tokens the server accepts.
In practice that means the SDKs agree on the things that are easy to get subtly wrong, and that the names line up:
| JavaScript | Ruby | |
|---|---|---|
| client | new Blackevin.Rest({ key }) | Blackevin::Rest.new(key:) |
| sign a token | rest.auth.createTokenRequest() | bk.auth.create_token_request |
| publish | rest.channels.get(name).publish() | bk.channels.get(name).publish |
| error | BlackevinError — statusCode, reason | Blackevin::Error — status_code, reason |
| key from the environment | BLACKEVIN_KEY | BLACKEVIN_KEY |
A language with neither
Two levels, depending on what you need.
A backend that signs tokens and publishes needs no SDK at all. The token is an HMAC-SHA256 over six fields, written out in Authentication, and a publish is one HTTP call, in REST publish. Both were checked against the node's verifier rather than eyeballed.
A realtime client is a WebSocket, JSON frames, and matching Ack / Nack
back to requests by id. The wire protocol is documented, not
reverse-engineered:
- Opcodes — the frame shapes, the handshake, the Nack codes
- JSON codec — serialisation, and what is validated
Both pages are written for someone implementing against them.