# Client Methods

Low-level messaging methods for advanced use cases. Most developers should use the higher-level resource methods instead.

# 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

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

## Core Functions

### configure()

Initialize the SDK.

**Signature:**

```typescript
configure(applicationName: string): void
```

**Parameters:**

* `applicationName` - Must match name in telemetry.config.json

**Example:**

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

configure('my-app-name');
```

**Important:** Call before using any other SDK methods.

### destroy()

Clean up SDK resources.

**Signature:**

```typescript
destroy(): void
```

**Example:**

```typescript
destroy();
```

Unbinds event listeners and clears global client instance.

### globalClient()

Access the underlying Client instance.

**Signature:**

```typescript
globalClient(): Client | null
```

**Returns:** Client instance or null if not configured

**Example:**

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

## Message Handlers

### on()

Register a message handler.

**Signature:**

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

**Parameters:**

* `name` - Message type to listen for
* `handler` - Callback function

**Example:**

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

### once()

Register a one-time message handler.

**Signature:**

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

**Example:**

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

### off()

Remove message handler(s).

**Signature:**

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

**Parameters:**

* `name` - Message type
* `handler` - Optional specific handler to remove

**Example:**

```typescript
off('custom-event', myHandler);
```

## Messaging

### send()

Send one-way message (no response expected).

**Signature:**

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

**Example:**

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

### request()

Send message and await response.

**Signature:**

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

**Parameters:**

* `name` - Message endpoint
* `data` - Request payload

**Returns:** Promise resolving to response data

**Example:**

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

### subscribe()

Set up persistent subscription.

**Signature:**

```typescript
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:**

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

### unsubscribe()

Cancel subscription.

**Signature:**

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

**Example:**

```typescript
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](./storage-methods.md)** - Data persistence
* **[Media API](./media-methods.md)** - Media access
* **[Platform APIs](./platform-methods.md)** - Other integration APIs