@sanity/bifur-client

A WebSocket client for Sanity's Bifur real-time service. Communicates over JSON-RPC 2.0 and returns RxJS Observables.

Installation

npm install @sanity/bifur-client

Usage

From a @sanity/client instance

The simplest way to get started if you already use @sanity/client:

import {fromSanityClient} from '@sanity/bifur-client'
import {createClient} from '@sanity/client'

const sanityClient = createClient({
  projectId: 'your-project-id',
  dataset: 'production',
  token: 'your-token',
})

const bifur = fromSanityClient(sanityClient)

fromSanityClient also accepts timeout and idleTimeout as a second argument, with the same meaning as for fromUrl below.

From a WebSocket URL

Connect directly to a Bifur WebSocket endpoint:

import {fromUrl} from '@sanity/bifur-client'
import {of} from 'rxjs'

const bifur = fromUrl('wss://example.sanity.io/socket/production', {
  timeout: 10_000,
  token$: of('your-token'),
})

Options

Option	Type	Description
timeout	number	Milliseconds to wait before timing out the initial connection
token$	Observable<string | null>	Auth token, or null for not authenticated. Must replay its latest value to new subscribers, like a BehaviorSubject or shareReplay, because each new connection subscribes to it and waits for a token. Emitting a new value re-authenticates the connection
idleTimeout	number | (() => ObservableInput)	Milliseconds to keep the socket open after the last subscriber leaves. Defaults to 0 (closes immediately). Pass a function to decide each time: the socket closes when the observable it returns emits.

Presence example

Subscribe to presence events with listen(), and send requests with request():

// Subscribe to presence events
bifur.listen('presence').subscribe((event) => {
  console.log(event.type, event) // 'rollCall', 'state', or 'disconnect'
})

// Respond to roll calls
bifur.request('presence_rollcall', {session: sessionId})

// Announce your location
bifur.request('presence_announce', {
  data: {sessionId, locations: [{documentId: 'my-doc', path: 'title'}]},
})

// Disconnect
bifur.request('presence_disconnect', {session: sessionId})

Heartbeats

heartbeats is an Observable that emits a Date each time a message (including heartbeat pings) is received. Subscribing to it keeps the connection alive between requests:

bifur.heartbeats.subscribe((timestamp) => {
  console.log('Last activity:', timestamp)
})

When the socket closes while heartbeats is subscribed, it errors with a WebSocketError of type CONNECTION_CLOSED that carries the close code and reason. Subscribe again to open a new connection.

Request and subscribe methods

Request methods: presence_rollcall, presence_announce, presence_disconnect, authorization

Subscribe methods: presence, authorization

Error codes

import {ERROR_CODES} from '@sanity/bifur-client'

// Connection-level
ERROR_CODES.BAD_REQUEST // 4000
ERROR_CODES.UNAUTHORIZED // 4001
ERROR_CODES.NOT_FOUND // 4004

// Application-level (JSON-RPC)
ERROR_CODES.INVALID_REQUEST // -32600
ERROR_CODES.METHOD_NOT_FOUND // -32601
ERROR_CODES.INVALID_PARAMS // -32602
ERROR_CODES.SUBSCRIPTION_NOT_FOUND // -32602
ERROR_CODES.PARSE_ERROR // -32700

License

MIT - See LICENSE