Skip to Content
UptimeBeacon 1.0 is released 🎉
API Reference

API Reference

Complete reference for all classes, methods, and types available in Sentinel Guard.

SentinelGuard Class

The main class for monitoring and heartbeat functionality.

Constructor

new SentinelGuard(config: SentinelGuardConfig)

Creates a new SentinelGuard instance with the specified configuration.

Parameters:

  • config - Configuration object containing API credentials and settings

Example:

const sentinel = new SentinelGuard({
	apiKey: process.env.SENTINEL_API_KEY!,
	baseUrl: process.env.SENTINEL_API_URL!,
	monitorApiKey: process.env.SENTINEL_MONITOR_API_KEY!,
	timeout: 10000,
});

Methods

startMonitoring()

startMonitoring(config: HeartbeatConfig): void

Starts automatic heartbeat monitoring with the specified configuration.

Parameters:

  • config.interval - Heartbeat interval in milliseconds (minimum: 5000)
  • config.maxConsecutiveErrors - Maximum consecutive errors before stopping (optional, default: 5)

Example:

sentinel.startMonitoring({
	interval: 30000,
	maxConsecutiveErrors: 5,
});

stopMonitoring()

stopMonitoring(): void

Stops automatic heartbeat monitoring and clears the interval timer.

Example:

sentinel.stopMonitoring();

sendHeartbeat()

sendHeartbeat(data: Partial<HeartbeatData>): Promise<HeartbeatResponse>

Sends a manual heartbeat to the monitoring service.

Parameters:

  • data.status - Application status (“ONLINE” | “OFFLINE” | “ERROR” | “HIGH_LATENCY”)
  • data.metadata - Additional metadata to include (optional)

Returns:

  • Promise resolving to HeartbeatResponse object

Example:

const response = await sentinel.sendHeartbeat({
	status: "ONLINE",
	metadata: {
		service: "my-app",
		version: "1.0.0",
		environment: "production",
	},
});
 
if (response.success) {
	console.log("Heartbeat sent successfully");
} else {
	console.error("Heartbeat failed:", response.error);
}

isMonitoringActive()

isMonitoringActive(): boolean

Returns whether automatic monitoring is currently active.

Returns:

  • true if monitoring is active, false otherwise

Example:

const isActive = sentinel.isMonitoringActive();
console.log("Monitoring active:", isActive);

getErrorCount()

getErrorCount(): number

Returns the current consecutive error count.

Returns:

  • Number of consecutive errors

Example:

const errorCount = sentinel.getErrorCount();
console.log("Error count:", errorCount);

setPrismaClient()

setPrismaClient(client: PrismaClientLike): void

Sets a Prisma client for database latency monitoring.

Parameters:

  • client - Prisma client instance

Example:

import { PrismaClient } from "@prisma/client";
 
const prisma = new PrismaClient();
sentinel.setPrismaClient(prisma);

setRedisClient()

setRedisClient(client: RedisClientLike): void

Sets a Redis client for cache latency monitoring.

Parameters:

  • client - Redis client instance

Example:

import { createClient } from "redis";
 
const redis = createClient();
await redis.connect();
sentinel.setRedisClient(redis);

destroy()

destroy(): void

Cleans up resources and stops all monitoring activities.

Example:

sentinel.destroy();

Interfaces

SentinelGuardConfig

Configuration object for SentinelGuard initialization.

interface SentinelGuardConfig {
	apiKey: string;
	baseUrl: string;
	monitorApiKey: string;
	timeout?: number;
	retryConfig?: RetryConfig;
}

