sauron-events

Real-time event monitoring SDK & CLI for Sauron IDE. Send events from your remote servers and see them live in Sauron's Events tab.

Install

npm install sauron-events
# or globally for CLI usage
npm install -g sauron-events

SDK Usage

import { SauronEvents } from 'sauron-events';

const sauron = new SauronEvents('ws://your-sauron-host:3001/ws?channel=events', {
  source: 'api-server',  // identifies this server in the Events tab
});

// Emit custom events
sauron.emit('user:created', { id: 1, name: 'John' });
sauron.emit('deploy:started', { version: '2.0.0' }, 'success');

// Convenience methods
sauron.log('Server started on port 8080');
sauron.warn('Memory usage at 92%');
sauron.error('Database connection failed', { code: 'ECONNREFUSED' });
sauron.success('Migration completed');

// Lifecycle events
sauron.on('connected', () => console.log('Connected to Sauron'));
sauron.on('disconnected', () => console.log('Disconnected'));

// Graceful shutdown
sauron.close();

Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | source | string | 'unknown' | Identifier shown in the Events tab | | token | string | '' | Optional auth token | | reconnect | boolean | true | Auto-reconnect on disconnect |

Severity Levels

| Level | Color | Method | |-------|-------|--------| | info | Blue | sauron.log() or sauron.emit(name, data, 'info') | | warn | Yellow | sauron.warn() | | error | Red | sauron.error() | | success | Green | sauron.success() | | debug | Gray | sauron.emit(name, data, 'debug') |

CLI Usage

# Emit a single event
sauron-events --url ws://localhost:3001/ws?channel=events --emit deploy '{"version":"2.0"}'

# Pipe application logs
node app.js 2>&1 | sauron-events --url ws://localhost:3001/ws?channel=events --pipe --source api

# Interactive mode
sauron-events --url ws://localhost:3001/ws?channel=events --watch --source my-server

CLI Options

| Flag | Description | |------|-------------| | --url <ws-url> | WebSocket URL to Sauron (required) | | --source <name> | Source identifier (defaults to hostname) | | --emit <event> [json] | Emit one event and exit | | --pipe | Read stdin line-by-line as log events | | --watch | Interactive mode | | --help | Show help |

Express Middleware Example

import { SauronEvents } from 'sauron-events';

const sauron = new SauronEvents('ws://sauron:3001/ws?channel=events', {
  source: 'express-api',
});

app.use((req, res, next) => {
  const start = Date.now();
  res.on('finish', () => {
    const ms = Date.now() - start;
    const severity = res.statusCode >= 500 ? 'error' : res.statusCode >= 400 ? 'warn' : 'info';
    sauron.emit('http:request', {
      method: req.method,
      path: req.path,
      status: res.statusCode,
      ms,
    }, severity);
  });
  next();
});

How It Works

1. Your server connects to Sauron's WebSocket as a publisher
2. Sauron's browser Events tab connects as a subscriber
3. Events flow in real-time: Server → Sauron WS Hub → Browser
4. Events are buffered when disconnected (up to 500) and sent on reconnect
5. The server keeps a ring buffer of 200 recent events for new subscribers

License

MIT