Configuration Options

The OMX Core SDK provides extensive configuration options to customize behavior for different environments, performance requirements, and integration scenarios.

Environment Configuration

Configure the SDK for different deployment environments:

import { OMXClient } from '@omx-sdk/core';

// Development environment
const devConfig = {
  clientId: process.env.OMX_CLIENT_ID,
  secretKey: process.env.OMX_SECRET_KEY,
  environment: 'development',
  
  // Development settings
  debug: true,
  logLevel: 'verbose',
  apiEndpoint: 'https://api-dev.omx.com/v1',
  timeout: 30000,
  retries: 1
};

// Production environment
const prodConfig = {
  clientId: process.env.OMX_CLIENT_ID,
  secretKey: process.env.OMX_SECRET_KEY,
  environment: 'production',
  
  // Production settings
  debug: false,
  logLevel: 'error',
  apiEndpoint: 'https://api.omx.com/v1',
  timeout: 10000,
  retries: 3
};

const omx = new OMXClient(
  process.env.NODE_ENV === 'production' ? prodConfig : devConfig
);

Logging Configuration

Customize logging behavior and output:

const omx = new OMXClient({
  clientId: 'your_client_id',
  secretKey: 'your_secret_key',
  
  logging: {
    level: 'info', // 'debug', 'info', 'warn', 'error', 'silent'
    format: 'json', // 'json', 'text', 'structured'
    
    // Custom logger
    logger: {
      debug: (message, meta) => console.debug('[OMX]', message, meta),
      info: (message, meta) => console.info('[OMX]', message, meta),
      warn: (message, meta) => console.warn('[OMX]', message, meta),
      error: (message, meta) => console.error('[OMX]', message, meta)
    },
    
    // Log filtering
    filters: {
      excludeHeaders: ['authorization', 'x-api-key'],
      excludePaths: ['/health', '/metrics'],
      maxBodySize: 1024 // bytes
    },
    
    // External logging services
    external: {
      datadog: {
        enabled: true,
        apiKey: process.env.DATADOG_API_KEY,
        service: 'omx-client'
      },
      sentry: {
        enabled: true,
        dsn: process.env.SENTRY_DSN
      }
    }
  }
});

Performance Configuration

Optimize performance with caching, connection pooling, and batching:

const omx = new OMXClient({
  clientId: 'your_client_id',
  secretKey: 'your_secret_key',
  
  performance: {
    // Request caching
    cache: {
      enabled: true,
      ttl: 300000, // 5 minutes
      maxSize: 100, // Max cached items
      strategy: 'lru' // 'lru', 'fifo', 'lfu'
    },
    
    // Connection pooling
    connectionPool: {
      maxConnections: 10,
      keepAlive: true,
      timeout: 5000
    },
    
    // Request batching
    batching: {
      enabled: true,
      maxBatchSize: 10,
      batchTimeout: 100, // ms
      endpoints: ['geotriggers', 'campaigns']
    },
    
    // Compression
    compression: {
      enabled: true,
      algorithm: 'gzip',
      threshold: 1024 // bytes
    }
  }
});

Retry and Circuit Breaker

Configure resilience patterns for API calls:

const omx = new OMXClient({
  clientId: 'your_client_id',
  secretKey: 'your_secret_key',
  
  resilience: {
    // Retry configuration
    retry: {
      maxRetries: 3,
      initialDelay: 1000, // ms
      maxDelay: 10000, // ms
      backoffMultiplier: 2,
      jitter: true,
      
      // Retry conditions
      retryableErrors: [
        'NETWORK_ERROR',
        'TIMEOUT',
        'RATE_LIMITED',
        'SERVER_ERROR'
      ],
      
      // Custom retry logic
      shouldRetry: (error, attemptCount) => {
        return attemptCount < 3 && error.isRetryable;
      }
    },
    
    // Circuit breaker
    circuitBreaker: {
      enabled: true,
      threshold: 5, // Failures before opening
      timeout: 60000, // ms before half-open
      resetTimeout: 30000, // ms in half-open state
      
      onOpen: () => console.log('Circuit breaker opened'),
      onHalfOpen: () => console.log('Circuit breaker half-open'),
      onClose: () => console.log('Circuit breaker closed')
    }
  }
});

