@firebreak/vitals 1.1.1 → 1.2.1

package/README.md

@@ -1,6 +1,6 @@
 # Vitals (Node.js)
 
-Structured deep healthcheck endpoints for Node.js services. Register health checks, run them concurrently with timeouts, and expose them via Express or Next.js.
+Structured healthcheck endpoints for Node.js services with shallow and deep response tiers. Register health checks, run them concurrently with timeouts, and expose them via Express or Next.js. Unauthenticated callers get a lightweight "alive" response with optional metadata; authenticated callers get full diagnostic results.
 
 ## Install
 
@@ -36,9 +36,21 @@ const app = express();
 app.get('/vitals', createHealthcheckMiddleware({
   registry,
   token: process.env.VITALS_TOKEN,
+  metadata: {
+    build: process.env.BUILD_SHA,
+    buildTimestamp: process.env.BUILD_TIMESTAMP,
+  },
 }));
 ```
 
+Hit `/vitals` without a token to get a shallow response:
+
+```json
+{ "status": "ok", "timestamp": "...", "build": "stg-45d76e5", "buildTimestamp": "2025-02-25T19:41:56Z" }
+```
+
+Provide the token (`?token=...` or `Authorization: Bearer ...`) to get the full deep response with check results.
+
 ## Quick Start (Next.js)
 
 ```typescript
@@ -58,6 +70,9 @@ registry.add('api', httpCheck(`${process.env.API_BASE_URL}/health`));
 export const GET = createNextHandler({
   registry,
   token: process.env.VITALS_TOKEN,
+  metadata: {
+    build: process.env.BUILD_SHA,
+  },
 });
 ```
 
@@ -194,6 +209,9 @@ app.get('/vitals', createHealthcheckMiddleware({
   registry,
   token: 'my-secret-token',   // optional — omit to disable auth
   queryParamName: 'token',     // default: 'token'
+  metadata: {                  // optional — included in shallow & deep responses
+    build: 'stg-45d76e5',
+  },
 }));
 ```
 
@@ -205,6 +223,7 @@ import { createNextHandler } from '@firebreak/vitals/next';
 export const GET = createNextHandler({
   registry,
   token: process.env.VITALS_TOKEN,
+  metadata: { build: process.env.BUILD_SHA },
 });
 ```
 
@@ -215,19 +234,55 @@ For other frameworks, use the generic handler directly:
 ```typescript
 import { createHealthcheckHandler } from '@firebreak/vitals';
 
-const handle = createHealthcheckHandler({ registry, token: process.env.VITALS_TOKEN });
+const handle = createHealthcheckHandler({
+  registry,
+  token: process.env.VITALS_TOKEN,
+  metadata: { build: 'stg-45d76e5' },
+});
+
+// No token → shallow response
+const shallow = await handle({});
+// { status: 200, body: { status: 'ok', timestamp: '...', build: 'stg-45d76e5' } }
 
