Client Configuration

The CloudSignalClient constructor accepts an options object that configures the client itself. Connection details (host, credentials, organization) are passed later to connect() or connectWithToken(), not to the constructor.

const client = new CloudSignalClient(options?);

The constructor takes no required options. Calling new CloudSignalClient() with no arguments is valid and applies the auto-detected platform preset.

Connection Options

{
  // MQTT protocol version, 4 (3.1.1) or 5 (default depends on preset)
  protocolVersion?: 4 | 5;
  
  // Connection timeout in ms (default: 30000)
  connectTimeout?: number;
  
  // Keep-alive interval in seconds (default: 60)
  keepalive?: number;
  
  // Start a clean (non-persistent) session
  cleanSession?: boolean;
  
  // Reconnect interval in ms
  reconnectPeriod?: number;
  
  // Max reconnect attempts (0 = unlimited)
  maxReconnectAttempts?: number;
}

Authentication Options

Token authentication (V2) is enabled by setting tokenServiceUrl. The organization, credentials, and external IdP token are supplied per-connection to connectWithToken() rather than in the constructor.

{
  // Token service URL — required for connectWithToken() / token auth
  tokenServiceUrl?: string;
  
  // Automatically refresh the token before it expires
  autoRefresh?: boolean;
}

Message Options

{
  // Enable message queue for offline (default depends on preset)
  offlineQueueEnabled?: boolean;
  
  // Max offline queue size
  offlineQueueMaxSize?: number;
  
  // Enable the request/response pattern (AI agent helper)
  enableRequestResponse?: boolean;
}

QoS is set per call on transmit(topic, message, { qos }) and subscribe(topic, { qos }), not as a single global constructor option.

Logging Options

{
  // Enable debug logging (default: false)
  debug?: boolean;
  
  // Custom logger instance
  logger?: any;
}

Platform Presets

The simplest way to apply optimized configuration is the preset option, which selects a built-in profile by name. Use 'auto' to detect the platform:

import { CloudSignalClient } from '@cloudsignal/mqtt-client';

// Mobile preset - optimized for battery and reconnection
const mobileClient = new CloudSignalClient({ preset: 'mobile' });

// Desktop preset - balanced performance
const desktopClient = new CloudSignalClient({ preset: 'desktop' });

// Agent preset - request/response enabled, fast reconnection
const agentClient = new CloudSignalClient({ preset: 'agent' });

// Server preset - high throughput, low latency
const serverClient = new CloudSignalClient({ preset: 'server' });

You can also import the raw preset objects and spread one in to override individual values:

import { CloudSignalClient, presets } from '@cloudsignal/mqtt-client';

// Start from the mobile preset, then override specific options
const client = new CloudSignalClient({
  ...presets.mobile,
  keepalive: 90
});

Preset Details

Mobile Preset:

MQTT 3.1.1 for broader device compatibility
Slower reconnection (10s) to conserve battery, up to 50 attempts
Persistent sessions and a staggered resubscribe for unreliable networks

Desktop Preset:

MQTT 5.0 for full feature support
Fast reconnection (5s) for responsive UX
Balanced offline queue and reconnection strategy

Agent Preset:

MQTT 5.0 with request/response enabled by default
Aggressive reconnection (2s) for reliability
Timestamps and sender IDs for tracing

Server Preset:

Short keep-alive (30s) for fast failure detection
Unlimited reconnection attempts for always-on services
Large offline queue for high throughput

Complete Example

Configure the client with the constructor, then pass the host, organization, and credentials to connectWithToken():

import { CloudSignalClient } from '@cloudsignal/mqtt-client';

const client = new CloudSignalClient({
  // Connection
  protocolVersion: 5,
  connectTimeout: 30000,
  keepalive: 60,
  maxReconnectAttempts: 10,
  reconnectPeriod: 1000,
  cleanSession: false,
  
  // Token authentication (V2)
  tokenServiceUrl: 'https://auth.cloudsignal.app',
  autoRefresh: true,
  
  // Messages
  offlineQueueEnabled: true,
  offlineQueueMaxSize: 100,
  
  // Logging
  debug: process.env.NODE_ENV === 'development'
});

await client.connectWithToken({
  host: 'wss://connect.cloudsignal.app:18885/',
  organizationId: 'org-abc123',
  secretKey: 'cs_...',
  userEmail: 'user@example.com'
});