Custom Interceptors

Add custom logic to request/response processing:

const omx = new OMXClient({
  clientId: 'your_client_id',
  secretKey: 'your_secret_key',
  
  interceptors: {
    // Request interceptors
    request: [
      (config) => {
        // Add custom headers
        config.headers['X-Request-ID'] = generateRequestId();
        config.headers['X-Timestamp'] = Date.now();
        return config;
      },
      (config) => {
        // Request validation
        if (!config.data) {
          throw new Error('Request data is required');
        }
        return config;
      }
    ],
    
    // Response interceptors
    response: [
      (response) => {
        // Transform response data
        if (response.data?.items) {
          response.data.items = response.data.items.map(transformItem);
        }
        return response;
      },
      (response) => {
        // Analytics tracking
        trackApiUsage(response.config.url, response.status);
        return response;
      }
    ],
    
    // Error interceptors
    error: [
      (error) => {
        // Error transformation
        if (error.code === 'NETWORK_ERROR') {
          throw new CustomNetworkError(error.message);
        }
        throw error;
      }
    ]
  }
});

Module-Specific Configuration

Configure individual modules with specific settings:

const omx = new OMXClient({
  clientId: 'your_client_id',
  secretKey: 'your_secret_key',
  
  modules: {
    geotrigger: {
      enabled: true,
      maxTriggers: 100,
      defaultRadius: 100,
      precisionLevel: 'high'
    },
    
    email: {
      enabled: true,
      provider: 'sendgrid',
      apiKey: process.env.SENDGRID_API_KEY,
      defaultFrom: 'noreply@yourapp.com',
      trackingEnabled: true
    },
    
    pushNotification: {
      enabled: true,
      providers: {
        ios: {
          keyId: process.env.APNS_KEY_ID,
          teamId: process.env.APNS_TEAM_ID,
          bundleId: 'com.yourapp.mobile'
        },
        android: {
          serverKey: process.env.FCM_SERVER_KEY,
          senderId: process.env.FCM_SENDER_ID
        }
      }
    },
    
    webhook: {
      enabled: true,
      maxRetries: 5,
      timeout: 30000,
      verifySSL: true
    }
  }
});

Configuration Validation

Validate configuration at runtime:

import { validateConfig } from '@omx-sdk/core';

const config = {
  clientId: 'your_client_id',
  secretKey: 'your_secret_key',
  // ... other config
};

// Validate configuration
const validation = validateConfig(config);
if (!validation.valid) {
  console.error('Configuration errors:', validation.errors);
  throw new Error('Invalid configuration');
}

// Initialize with validated config
const omx = new OMXClient(config);

// Runtime configuration updates
await omx.updateConfig({
  logging: { level: 'debug' },
  performance: { cache: { enabled: false } }
});

Environment Variables

Recommended environment variables for different configurations:

# Core authentication
OMX_CLIENT_ID=your_client_id
OMX_SECRET_KEY=your_secret_key
OMX_ENVIRONMENT=production

# API configuration
OMX_API_ENDPOINT=https://api.omx.com/v1
OMX_TIMEOUT=10000
OMX_MAX_RETRIES=3

# Logging
OMX_LOG_LEVEL=info
OMX_DEBUG=false

# External services
DATADOG_API_KEY=your_datadog_key
SENTRY_DSN=your_sentry_dsn

# Module-specific
SENDGRID_API_KEY=your_sendgrid_key
APNS_KEY_ID=your_apns_key_id
FCM_SERVER_KEY=your_fcm_key

Configuration Best Practices

Environment Separation: Use different configs for dev/staging/prod
Secret Management: Never commit secrets to version control
Validation: Always validate configuration before use
Documentation: Document all configuration options
Defaults: Provide sensible defaults for all settings
Runtime Updates: Support hot-reloading of non-sensitive configs

Core Configuration