Radar Client

https://github.com/zendesk/radar_client
Admin
Radar Client is a high-level API for building real-time web applications using engine.io, enabling...
Tokens:3,252
Snippets:24
Trust Score:9.5
Update:6 months ago
Show doc for...
Tokens:
Raw
### Configure Radar Client

Source: https://context7.com/zendesk/radar_client/llms.txt

Initialize the client with account credentials and user information before establishing connections.

```javascript
const RadarClient = require('radar_client');

// Configure the client with required credentials
RadarClient.configure({
  accountName: 'my-account',      // Your Radar account name
  userId: 12345,                   // Current user's ID
  userType: 2,                     // User type identifier
  auth: 'AUTH_TOKEN'              // Optional authentication token
});

// Access configuration values
const accountName = RadarClient.configuration('accountName');
const userId = RadarClient.currentUserId();
```

--------------------------------

### Create and Inject Mock Backend for Testing

Source: https://context7.com/zendesk/radar_client/llms.txt

Substitute the default engine.io backend with a mock implementation for testing client functionality without establishing actual server connections. This mock allows inspection of sent messages and simulation of connection events.

```javascript
const RadarClient = require('radar_client');

// Create a mock engine for testing
const MockEngine = {
  Socket: function(config) {
    this.id = 'mock-socket-id';
    this._written = [];
    this._listeners = {};

    const self = this;
    setTimeout(function() {
      self.emit('open');
    }, 10);
  }
};

MockEngine.Socket.prototype.send = function(message) {
  this._written.push(JSON.parse(message));
};

MockEngine.Socket.prototype.on = function(event, handler) {
  this._listeners[event] = this._listeners[event] || [];
  this._listeners[event].push(handler);
};

MockEngine.Socket.prototype.once = MockEngine.Socket.prototype.on;

MockEngine.Socket.prototype.emit = function(event, data) {
  const handlers = this._listeners[event] || [];
  handlers.forEach(function(h) { h(data); });
};

MockEngine.Socket.prototype.removeAllListeners = function() {
  this._listeners = {};
};

MockEngine.Socket.prototype.close = function() {
  this.emit('close');
};

// Inject mock backend
RadarClient.setBackend(MockEngine);

// Now use the client normally - no real server connection needed
const client = new (require('radar_client').constructor)();
client.configure({ accountName: 'test', userId: 123 });
client.alloc('test', function() {
  // Test operations
  client.presence('room/1').set('online');

  // Inspect written messages
  console.log('Messages sent:', MockEngine.Socket.prototype._written);
});

// Reset backend after testing
RadarClient.setBackend(require('engine.io-client'));
```

--------------------------------

### Handle Client Events

Source: https://context7.com/zendesk/radar_client/llms.txt

The client uses MicroEE for event handling, supporting connection lifecycle events, message tracking, and conditional listeners. Use removeListener or removeAllListeners to manage memory and event flow.

```javascript
const RadarClient = require('radar_client');

RadarClient.configure({ accountName: 'dev', userId: 123 });

// Connection lifecycle events
RadarClient.on('ready', function() {
  console.log('Client connected and ready');
});

RadarClient.on('disconnected', function() {
  console.log('Client disconnected, will auto-reconnect');
});

RadarClient.on('backoff', function(time, step) {
  console.log('Reconnecting in', time, 'ms (attempt', step, ')');
});

RadarClient.on('unavailable', function() {
  console.log('Server appears unavailable after multiple retries');
});

RadarClient.on('socketError', function(error) {
  console.error('Socket error:', error);
});

// Message events (incoming/outgoing)
RadarClient.on('message:in', function(message) {
  console.log('Incoming:', message);
});

RadarClient.on('message:out', function(message) {
  console.log('Outgoing:', message);
});

// One-time event listener
RadarClient.once('ready', function() {
  console.log('First ready event');
});

// Conditional event handling with 'when'
RadarClient.when('get', function(message) {
  if (message.to === 'presence:/dev/tickets/21') {
    console.log('Got presence data');
    return true; // Remove listener
  }
  return false; // Keep listening
});

// Remove specific listeners
const handler = function() { console.log('ready'); };
RadarClient.on('ready', handler);
RadarClient.removeListener('ready', handler);

// Remove all listeners for an event
RadarClient.removeAllListeners('ready');

RadarClient.alloc('events-demo');
```

