@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)

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> | Observable of auth tokens. Emitting a new value re-authenticates the connection |

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)
})

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