@apinator/client
JavaScript client SDK for Apinator — real-time WebSocket messaging for web applications.
Features
- Public, private, presence, and cache channels
- Automatic reconnection with exponential backoff
- Client events on private/presence channels
- Presence member tracking
- TypeScript-first with full type definitions
- Zero dependencies — works in any modern browser
- ESM, CommonJS and script-tag builds
Installation
npm install @apinator/client
Without a bundler
Save this as index.html and open it. The script tag defines a global Apinator:
<!DOCTYPE html>
<html>
<body>
<script src="https://cdn.jsdelivr.net/npm/@apinator/[email protected]/dist/apinator.min.js"></script>
<script>
const client = new Apinator({
appKey: 'your-app-key',
cluster: 'eu',
});
client.connect();
const channel = client.subscribe('my-channel');
channel.bind('my-event', (data) => {
console.log('Received:', data);
});
</script>
</body>
</html>
Then publish my-event on my-channel from your server (for example with
@apinator/server) and it is logged in the browser console.
Prefer ES modules? Import from the module build instead:
<script type="module">
import { Apinator } from 'https://cdn.jsdelivr.net/npm/@apinator/[email protected]/dist/index.mjs';
</script>
Node.js
Node 22+ has a global WebSocket. On older versions, install ws
and pass it in:
import WebSocket from 'ws';
import { Apinator } from '@apinator/client';
const client = new Apinator({ appKey: 'your-app-key', cluster: 'eu', WebSocket });
Without one, connect() logs No WebSocket implementation found…, reports it to
bind('realtime:error', ...) and moves to unavailable instead of retrying.
Quick Start
import { Apinator } from '@apinator/client';
const client = new Apinator({
appKey: 'your-app-key',
cluster: 'eu',
});
client.connect();
const channel = client.subscribe('my-channel');
channel.bind('my-event', (data) => {
console.log('Received:', data);
});
Channel Types
Public Channels
No authentication required. Any client can subscribe.
const channel = client.subscribe('news');
channel.bind('update', (data) => { /* ... */ });
Private Channels
Require server-side authentication. Prefix with private-.
const client = new Apinator({
appKey: 'your-app-key',
cluster: 'eu',
authEndpoint: '/api/realtime/auth',
});
const channel = client.subscribe('private-orders');
channel.bind('new-order', (data) => { /* ... */ });
Presence Channels
Like private channels, but also track who is subscribed. Prefix with presence-.
const presence = client.subscribe('presence-chat') as PresenceChannel;
presence.bind('realtime:subscription_succeeded', () => {
console.log('Members:', presence.getMembers());
console.log('Me:', presence.me);
});
presence.bind('realtime:member_added', (member) => {
console.log('Joined:', member);
});
presence.bind('realtime:member_removed', (member) => {
console.log('Left:', member);
});
channel.me is derived from the signed channel_data returned by your authEndpoint.
It becomes available only after realtime:subscription_succeeded.
Cache Channels
A channel named cache-, private-cache- or presence-cache- keeps its last event for
30 minutes. A client that subscribes late gets it right after realtime:subscription_succeeded,
so bind your handlers straight after subscribe().
const job = client.subscribe(`private-cache-job-${jobId}`);
job.bind('job-finished', (data) => { /* runs even if the job finished before you subscribed */ });
If nothing is cached (or it has expired) no event arrives, so keep a fallback such as a status API call.
Client Events
Trigger events directly from the client on private or presence channels:
const privateChannel = client.subscribe('private-chat');
privateChannel.trigger('client-typing', { user: 'alice' });
Connection States
Monitor the connection lifecycle:
client.bind('state_change', ({ previous, current }) => {
console.log(`${previous} -> ${current}`);
});
States: initialized → connecting → connected → disconnected / unavailable
API Reference
See docs/api-reference.md for the full API.
Browser Support
Any browser with WebSocket and fetch support:
- Chrome 42+
- Firefox 39+
- Safari 10.1+
- Edge 14+
- Brave 10+
Links
License
MIT — see LICENSE.