--------------------------------

### Monitor Connection State Machine

Source: https://context7.com/zendesk/radar_client/llms.txt

Access internal connection states and attach error handlers for debugging transitions. Useful for tracking the lifecycle from initial connection to full activation.

```javascript
const RadarClient = require('radar_client');

RadarClient.configure({ accountName: 'dev', userId: 123 });

// Check current connection state
// States: 'opened', 'connecting', 'connected', 'authenticating', 'activated', 'disconnected', 'closed'
console.log('Current state:', RadarClient.currentState());

// Get current socket client ID (when connected)
console.log('Client ID:', RadarClient.currentClientId());

// Attach custom error handler for state machine errors
RadarClient.attachStateMachineErrorHandler(function(name, from, to, args, type, message, err) {
  console.error('State machine error:', {
    transition: name,
    from: from,
    to: to,
    type: type,
    message: message,
    error: err
  });
});

// Listen for state transitions
RadarClient.on('connecting', function() {
  console.log('Connecting to server...');
});

RadarClient.on('connected', function() {
  console.log('Socket connected, authenticating...');
});

RadarClient.on('activated', function() {
  console.log('Connection fully activated');
});

RadarClient.alloc('state-demo');
```

--------------------------------

### Configure Radar Client Backoff Settings

Source: https://context7.com/zendesk/radar_client/llms.txt

Customize exponential backoff behavior for reconnection attempts by setting custom retry intervals, fallback durations, and random jitter. Listen for backoff and unavailable events to manage retry logic and user feedback.

```javascript
const RadarClient = require('radar_client');
const Backoff = RadarClient.Backoff;

// Default backoff durations (milliseconds)
console.log('Default durations:', Backoff.durations);
// [1000, 2000, 4000, 8000, 16000, 32000]

// Customize backoff settings
Backoff.durations = [500, 1000, 2000, 5000, 10000];  // Custom retry intervals
Backoff.fallback = 30000;  // Fallback after exhausting durations (default: 60000)
Backoff.maxSplay = 3000;   // Random jitter to prevent thundering herd (default: 5000)

// Listen for backoff events
RadarClient.on('backoff', function(time, step) {
  console.log('Will retry in', time, 'ms (failure #' + step + ')');
});

RadarClient.on('unavailable', function() {
  // Triggered when all retry durations are exhausted
  console.log('Server unavailable - consider showing user a message');
});

RadarClient.configure({ accountName: 'dev', userId: 123 });
RadarClient.alloc('backoff-demo');
```

--------------------------------

### Manage Presence Scope

Source: https://context7.com/zendesk/radar_client/llms.txt

Track user online/offline status and receive updates within specific channels.

```javascript
const RadarClient = require('radar_client');

RadarClient.configure({ accountName: 'dev', userId: 123, userType: 1 });
RadarClient.alloc('presence-demo', function() {
  const presence = RadarClient.presence('tickets/21');

  // Set current user's presence to online
  presence.set('online');

  // Set presence with custom client data (broadcasted to other users)
  presence.set('online', { status: 'Available', device: 'desktop' });

  // Subscribe to presence changes in this scope
  presence.subscribe();

  // Listen for presence events
  RadarClient.on('presence:/dev/tickets/21', function(message) {
    console.log('Presence update:', message);
    // { op: 'online', to: 'presence:/dev/tickets/21', value: {...} }
  });

  // Get current presence snapshot
  presence.get(function(results) {
    console.log('Current users online:', results);
  });

  // Get with options (v2 format)
  presence.get({ version: 2 }, function(results) {
    console.log('Presence v2 format:', results);
  });

  // Sync presence (subscribe + get initial state)
  presence.sync({ version: 2 });

  // Set presence to offline when leaving
  presence.set('offline');

  // Unsubscribe from presence updates
  presence.unsubscribe();
});
```

