@telehost/jarvis-client

Expose your Node.js app to Jarvis — the autonomous monitoring agent that watches your infrastructure and alerts you via WhatsApp when things go wrong.

What it does

Jarvis is an AI agent that polls your app every 15 minutes. If anything is off — queue backlog, dropped users, rising error rate, failed jobs — it sends you a WhatsApp message with evidence-based suggestions.

This package exposes a standardized /jarvis/health endpoint that Jarvis polls. You define what metrics to expose. The package handles auth, formatting, timeouts, and error isolation.

Installation

npm install @telehost/jarvis-client
# or
pnpm add @telehost/jarvis-client
# or
bun add @telehost/jarvis-client

Quick Start

Express

import express from 'express';
import { jarvisHealth } from '@telehost/jarvis-client/express';

const app = express();

app.get(
  '/jarvis/health',
  jarvisHealth({
    token: process.env.JARVIS_TOKEN!,
    appName: 'my-app',
    metrics: {
      users_active: async () => await User.count(),
      revenue_today: async () => await Order.sumToday(),
      queue: async () => ({
        pending: await jobQueue.count(),
        failed_1h: await jobQueue.failedInLastHour(),
      }),
    },
    alerts: {
      disk_low: async () => {
        const free = await getFreeDiskBytes();
        return free < 1_000_000_000
          ? { severity: 'critical', message: 'Less than 1GB disk free' }
          : null;
      },
    },
  })
);

Fastify

import Fastify from 'fastify';
import { jarvisPlugin } from '@telehost/jarvis-client/fastify';

const app = Fastify();

await app.register(jarvisPlugin, {
  token: process.env.JARVIS_TOKEN!,
  appName: 'my-app',
  metrics: {
    users_active: async () => await User.count(),
  },
});

Hono

import { Hono } from 'hono';
import { jarvisHandler } from '@telehost/jarvis-client/hono';

const app = new Hono();

app.get(
  '/jarvis/health',
  jarvisHandler({
    token: process.env.JARVIS_TOKEN!,
    appName: 'my-app',
    metrics: {
      users_active: async () => await User.count(),
    },
  })
);

Any other framework (manual)

import { JarvisManager, extractAndValidateToken } from '@telehost/jarvis-client';

const jarvis = new JarvisManager({
  appName: 'my-app',
  metrics: {
    users_active: async () => await User.count(),
  },
});

// In your route handler:
async function healthHandler(req, res) {
  const auth = extractAndValidateToken(
    req.headers.authorization,
    req.headers['x-jarvis-token'],
    process.env.JARVIS_TOKEN!
  );
  if (!auth.valid) return res.status(401).json({ error: 'unauthorized' });

  const payload = await jarvis.buildPayload();
  res.json(payload);
}

Setup in 3 steps

1. Get your token from https://jarvis.telehost.net/dashboard
2. Set JARVIS_TOKEN=jrv_app_abc123... in your .env
3. Add the adapter to your app (see examples above)

Verify:

curl -H "Authorization: Bearer $JARVIS_TOKEN" http://localhost:3000/jarvis/health

Response:

{
  "app": "my-app",
  "version": "1.0",
  "timestamp": "2026-04-19T14:30:00Z",
  "status": "healthy",
  "metrics": {
    "users_active": 1247,
    "revenue_today": 82340.50,
    "queue": { "pending": 3, "failed_1h": 0 }
  },
  "alerts": [],
  "custom": {}
}

What your closures can return

Metrics

• Scalars: number, string, boolean
• Objects (for grouped metrics):

  queue: async () => ({
    pending: 5,
    failed_1h: 0,
    by_type: { email: 2, webhook: 3 },
  })

• null (metric skipped this cycle)

Alerts

// Alert triggered
return { severity: 'info' | 'warning' | 'critical', message: 'Human-readable' };

// No alert
return null;

Features

• Error isolation: one failing metric doesn't break the payload
• Timeout protection: metrics that take too long are cancelled (default 5s, configurable)
• Timing-safe auth: resistant to timing attacks on the bearer token
• Zero peer dependencies: works with any Node.js HTTP framework
• First-class TypeScript: fully typed, strict mode friendly
• Tiny: <5KB gzipped

Configuration

new JarvisManager({
  appName: 'my-app',       // Name shown in Jarvis alerts
  appVersion: '1.2.3',     // Reported in payload
  metrics: { /* ... */ },
  alerts: { /* ... */ },
  custom: { /* ... */ },
  metricTimeoutMs: 5000,   // Max time per metric (default)
});

Why WhatsApp?

Because you don't have Slack open at 3am when your queue is backed up. You have WhatsApp.

License

MIT © TeleHost C.A.

Related

• telehost/jarvis-client (Laravel version, same contract)
• jarvis.telehost.net (dashboard)