Real-time Events

The EventsClient provides real-time event streaming for bucket and upload changes over WebSocket. Use it to react to file uploads, deletions, moves, and other changes as they happen.

Setup

import { EventsClient } from '@xeonr/uploads-sdk/api/Events';

const upl = new Upl({ clientId: 'your-client-id' });
const events = new EventsClient(upl.getApiAdapter());

await events.connect();

Subscribing to events

// Subscribe to all changes in a bucket
const subId = await events.subscribe({
  bucketId: 'bkt_abc123',
});

// Subscribe to a specific upload
const subId = await events.subscribe({
  bucketId: 'bkt_abc123',
  uploadId: 'upl_xyz789',
});

// Subscribe to everything the user has access to
const subId = await events.subscribe({
  everything: true,
});

// Subscribe with filters
const subId = await events.subscribe({
  bucketId: 'bkt_abc123',
  filter: {
    changeTypes: ['CREATE', 'UPDATE', 'DELETE'],
    resourceTypes: ['UPLOAD', 'FOLDER'],
    pathPrefix: '/images',
  },
});

Option	Type	Description
`everything`	`boolean`	Subscribe to all accessible buckets
`bucketId`	`string`	Subscribe to a specific bucket
`uploadId`	`string`	Subscribe to a specific upload (requires `bucketId`)
`filter.changeTypes`	`ChangeType[]`	Filter by change type
`filter.resourceTypes`	`ChangeTarget[]`	Filter by resource type
`filter.pathPrefix`	`string`	Filter by path prefix

Listening to events

// Resource changes (uploads, folders)
events.on('resourceChange', (event) => {
  console.log('Change:', event.changeType, event.resourceType, event.resourceId);
});

// Connection events
events.on('connected', () => console.log('Connected'));
events.on('disconnected', ({ code, reason }) => console.log('Disconnected:', reason));

// State changes
events.on('stateChange', (state) => {
  // state: 'disconnected' | 'connecting' | 'connected' | 'reconnecting'
});

// Errors
events.on('error', (error) => console.error('Event error:', error));

Event types

Event	Payload	Description
`resourceChange`	Change event object	Upload or folder changed
`hello`	`{ socketId }`	Initial connection acknowledgement
`connected`	—	WebSocket connected
`disconnected`	`{ code, reason }`	WebSocket disconnected
`stateChange`	`ConnectionState`	Connection state transition
`subscribeAck`	Subscription confirmation	Subscribe succeeded
`unsubscribeAck`	—	Unsubscribe succeeded
`error`	Error object	Server-side error

Unsubscribing

await events.unsubscribe(subId);

Disconnecting

events.disconnect();

Reconnection

The client automatically reconnects on disconnection using exponential backoff:

Min delay: 1 second
Max delay: 30 seconds
Strategy: minMs * 2^attempt, capped at maxMs

On reconnect, all active subscriptions are automatically re-established.

A keepalive ping is sent every 5 seconds to detect stale connections.

Connection options

const events = new EventsClient(adapter, {
  reconnect: {
    minMs: 1000,    // Minimum reconnect delay (default: 1000)
    maxMs: 30000,   // Maximum reconnect delay (default: 30000)
  },
});

Real-time Events

On this page