@huddle01/observer-client-sdk

Observer Client SDK

This is the client SDK for the Observer service. It is a library that can be used to connect to the Observer service and execute operations on it.

Table of Contents

• Install and Connect
• ObserverClient
• DataFrame
• ObserverAdminClient

Install and Connect

npm install observer-client-sdk

import { ObserverClient } from '@huddle01/observer-client-sdk';

const observerClient = new ObserverClient({
	// configuration options for connection
	connection: {
		// url of the observer service
		url: 'http://localhost:8080',

		// access token for the observer service
		getAccessToken: async () => {
			// fetch my access Token
		}
	},
});

observerClient.connect();

ObserverClient

The ObserverClient API provides an interface for interacting with data streams and real-time data updates via WebSocket connections. This client enables users to access call data, ongoing call information, client snapshots, and other related data through the following methods and events:

Events

• 'close': Triggered when the WebSocket connection is closed.

Configuration

• ObserverClientConfig: Configuration object used to initialize the ObserverClient.
  • connection: Configuration for the WebSocket connection, using WebSocketConnectorConfig.

Methods

connect(accessToken?: string): Promise

• Establishes a WebSocket connection.
• accessToken (optional): An access token to authenticate the connection.

close(): void

• Closes the WebSocket connection and cleans up resources.

findCalls(params: DashboardQueryOperations['findCalls']): Promise

• Queries the system for historical calls based on specified parameters.
• params: Object containing query filters such as producerId, consumerId, transportId, callId, roomId, clientId, and mediaTrackId

fetchOngoingCalls(): Promise

• Retrieves data about ongoing calls.
• No parameters required.

getSummaryStats(params: DashboardQueryOperations['getSummaryStats']): Promise

• Fetches summarized statistics based on the given parameters.
• params: Parameters to filter and aggregate the summary data.

createDatabaseFrame(resourceId: K, conditions: DatabaseFrameConditions<DatabaseFrameSchema[K]>, updateOnCreate = true): Promise<DataFrame<DatabaseFrameSchema[K]>>

• Creates a data frame for a specific resource in the database with filtering conditions.
• resourceId: Identifier for the database resource.
• conditions: Filter conditions for the data.
• updateOnCreate (optional): Whether to fetch the initial data on creation.

createCallSnapshotsFrame(callId: string): Promise<DataFrame>

• Creates a data frame for tracking snapshots of a specific call.
• callId: Unique identifier of the call.

createClientSnapshotsFrame(options: { callId: string, clientId: string }): Promise<DataFrame>

• Creates a data frame for tracking snapshots of a specific client within a call.
• options: An object containing:
  • callId: Unique identifier of the call.
  • clientId: Unique identifier of the client.

This API provides a structured way to access and interact with call and client data in real-time, making it suitable for applications that require live monitoring and data analysis.

DataFrame

The DataFrame API provides a flexible and efficient interface for data extraction and real-time data updates. It allows users to either:

1. Batch Retrieval: Extract large volumes of data in chunks, such as comprehensive reports on calls or clients. This is useful for obtaining historical data or performing extensive data analysis.

2. Continuous Streaming: Subscribe to updates for a particular resource, receiving real-time data as it changes. This is ideal for monitoring ongoing events or tracking live updates, such as changes in call status or client activity.

Constructor

constructor(
  config: DataFrameConfig,
  channel: WebSocketConnector,
  sortFn?: (a: T, b: T) => number
)

• config: Configuration object containing the unique dataFrameId.
• channel: WebSocket connector instance used for backend communication.
• sortFn (optional): Function to sort the rows within the data frame.

Methods

• close(): void: Closes the data frame, stops receiving updates, and triggers a 'close' event.
• update(): Promise: Fetches the latest data from the server and updates the local data frame. If a sorting function is provided, the rows will be sorted after the update.
• Symbol.iterator: IterableIterator: Allows iteration over the rows in the data frame.
• dispatch(event: DashboardDataStreamNotification['event']): void: Handles incoming WebSocket events and updates the data frame accordingly.

Events

• 'close': Emitted when the data frame is closed.
• 'newrow' (row: T): Emitted whenever a new row of data is added to the data frame.
• 'error' (error: string): Emitted when an error occurs.

Usage Example

// Creating a new data frame instance
const myDataFrame = observerClient.createClientSnapshotsFrame({
	callId: '12345',
	clientId: '67890',
});

// Listen for new rows
myDataFrame.on('newrow', (row) => {
  console.log('New data row received:', row);
});

// Listen for errors
myDataFrame.on('error', (error) => {
  console.error('Data frame error:', error);
});

// Update the data frame
await myDataFrame.update();

// Iterate over the rows
for (const row of myDataFrame) {
  console.log('Row:', row);
}

// Close the data frame when done
myDataFrame.close();

ObserverAdminClient

The ObserverAdminClient is an extension of the ObserverClient class designed to provide administrative control over the system. It offers additional methods to manage and monitor server and worker states, initiate and manage jobs, and clean up completed or failed tasks.

Constructor

constructor(config: ObserverClientConfig)

• config: Configuration object for the ObserverAdminClient, inheriting from ObserverClientConfig.

Methods

• getWorkerState(): Promise
  • Retrieves the current state of all workers in the system.
  • Returns a promise that resolves to the worker states payload.
• getServerState(): Promise
  • Retrieves the current state of all servers in the system.
  • Returns a promise that resolves to the server states payload.
• startJob(type: J, parameters: ConsumableJobMap[J]['input']): Promise<{ jobId?: string }>
  • Starts a new job of a specified type with the given parameters.
  • type: The type of job to be started, as defined in ConsumableJobMap.
  • parameters: The input parameters required for the specified job type.
  • Returns a promise that resolves to an object containing the jobId of the started job.
• cleanFailedJobs(...jobIds: string[]): Promise
  • Cleans up failed jobs from the system. If no job IDs are provided, it cleans up all failed jobs.
  • jobIds (optional): An array of job IDs to clean. If omitted, all failed jobs will be cleaned.
  • Returns a promise that resolves when the operation is complete.
• cleanCompletedJobs(...jobIds: string[]): Promise
  • Cleans up completed jobs from the system. If no job IDs are provided, it cleans up all completed jobs.
  • jobIds (optional): An array of job IDs to clean. If omitted, all completed jobs will be cleaned.
  • Returns a promise that resolves when the operation is complete.
• cancelJob(type: J, jobId: string): Promise
  • Cancels a running job of a specified type and ID.
  • type: The type of job to be canceled.
  • jobId: The unique identifier of the job to be canceled.
  • Returns a promise that resolves to a boolean indicating whether the cancellation was successful.
• listJobs(): Promise
  • Lists all jobs currently present in the system, including their status and details.
  • Returns a promise that resolves to the list of jobs.