@firebreak/vitals 1.0.2 → 1.0.3

package/README.md

@@ -1,11 +1,11 @@
 # Vitals (Node.js)
 
-Structured deep healthcheck endpoints for Node.js services. Register health checks, run them concurrently with timeouts, and expose them via Express.
+Structured deep healthcheck endpoints for Node.js services. Register health checks, run them concurrently with timeouts, and expose them via Express or Next.js.
 
 ## Install
 
 ```bash
-npm install vitals
+npm install @firebreak/vitals
 ```
 
 Peer dependencies are optional — install only what you need:
@@ -16,40 +16,51 @@ npm install ioredis   # for Redis checks
 npm install express   # for Express integration
 ```
 
-## Quick Start
+## Quick Start (Express)
 
 ```typescript
-import { HealthcheckRegistry, Status } from 'vitals';
-import { createHealthcheckMiddleware } from 'vitals/express';
-import { pgPoolCheck } from 'vitals/checks/postgres';
-import { ioredisClientCheck } from 'vitals/checks/redis';
+import { HealthcheckRegistry } from '@firebreak/vitals';
+import { createHealthcheckMiddleware } from '@firebreak/vitals/express';
+import { pgPoolCheck } from '@firebreak/vitals/checks/postgres';
+import { ioredisClientCheck } from '@firebreak/vitals/checks/redis';
+import { httpCheck } from '@firebreak/vitals/checks/http';
 import express from 'express';
 
 const registry = new HealthcheckRegistry({ defaultTimeout: 5000 });
 
-// Add checks using an existing connection pool / client
 registry.add('postgres', pgPoolCheck(pool));
 registry.add('redis', ioredisClientCheck(redisClient));
+registry.add('api', httpCheck('https://api.example.com/health'));
 
-// Or add a custom check
-registry.add('api', async () => {
-  const start = Date.now();
-  const res = await fetch('https://api.example.com/ping');
-  return {
-    status: res.ok ? Status.HEALTHY : Status.OUTAGE,
-    latencyMs: Date.now() - start,
-    message: res.ok ? '' : `HTTP ${res.status}`,
-  };
-});
-
-// Mount as Express middleware
 const app = express();
