Fluxum SDK for Node.js

A comprehensive Node.js SDK for the Fluxum API queue management service with real-time WebSocket communication, client-side encryption, and advanced analytics.

Features

• 🔐 Authentication: Secure API key-based authentication
• 🔄 Real-time Communication: WebSocket-based job updates and status tracking
• 🔒 Client-side Encryption: RSA encryption for sensitive data
• 📊 Comprehensive Analytics: Detailed performance and usage metrics
• 🚦 Rate Limiting: Built-in rate limit detection and automatic recovery
• 🔄 Auto-reconnection: Automatic reconnection with configurable retry logic
• 📝 Job Management: Submit jobs and track their progress in real-time
• 🎯 Promise-based API: Simple promise-based methods for easy integration

Installation

npm install fluxum-sdk-node
# or
yarn add fluxum-sdk-node

Quick Start

const { FluxumSDK, SDK_EVENTS } = require('fluxum-sdk-node');

// Create SDK instance
const sdk = new FluxumSDK({
  apiKey: 'your-api-key-here',
  enableAnalytics: true,
});

// Set up event listeners
sdk.on(SDK_EVENTS.AUTHENTICATED, () => {
  console.log('✅ Connected and authenticated!');
});

sdk.on(SDK_EVENTS.JOB_SUBMITTED, (data) => {
  console.log(`📤 Job submitted: ${data.jobId}`);
});

sdk.on(SDK_EVENTS.JOB_UPDATE, (update) => {
  console.log(`📊 Job ${update.jobId}: ${update.status}`);
  
  if (update.status === 'completed') {
    console.log('✅ Job completed successfully');
    if (update.targetResponse) {
      console.log(`📄 Response status: ${update.targetResponse.status}`);
    }
  }
});

sdk.on(SDK_EVENTS.ERROR, (error) => {
  console.error('❌ SDK Error:', error.message);
});

// Connect to the service
sdk.connect();

// Submit a job
const jobPayload = {
  requestData: {
    method: 'GET',
    url: 'https://httpbin.org/get',
    headers: {
      'X-Test': 'fluxum-sdk-test',
    },
  },
};

try {
  await sdk.submitJob(jobPayload);
  console.log('📤 Job submitted successfully');
} catch (error) {
  console.error('❌ Job submission failed:', error.message);
}

Environment Configuration

The SDK supports environment variables for configuration. Create a .env file in your project root:

# Copy the example file
cp env.example .env

# Edit .env with your API key
FLUXUM_API_KEY=fk_live_your_actual_api_key_here

Environment Variables

| Variable | Description | Required | |----------|-------------|----------| | FLUXUM_API_KEY | Your Fluxum API key | Yes |

Using Environment Variables

require('dotenv').config();
const { FluxumSDK, SDK_EVENTS } = require('fluxum-sdk-node');

const sdk = new FluxumSDK({
  apiKey: process.env.FLUXUM_API_KEY, // From .env file
  enableAnalytics: true,
});

// Your SDK code here...

Configuration Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | apiKey | string | required | Your Fluxum API key | | autoConnect | boolean | true | Automatically connect on initialization | | enableClientSideEncryption | boolean | true | Enable client-side encryption | | enableAnalytics | boolean | true | Enable comprehensive analytics tracking | | rsaKeySize | number | 2048 | RSA key size for encryption | | reconnectInterval | number | 5000 | Reconnection interval in milliseconds | | maxReconnectAttempts | number | 10 | Maximum reconnection attempts |

API Reference

Core Methods

connect()

Connect to the WebSocket server.

sdk.connect();

submitJob(jobPayload)

Submit a new job to the queue.

const jobPayload = {
  requestData: {
    method: 'POST',
    url: 'https://api.example.com/data',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer token',
    },
    body: JSON.stringify({ key: 'value' }),
  },
};

await sdk.submitJob(jobPayload);

submitJobAndWaitForResult(jobPayload, options)

Submit a job and wait for completion.

const result = await sdk.submitJobAndWaitForResult({
  requestData: {
    method: 'GET',
    url: 'https://api.example.com/data',
  },
}, {
  timeout: 30000, // 30 seconds
  onProgress: (update) => console.log('Progress:', update.status),
});

checkRateLimitStatus()

Check current rate limit status.

const status = await sdk.checkRateLimitStatus();
console.log(`Rate limited: ${status.isRateLimited}`);
console.log(`Current: ${status.currentCount}/${status.limit}`);
console.log(`Remaining: ${status.remainingRequests}`);

enableRateLimitRecovery(options)

Enable automatic rate limit recovery.

sdk.enableRateLimitRecovery({
  checkInterval: 15000, // Check every 15 seconds
  maxChecks: 8, // Check for up to 2 minutes
});

getAnalytics()

Get comprehensive analytics data.

const analytics = sdk.getAnalytics();
console.log('Analytics:', analytics);

analytics (getter)

Convenient access to analytics data.

console.log('Current analytics:', sdk.analytics);

close()

Close the WebSocket connection.

sdk.close();

Events

| Event | Description | Data | |-------|-------------|------| | authenticated | Successfully authenticated | { clientId } | | jobSubmitted | Job submitted successfully | { jobId, internalRequestId } | | jobUpdate | Job status update | JobUpdateData | | jobSubmissionError | Job submission failed | { error, jobId } | | rateLimitStatus | Rate limit status update | { isRateLimited, currentCount, limit, remainingRequests } | | rateLimitRecovered | Rate limit expired | { isRateLimited, currentCount, limit, remainingRequests } | | error | Error occurred | { type, message, originalError } |

