Connect

Opening a connection

import * as Blackevin from '@blackevin/client';

const realtime = new Blackevin.Realtime({
  key: process.env.BLACKEVIN_KEY,
  clientId: 'alice',
});

The socket opens lazily, on the first operation that needs it. connect() is there if you want to force it early:

realtime.connect();
realtime.close();

Both also live on realtime.connection.

What the handshake does

1. connection.state becomes connecting
2. the WebSocket opens, carrying the credential in the query string
3. the server answers Connected, the client stores connectionId, state becomes connected
4. any channel that was attached or subscribed before the drop is restored

Step 4 is why a reconnect is invisible to your code. The SDK replays its own Attach and Subscribe frames — including each channel's rewind — so your callbacks stay wired to the same channels they were wired to before.

Options

Where it connects

The derivation only happens when you passed endpoint yourself — see install for why the default does not swap schemes.

Who you are

How you authenticate

Pass exactly one. See authentication.

How it behaves

autoReconnect is disabled permanently after an intentional close() — that is what makes close() mean closed.

For tests

WebSocketImpl, fetchImpl, setTimeoutImpl and clearTimeoutImpl are injection points. They default to the globals, bound — which matters in a browser, where calling window.setTimeout through a property hands it the wrong this and throws.

The surfaces you get

realtime.channels.get('chat:lobby');   // → Channel
realtime.connection;                    // → state + events
realtime.auth;                          // → createTokenRequest, requestToken
realtime.clientId;                      // → the resolved id

Publishing without a socket

Blackevin.Rest is the same API over HTTP, for code that has no reason to hold a connection open — a job, a cron, an inbound webhook:

const rest = new Blackevin.Rest({ key: process.env.BLACKEVIN_KEY });

await rest.channels.get('orders:new').publish('order.created', { id: 7 });
await rest.channels.get('orders:new').history({ limit: 50 });
await rest.channels.get('ops').presence.get();

It takes the same key / token options and builds the right Authorization header from whichever you passed. See the REST overview.