# Node.js Example | Stream API

> Node.js code example demonstrating how to connect to the real-time SEC filings Stream API using socket.io. The example prints new filings in real-time to your console.

Source: https://sec-api.io/docs/stream-api/node-js-example

This guide illustrates how to use Node.js and WebSocket for streaming SEC filings in real-time, immediately after their publication on EDGAR. You'll learn to connect to the Stream API and display filing metadata - such as filing ID, CIK of the filer, form type, the acceptance date/time by the EDGAR system, and the filing URL - as soon as a filing is released.

First, install the [WebSocket ws package](https://www.npmjs.com/package/ws) for Node.js by running the following command in your terminal:

`npm install ws`

Next, copy the example code provided below into a new file on your machine, naming it `websocket-client.js`. Ensure to replace `YOUR_API_KEY` with the actual API key from your account.

Node.js

```javascript
const WebSocket = require('ws');

const API_KEY = 'YOUR_API'; // Replace this with your actual API key
const STREAM_API_URL = 'wss://stream.sec-api.io?apiKey=' + API_KEY;

const ws = new WebSocket(STREAM_API_URL);

ws.on('open', () => console.log('✅ Connected to:', STREAM_API_URL));
ws.on('close', () => console.log('Connection closed'));
ws.on('error', (err) => console.log('Error:', err.message));

ws.on('message', (message) => {
  const filings = JSON.parse(message.toString());
  filings.forEach((filing) => {
    console.log(
      filing.id,
      filing.cik,
      filing.formType,
      filing.filedAt,
      filing.linkToFilingDetails,
    );
  });
});
```

To initiate the connection and start receiving new filings, enter the following command in your terminal:

`node websocket-client.js`

By following these steps, you'll set up a real-time stream of SEC filings, directly accessible from your terminal.

## Advanced Example: Auto-Reconnect, Heartbeats, and Keep-Alives

This advanced Node.js code sample introduces a robust reconnection mechanism. It enables the client to monitor the connection status actively and perform an automatic reconnection if the connection drops. The strategy involves dispatching a heartbeat ping to the server at 30-second intervals, awaiting a pong response. Should the server fail to reply within a 5-second window, the client terminates the current connection and initiates a new connection process, thereby maintaining continuous connectivity.

Node.js

```javascript
const WebSocket = require('ws');

const API_KEY = 'YOUR_API_KEY'; // Replace this with your actual API key
const STREAM_API_URL = 'wss://stream.sec-api.io?apiKey=' + API_KEY;

let connectionAttempts = 0;
const maxConnectionAttempts = 4;

function connect() {
  const ws = new WebSocket(STREAM_API_URL);

  let pingTimeout = null;
  let heartbeatInterval = null;

  const heartbeat = () => {
    clearTimeout(pingTimeout);

    // Terminate connection if pong is not received within 5 seconds
    pingTimeout = setTimeout(() => {
      console.log('Pong not received, terminating connection...');
      ws.terminate();
    }, 5000);

    // Send a ping every 30 seconds
    ws.ping();
  };

  ws.on('open', () => {
    console.log('✅ Connected to:', STREAM_API_URL);
    connectionAttempts = 0; // Reset connection attempts on successful connection
    heartbeat(); // Initiate the heartbeat process
    // Ensure heartbeat continues, so setup interval right after connection
    heartbeatInterval = setInterval(heartbeat, 30000);
  });

  ws.on('pong', () => {
    console.log('Pong received');
    clearTimeout(pingTimeout); // Clear the pong wait timeout
  });

  ws.on('close', () => {
    console.log('Connection closed');
    clearTimeout(pingTimeout);
    clearInterval(heartbeatInterval);
    attemptReconnect();
  });

  ws.on('error', (err) => {
    console.log('Error:', err.message);
    clearTimeout(pingTimeout);
    clearInterval(heartbeatInterval);
  });

  ws.on('message', (message) => {
    const filings = JSON.parse(message.toString());
    filings.forEach((filing) => {
      console.log(
        filing.id,
        filing.cik,
        filing.formType,
        filing.filedAt,
        filing.linkToFilingDetails,
      );
    });
  });
}

function attemptReconnect() {
  if (connectionAttempts < maxConnectionAttempts) {
    connectionAttempts++;
    console.log(`Attempt ${connectionAttempts} to reconnect...`);
    setTimeout(connect, 1000 * connectionAttempts); // Exponential back-off
  } else {
    console.log('Max reconnection attempts reached. Giving up.');
  }
}

connect();
```