Job Update Data Structure

{
  jobId: string,
  jobHash: string,
  status: 'progress' | 'processing' | 'completed' | 'failed',
  timestamp: string,
  targetResponse?: {
    status: number,
    headers: object,
    body: any,
  },
  sdkData: {
    sdkVersion: string,
    sdkName: string,
    wasDecrypted: boolean,
    processedAt: string,
    connectionId: string,
  },
}

Analytics

The SDK provides comprehensive analytics tracking to help you monitor performance and usage:

Getting Analytics Data

const analytics = sdk.getAnalytics();
console.log('Session duration:', analytics.session.duration);
console.log('Jobs submitted:', analytics.jobs.totalJobsSubmitted);
console.log('Success rate:', analytics.jobs.successRate);

Available Analytics Metrics

Session Statistics

• Session start time and duration
• Connection statistics (total, successful, failed)
• Average connection duration

Job Statistics

• Total jobs submitted, successful, and failed
• Rate-limited jobs count
• Average job processing time
• Jobs per minute rate
• Success rate calculation

Rate Limit Statistics

• Total rate limit events
• Recovery attempts and success rate
• Average recovery time

Performance Statistics

• Encryption/decryption attempts and success rates
• Average encryption/decryption times

Error Statistics

• Total errors and error types
• Most common error identification
• Error rate calculation

Memory Statistics

• Peak and current listener counts
• Memory cleanup operations

Analytics Example

// Enable analytics (enabled by default)
const sdk = new FluxumSDK({
  apiKey: 'your-key',
  enableAnalytics: true,
});

// After some operations, get analytics
const analytics = sdk.getAnalytics();

console.log('📊 Performance Summary:');
console.log(`Session: ${Math.round(analytics.session.duration / 1000)}s`);
console.log(`Jobs: ${analytics.jobs.totalJobsSubmitted}`);
console.log(`Success Rate: ${analytics.jobs.successRate.toFixed(1)}%`);
console.log(`Jobs/Min: ${analytics.jobs.jobsPerMinute.toFixed(2)}`);
console.log(`Avg Response: ${analytics.jobs.averageResponseTime.toFixed(0)}ms`);

Client-Side Encryption

The SDK supports client-side encryption for sensitive data:

Auto-Generated Keys

const sdk = new FluxumSDK({
  apiKey: 'your-api-key',
  enableClientSideEncryption: true,
  rsaKeySize: 2048, // Default
});

sdk.on(SDK_EVENTS.CLIENT_KEY_PAIR_GENERATED, (data) => {
  console.log('🔑 Auto-generated RSA key pair');
  console.log('Public key fingerprint:', data.publicKeyPem.substring(0, 50) + '...');
});

Using Your Own Keys

const sdk = new FluxumSDK({
  apiKey: 'your-api-key',
  enableClientSideEncryption: true,
  clientPrivateKeyPem: '-----BEGIN PRIVATE KEY-----\n...',
  clientPublicKeyPem: '-----BEGIN PUBLIC KEY-----\n...',
});

sdk.on(SDK_EVENTS.CLIENT_KEY_PAIR_LOADED, (data) => {
  console.log('🔑 Loaded client-specified RSA key pair');
});

Error Handling

The SDK provides comprehensive error handling:

sdk.on(SDK_EVENTS.ERROR, (error) => {
  console.log(`Error type: ${error.type}`);
  console.log(`Error message: ${error.message}`);
  
  switch (error.type) {
    case 'NOT_CONNECTED':
      console.log('Not connected to WebSocket server');
      break;
    case 'NOT_AUTHENTICATED':
      console.log('Not authenticated');
      break;
    case 'RATE_LIMIT_EXCEEDED':
      console.log('Rate limit exceeded');
      break;
    case 'JOB_SUBMISSION_ERROR':
      console.log('Job submission failed');
      break;
    default:
      console.log('Other error occurred');
  }
});

Examples

The SDK includes working examples in the examples/ directory:

• basic-usage.js - Basic SDK usage with rate limiting
• demo-test.js - Comprehensive demo with encryption modes
• encryption-auto-generate.js - Client-side encryption with auto-generated keys
• encryption-provide-keys.js - Client-side encryption with provided keys

Running Examples

# Set your API key
export FLUXUM_API_KEY="your-api-key-here"

# Run basic usage example
node examples/basic-usage.js

# Run demo test
node examples/demo-test.js

# Or use npm scripts
npm run example:basic
npm run example:demo
npm run example:encryption

Rate Limiting

The SDK automatically handles rate limiting:

// Enable automatic rate limit recovery
sdk.enableRateLimitRecovery({
  checkInterval: 10000, // Check every 10 seconds
  maxChecks: 6, // Check for up to 1 minute
});

// Listen for rate limit events
sdk.on('rateLimitStatus', (status) => {
  if (status.isRateLimited) {
    console.log(`Rate limited: ${status.currentCount}/${status.limit}`);
    console.log(`Remaining requests: ${status.remainingRequests}`);
  }
});

sdk.on('rateLimitRecovered', (status) => {
  console.log('Rate limit expired, resuming operations');
  console.log(`Remaining requests: ${status.remainingRequests}`);
});

License

MIT License - see LICENSE file for details.

Support

For support and questions, please contact Fluxum support or refer to the Fluxum documentation.