Properties:

  • apiKey - Your UptimeBeacon.cloud API key
  • baseUrl - API base URL (typically “https://api.uptimebeacon.cloud ”)
  • monitorApiKey - Monitor-specific API key
  • timeout - Request timeout in milliseconds (optional, default: 10000)
  • retryConfig - Retry configuration (optional)

RetryConfig

Configuration for automatic retry behavior.

interface RetryConfig {
	maxRetries: number;
	baseDelay: number;
	backoffMultiplier: number;
}

Properties:

  • maxRetries - Maximum number of retry attempts
  • baseDelay - Base delay between retries in milliseconds
  • backoffMultiplier - Exponential backoff multiplier

HeartbeatConfig

Configuration for automatic heartbeat monitoring.

interface HeartbeatConfig {
	interval: number;
	maxConsecutiveErrors?: number;
}

Properties:

  • interval - Heartbeat interval in milliseconds
  • maxConsecutiveErrors - Maximum consecutive errors before stopping (optional, default: 5)

HeartbeatData

Data structure for heartbeat payloads.

interface HeartbeatData {
	status: "ONLINE" | "OFFLINE" | "ERROR" | "HIGH_LATENCY";
	type: "CUSTOM";
	latencyMs?: number;
	performance?: PerformanceMetrics;
	metadata?: Record<string, unknown>;
}

Properties:

  • status - Current application status
  • type - Heartbeat type (always “CUSTOM”)
  • latencyMs - Service latency in milliseconds (optional)
  • performance - Performance metrics (optional)
  • metadata - Additional metadata (optional)

PerformanceMetrics

Performance data included in heartbeats.

interface PerformanceMetrics {
	serviceLatency: number;
	prismaLatency?: number;
	redisLatency?: number;
	timestamp: string;
}

Properties:

  • serviceLatency - Service response time in milliseconds
  • prismaLatency - Database query latency in milliseconds (optional)
  • redisLatency - Redis operation latency in milliseconds (optional)
  • timestamp - ISO 8601 timestamp of measurement

HeartbeatResponse

Response object from heartbeat operations.

interface HeartbeatResponse {
	success: boolean;
	timestamp: string;
	message?: string;
}

Properties:

  • success - Whether the heartbeat was successful
  • timestamp - ISO 8601 timestamp of the response
  • message - Optional response message

ApiResponse

Generic API response wrapper.

interface ApiResponse<T = unknown> {
	success: boolean;
	data?: T;
	error?: string;
	timestamp: string;
}

Properties:

  • success - Whether the request was successful
  • data - Response data (optional)
  • error - Error message if unsuccessful (optional)
  • timestamp - ISO 8601 timestamp of the response

PrismaClientLike

Interface for Prisma client compatibility.

interface PrismaClientLike {
	$queryRaw: (
		query: TemplateStringsArray,
		...values: unknown[]
	) => Promise<unknown>;
}

Properties:

  • $queryRaw - Method for executing raw database queries

RedisClientLike

Interface for Redis client compatibility.

interface RedisClientLike {
	ping: () => Promise<string>;
}

Properties:

  • ping - Method for testing Redis connection

Error Classes

SentinelGuardError

Base error class for all Sentinel Guard errors.

class SentinelGuardError extends Error {
	constructor(message: string, statusCode?: number);
}

Properties:

  • message - Error message
  • statusCode - HTTP status code (optional)

NetworkError

Error thrown for network-related issues.

class NetworkError extends SentinelGuardError {
	constructor(message: string, originalError?: Error);
}

Properties:

  • message - Error message
  • originalError - Original error that caused the network error (optional)

AuthenticationError

Error thrown for authentication failures.

class AuthenticationError extends SentinelGuardError {
	constructor(message?: string);
}

Properties:

  • message - Error message (default: “Authentication failed”)
  • statusCode - Always 401

RateLimitError

Error thrown when rate limits are exceeded.

class RateLimitError extends SentinelGuardError {
	constructor(message?: string);
}

Properties:

  • message - Error message (default: “Rate limit exceeded”)
  • statusCode - Always 429

Usage Examples

Basic Usage

import { SentinelGuard } from "@uptimebeacon/sentinel-guard";
 
const sentinel = new SentinelGuard({
	apiKey: process.env.SENTINEL_API_KEY!,
	baseUrl: process.env.SENTINEL_API_URL!,
	monitorApiKey: process.env.SENTINEL_MONITOR_API_KEY!,
});
 
sentinel.startMonitoring({
	interval: 30000,
	maxConsecutiveErrors: 5,
});

Error Handling

import {
	SentinelGuard,
	NetworkError,
	AuthenticationError,
	RateLimitError,
} from "@uptimebeacon/sentinel-guard";
 
try {
	const response = await sentinel.sendHeartbeat({
		status: "ONLINE",
	});
} catch (error) {
	if (error instanceof AuthenticationError) {
		console.error("Authentication failed - check your API keys");
	} else if (error instanceof NetworkError) {
		console.error("Network error - check your connection");
	} else if (error instanceof RateLimitError) {
		console.error("Rate limit exceeded - slow down requests");
	} else {
		console.error("Unknown error:", error);
	}
}

Advanced Configuration

const sentinel = new SentinelGuard({
	apiKey: process.env.SENTINEL_API_KEY!,
	baseUrl: process.env.SENTINEL_API_URL!,
	monitorApiKey: process.env.SENTINEL_MONITOR_API_KEY!,
	timeout: 15000,
	retryConfig: {
		maxRetries: 5,
		baseDelay: 2000,
		backoffMultiplier: 2,
	},
});
 
// Set up database monitoring
const prisma = new PrismaClient();
const redis = createClient();
await redis.connect();
 
sentinel.setPrismaClient(prisma);
sentinel.setRedisClient(redis);
 
// Start monitoring with custom configuration
sentinel.startMonitoring({
	interval: 45000,
	maxConsecutiveErrors: 3,
});

Graceful Shutdown

process.on("SIGINT", () => {
	console.log("Shutting down...");
	sentinel.stopMonitoring();
	sentinel.destroy();
	process.exit(0);
});

Type Exports

All types are exported from the main module:

import type {
	SentinelGuardConfig,
	HeartbeatConfig,
	HeartbeatData,
	PerformanceMetrics,
	HeartbeatResponse,
	ApiResponse,
	PrismaClientLike,
	RedisClientLike,
	RetryConfig,
} from "@uptimebeacon/sentinel-guard";
ConfigurationPerformance Monitoring