-// In any framework:
-const result = await handle({
-  queryParams: { token: 'abc' },
-  authorizationHeader: 'Bearer abc',
+// Valid token → deep response
+const deep = await handle({ queryParams: { token: '...' } });
+// { status: 200, body: { status: 'healthy', timestamp: '...', build: 'stg-45d76e5', checks: { ... } } }
+```
+
+### Shallow / Deep Responses
+
+When a `token` is configured, the endpoint serves two tiers from a single route:
+
+| Request | Response |
+|---------|----------|
+| No token provided | **Shallow** — `200` with `{ status: "ok", timestamp, ...metadata }` |
+| Valid token provided | **Deep** — `200`/`503` with full check results + metadata |
+| Invalid token provided | `403 Forbidden` |
+| No token configured | Deep response always (backwards-compatible) |
+
+The shallow response lets load balancers and uptime monitors confirm the process is alive without needing a secret. The deep response is a superset of shallow — it includes everything shallow returns plus the `checks` object and a real health status.
+
+### Metadata
+
+Attach static key-value pairs that appear in both shallow and deep responses:
+
+```typescript
+createHealthcheckHandler({
+  registry,
+  token: process.env.VITALS_TOKEN,
+  metadata: {
+    build: 'stg-45d76e5',
+    buildTimestamp: '2025-02-25T19:41:56Z',
+    region: 'us-east-1',
+  },
 });
-// result = { status: 200, body: { status: 'healthy', ... } }
 ```
 
+Metadata values can be `string`, `number`, or `boolean`. Keys `status`, `timestamp`, and `checks` are reserved — passing them throws at handler creation time.
+
 ### Authentication
 
-When a token is configured, requests must provide it via:
+Tokens can be provided via:
 - Query parameter: `?token=my-secret-token`
 - Bearer header: `Authorization: Bearer my-secret-token`
 
@@ -247,10 +302,25 @@ const token = extractToken({
 
 ## Response Format
 
+**Shallow response** (no token provided):
+
+```json
+{
+  "status": "ok",
+  "timestamp": "2025-02-26T12:00:00.000Z",
+  "build": "stg-45d76e5",
+  "buildTimestamp": "2025-02-25T19:41:56Z"
+}
+```
+
+**Deep response** (valid token provided):
+
 ```json
 {
   "status": "healthy",
   "timestamp": "2025-02-26T12:00:00.000Z",
+  "build": "stg-45d76e5",
+  "buildTimestamp": "2025-02-25T19:41:56Z",
   "checks": {
     "postgres": {
       "status": "healthy",
@@ -266,12 +336,13 @@ const token = extractToken({
 }
 ```
 
-| Overall Status | HTTP Code |
-|---------------|-----------|
-| `healthy` | `200` |
-| `degraded` | `503` |
-| `outage` | `503` |
-| Auth failure | `403` |
+| Condition | HTTP Code | Status |
+|-----------|-----------|--------|
+| Shallow (no token) | `200` | `"ok"` |
+| Deep — healthy | `200` | `"healthy"` |
+| Deep — degraded | `503` | `"degraded"` |
+| Deep — outage | `503` | `"outage"` |
+| Invalid token | `403` | — |
 
 ## Requirements
 

package/dist/{handler-Bccbso4b.d.cts → handler-Bvf66wzh.d.cts}

@@ -4,22 +4,23 @@ interface HealthcheckHandlerOptions {
     registry: HealthcheckRegistry;
     token?: string | null;
     queryParamName?: string;
+    metadata?: Record<string, string | number | boolean>;
 }
 interface HealthcheckRequest {
     queryParams?: Record<string, string | string[] | undefined>;
     authorizationHeader?: string | null;
 }
+interface ShallowResponseJson {
+    status: 'ok';
+    timestamp: string;
+    [key: string]: string | number | boolean;
+}
 interface HealthcheckHandlerResult {
     status: number;
-    body: HealthcheckResponseJson | {
+    body: HealthcheckResponseJson | ShallowResponseJson | {
         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 };
+export { type HealthcheckHandlerOptions as H, type ShallowResponseJson as S, type HealthcheckHandlerResult as a, type HealthcheckRequest as b, createHealthcheckHandler as c };

package/dist/{handler-D0nYVQvu.d.ts → handler-R2U3ygLo.d.ts}

@@ -4,22 +4,23 @@ interface HealthcheckHandlerOptions {
     registry: HealthcheckRegistry;
     token?: string | null;
     queryParamName?: string;
+    metadata?: Record<string, string | number | boolean>;
 }
 interface HealthcheckRequest {
     queryParams?: Record<string, string | string[] | undefined>;
     authorizationHeader?: string | null;
 }
+interface ShallowResponseJson {
+    status: 'ok';
+    timestamp: string;
+    [key: string]: string | number | boolean;
+}
 interface HealthcheckHandlerResult {
     status: number;
-    body: HealthcheckResponseJson | {
+    body: HealthcheckResponseJson | ShallowResponseJson | {
         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 };
+export { type HealthcheckHandlerOptions as H, type ShallowResponseJson as S, type HealthcheckHandlerResult as a, type HealthcheckRequest as b, createHealthcheckHandler as c };

package/dist/index.cjs

@@ -189,8 +189,14 @@ function extractToken(options) {
 }
 
 // src/handler.ts
+var RESERVED_METADATA_KEYS = ["status", "timestamp", "checks"];
 function createHealthcheckHandler(options) {
-  const { registry, token = null, queryParamName = "token" } = options;
+  const { registry, token = null, queryParamName = "token", metadata = {} } = options;
+  for (const key of Object.keys(metadata)) {
+    if (RESERVED_METADATA_KEYS.includes(key)) {
+      throw new Error(`Metadata key '${key}' is reserved. Use a different key name.`);
+    }
+  }
   return async (req) => {
     if (token !== null) {
       const provided = extractToken({
@@ -198,14 +204,22 @@ function createHealthcheckHandler(options) {
         authorizationHeader: req.authorizationHeader,
         queryParamName
       });
-      if (provided === null || !verifyToken(provided, token)) {
+      if (provided === null) {
+        const body = {
+          status: "ok",
+          timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+          ...metadata
+        };
+        return { status: 200, body };
+      }
+      if (!verifyToken(provided, token)) {
         return { status: 403, body: { error: "Forbidden" } };
       }
     }
     const response = await registry.run();
     return {
       status: httpStatusCode(response.status),
-      body: toJson(response)
+      body: { ...metadata, ...toJson(response) }
     };
   };
 }

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 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';
+export { H as HealthcheckHandlerOptions, a as HealthcheckHandlerResult, b as HealthcheckRequest, S as ShallowResponseJson, c as createHealthcheckHandler } from './handler-Bvf66wzh.cjs';
 
 declare function verifyToken(provided: string, expected: string): boolean;
 declare function extractToken(options: {

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 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';
+export { H as HealthcheckHandlerOptions, a as HealthcheckHandlerResult, b as HealthcheckRequest, S as ShallowResponseJson, c as createHealthcheckHandler } from './handler-R2U3ygLo.js';
 
 declare function verifyToken(provided: string, expected: string): boolean;
 declare function extractToken(options: {

package/dist/index.mjs

@@ -154,8 +154,14 @@ function extractToken(options) {
 }
 
 // src/handler.ts
+var RESERVED_METADATA_KEYS = ["status", "timestamp", "checks"];
 function createHealthcheckHandler(options) {
-  const { registry, token = null, queryParamName = "token" } = options;
+  const { registry, token = null, queryParamName = "token", metadata = {} } = options;
+  for (const key of Object.keys(metadata)) {
+    if (RESERVED_METADATA_KEYS.includes(key)) {
+      throw new Error(`Metadata key '${key}' is reserved. Use a different key name.`);
+    }
+  }
   return async (req) => {
     if (token !== null) {
       const provided = extractToken({
@@ -163,14 +169,22 @@ function createHealthcheckHandler(options) {
         authorizationHeader: req.authorizationHeader,
         queryParamName
       });
-      if (provided === null || !verifyToken(provided, token)) {
+      if (provided === null) {
+        const body = {
+          status: "ok",
+          timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+          ...metadata
+        };
+        return { status: 200, body };
+      }
+      if (!verifyToken(provided, token)) {
         return { status: 403, body: { error: "Forbidden" } };
       }
     }
     const response = await registry.run();
     return {
       status: httpStatusCode(response.status),
-      body: toJson(response)
+      body: { ...metadata, ...toJson(response) }
     };
   };
 }

package/dist/integrations/express.cjs

@@ -77,8 +77,14 @@ function httpStatusCode(status) {
 }
 
 // src/handler.ts
+var RESERVED_METADATA_KEYS = ["status", "timestamp", "checks"];
 function createHealthcheckHandler(options) {
-  const { registry, token = null, queryParamName = "token" } = options;
+  const { registry, token = null, queryParamName = "token", metadata = {} } = options;
+  for (const key of Object.keys(metadata)) {
+    if (RESERVED_METADATA_KEYS.includes(key)) {
+      throw new Error(`Metadata key '${key}' is reserved. Use a different key name.`);
+    }
+  }
   return async (req) => {
     if (token !== null) {
       const provided = extractToken({
@@ -86,14 +92,22 @@ function createHealthcheckHandler(options) {
         authorizationHeader: req.authorizationHeader,
         queryParamName
       });
-      if (provided === null || !verifyToken(provided, token)) {
+      if (provided === null) {
+        const body = {
+          status: "ok",
+          timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+          ...metadata
+        };
+        return { status: 200, body };
+      }
+      if (!verifyToken(provided, token)) {
         return { status: 403, body: { error: "Forbidden" } };
       }
     }
     const response = await registry.run();
     return {
       status: httpStatusCode(response.status),
-      body: toJson(response)
+      body: { ...metadata, ...toJson(response) }
     };
   };
 }

package/dist/integrations/express.d.cts

@@ -1,5 +1,5 @@
 import { RequestHandler } from 'express';
-import { H as HealthcheckHandlerOptions } from '../handler-Bccbso4b.cjs';
+import { H as HealthcheckHandlerOptions } from '../handler-Bvf66wzh.cjs';
 import '../core-BJ2Z0rRi.cjs';
 
 type HealthcheckMiddlewareOptions = HealthcheckHandlerOptions;

package/dist/integrations/express.d.ts

@@ -1,5 +1,5 @@
 import { RequestHandler } from 'express';
-import { H as HealthcheckHandlerOptions } from '../handler-D0nYVQvu.js';
+import { H as HealthcheckHandlerOptions } from '../handler-R2U3ygLo.js';
 import '../core-BJ2Z0rRi.js';
 
 type HealthcheckMiddlewareOptions = HealthcheckHandlerOptions;

package/dist/integrations/express.mjs

@@ -51,8 +51,14 @@ function httpStatusCode(status) {
 }
 
 // src/handler.ts
+var RESERVED_METADATA_KEYS = ["status", "timestamp", "checks"];
 function createHealthcheckHandler(options) {
-  const { registry, token = null, queryParamName = "token" } = options;
+  const { registry, token = null, queryParamName = "token", metadata = {} } = options;
+  for (const key of Object.keys(metadata)) {
+    if (RESERVED_METADATA_KEYS.includes(key)) {
+      throw new Error(`Metadata key '${key}' is reserved. Use a different key name.`);
+    }
+  }
   return async (req) => {
     if (token !== null) {
       const provided = extractToken({
@@ -60,14 +66,22 @@ function createHealthcheckHandler(options) {
         authorizationHeader: req.authorizationHeader,
         queryParamName
       });
-      if (provided === null || !verifyToken(provided, token)) {
+      if (provided === null) {
+        const body = {
+          status: "ok",
+          timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+          ...metadata
+        };
+        return { status: 200, body };
+      }
+      if (!verifyToken(provided, token)) {
         return { status: 403, body: { error: "Forbidden" } };
       }
     }
     const response = await registry.run();
     return {
       status: httpStatusCode(response.status),
-      body: toJson(response)
+      body: { ...metadata, ...toJson(response) }
     };
   };
 }

package/dist/integrations/next.cjs

@@ -77,8 +77,14 @@ function httpStatusCode(status) {
 }
 
 // src/handler.ts
+var RESERVED_METADATA_KEYS = ["status", "timestamp", "checks"];
 function createHealthcheckHandler(options) {
-  const { registry, token = null, queryParamName = "token" } = options;
+  const { registry, token = null, queryParamName = "token", metadata = {} } = options;
+  for (const key of Object.keys(metadata)) {
+    if (RESERVED_METADATA_KEYS.includes(key)) {
+      throw new Error(`Metadata key '${key}' is reserved. Use a different key name.`);
+    }
+  }
   return async (req) => {
     if (token !== null) {
       const provided = extractToken({
@@ -86,14 +92,22 @@ function createHealthcheckHandler(options) {
         authorizationHeader: req.authorizationHeader,
         queryParamName
       });
-      if (provided === null || !verifyToken(provided, token)) {
+      if (provided === null) {
+        const body = {
+          status: "ok",
+          timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+          ...metadata
+        };
+        return { status: 200, body };
+      }
+      if (!verifyToken(provided, token)) {
         return { status: 403, body: { error: "Forbidden" } };
       }
     }
     const response = await registry.run();
     return {
       status: httpStatusCode(response.status),
-      body: toJson(response)
+      body: { ...metadata, ...toJson(response) }
     };
   };
 }

package/dist/integrations/next.d.cts

@@ -1,4 +1,4 @@
-import { H as HealthcheckHandlerOptions } from '../handler-Bccbso4b.cjs';
+import { H as HealthcheckHandlerOptions } from '../handler-Bvf66wzh.cjs';
 import '../core-BJ2Z0rRi.cjs';
 
 type NextHealthcheckOptions = HealthcheckHandlerOptions;

package/dist/integrations/next.d.ts

@@ -1,4 +1,4 @@
-import { H as HealthcheckHandlerOptions } from '../handler-D0nYVQvu.js';
+import { H as HealthcheckHandlerOptions } from '../handler-R2U3ygLo.js';
 import '../core-BJ2Z0rRi.js';
 
 type NextHealthcheckOptions = HealthcheckHandlerOptions;

package/dist/integrations/next.mjs

@@ -51,8 +51,14 @@ function httpStatusCode(status) {
 }
 
 // src/handler.ts
+var RESERVED_METADATA_KEYS = ["status", "timestamp", "checks"];
 function createHealthcheckHandler(options) {
-  const { registry, token = null, queryParamName = "token" } = options;
+  const { registry, token = null, queryParamName = "token", metadata = {} } = options;
+  for (const key of Object.keys(metadata)) {
+    if (RESERVED_METADATA_KEYS.includes(key)) {
+      throw new Error(`Metadata key '${key}' is reserved. Use a different key name.`);
+    }
+  }
   return async (req) => {
     if (token !== null) {
       const provided = extractToken({
@@ -60,14 +66,22 @@ function createHealthcheckHandler(options) {
         authorizationHeader: req.authorizationHeader,
         queryParamName
       });
-      if (provided === null || !verifyToken(provided, token)) {
+      if (provided === null) {
+        const body = {
+          status: "ok",
+          timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+          ...metadata
+        };
+        return { status: 200, body };
+      }
+      if (!verifyToken(provided, token)) {
         return { status: 403, body: { error: "Forbidden" } };
       }
     }
     const response = await registry.run();
     return {
       status: httpStatusCode(response.status),
-      body: toJson(response)
+      body: { ...metadata, ...toJson(response) }
     };
   };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@firebreak/vitals",
-  "version": "1.1.1",
+  "version": "1.2.1",
   "description": "Deep healthcheck endpoints following the HEALTHCHECK_SPEC format",
   "type": "module",
   "exports": {