Client Configuration

The CloudSignalClient constructor accepts a configuration object with the following options.

Required Options

interface CloudSignalConfig {
  organizationId: string;  // Your CloudSignal organization ID
}

Connection Options

{
  // MQTT broker URL (default: wss://mqtt.cloudsignal.io:8084/mqtt)
  brokerUrl?: string;
  
  // Connection timeout in ms (default: 30000)
  connectTimeout?: number;
  
  // Keep-alive interval in seconds (default: 60)
  keepAlive?: number;
  
  // Auto-reconnect on disconnect (default: true)
  autoReconnect?: boolean;
  
  // Max reconnect attempts (default: Infinity)
  maxReconnectAttempts?: number;
  
  // Base delay for reconnect backoff in ms (default: 1000)
  reconnectDelay?: number;
  
  // Max reconnect delay in ms (default: 30000)
  maxReconnectDelay?: number;
}

Authentication Options

{
  // API key for token auth
  apiKey?: string;
  
  // Token authentication config
  auth?: {
    enabled: boolean;
    userId?: string;
    token?: string;
    tokenRefreshBuffer?: number;  // seconds before expiry
    onTokenExpiring?: () => Promise<string>;
  };
  
  // External IdP authentication
  externalAuth?: {
    provider: 'supabase' | 'firebase' | 'auth0' | 'oidc';
    getToken: () => Promise<string | null>;
    getUserId: () => string | undefined;
    issuer?: string;
    audience?: string;
    refreshInterval?: number;
  };
}

Message Options

{
  // Default QoS level (default: 1)
  qos?: 0 | 1 | 2;
  
  // Enable message queue for offline (default: true)
  enableOfflineQueue?: boolean;
  
  // Max offline queue size (default: 100)
  maxOfflineQueueSize?: number;
  
  // Auto-parse JSON messages (default: true)
  autoParseJson?: boolean;
}

Logging Options

{
  // Enable debug logging (default: false)
  debug?: boolean;
  
  // Log level (default: 'warn')
  logLevel?: 'debug' | 'info' | 'warn' | 'error';
  
  // Custom logger function
  logger?: (level: string, message: string, ...args: any[]) => void;
}

Platform Presets

Use presets for optimized configuration:

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

// Mobile preset - optimized for battery and reconnection
const mobileClient = new CloudSignalClient({
  organizationId: 'your-org-id',
  ...presets.mobile
});

// Desktop preset - balanced performance
const desktopClient = new CloudSignalClient({
  organizationId: 'your-org-id',
  ...presets.desktop
});

// Server preset - high throughput, low latency
const serverClient = new CloudSignalClient({
  organizationId: 'your-org-id',
  ...presets.server
});

Preset Details

Mobile Preset:

• Longer keep-alive (120s) for battery optimization
• Aggressive reconnection with exponential backoff
• Smaller offline queue (50 messages)

Desktop Preset:

• Standard keep-alive (60s)
• Moderate offline queue (100 messages)
• Balanced reconnection strategy

Server Preset:

• Short keep-alive (30s) for fast failure detection
• Large offline queue (1000 messages)
• Immediate reconnection attempts

Complete Example

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

const client = new CloudSignalClient({
  // Required
  organizationId: 'org-abc123',
  
  // Connection
  brokerUrl: 'wss://mqtt.cloudsignal.io:8084/mqtt',
  connectTimeout: 30000,
  keepAlive: 60,
  autoReconnect: true,
  maxReconnectAttempts: 10,
  reconnectDelay: 1000,
  maxReconnectDelay: 30000,
  
  // Authentication
  auth: {
    enabled: true,
    userId: 'user-123',
    tokenRefreshBuffer: 300
  },
  
  // Messages
  qos: 1,
  enableOfflineQueue: true,
  maxOfflineQueueSize: 100,
  autoParseJson: true,
  
  // Logging
  debug: process.env.NODE_ENV === 'development',
  logLevel: 'info'
});