pulsewatch-server

Complete uptime monitoring server - Drop-in Express backend with monitoring engine, database, REST API, and real-time updates. No authentication required - integrate your own!

🎯 One Complete Package

This package combines everything you need for uptime monitoring:

• ✅ Monitoring Engine - 8 monitor types (HTTP, TCP, DNS, Ping, WebSocket, Keyword, JSON Query, Push)
• ✅ Express Backend - Complete REST API
• ✅ Database Schema - Drizzle ORM ready
• ✅ Real-time Updates - Socket.IO integration
• ✅ No Authentication - Use your own auth system

📦 Installation

npm install pulsewatch-server

Peer Dependencies

npm install express socket.io drizzle-orm pg

🚀 Quick Start

import express from "express";
import { createPulseWatch, createDatabase } from "pulsewatch-server";
import * as schema from "pulsewatch-server/database";

const app = express();

// Create database connection
const { db } = createDatabase({
  connectionString: process.env.DATABASE_URL,
});

// Create PulseWatch server
const pulsewatch = createPulseWatch({ app, db, schema });

// Start monitoring
await pulsewatch.start();

// Start HTTP server
pulsewatch.httpServer.listen(3000, () => {
  console.log("Server running on port 3000");
});

That's it! You now have a complete monitoring system with:

• REST API at /api/monitors
• Push endpoints at /api/push/:token
• Real-time updates via WebSocket at /ws

📊 Monitor Types

1. HTTP/HTTPS

{
  name: "My API",
  type: "http",
  url: "https://api.example.com",
  method: "GET",
  intervalSeconds: 60
}

2. TCP Port

{
  name: "Database",
  type: "tcp",
  host: "db.example.com",
  port: 5432
}

3. DNS

{
  name: "DNS Check",
  type: "dns",
  host: "example.com",
  dnsRecordType: "A"
}

4. Ping

{
  name: "Server Ping",
  type: "ping",
  host: "example.com"
}

5. WebSocket

{
  name: "WebSocket",
  type: "websocket",
  url: "wss://example.com/socket"
}

6. Keyword Search

{
  name: "Homepage Check",
  type: "keyword",
  url: "https://example.com",
  keyword: "Welcome"
}

7. JSON Query

{
  name: "API Health",
  type: "json_query",
  url: "https://api.example.com/health",
  jsonQuery: "$.status",
  expectedValue: "healthy"
}

8. Push (Heartbeat)

{
  name: "Cron Job",
  type: "push",
  intervalSeconds: 300
}

Then send heartbeats:

curl https://your-server.com/api/push/YOUR_TOKEN

🔌 API Endpoints

Once integrated, these endpoints are available:

GET    /api/monitors              - List all monitors
GET    /api/monitors/summary      - Get monitors with uptime stats
POST   /api/monitors              - Create monitor
PUT    /api/monitors/:id          - Update monitor
DELETE /api/monitors/:id          - Delete monitor
POST   /api/monitors/:id/pause    - Pause/unpause monitor
POST   /api/monitors/:id/clone    - Clone monitor
GET    /api/monitors/:id/results  - Get check results
POST   /api/push/:token           - Receive heartbeat
GET    /api/push/:token           - Receive heartbeat (GET)
GET    /api/health                - Health check

🔄 Real-time Updates

Listen for monitor updates via Socket.IO:

import { io } from "socket.io-client";

const socket = io("http://localhost:3000", {
  path: "/ws",
});

socket.on("monitor:update", (data) => {
  console.log("Monitor update:", data);
  // {
  //   monitorId: '123',
  //   status: 'up',
  //   message: 'OK',
  //   pingMs: 145,
  //   httpStatus: 200,
  //   checkedAt: '2026-01-30T12:00:00.000Z'
  // }
});

💾 Database

The package includes a complete Drizzle ORM schema:

import * as schema from "pulsewatch-server/database";

// Tables included:
// - monitors
// - monitorResults
// - proxies
// - notifications
// - monitorNotifications
// - statusPages
// - statusPageMonitors

Run Migrations

# Install drizzle-kit
npm install -D drizzle-kit

# Generate migrations
npx drizzle-kit generate

# Push to database
npx drizzle-kit push

🔐 Adding Authentication

The package doesn't include authentication - add your own:

import express from "express";
import { createPulseWatch } from "pulsewatch-server";