--------------------------------

### Manage Message Scope

Source: https://context7.com/zendesk/radar_client/llms.txt

Publish and subscribe to messages within specific channels for real-time broadcasting.

```javascript
const RadarClient = require('radar_client');

RadarClient.configure({ accountName: 'dev', userId: 123 });
RadarClient.alloc('messaging', function() {
  const channel = RadarClient.message('user/456');

  // Subscribe to incoming messages
  channel.subscribe();

  // Listen for messages on this channel
  RadarClient.on('message:/dev/user/456', function(message) {
    console.log('Received message:', message.value);
  });

  // Publish a message (string)
  channel.publish('Hello, world!');

  // Publish a message with callback confirmation
  channel.publish('Important message', function(ack) {
    console.log('Message acknowledged:', ack);
  });

  // Publish complex data (objects are supported)
  channel.publish({
    type: 'notification',
    content: 'New comment on your ticket',
    timestamp: Date.now()
  });

  // Unsubscribe when done
  channel.unsubscribe();
});
```

--------------------------------

### Manage Resource Status with RadarClient

Source: https://context7.com/zendesk/radar_client/llms.txt

Use status scopes to track arbitrary key-value data for resources. Requires an allocated scope and provides methods for setting, subscribing, and syncing status updates.

```javascript
const RadarClient = require('radar_client');

RadarClient.configure({ accountName: 'dev', userId: 123, userType: 2 });
RadarClient.alloc('status-demo', function() {
  const status = RadarClient.status('user/123');

  // Set a status value
  status.set('away');

  // Set status with custom client data
  status.set('busy', { reason: 'In a meeting', until: '3:00 PM' });

  // Subscribe to status changes
  status.subscribe();

  // Listen for status updates
  RadarClient.on('status:/dev/user/123', function(message) {
    console.log('Status changed:', message.value);
  });

  // Get current status
  status.get(function(result) {
    console.log('Current status:', result);
  });

  // Sync status (subscribe + get)
  status.sync();

  // Unsubscribe
  status.unsubscribe();
});
```

--------------------------------

### Manage Client Allocation

Source: https://context7.com/zendesk/radar_client/llms.txt

Register and unregister usage of the client connection to control automatic connection and disconnection.

```javascript
const RadarClient = require('radar_client');

// Allocate the client for a specific use case
RadarClient.configure({ accountName: 'dev', userId: 123 });

RadarClient.alloc('chat-widget', function() {
  console.log('Client ready for chat-widget');

  // Perform real-time operations
  RadarClient.presence('chat-room/1').set('online');
  RadarClient.message('chat-room/1').subscribe();
});

// Later, when done with this feature
RadarClient.dealloc('chat-widget');

// Multiple allocations are supported
RadarClient.alloc('notifications', function() {
  console.log('Client ready for notifications');
});

// Client stays connected until all uses are deallocated
RadarClient.dealloc('notifications'); // Connection closes if no other allocs
```

--------------------------------

### Subscribe to Data Streams

Source: https://context7.com/zendesk/radar_client/llms.txt

Stream scopes allow for receiving sequential, time-ordered data. Use sync to retrieve historical data while simultaneously subscribing to new updates.

```javascript
const RadarClient = require('radar_client');

RadarClient.configure({ accountName: 'dev', userId: 123 });
RadarClient.alloc('stream-demo', function() {
  const stream = RadarClient.stream('activity/feed');

  // Subscribe to the stream
  stream.subscribe();

  // Listen for stream events
  RadarClient.on('stream:/dev/activity/feed', function(message) {
    console.log('Stream data:', message);
  });

  // Sync to get historical data and subscribe
  stream.sync();

  // Get stream data with options
  stream.get({ limit: 50 }, function(results) {
    console.log('Stream history:', results);
  });

  // Unsubscribe from stream
  stream.unsubscribe();
});
```
Tokens:
Raw