SSE Client

A custom SSE (Server-Sent Events) client that supports headers and bypasses certificate issues. This package provides a robust implementation for connecting to SSE endpoints with features like:

Custom headers support
SSL certificate validation bypass
Automatic reconnection with exponential backoff
Connection management
Event handling
TypeScript support

Installation

npm install sse-client
# or
yarn add sse-client
# or
pnpm add sse-client

Basic Usage

import { SSEClient } from 'sse-client';

// Create a new SSE client
const client = new SSEClient('https://api.example.com/events', {
  headers: {
    'Authorization': 'Bearer token123',
    'X-Custom-Header': 'value'
  },
  debug: true // Enable debug logging
});

// Listen for events
client.on('message', (event) => {
  console.log('Received message:', event.parsedData);
});

// Connect to the SSE endpoint
client.connect();

// Later, when you're done
client.close();

SSL Certificate Bypass

In Node.js environments, you can bypass SSL certificate validation:

import { SSEClient } from 'sse-client';

// Create a new SSE client with SSL certificate validation bypass
const client = new SSEClient('https://api.example.com/events', {
  headers: {
    'Authorization': 'Bearer token123'
  },
  skipSSLValidation: true, // Bypass SSL certificate validation
  debug: true
});

client.on('message', (event) => {
  console.log('Received message:', event.parsedData);
});

client.connect();

This is particularly useful for development environments or when dealing with self-signed certificates.

Connection Management

The package includes a connection manager for handling multiple SSE connections:

import { getSSEConnection, closeSSEConnection, closeAllSSEConnections } from 'sse-client';

// Get or create a connection
const client = getSSEConnection(
  'https://api.example.com/events/orders/123',
  'order-123', // Unique ID for this connection
  {
    headers: {
      'Authorization': 'Bearer token123'
    }
  }
);

// Listen for events
client.on('orderStateChanged', (event) => {
  console.log('Order state changed:', event.parsedData);
});

// Close a specific connection
closeSSEConnection('order-123');

// Close all connections
closeAllSSEConnections();

Automatic Cleanup

You can set up automatic cleanup of all SSE connections when the page is unloaded:

import { setupSSECleanup } from 'sse-client';

// Call this once in your application
setupSSECleanup();

Configuration Options

The SSEClient constructor accepts the following options:

interface SSEClientOptions {
  // Headers to include in the SSE request
  headers?: Record<string, string>;

  // Whether to include credentials in the request (default: true)
  withCredentials?: boolean;

  // Timeout for heartbeat in milliseconds (default: 21600000 - 6 hours)
  heartbeatTimeout?: number;

  // Maximum number of retry attempts (default: 10)
  maxRetryAttempts?: number;

  // Initial delay for retry in milliseconds (default: 1000)
  initialRetryDelay?: number;

  // Maximum delay for retry in milliseconds (default: 30000)
  maxRetryDelay?: number;

  // Whether to automatically reconnect on error (default: true)
  autoReconnect?: boolean;

  // Debug mode (default: false)
  debug?: boolean;

  // Whether to bypass SSL certificate validation (default: false)
  // Only works in Node.js environments
  skipSSLValidation?: boolean;
}

Event Handling

The SSE client provides methods for handling events:

// Add an event listener
client.on('eventName', (event) => {
  console.log('Event received:', event);
});

// Remove a specific event listener
client.off('eventName', listener);

// Remove all listeners for an event
client.removeAllListeners('eventName');

// Remove all listeners for all events
client.removeAllListeners();

Building and Publishing

For instructions on how to build and publish this package to the Generation One Gitea repository, see PUBLISHING.md.

License

MIT

4.0 KiB Raw Blame History