-app.get('/healthcheck/deep', createHealthcheckMiddleware({
+app.get('/vitals', createHealthcheckMiddleware({
   registry,
-  token: process.env.HEALTHCHECK_TOKEN,
+  token: process.env.VITALS_TOKEN,
 }));
 ```
 
+## Quick Start (Next.js)
+
+```typescript
+// app/vitals/route.ts
+import { HealthcheckRegistry } from '@firebreak/vitals';
+import { createNextHandler } from '@firebreak/vitals/next';
+import { pgClientCheck } from '@firebreak/vitals/checks/postgres';
+import { httpCheck } from '@firebreak/vitals/checks/http';
+
+const registry = new HealthcheckRegistry({ defaultTimeout: 5000 });
+
+if (process.env.DATABASE_URL) {
+  registry.add('postgres', pgClientCheck(process.env.DATABASE_URL));
+}
+registry.add('api', httpCheck(`${process.env.API_BASE_URL}/health`));
+
+export const GET = createNextHandler({
+  registry,
+  token: process.env.VITALS_TOKEN,
+});
+```
+
 ## API
 
 ### `HealthcheckRegistry`
@@ -65,18 +76,19 @@ Register a named async check function. Options: `{ timeout?: number }`.
 ```typescript
 registry.add('service', async () => ({
   status: Status.HEALTHY,
-  latencyMs: 0,
   message: '',
 }), { timeout: 3000 });
 ```
 
+Check functions return a `CheckInput` with `status` and `message`. The `latencyMs` field is optional — the registry measures wall-clock latency automatically using `performance.now()`.
+
 **`registry.check(name, checkFn?, options?)`**
 
 Decorator-style registration. Can be used as a method decorator or called directly.
 
 **`registry.run()`**
 
-Execute all registered checks concurrently. Returns a `HealthcheckResponse` with the worst overall status.
+Execute all registered checks concurrently. Returns a `HealthcheckResponse` with the worst overall status and registry-measured latency for each check.
 
 ```typescript
 const response = await registry.run();
@@ -89,7 +101,7 @@ const json = toJson(response);
 ### Status
 
 ```typescript
-import { Status, statusToLabel, statusFromString, httpStatusCode } from 'vitals';
+import { Status, statusToLabel, statusFromString, httpStatusCode } from '@firebreak/vitals';
 
 Status.HEALTHY  // 2
 Status.DEGRADED // 1
@@ -103,10 +115,26 @@ httpStatusCode(Status.OUTAGE)  // 503
 
 ### Built-in Checks
 
+#### HTTP
+
+```typescript
+import { httpCheck } from '@firebreak/vitals/checks/http';
+
+// Basic URL check — returns HEALTHY if response is 2xx
+registry.add('api', httpCheck('https://api.example.com/health'));
+
+// With options
+registry.add('api', httpCheck('https://api.example.com/health', {
+  method: 'HEAD',
+  headers: { 'X-Api-Key': 'secret' },
+  timeout: 3000, // default: 5000ms
+}));
+```
+
 #### PostgreSQL
 
 ```typescript
-import { pgClientCheck, pgPoolCheck } from 'vitals/checks/postgres';
+import { pgClientCheck, pgPoolCheck } from '@firebreak/vitals/checks/postgres';
 
 // Fresh connection each time (good for validating connectivity)
 registry.add('pg', pgClientCheck('postgresql://localhost:5432/mydb'));
@@ -118,7 +146,7 @@ registry.add('pg', pgPoolCheck(pool));
 #### Redis
 
 ```typescript
-import { ioredisCheck, ioredisClientCheck } from 'vitals/checks/redis';
+import { ioredisCheck, ioredisClientCheck } from '@firebreak/vitals/checks/redis';
 
 // Fresh connection each time
 registry.add('redis', ioredisCheck('redis://localhost:6379'));
@@ -127,48 +155,89 @@ registry.add('redis', ioredisCheck('redis://localhost:6379'));
 registry.add('redis', ioredisClientCheck(client));
 ```
 
+### Custom Checks
+
+Check functions only need to return `status` and `message`. The registry measures latency automatically:
+
+```typescript
+registry.add('databricks', async () => {
+  try {
+    await databricksService.query('SELECT 1');
+    return { status: Status.HEALTHY, message: '' };
+  } catch (error) {
+    return { status: Status.OUTAGE, message: error.message };
+  }
+});
+```
+
 ### Sync Checks
 
 Wrap synchronous functions to use as health checks:
 
 ```typescript
-import { syncCheck, Status } from 'vitals';
-
-registry.add('disk', syncCheck(() => {
-  const free = checkDiskSpace('/');
-  return {
-    status: free > 1_000_000_000 ? Status.HEALTHY : Status.DEGRADED,
-    latencyMs: 0,
-    message: `${free} bytes free`,
-  };
-}));
+import { syncCheck, Status } from '@firebreak/vitals';
+
+registry.add('disk', syncCheck(() => ({
+  status: checkDiskSpace('/') > 1_000_000_000 ? Status.HEALTHY : Status.DEGRADED,
+  message: '',
+})));
 ```
 
-### Express Integration
+### Framework Integrations
+
+#### Express
 
 ```typescript
-import { createHealthcheckMiddleware } from 'vitals/express';
+import { createHealthcheckMiddleware } from '@firebreak/vitals/express';
 
-app.get('/healthcheck/deep', createHealthcheckMiddleware({
+app.get('/vitals', createHealthcheckMiddleware({
   registry,
   token: 'my-secret-token',   // optional — omit to disable auth
   queryParamName: 'token',     // default: 'token'
 }));
 ```
 
+#### Next.js (App Router)
+
+```typescript
+import { createNextHandler } from '@firebreak/vitals/next';
+
+export const GET = createNextHandler({
+  registry,
+  token: process.env.VITALS_TOKEN,
+});
+```
+
+#### Framework-Agnostic Handler
+
+For other frameworks, use the generic handler directly:
+
+```typescript
+import { createHealthcheckHandler } from '@firebreak/vitals';
+
+const handle = createHealthcheckHandler({ registry, token: process.env.VITALS_TOKEN });
+
+// In any framework:
+const result = await handle({
+  queryParams: { token: 'abc' },
+  authorizationHeader: 'Bearer abc',
+});
+// result = { status: 200, body: { status: 'healthy', ... } }
+```
+
+### Authentication
+
 When a token is configured, requests must provide it via:
 - Query parameter: `?token=my-secret-token`
 - Bearer header: `Authorization: Bearer my-secret-token`
 
-### Authentication
+Tokens are compared using timing-safe SHA-256 comparison.
 
 ```typescript
-import { verifyToken, extractToken } from 'vitals';
+import { verifyToken, extractToken } from '@firebreak/vitals';
 
-// Timing-safe token comparison
 verifyToken('provided-token', 'expected-token'); // boolean
 
-// Extract token from request
 const token = extractToken({
   queryParams: { token: 'abc' },
   authorizationHeader: 'Bearer abc',
@@ -185,12 +254,12 @@ const token = extractToken({
   "checks": {
     "postgres": {
       "status": "healthy",
-      "latencyMs": 4.2,
+      "latencyMs": 4,
       "message": ""
     },
     "redis": {
       "status": "healthy",
-      "latencyMs": 1.1,
+      "latencyMs": 1,
       "message": ""
     }
   }

package/dist/checks/http.cjs

@@ -0,0 +1,63 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/checks/http.ts
+var http_exports = {};
+__export(http_exports, {
+  httpCheck: () => httpCheck
+});
+module.exports = __toCommonJS(http_exports);
+
+// src/types.ts
+var Status = {
+  HEALTHY: 2,
+  DEGRADED: 1,
+  OUTAGE: 0
+};
+
+// src/checks/http.ts
+function httpCheck(url, options) {
+  const { method = "GET", headers, timeout = 5e3 } = options ?? {};
+  return async () => {
+    try {
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), timeout);
+      try {
+        const res = await fetch(url, {
+          method,
+          headers,
+          signal: controller.signal
+        });
+        return {
+          status: res.ok ? Status.HEALTHY : Status.OUTAGE,
+          message: res.ok ? "" : `HTTP ${res.status}`
+        };
+      } finally {
+        clearTimeout(timeoutId);
+      }
+    } catch (error) {
+      const message = error instanceof Error ? error.name === "AbortError" ? `Request to ${url} timed out after ${timeout}ms` : error.message : String(error);
+      return { status: Status.OUTAGE, message };
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  httpCheck
+});

package/dist/checks/http.d.cts

@@ -0,0 +1,17 @@
+import { A as AsyncCheckFn } from '../core-BJ2Z0rRi.cjs';
+
+interface HttpCheckOptions {
+    /** HTTP method to use. Defaults to 'GET'. */
+    method?: string;
+    /** Request headers to include. */
+    headers?: Record<string, string>;
+    /** Timeout in milliseconds for the fetch call. Defaults to 5000. */
+    timeout?: number;
+}
+/**
+ * Creates a healthcheck function that fetches a URL and checks for an ok response.
+ * Returns HEALTHY if the response status is 2xx, OUTAGE otherwise.
+ */
+declare function httpCheck(url: string, options?: HttpCheckOptions): AsyncCheckFn;
+
+export { AsyncCheckFn, type HttpCheckOptions, httpCheck };

package/dist/checks/http.d.ts

@@ -0,0 +1,17 @@
+import { A as AsyncCheckFn } from '../core-BJ2Z0rRi.js';
+
+interface HttpCheckOptions {
+    /** HTTP method to use. Defaults to 'GET'. */
+    method?: string;
+    /** Request headers to include. */
+    headers?: Record<string, string>;
+    /** Timeout in milliseconds for the fetch call. Defaults to 5000. */
+    timeout?: number;
+}
+/**
+ * Creates a healthcheck function that fetches a URL and checks for an ok response.
+ * Returns HEALTHY if the response status is 2xx, OUTAGE otherwise.
+ */
+declare function httpCheck(url: string, options?: HttpCheckOptions): AsyncCheckFn;
+
+export { AsyncCheckFn, type HttpCheckOptions, httpCheck };

package/dist/checks/http.mjs

@@ -0,0 +1,36 @@
+// src/types.ts
+var Status = {
+  HEALTHY: 2,
+  DEGRADED: 1,
+  OUTAGE: 0
+};
+
+// src/checks/http.ts
+function httpCheck(url, options) {
+  const { method = "GET", headers, timeout = 5e3 } = options ?? {};
+  return async () => {
+    try {
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), timeout);
+      try {
+        const res = await fetch(url, {
+          method,
+          headers,
+          signal: controller.signal
+        });
+        return {
+          status: res.ok ? Status.HEALTHY : Status.OUTAGE,
+          message: res.ok ? "" : `HTTP ${res.status}`
+        };
+      } finally {
+        clearTimeout(timeoutId);
+      }
+    } catch (error) {
+      const message = error instanceof Error ? error.name === "AbortError" ? `Request to ${url} timed out after ${timeout}ms` : error.message : String(error);
+      return { status: Status.OUTAGE, message };
+    }
+  };
+}
+export {
+  httpCheck
+};

package/dist/checks/postgres.cjs

@@ -34,7 +34,6 @@ __export(postgres_exports, {
   pgPoolCheck: () => pgPoolCheck
 });
 module.exports = __toCommonJS(postgres_exports);
-var import_node_perf_hooks = require("perf_hooks");
 
 // src/types.ts
 var Status = {
@@ -46,18 +45,15 @@ var Status = {
 // src/checks/postgres.ts
 function pgClientCheck(connectionString, options) {
   return async () => {
-    const start = import_node_perf_hooks.performance.now();
     const { Client } = await import("pg");
     const client = new Client({ connectionString, ...options });
     try {
       await client.connect();
       await client.query("SELECT 1");
-      const latencyMs = Math.round(import_node_perf_hooks.performance.now() - start);
-      return { status: Status.HEALTHY, latencyMs, message: "" };
+      return { status: Status.HEALTHY, message: "" };
     } catch (error) {
-      const latencyMs = Math.round(import_node_perf_hooks.performance.now() - start);
       const message = error instanceof Error ? error.message : String(error);
-      return { status: Status.OUTAGE, latencyMs, message };
+      return { status: Status.OUTAGE, message };
     } finally {
       client.end().catch(() => {
       });
@@ -66,17 +62,14 @@ function pgClientCheck(connectionString, options) {
 }
 function pgPoolCheck(pool) {
   return async () => {
-    const start = import_node_perf_hooks.performance.now();
     let client;
     try {
       client = await pool.connect();
       await client.query("SELECT 1");
-      const latencyMs = Math.round(import_node_perf_hooks.performance.now() - start);
-      return { status: Status.HEALTHY, latencyMs, message: "" };
+      return { status: Status.HEALTHY, message: "" };
     } catch (error) {
-      const latencyMs = Math.round(import_node_perf_hooks.performance.now() - start);
       const message = error instanceof Error ? error.message : String(error);
-      return { status: Status.OUTAGE, latencyMs, message };
+      return { status: Status.OUTAGE, message };
     } finally {
       client?.release();
     }

package/dist/checks/postgres.d.cts

@@ -1,4 +1,4 @@
-import { A as AsyncCheckFn } from '../core-9-MXAO0I.cjs';
+import { A as AsyncCheckFn } from '../core-BJ2Z0rRi.cjs';
 import { Pool } from 'pg';
 
 /**

package/dist/checks/postgres.d.ts

@@ -1,4 +1,4 @@
-import { A as AsyncCheckFn } from '../core-9-MXAO0I.js';
+import { A as AsyncCheckFn } from '../core-BJ2Z0rRi.js';
 import { Pool } from 'pg';
 
 /**

package/dist/checks/postgres.mjs

@@ -1,6 +1,3 @@
-// src/checks/postgres.ts
-import { performance } from "perf_hooks";
-
 // src/types.ts
 var Status = {
   HEALTHY: 2,
@@ -11,18 +8,15 @@ var Status = {
 // src/checks/postgres.ts
 function pgClientCheck(connectionString, options) {
   return async () => {
-    const start = performance.now();
     const { Client } = await import("pg");
     const client = new Client({ connectionString, ...options });
     try {
       await client.connect();
       await client.query("SELECT 1");
-      const latencyMs = Math.round(performance.now() - start);
-      return { status: Status.HEALTHY, latencyMs, message: "" };
+      return { status: Status.HEALTHY, message: "" };
     } catch (error) {
-      const latencyMs = Math.round(performance.now() - start);
       const message = error instanceof Error ? error.message : String(error);
-      return { status: Status.OUTAGE, latencyMs, message };
+      return { status: Status.OUTAGE, message };
     } finally {
       client.end().catch(() => {
       });
@@ -31,17 +25,14 @@ function pgClientCheck(connectionString, options) {
 }
 function pgPoolCheck(pool) {
   return async () => {
-    const start = performance.now();
     let client;
     try {
       client = await pool.connect();
       await client.query("SELECT 1");
-      const latencyMs = Math.round(performance.now() - start);
-      return { status: Status.HEALTHY, latencyMs, message: "" };
+      return { status: Status.HEALTHY, message: "" };
     } catch (error) {
-      const latencyMs = Math.round(performance.now() - start);
       const message = error instanceof Error ? error.message : String(error);
-      return { status: Status.OUTAGE, latencyMs, message };
+      return { status: Status.OUTAGE, message };
     } finally {
       client?.release();
     }

package/dist/checks/redis.cjs

@@ -34,7 +34,6 @@ __export(redis_exports, {
   ioredisClientCheck: () => ioredisClientCheck
 });
 module.exports = __toCommonJS(redis_exports);
-var import_node_perf_hooks = require("perf_hooks");
 
 // src/types.ts
 var Status = {
@@ -46,7 +45,6 @@ var Status = {
 // src/checks/redis.ts
 function ioredisCheck(url, options) {
   return async () => {
-    const start = import_node_perf_hooks.performance.now();
     const { default: RedisClient } = await import("ioredis");
     const client = new RedisClient(url, {
       lazyConnect: true,
@@ -60,12 +58,10 @@ function ioredisCheck(url, options) {
       if (result !== "PONG") {
         throw new Error(`PING returned ${result}`);
       }
-      const latencyMs = Math.round(import_node_perf_hooks.performance.now() - start);
-      return { status: Status.HEALTHY, latencyMs, message: "" };
+      return { status: Status.HEALTHY, message: "" };
     } catch (error) {
-      const latencyMs = Math.round(import_node_perf_hooks.performance.now() - start);
       const message = error instanceof Error ? error.message : String(error);
-      return { status: Status.OUTAGE, latencyMs, message };
+      return { status: Status.OUTAGE, message };
     } finally {
       client.disconnect();
     }
@@ -73,18 +69,15 @@ function ioredisCheck(url, options) {
 }
 function ioredisClientCheck(client) {
   return async () => {
-    const start = import_node_perf_hooks.performance.now();
     try {
       const result = await client.ping();
       if (result !== "PONG") {
         throw new Error(`PING returned ${result}`);
       }
-      const latencyMs = Math.round(import_node_perf_hooks.performance.now() - start);
-      return { status: Status.HEALTHY, latencyMs, message: "" };
+      return { status: Status.HEALTHY, message: "" };
     } catch (error) {
-      const latencyMs = Math.round(import_node_perf_hooks.performance.now() - start);
       const message = error instanceof Error ? error.message : String(error);
-      return { status: Status.OUTAGE, latencyMs, message };
+      return { status: Status.OUTAGE, message };
     }
   };
 }

package/dist/checks/redis.d.cts

@@ -1,4 +1,4 @@
-import { A as AsyncCheckFn } from '../core-9-MXAO0I.cjs';
+import { A as AsyncCheckFn } from '../core-BJ2Z0rRi.cjs';
 import Redis from 'ioredis';
 
 /**

package/dist/checks/redis.d.ts

@@ -1,4 +1,4 @@
-import { A as AsyncCheckFn } from '../core-9-MXAO0I.js';
+import { A as AsyncCheckFn } from '../core-BJ2Z0rRi.js';
 import Redis from 'ioredis';
 
 /**

package/dist/checks/redis.mjs

@@ -1,6 +1,3 @@
-// src/checks/redis.ts
-import { performance } from "perf_hooks";
-
 // src/types.ts
 var Status = {
   HEALTHY: 2,
@@ -11,7 +8,6 @@ var Status = {
 // src/checks/redis.ts
 function ioredisCheck(url, options) {
   return async () => {
-    const start = performance.now();
     const { default: RedisClient } = await import("ioredis");
     const client = new RedisClient(url, {
       lazyConnect: true,
@@ -25,12 +21,10 @@ function ioredisCheck(url, options) {
       if (result !== "PONG") {
         throw new Error(`PING returned ${result}`);
       }
-      const latencyMs = Math.round(performance.now() - start);
-      return { status: Status.HEALTHY, latencyMs, message: "" };
+      return { status: Status.HEALTHY, message: "" };
     } catch (error) {
-      const latencyMs = Math.round(performance.now() - start);
       const message = error instanceof Error ? error.message : String(error);
-      return { status: Status.OUTAGE, latencyMs, message };
+      return { status: Status.OUTAGE, message };
     } finally {
       client.disconnect();
     }
@@ -38,18 +32,15 @@ function ioredisCheck(url, options) {
 }
 function ioredisClientCheck(client) {
   return async () => {
-    const start = performance.now();
     try {
       const result = await client.ping();
       if (result !== "PONG") {
         throw new Error(`PING returned ${result}`);
       }
-      const latencyMs = Math.round(performance.now() - start);
-      return { status: Status.HEALTHY, latencyMs, message: "" };
+      return { status: Status.HEALTHY, message: "" };
     } catch (error) {
-      const latencyMs = Math.round(performance.now() - start);
       const message = error instanceof Error ? error.message : String(error);
-      return { status: Status.OUTAGE, latencyMs, message };
+      return { status: Status.OUTAGE, message };
     }
   };
 }

package/dist/{core-9-MXAO0I.d.cts → core-BJ2Z0rRi.d.cts}

@@ -7,6 +7,16 @@ type StatusValue = (typeof Status)[keyof typeof Status];
 type StatusLabel = 'healthy' | 'degraded' | 'outage';
 declare function statusToLabel(status: StatusValue): StatusLabel;
 declare function statusFromString(value: string): StatusValue;
+/**
+ * What a check function returns. `latencyMs` is optional because the registry
+ * always measures wall-clock latency and overwrites this value.
+ */
+interface CheckInput {
+    readonly status: StatusValue;
+    readonly latencyMs?: number;
+    readonly message: string;
+}
+/** The final result stored per-check after the registry measures latency. */
 interface CheckResult {
     readonly status: StatusValue;
     readonly latencyMs: number;
@@ -29,8 +39,8 @@ interface HealthcheckResponseJson {
 declare function toJson(response: HealthcheckResponse): HealthcheckResponseJson;
 declare function httpStatusCode(status: StatusValue): 200 | 503;
 
-type AsyncCheckFn = () => Promise<CheckResult>;
-type SyncCheckFn = () => CheckResult;
+type AsyncCheckFn = () => Promise<CheckInput>;
+type SyncCheckFn = () => CheckInput;
 interface RegistryOptions {
     defaultTimeout?: number;
 }
@@ -52,4 +62,4 @@ declare class HealthcheckRegistry {
 }
 declare function syncCheck(fn: SyncCheckFn): AsyncCheckFn;
 
-export { type AsyncCheckFn as A, type CheckResult as C, HealthcheckRegistry as H, Status as S, type HealthcheckResponse as a, type HealthcheckResponseJson as b, type StatusLabel as c, type StatusValue as d, type SyncCheckFn as e, statusToLabel as f, syncCheck as g, httpStatusCode as h, statusFromString as s, toJson as t };
+export { type AsyncCheckFn as A, type CheckInput as C, HealthcheckRegistry as H, Status as S, type CheckResult as a, type HealthcheckResponse as b, type HealthcheckResponseJson as c, type StatusLabel as d, type StatusValue as e, type SyncCheckFn as f, statusToLabel as g, httpStatusCode as h, syncCheck as i, statusFromString as s, toJson as t };

package/dist/{core-9-MXAO0I.d.ts → core-BJ2Z0rRi.d.ts}

@@ -7,6 +7,16 @@ type StatusValue = (typeof Status)[keyof typeof Status];
 type StatusLabel = 'healthy' | 'degraded' | 'outage';
 declare function statusToLabel(status: StatusValue): StatusLabel;
 declare function statusFromString(value: string): StatusValue;
+/**
+ * What a check function returns. `latencyMs` is optional because the registry
+ * always measures wall-clock latency and overwrites this value.
+ */
+interface CheckInput {
+    readonly status: StatusValue;
+    readonly latencyMs?: number;
+    readonly message: string;
+}
+/** The final result stored per-check after the registry measures latency. */
 interface CheckResult {
     readonly status: StatusValue;
     readonly latencyMs: number;
@@ -29,8 +39,8 @@ interface HealthcheckResponseJson {
 declare function toJson(response: HealthcheckResponse): HealthcheckResponseJson;
 declare function httpStatusCode(status: StatusValue): 200 | 503;
 
-type AsyncCheckFn = () => Promise<CheckResult>;
-type SyncCheckFn = () => CheckResult;
+type AsyncCheckFn = () => Promise<CheckInput>;
+type SyncCheckFn = () => CheckInput;
 interface RegistryOptions {
     defaultTimeout?: number;
 }
@@ -52,4 +62,4 @@ declare class HealthcheckRegistry {
 }
 declare function syncCheck(fn: SyncCheckFn): AsyncCheckFn;
 
-export { type AsyncCheckFn as A, type CheckResult as C, HealthcheckRegistry as H, Status as S, type HealthcheckResponse as a, type HealthcheckResponseJson as b, type StatusLabel as c, type StatusValue as d, type SyncCheckFn as e, statusToLabel as f, syncCheck as g, httpStatusCode as h, statusFromString as s, toJson as t };
+export { type AsyncCheckFn as A, type CheckInput as C, HealthcheckRegistry as H, Status as S, type CheckResult as a, type HealthcheckResponse as b, type HealthcheckResponseJson as c, type StatusLabel as d, type StatusValue as e, type SyncCheckFn as f, statusToLabel as g, httpStatusCode as h, syncCheck as i, statusFromString as s, toJson as t };

package/dist/handler-Bccbso4b.d.cts

@@ -0,0 +1,25 @@
+import { H as HealthcheckRegistry, c as HealthcheckResponseJson } from './core-BJ2Z0rRi.cjs';
+
+interface HealthcheckHandlerOptions {
+    registry: HealthcheckRegistry;
+    token?: string | null;
+    queryParamName?: string;
+}
+interface HealthcheckRequest {
+    queryParams?: Record<string, string | string[] | undefined>;
+    authorizationHeader?: string | null;
+}
+interface HealthcheckHandlerResult {
+    status: number;
+    body: HealthcheckResponseJson | {
+        error: string;
+    };
+}
+/**
+ * Framework-agnostic healthcheck handler. Takes a simple request object
+ * and returns a status code + JSON body. Framework integrations (Express,
+ * Next.js, etc.) are thin wrappers around this function.
+ */
+declare function createHealthcheckHandler(options: HealthcheckHandlerOptions): (req: HealthcheckRequest) => Promise<HealthcheckHandlerResult>;
+
+export { type HealthcheckHandlerOptions as H, type HealthcheckHandlerResult as a, type HealthcheckRequest as b, createHealthcheckHandler as c };

package/dist/handler-D0nYVQvu.d.ts

@@ -0,0 +1,25 @@
+import { H as HealthcheckRegistry, c as HealthcheckResponseJson } from './core-BJ2Z0rRi.js';
+
+interface HealthcheckHandlerOptions {
+    registry: HealthcheckRegistry;
+    token?: string | null;
+    queryParamName?: string;
+}
+interface HealthcheckRequest {
+    queryParams?: Record<string, string | string[] | undefined>;
+    authorizationHeader?: string | null;
+}
+interface HealthcheckHandlerResult {
+    status: number;
+    body: HealthcheckResponseJson | {
+        error: string;
+    };
+}
+/**
+ * Framework-agnostic healthcheck handler. Takes a simple request object
+ * and returns a status code + JSON body. Framework integrations (Express,
+ * Next.js, etc.) are thin wrappers around this function.
+ */
+declare function createHealthcheckHandler(options: HealthcheckHandlerOptions): (req: HealthcheckRequest) => Promise<HealthcheckHandlerResult>;
+
+export { type HealthcheckHandlerOptions as H, type HealthcheckHandlerResult as a, type HealthcheckRequest as b, createHealthcheckHandler as c };

package/dist/index.cjs

@@ -22,6 +22,7 @@ var src_exports = {};
 __export(src_exports, {
   HealthcheckRegistry: () => HealthcheckRegistry,
   Status: () => Status,
+  createHealthcheckHandler: () => createHealthcheckHandler,
   extractToken: () => extractToken,
   httpStatusCode: () => httpStatusCode,
   statusFromString: () => statusFromString,
@@ -186,10 +187,33 @@ function extractToken(options) {
   }
   return null;
 }
+
+// src/handler.ts
+function createHealthcheckHandler(options) {
+  const { registry, token = null, queryParamName = "token" } = options;
+  return async (req) => {
+    if (token !== null) {
+      const provided = extractToken({
+        queryParams: req.queryParams,
+        authorizationHeader: req.authorizationHeader,
+        queryParamName
+      });
+      if (provided === null || !verifyToken(provided, token)) {
+        return { status: 403, body: { error: "Forbidden" } };
+      }
+    }
+    const response = await registry.run();
+    return {
+      status: httpStatusCode(response.status),
+      body: toJson(response)
+    };
+  };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   HealthcheckRegistry,
   Status,
+  createHealthcheckHandler,
   extractToken,
   httpStatusCode,
   statusFromString,

package/dist/index.d.cts

@@ -1,4 +1,5 @@
-export { A as AsyncCheckFn, C as CheckResult, H as HealthcheckRegistry, a as HealthcheckResponse, b as HealthcheckResponseJson, S as Status, c as StatusLabel, d as StatusValue, e as SyncCheckFn, h as httpStatusCode, s as statusFromString, f as statusToLabel, g as syncCheck, t as toJson } from './core-9-MXAO0I.cjs';
+export { A as AsyncCheckFn, C as CheckInput, a as CheckResult, H as HealthcheckRegistry, b as HealthcheckResponse, c as HealthcheckResponseJson, S as Status, d as StatusLabel, e as StatusValue, f as SyncCheckFn, h as httpStatusCode, s as statusFromString, g as statusToLabel, i as syncCheck, t as toJson } from './core-BJ2Z0rRi.cjs';
+export { H as HealthcheckHandlerOptions, a as HealthcheckHandlerResult, b as HealthcheckRequest, c as createHealthcheckHandler } from './handler-Bccbso4b.cjs';
 
 declare function verifyToken(provided: string, expected: string): boolean;
 declare function extractToken(options: {

package/dist/index.d.ts

@@ -1,4 +1,5 @@
-export { A as AsyncCheckFn, C as CheckResult, H as HealthcheckRegistry, a as HealthcheckResponse, b as HealthcheckResponseJson, S as Status, c as StatusLabel, d as StatusValue, e as SyncCheckFn, h as httpStatusCode, s as statusFromString, f as statusToLabel, g as syncCheck, t as toJson } from './core-9-MXAO0I.js';
+export { A as AsyncCheckFn, C as CheckInput, a as CheckResult, H as HealthcheckRegistry, b as HealthcheckResponse, c as HealthcheckResponseJson, S as Status, d as StatusLabel, e as StatusValue, f as SyncCheckFn, h as httpStatusCode, s as statusFromString, g as statusToLabel, i as syncCheck, t as toJson } from './core-BJ2Z0rRi.js';
+export { H as HealthcheckHandlerOptions, a as HealthcheckHandlerResult, b as HealthcheckRequest, c as createHealthcheckHandler } from './handler-D0nYVQvu.js';
 
 declare function verifyToken(provided: string, expected: string): boolean;
 declare function extractToken(options: {

package/dist/index.mjs

@@ -152,9 +152,32 @@ function extractToken(options) {
   }
   return null;
 }
+
+// src/handler.ts
+function createHealthcheckHandler(options) {
+  const { registry, token = null, queryParamName = "token" } = options;
+  return async (req) => {
+    if (token !== null) {
+      const provided = extractToken({
+        queryParams: req.queryParams,
+        authorizationHeader: req.authorizationHeader,
+        queryParamName
+      });
+      if (provided === null || !verifyToken(provided, token)) {
+        return { status: 403, body: { error: "Forbidden" } };
+      }
+    }
+    const response = await registry.run();
+    return {
+      status: httpStatusCode(response.status),
+      body: toJson(response)
+    };
+  };
+}
 export {
   HealthcheckRegistry,
   Status,
+  createHealthcheckHandler,
   extractToken,
   httpStatusCode,
   statusFromString,

package/dist/integrations/express.cjs

@@ -76,24 +76,38 @@ function httpStatusCode(status) {
   return status === Status.HEALTHY ? 200 : 503;
 }
 
+// src/handler.ts
+function createHealthcheckHandler(options) {
+  const { registry, token = null, queryParamName = "token" } = options;
+  return async (req) => {
+    if (token !== null) {
+      const provided = extractToken({
+        queryParams: req.queryParams,
+        authorizationHeader: req.authorizationHeader,
+        queryParamName
+      });
+      if (provided === null || !verifyToken(provided, token)) {
+        return { status: 403, body: { error: "Forbidden" } };
+      }
+    }
+    const response = await registry.run();
+    return {
+      status: httpStatusCode(response.status),
+      body: toJson(response)
+    };
+  };
+}
+
 // src/integrations/express.ts
 function createHealthcheckMiddleware(options) {
-  const { registry, token = null, queryParamName = "token" } = options;
+  const handle = createHealthcheckHandler(options);
   return async (req, res) => {
     try {
-      if (token !== null) {
-        const provided = extractToken({
-          queryParams: req.query,
-          authorizationHeader: req.headers.authorization ?? null,
-          queryParamName
-        });
-        if (provided === null || !verifyToken(provided, token)) {
-          res.status(403).json({ error: "Forbidden" });
-          return;
-        }
-      }
-      const response = await registry.run();
-      res.status(httpStatusCode(response.status)).json(toJson(response));
+      const result = await handle({
+        queryParams: req.query,
+        authorizationHeader: req.headers.authorization ?? null
+      });
+      res.status(result.status).json(result.body);
     } catch {
       res.status(500).json({ error: "Internal Server Error" });
     }

package/dist/integrations/express.d.cts

@@ -1,11 +1,8 @@
 import { RequestHandler } from 'express';
-import { H as HealthcheckRegistry } from '../core-9-MXAO0I.cjs';
+import { H as HealthcheckHandlerOptions } from '../handler-Bccbso4b.cjs';
+import '../core-BJ2Z0rRi.cjs';
 
-interface HealthcheckMiddlewareOptions {
-    registry: HealthcheckRegistry;
-    token?: string | null;
-    queryParamName?: string;
-}
+type HealthcheckMiddlewareOptions = HealthcheckHandlerOptions;
 declare function createHealthcheckMiddleware(options: HealthcheckMiddlewareOptions): RequestHandler;
 
 export { type HealthcheckMiddlewareOptions, createHealthcheckMiddleware };

package/dist/integrations/express.d.ts

@@ -1,11 +1,8 @@
 import { RequestHandler } from 'express';
-import { H as HealthcheckRegistry } from '../core-9-MXAO0I.js';
+import { H as HealthcheckHandlerOptions } from '../handler-D0nYVQvu.js';
+import '../core-BJ2Z0rRi.js';
 
-interface HealthcheckMiddlewareOptions {
-    registry: HealthcheckRegistry;
-    token?: string | null;
-    queryParamName?: string;
-}
+type HealthcheckMiddlewareOptions = HealthcheckHandlerOptions;
 declare function createHealthcheckMiddleware(options: HealthcheckMiddlewareOptions): RequestHandler;
 
 export { type HealthcheckMiddlewareOptions, createHealthcheckMiddleware };

package/dist/integrations/express.mjs

@@ -50,24 +50,38 @@ function httpStatusCode(status) {
   return status === Status.HEALTHY ? 200 : 503;
 }
 
+// src/handler.ts
+function createHealthcheckHandler(options) {
+  const { registry, token = null, queryParamName = "token" } = options;
+  return async (req) => {
+    if (token !== null) {
+      const provided = extractToken({
+        queryParams: req.queryParams,
+        authorizationHeader: req.authorizationHeader,
+        queryParamName
+      });
+      if (provided === null || !verifyToken(provided, token)) {
+        return { status: 403, body: { error: "Forbidden" } };
+      }
+    }
+    const response = await registry.run();
+    return {
+      status: httpStatusCode(response.status),
+      body: toJson(response)
+    };
+  };
+}
+
 // src/integrations/express.ts
 function createHealthcheckMiddleware(options) {
-  const { registry, token = null, queryParamName = "token" } = options;
+  const handle = createHealthcheckHandler(options);
   return async (req, res) => {
     try {
-      if (token !== null) {
-        const provided = extractToken({
-          queryParams: req.query,
-          authorizationHeader: req.headers.authorization ?? null,
-          queryParamName
-        });
-        if (provided === null || !verifyToken(provided, token)) {
-          res.status(403).json({ error: "Forbidden" });
-          return;
-        }
-      }
-      const response = await registry.run();
-      res.status(httpStatusCode(response.status)).json(toJson(response));
+      const result = await handle({
+        queryParams: req.query,
+        authorizationHeader: req.headers.authorization ?? null
+      });
+      res.status(result.status).json(result.body);
     } catch {
       res.status(500).json({ error: "Internal Server Error" });
     }

package/dist/integrations/next.cjs

@@ -0,0 +1,121 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/integrations/next.ts
+var next_exports = {};
+__export(next_exports, {
+  createNextHandler: () => createNextHandler
+});
+module.exports = __toCommonJS(next_exports);
+
+// src/auth.ts
+var import_node_crypto = require("crypto");
+function verifyToken(provided, expected) {
+  if (!provided || !expected) return false;
+  const providedHash = (0, import_node_crypto.createHash)("sha256").update(provided).digest();
+  const expectedHash = (0, import_node_crypto.createHash)("sha256").update(expected).digest();
+  return (0, import_node_crypto.timingSafeEqual)(providedHash, expectedHash);
+}
+function extractToken(options) {
+  const { queryParams, authorizationHeader, queryParamName = "token" } = options;
+  if (queryParams) {
+    const value = queryParams[queryParamName];
+    const str = Array.isArray(value) ? value[0] : value;
+    if (str) return str;
+  }
+  if (authorizationHeader?.startsWith("Bearer ")) {
+    const token = authorizationHeader.slice("Bearer ".length);
+    if (token) return token;
+  }
+  return null;
+}
+
+// src/types.ts
+var Status = {
+  HEALTHY: 2,
+  DEGRADED: 1,
+  OUTAGE: 0
+};
+function statusToLabel(status) {
+  const labels = {
+    [Status.HEALTHY]: "healthy",
+    [Status.DEGRADED]: "degraded",
+    [Status.OUTAGE]: "outage"
+  };
+  return labels[status];
+}
+function toJson(response) {
+  return {
+    status: statusToLabel(response.status),
+    timestamp: response.timestamp,
+    checks: Object.fromEntries(
+      Object.entries(response.checks).map(([name, result]) => [
+        name,
+        { status: statusToLabel(result.status), latencyMs: result.latencyMs, message: result.message }
+      ])
+    )
+  };
+}
+function httpStatusCode(status) {
+  return status === Status.HEALTHY ? 200 : 503;
+}
+
+// src/handler.ts
+function createHealthcheckHandler(options) {
+  const { registry, token = null, queryParamName = "token" } = options;
+  return async (req) => {
+    if (token !== null) {
+      const provided = extractToken({
+        queryParams: req.queryParams,
+        authorizationHeader: req.authorizationHeader,
+        queryParamName
+      });
+      if (provided === null || !verifyToken(provided, token)) {
+        return { status: 403, body: { error: "Forbidden" } };
+      }
+    }
+    const response = await registry.run();
+    return {
+      status: httpStatusCode(response.status),
+      body: toJson(response)
+    };
+  };
+}
+
+// src/integrations/next.ts
+function createNextHandler(options) {
+  const handle = createHealthcheckHandler(options);
+  return async (request) => {
+    try {
+      const url = new URL(request.url);
+      const queryParams = Object.fromEntries(url.searchParams);
+      const result = await handle({
+        queryParams,
+        authorizationHeader: request.headers.get("authorization")
+      });
+      return Response.json(result.body, { status: result.status });
+    } catch {
+      return Response.json({ error: "Internal Server Error" }, { status: 500 });
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createNextHandler
+});

package/dist/integrations/next.d.cts

@@ -0,0 +1,24 @@
+import { H as HealthcheckHandlerOptions } from '../handler-Bccbso4b.cjs';
+import '../core-BJ2Z0rRi.cjs';
+
+type NextHealthcheckOptions = HealthcheckHandlerOptions;
+/**
+ * Creates a Next.js App Router GET handler for the healthcheck endpoint.
+ *
+ * Usage in `app/vitals/route.ts`:
+ * ```ts
+ * import { HealthcheckRegistry } from '@firebreak/vitals';
+ * import { createNextHandler } from '@firebreak/vitals/next';
+ *
+ * const registry = new HealthcheckRegistry();
+ * // ... register checks ...
+ *
+ * export const GET = createNextHandler({
+ *   registry,
+ *   token: process.env.VITALS_TOKEN,
+ * });
+ * ```
+ */
+declare function createNextHandler(options: NextHealthcheckOptions): (request: Request) => Promise<Response>;
+
+export { type NextHealthcheckOptions, createNextHandler };

package/dist/integrations/next.d.ts

@@ -0,0 +1,24 @@
+import { H as HealthcheckHandlerOptions } from '../handler-D0nYVQvu.js';
+import '../core-BJ2Z0rRi.js';
+
+type NextHealthcheckOptions = HealthcheckHandlerOptions;
+/**
+ * Creates a Next.js App Router GET handler for the healthcheck endpoint.
+ *
+ * Usage in `app/vitals/route.ts`:
+ * ```ts
+ * import { HealthcheckRegistry } from '@firebreak/vitals';
+ * import { createNextHandler } from '@firebreak/vitals/next';
+ *
+ * const registry = new HealthcheckRegistry();
+ * // ... register checks ...
+ *
+ * export const GET = createNextHandler({
+ *   registry,
+ *   token: process.env.VITALS_TOKEN,
+ * });
+ * ```
+ */
+declare function createNextHandler(options: NextHealthcheckOptions): (request: Request) => Promise<Response>;
+
+export { type NextHealthcheckOptions, createNextHandler };

package/dist/integrations/next.mjs

@@ -0,0 +1,94 @@
+// src/auth.ts
+import { createHash, timingSafeEqual } from "crypto";
+function verifyToken(provided, expected) {
+  if (!provided || !expected) return false;
+  const providedHash = createHash("sha256").update(provided).digest();
+  const expectedHash = createHash("sha256").update(expected).digest();
+  return timingSafeEqual(providedHash, expectedHash);
+}
+function extractToken(options) {
+  const { queryParams, authorizationHeader, queryParamName = "token" } = options;
+  if (queryParams) {
+    const value = queryParams[queryParamName];
+    const str = Array.isArray(value) ? value[0] : value;
+    if (str) return str;
+  }
+  if (authorizationHeader?.startsWith("Bearer ")) {
+    const token = authorizationHeader.slice("Bearer ".length);
+    if (token) return token;
+  }
+  return null;
+}
+
+// src/types.ts
+var Status = {
+  HEALTHY: 2,
+  DEGRADED: 1,
+  OUTAGE: 0
+};
+function statusToLabel(status) {
+  const labels = {
+    [Status.HEALTHY]: "healthy",
+    [Status.DEGRADED]: "degraded",
+    [Status.OUTAGE]: "outage"
+  };
+  return labels[status];
+}
+function toJson(response) {
+  return {
+    status: statusToLabel(response.status),
+    timestamp: response.timestamp,
+    checks: Object.fromEntries(
+      Object.entries(response.checks).map(([name, result]) => [
+        name,
+        { status: statusToLabel(result.status), latencyMs: result.latencyMs, message: result.message }
+      ])
+    )
+  };
+}
+function httpStatusCode(status) {
+  return status === Status.HEALTHY ? 200 : 503;
+}
+
+// src/handler.ts
+function createHealthcheckHandler(options) {
+  const { registry, token = null, queryParamName = "token" } = options;
+  return async (req) => {
+    if (token !== null) {
+      const provided = extractToken({
+        queryParams: req.queryParams,
+        authorizationHeader: req.authorizationHeader,
+        queryParamName
+      });
+      if (provided === null || !verifyToken(provided, token)) {
+        return { status: 403, body: { error: "Forbidden" } };
+      }
+    }
+    const response = await registry.run();
+    return {
+      status: httpStatusCode(response.status),
+      body: toJson(response)
+    };
+  };
+}
+
+// src/integrations/next.ts
+function createNextHandler(options) {
+  const handle = createHealthcheckHandler(options);
+  return async (request) => {
+    try {
+      const url = new URL(request.url);
+      const queryParams = Object.fromEntries(url.searchParams);
+      const result = await handle({
+        queryParams,
+        authorizationHeader: request.headers.get("authorization")
+      });
+      return Response.json(result.body, { status: result.status });
+    } catch {
+      return Response.json({ error: "Internal Server Error" }, { status: 500 });
+    }
+  };
+}
+export {
+  createNextHandler
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@firebreak/vitals",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "Deep healthcheck endpoints following the HEALTHCHECK_SPEC format",
   "type": "module",
   "exports": {
@@ -24,6 +24,16 @@
         "default": "./dist/checks/postgres.cjs"
       }
     },
+    "./checks/http": {
+      "import": {
+        "types": "./dist/checks/http.d.ts",
+        "default": "./dist/checks/http.mjs"
+      },
+      "require": {
+        "types": "./dist/checks/http.d.cts",
+        "default": "./dist/checks/http.cjs"
+      }
+    },
     "./checks/redis": {
       "import": {
         "types": "./dist/checks/redis.d.ts",
@@ -43,6 +53,16 @@
         "types": "./dist/integrations/express.d.cts",
         "default": "./dist/integrations/express.cjs"
       }
+    },
+    "./next": {
+      "import": {
+        "types": "./dist/integrations/next.d.ts",
+        "default": "./dist/integrations/next.mjs"
+      },
+      "require": {
+        "types": "./dist/integrations/next.d.cts",
+        "default": "./dist/integrations/next.cjs"
+      }
     }
   },
   "main": "./dist/index.cjs",