Client Methods

Low-level messaging methods (Advanced).

Overview

The Client Methods provide low-level message passing between your application and the TelemetryOS platform. Most developers should use the higher-level resource methods (storage, media, playlist, etc.) instead.

Note: These are advanced methods. Use resource-specific methods when possible.

Importing

import { configure, on, once, off, send, request, subscribe, unsubscribe, globalClient } from '@telemetryos/sdk';

Core Functions

configure()

Initialize the SDK.

Signature:

configure(applicationName: string): void

Parameters:

applicationName - Must match name in telemetry.config.json

Example:

import { configure } from '@telemetryos/sdk';

configure('my-app-name');

Important: Call before using any other SDK methods.

destroy()

Clean up SDK resources.

Signature:

destroy(): void

Example:

destroy();

Unbinds event listeners and clears global client instance.

globalClient()

Access the underlying Client instance.

Signature:

globalClient(): Client | null

Returns: Client instance or null if not configured

Example:

const client = globalClient();
if (client) {
  console.log('SDK is configured');
}

Message Handlers

on()

Signature:

on(name: string, handler: (data: any) => void): void

Parameters:

name - Message type to listen for
handler - Callback function

Example:

on('custom-event', (data) => {
  console.log('Received:', data);
});

once()

Signature:

once(name: string, handler: (data: any) => void): void

Example:

once('initialized', (data) => {
  console.log('App initialized');
});

off()

Remove message handler(s).

Signature:

off(name: string, handler?: (data: any) => void): void

Parameters:

name - Message type
handler - Optional specific handler to remove

Example:

off('custom-event', myHandler);

Messaging

send()

Send one-way message (no response expected).

Signature:

send(name: string, data: any): void

Example:

send('log-event', { action: 'button-click', timestamp: Date.now() });

request()

Send message and await response.

Signature:

async request<T>(name: string, data: any): Promise<T>

Parameters:

name - Message endpoint
data - Request payload

Returns: Promise resolving to response data

Example:

const result = await request('custom.get', { key: 'setting' });

subscribe()

Set up persistent subscription.

Signature:

async subscribe(name: string, key: any, handler: (data: any) => void): Promise<SubscriptionResult>

Parameters:

name - Subscription endpoint
key - Subscription identifier
handler - Callback for messages

Returns: Promise resolving to SubscriptionResult object with success boolean property

Example:

await subscribe('data.updates', 'temperature', (temp) => {
  console.log('New temperature:', temp);
});

unsubscribe()

Cancel subscription.

Signature:

async unsubscribe(name: string, key: any, handler?: (data: any) => void): Promise<SubscriptionResult>

Example:

await unsubscribe('data.updates', 'temperature', myHandler);

When to Use Client API

Use resource-specific APIs for common operations. Only use Client API for advanced use cases like building SDK extensions, implementing custom protocols, or debugging message flow.

Next Steps

Storage API - Data persistence
Media API - Media access
Platform APIs - Other integration APIs