177 lines
4.0 KiB
Markdown
177 lines
4.0 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
npm install sse-client
|
|
# or
|
|
yarn add sse-client
|
|
# or
|
|
pnpm add sse-client
|
|
```
|
|
|
|
## Basic Usage
|
|
|
|
```typescript
|
|
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:
|
|
|
|
```typescript
|
|
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:
|
|
|
|
```typescript
|
|
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:
|
|
|
|
```typescript
|
|
import { setupSSECleanup } from 'sse-client';
|
|
|
|
// Call this once in your application
|
|
setupSSECleanup();
|
|
```
|
|
|
|
## Configuration Options
|
|
|
|
The `SSEClient` constructor accepts the following options:
|
|
|
|
```typescript
|
|
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:
|
|
|
|
```typescript
|
|
// 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](./PUBLISHING.md).
|
|
|
|
## License
|
|
|
|
MIT
|