const app = express();

// Your auth middleware
function authMiddleware(req, res, next) {
  // Check JWT, session, API key, etc.
  if (!req.headers.authorization) {
    return res.status(401).json({ error: "Unauthorized" });
  }
  next();
}

// Protect all API routes
app.use("/api", authMiddleware);

// Add PulseWatch (now protected by your auth)
const pulsewatch = createPulseWatch({ app, db, schema });

⚙️ Configuration

Full Configuration

const pulsewatch = createPulseWatch({
  app, // Express app
  db, // Drizzle database instance
  schema: {
    // Database schema
    monitors,
    monitorResults,
    proxies,
    notifications,
    monitorNotifications,
  },
  socketIO: {
    // Optional Socket.IO config
    cors: { origin: "*" },
    path: "/ws",
  },
  logger: {
    // Optional logger
    error: (err, msg) => console.error(msg, err),
    warn: (msg) => console.warn(msg),
    info: (msg) => console.log(msg),
  },
});

🎯 Advanced Usage

Use Check Functions Directly

import { checkHttp, checkTcp } from "pulsewatch-server";

// Run checks manually
const result = await checkHttp({
  type: "http",
  url: "https://example.com",
  timeoutMs: 5000,
});

console.log(result);
// { status: 'up', message: 'OK', pingMs: 123, httpStatus: 200 }

Custom Routes

import {
  createMonitorsRouter,
  createPushRouter,
} from "pulsewatch-server/routes";

// Create routes separately
const monitorsRouter = createMonitorsRouter({ db, schema, runner });
const pushRouter = createPushRouter({ runner });

// Mount with custom paths
app.use("/monitoring/monitors", monitorsRouter);
app.use("/monitoring/push", pushRouter);

Use MonitorRunner Directly

import { MonitorRunner } from "pulsewatch-server";
import { eq, desc, inArray } from "drizzle-orm";

const runner = new MonitorRunner({
  io,
  db,
  schema,
  orm: { eq, desc, inArray },
  logger: console,
});

await runner.start();

📝 Complete Example

import express from "express";
import { createPulseWatch, createDatabase } from "pulsewatch-server";
import * as schema from "pulsewatch-server/database";

const app = express();

// Create database
const { db, pool } = createDatabase({
  connectionString: process.env.DATABASE_URL,
  max: 20,
});

// Create PulseWatch
const pulsewatch = createPulseWatch({
  app,
  db,
  schema,
  socketIO: {
    cors: { origin: process.env.FRONTEND_URL },
    path: "/ws",
  },
  logger: console,
});

// Start monitoring
await pulsewatch.start();

// Start server
const PORT = process.env.PORT || 3000;
pulsewatch.httpServer.listen(PORT, () => {
  console.log(`PulseWatch running on port ${PORT}`);
});

// Graceful shutdown
process.on("SIGTERM", () => {
  pulsewatch.stop();
  pool.end();
  process.exit(0);
});

🌟 Features

• ✅ 8 Monitor Types - HTTP, TCP, DNS, Ping, WebSocket, Keyword, JSON Query, Push
• ✅ Real-time Updates - Socket.IO for live monitoring
• ✅ Database Included - Complete Drizzle ORM schema
• ✅ REST API - Full CRUD for monitors
• ✅ No Auth Required - Integrate your own authentication
• ✅ TypeScript - Full type definitions
• ✅ Lightweight - Minimal dependencies
• ✅ Flexible - Use as-is or customize

📦 Exports

// Main server
export { createPulseWatch, type PulseWatchConfig, type PulseWatchServer };

// Database
export { createDatabase, type DatabaseConfig };
export * from "./database/schema";

// Routes
export { createMonitorsRouter, createPushRouter };

// Monitor checks
export {
  checkHttp,
  checkTcp,
  checkDns,
  checkPing,
  checkWebsocket,
  checkKeyword,
  checkJsonQuery,
};

// MonitorRunner
export { MonitorRunner, type MonitorRunnerConfig };

// Types
export type { Monitor, Proxy, CheckResult, MonitorType, MonitorStatus };

🔧 Environment Variables

DATABASE_URL=postgresql://user:password@localhost:5432/pulsewatch
PORT=3000

📄 License

MIT

🤝 Support

For issues and questions, visit GitHub Issues.

Made with ❤️ by Abishek