@firebreak/vitals 2.0.0 → 2.1.0

package/README.md

@@ -1,6 +1,6 @@
 # Vitals (Node.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.
+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. A configurable depth policy controls whether callers get a lightweight "alive" response or full diagnostic results.
 
 ## Install
 
@@ -19,7 +19,7 @@ npm install express   # for Express integration
 ## Quick Start (Express)
 
 ```typescript
-import { HealthcheckRegistry } from '@firebreak/vitals';
+import { HealthcheckRegistry, extractToken, verifyToken } from '@firebreak/vitals';
 import { createHealthcheckMiddleware } from '@firebreak/vitals/express';
 import { pgPoolCheck } from '@firebreak/vitals/checks/postgres';
 import { ioredisClientCheck } from '@firebreak/vitals/checks/redis';
@@ -35,7 +35,14 @@ registry.add('api', httpCheck('https://api.example.com/health'));
 const app = express();
 app.get('/vitals', createHealthcheckMiddleware({
   registry,
-  token: process.env.VITALS_TOKEN,
+  resolveDepth: (req) => {
+    const token = extractToken({
+      queryParams: req.queryParams as Record<string, string>,
+      authorizationHeader: req.authorizationHeader as string | null,
+    });
+    if (token && verifyToken(token, process.env.VITALS_TOKEN!)) return 'deep';
+    return 'shallow';
+  },
   metadata: {
     build: process.env.BUILD_SHA,
     buildTimestamp: process.env.BUILD_TIMESTAMP,
@@ -43,19 +50,19 @@ app.get('/vitals', createHealthcheckMiddleware({
 }));
 ```
 
-Hit `/vitals` without a token to get a shallow response:
+Hit `/vitals` without a valid 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.
+When `resolveDepth` returns `'deep'`, the full deep response with check results is returned.
 
 ## Quick Start (Next.js)
 
 ```typescript
 // app/vitals/route.ts
-import { HealthcheckRegistry } from '@firebreak/vitals';
+import { HealthcheckRegistry, extractToken, verifyToken } from '@firebreak/vitals';
 import { createNextHandler } from '@firebreak/vitals/next';
 import { pgClientCheck } from '@firebreak/vitals/checks/postgres';
 import { httpCheck } from '@firebreak/vitals/checks/http';
@@ -69,7 +76,14 @@ registry.add('api', httpCheck(`${process.env.API_BASE_URL}/health`));
 
 export const GET = createNextHandler({
   registry,
-  token: process.env.VITALS_TOKEN,
+  resolveDepth: (req) => {
+    const token = extractToken({
+      queryParams: req.queryParams as Record<string, string>,
+      authorizationHeader: req.authorizationHeader as string | null,
+    });
+    if (token && verifyToken(token, process.env.VITALS_TOKEN!)) return 'deep';
+    return 'shallow';
+  },
   metadata: {
     build: process.env.BUILD_SHA,
   },
@@ -207,8 +221,14 @@ import { createHealthcheckMiddleware } from '@firebreak/vitals/express';
 
 app.get('/vitals', createHealthcheckMiddleware({
   registry,
-  token: 'my-secret-token',   // optional — omit to disable auth
-  queryParamName: 'token',     // default: 'token'
+  resolveDepth: (req) => {     // optional — omit for always-shallow
+    const token = extractToken({
+      queryParams: req.queryParams as Record<string, string>,
+      authorizationHeader: req.authorizationHeader as string | null,
+    });
+    if (token && verifyToken(token, 'my-secret-token')) return 'deep';
+    return 'shallow';
+  },
   metadata: {                  // optional — included in shallow & deep responses
     build: 'stg-45d76e5',
   },
@@ -222,7 +242,14 @@ import { createNextHandler } from '@firebreak/vitals/next';
 
 export const GET = createNextHandler({
   registry,
-  token: process.env.VITALS_TOKEN,
+  resolveDepth: (req) => {
+    const token = extractToken({
+      queryParams: req.queryParams as Record<string, string>,
+      authorizationHeader: req.authorizationHeader as string | null,
+    });
+    if (token && verifyToken(token, process.env.VITALS_TOKEN!)) return 'deep';
+    return 'shallow';
+  },
   metadata: { build: process.env.BUILD_SHA },
 });
 ```
@@ -232,101 +259,120 @@ export const GET = createNextHandler({
 For other frameworks, use the generic handler directly:
 
 ```typescript
-import { createHealthcheckHandler } from '@firebreak/vitals';
+import { createHealthcheckHandler, extractToken, verifyToken } from '@firebreak/vitals';
 
 const handle = createHealthcheckHandler({
   registry,
-  token: process.env.VITALS_TOKEN,
+  resolveDepth: (req) => {
+    const token = extractToken({
+      queryParams: req.queryParams as Record<string, string>,
+      authorizationHeader: req.authorizationHeader as string | null,
+    });
+    if (token && verifyToken(token, process.env.VITALS_TOKEN!)) return 'deep';
+    return 'shallow';
+  },
   metadata: { build: 'stg-45d76e5' },
 });
 
-// No token → shallow response
+// resolveDepth returns 'shallow' → shallow response
 const shallow = await handle({});
 // { status: 200, body: { status: 'ok', timestamp: '...', build: 'stg-45d76e5' } }
 
-// Valid token → deep response
+// resolveDepth returns 'deep' → 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:
+The endpoint serves two tiers from a single route, controlled by the `resolveDepth` option:
 
-| 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 | **Shallow** by default (see `deep` option below) |
+| `resolveDepth` returns | Response |
+|------------------------|----------|
+| `'shallow'` (or omitted) | **Shallow** — `200` with `{ status: "ok", timestamp, ...metadata }` |
+| `'deep'` | **Deep** — `200`/`503` with full check results + metadata |
 
-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.
-
-#### The `deep` Option
+When `resolveDepth` is not provided, the handler always returns a shallow response.
 
-When no `token` is configured, the handler returns a **shallow** response by default. To expose full healthcheck results without requiring token authentication, set `deep: true`:
+The `resolveDepth` function receives the request object (`{ ip, headers, queryParams, authorizationHeader }`) and returns `'deep'` or `'shallow'` (or a promise of either). This lets you implement any depth policy — token-based, IP-based, header-based, or always-deep for internal services:
 
 ```typescript
+// Always deep (internal service behind a private network)
 createHealthcheckHandler({
   registry,
-  deep: true,   // no token → always return deep response
+  resolveDepth: () => 'deep',
 });
 ```
 
-This is useful for internal services behind a private network where token auth is unnecessary. The `deep` option defaults to `false`.
+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.
 
-> **Security note:** Using `deep: true` with an empty string token (e.g. `token: ''`) will throw an error at handler creation time. This prevents misconfigured environments (e.g. `VITALS_TOKEN=""`) from silently exposing deep healthcheck data. If you intend to run without authentication, explicitly omit the `token` option or set it to `null`.
+### Metadata
 
-When both `token` and `deep` are set, the `token` takes precedence — callers must still authenticate to see deep results:
+Attach static key-value pairs that appear in both shallow and deep responses:
 
-| Configuration | No token in request | Valid token | Invalid token |
-|---------------|---------------------|-------------|---------------|
-| `token` set, `deep` unset | Shallow | Deep | 403 |
-| `token` set, `deep: true` | Shallow | Deep | 403 |
-| No `token`, `deep` unset | Shallow | — | — |
-| No `token`, `deep: true` | Deep | — | — |
+```typescript
+createHealthcheckHandler({
+  registry,
+  metadata: {
+    build: 'stg-45d76e5',
+    buildTimestamp: '2025-02-25T19:41:56Z',
+    region: 'us-east-1',
+  },
+});
+```
 
-### Metadata
+Metadata values can be `string`, `number`, or `boolean`. Keys `status`, `timestamp`, `checks`, and `cachedAt` are reserved -- passing them throws at handler creation time.
 
-Attach static key-value pairs that appear in both shallow and deep responses:
+#### `shallowMetadata`
+
+By default, shallow responses include all `metadata` fields. Use `shallowMetadata` to override what appears in shallow responses while keeping `metadata` for deep responses:
 
 ```typescript
 createHealthcheckHandler({
   registry,
-  token: process.env.VITALS_TOKEN,
   metadata: {
     build: 'stg-45d76e5',
     buildTimestamp: '2025-02-25T19:41:56Z',
     region: 'us-east-1',
   },
+  // Shallow responses only include status + timestamp (no build info)
+  shallowMetadata: {},
 });
 ```
 
-Metadata values can be `string`, `number`, or `boolean`. Keys `status`, `timestamp`, and `checks` are reserved — passing them throws at handler creation time.
+You can also include a subset of fields:
+
+```typescript
+createHealthcheckHandler({
+  registry,
+  metadata: { build: 'stg-45d76e5', region: 'us-east-1', version: '1.0.0' },
+  // Shallow responses include only version
+  shallowMetadata: { version: '1.0.0' },
+});
+```
 
-### Authentication
+When `shallowMetadata` is omitted, shallow responses fall back to using `metadata` (existing behavior).
 
-Tokens can be provided via:
-- Query parameter: `?token=my-secret-token`
-- Bearer header: `Authorization: Bearer my-secret-token`
+### Utilities
 
-Tokens are compared using timing-safe SHA-256 comparison.
+`extractToken` and `verifyToken` are exported helpers for use inside your `resolveDepth` function.
 
 ```typescript
 import { verifyToken, extractToken } from '@firebreak/vitals';
 
-verifyToken('provided-token', 'expected-token'); // boolean
-
+// Extract a token from query params (?token=...) or Authorization header
 const token = extractToken({
   queryParams: { token: 'abc' },
   authorizationHeader: 'Bearer abc',
-  queryParamName: 'token',
 });
+
+// Timing-safe SHA-256 comparison
+verifyToken('provided-token', 'expected-token'); // boolean
 ```
 
 ## Response Format
 
-**Shallow response** (no token provided):
+**Shallow response** (`resolveDepth` returns `'shallow'` or is omitted):
 
 ```json
 {
@@ -337,7 +383,7 @@ const token = extractToken({
 }
 ```
 
-**Deep response** (valid token provided):
+**Deep response** (`resolveDepth` returns `'deep'`):
 
 ```json
 {
@@ -362,11 +408,10 @@ const token = extractToken({
 
 | Condition | HTTP Code | Status |
 |-----------|-----------|--------|
-| Shallow (no token) | `200` | `"ok"` |
+| Shallow | `200` | `"ok"` |
 | Deep — healthy | `200` | `"healthy"` |
 | Deep — degraded | `503` | `"degraded"` |
 | Deep — outage | `503` | `"outage"` |
-| Invalid token | `403` | — |
 
 ## Requirements
 

package/dist/{handler-TZOgZvY7.d.cts → handler-C3eTDuSQ.d.cts}

@@ -5,6 +5,7 @@ interface HealthcheckHandlerOptions {
     registry: HealthcheckRegistry;
     resolveDepth?: ResolveDepthFn;
     metadata?: Record<string, string | number | boolean>;
+    shallowMetadata?: Record<string, string | number | boolean>;
 }
 interface ShallowResponseJson {
     status: 'ok';

package/dist/{handler-BvjN4Ot9.d.ts → handler-DaFJivGK.d.ts}

@@ -5,6 +5,7 @@ interface HealthcheckHandlerOptions {
     registry: HealthcheckRegistry;
     resolveDepth?: ResolveDepthFn;
     metadata?: Record<string, string | number | boolean>;
+    shallowMetadata?: Record<string, string | number | boolean>;
 }
 interface ShallowResponseJson {
     status: 'ok';

package/dist/index.cjs

@@ -220,10 +220,12 @@ function extractToken(options) {
 // src/handler.ts
 var RESERVED_METADATA_KEYS = ["status", "timestamp", "checks", "cachedAt"];
 function createHealthcheckHandler(options) {
-  const { registry, resolveDepth, 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.`);
+  const { registry, resolveDepth, metadata = {}, shallowMetadata } = options;
+  for (const bag of [metadata, shallowMetadata ?? {}]) {
+    for (const key of Object.keys(bag)) {
+      if (RESERVED_METADATA_KEYS.includes(key)) {
+        throw new Error(`Metadata key '${key}' is reserved. Use a different key name.`);
+      }
     }
   }
   return async (req) => {
@@ -247,7 +249,7 @@ function createHealthcheckHandler(options) {
     const body = {
       status: "ok",
       timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-      ...metadata
+      ...shallowMetadata ?? metadata
     };
     return { status: 200, body };
   };

package/dist/index.d.cts

@@ -1,7 +1,7 @@
 import { H as HealthcheckResponseJson } from './core-Bee03bJm.cjs';
 export { A as AsyncCheckFn, C as CheckInput, a as CheckResult, b as HealthcheckRegistry, c as HealthcheckResponse, 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-Bee03bJm.cjs';
-import { S as ShallowResponseJson } from './handler-TZOgZvY7.cjs';
-export { H as HealthcheckHandlerOptions, a as HealthcheckHandlerResult, R as ResolveDepthFn, c as createHealthcheckHandler } from './handler-TZOgZvY7.cjs';
+import { S as ShallowResponseJson } from './handler-C3eTDuSQ.cjs';
+export { H as HealthcheckHandlerOptions, a as HealthcheckHandlerResult, R as ResolveDepthFn, c as createHealthcheckHandler } from './handler-C3eTDuSQ.cjs';
 
 declare function verifyToken(provided: string, expected: string): boolean;
 declare function extractToken(options: {

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { H as HealthcheckResponseJson } from './core-Bee03bJm.js';
 export { A as AsyncCheckFn, C as CheckInput, a as CheckResult, b as HealthcheckRegistry, c as HealthcheckResponse, 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-Bee03bJm.js';
-import { S as ShallowResponseJson } from './handler-BvjN4Ot9.js';
-export { H as HealthcheckHandlerOptions, a as HealthcheckHandlerResult, R as ResolveDepthFn, c as createHealthcheckHandler } from './handler-BvjN4Ot9.js';
+import { S as ShallowResponseJson } from './handler-DaFJivGK.js';
+export { H as HealthcheckHandlerOptions, a as HealthcheckHandlerResult, R as ResolveDepthFn, c as createHealthcheckHandler } from './handler-DaFJivGK.js';
 
 declare function verifyToken(provided: string, expected: string): boolean;
 declare function extractToken(options: {

package/dist/index.mjs

@@ -184,10 +184,12 @@ function extractToken(options) {
 // src/handler.ts
 var RESERVED_METADATA_KEYS = ["status", "timestamp", "checks", "cachedAt"];
 function createHealthcheckHandler(options) {
-  const { registry, resolveDepth, 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.`);
+  const { registry, resolveDepth, metadata = {}, shallowMetadata } = options;
+  for (const bag of [metadata, shallowMetadata ?? {}]) {
+    for (const key of Object.keys(bag)) {
+      if (RESERVED_METADATA_KEYS.includes(key)) {
+        throw new Error(`Metadata key '${key}' is reserved. Use a different key name.`);
+      }
     }
   }
   return async (req) => {
@@ -211,7 +213,7 @@ function createHealthcheckHandler(options) {
     const body = {
       status: "ok",
       timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-      ...metadata
+      ...shallowMetadata ?? metadata
     };
     return { status: 200, body };
   };

package/dist/integrations/express.cjs

@@ -61,10 +61,12 @@ function httpStatusCode(status) {
 // src/handler.ts
 var RESERVED_METADATA_KEYS = ["status", "timestamp", "checks", "cachedAt"];
 function createHealthcheckHandler(options) {
-  const { registry, resolveDepth, 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.`);
+  const { registry, resolveDepth, metadata = {}, shallowMetadata } = options;
+  for (const bag of [metadata, shallowMetadata ?? {}]) {
+    for (const key of Object.keys(bag)) {
+      if (RESERVED_METADATA_KEYS.includes(key)) {
+        throw new Error(`Metadata key '${key}' is reserved. Use a different key name.`);
+      }
     }
   }
   return async (req) => {
@@ -88,7 +90,7 @@ function createHealthcheckHandler(options) {
     const body = {
       status: "ok",
       timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-      ...metadata
+      ...shallowMetadata ?? metadata
     };
     return { status: 200, body };
   };

package/dist/integrations/express.d.cts

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

package/dist/integrations/express.d.ts

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

package/dist/integrations/express.mjs

@@ -35,10 +35,12 @@ function httpStatusCode(status) {
 // src/handler.ts
 var RESERVED_METADATA_KEYS = ["status", "timestamp", "checks", "cachedAt"];
 function createHealthcheckHandler(options) {
-  const { registry, resolveDepth, 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.`);
+  const { registry, resolveDepth, metadata = {}, shallowMetadata } = options;
+  for (const bag of [metadata, shallowMetadata ?? {}]) {
+    for (const key of Object.keys(bag)) {
+      if (RESERVED_METADATA_KEYS.includes(key)) {
+        throw new Error(`Metadata key '${key}' is reserved. Use a different key name.`);
+      }
     }
   }
   return async (req) => {
@@ -62,7 +64,7 @@ function createHealthcheckHandler(options) {
     const body = {
       status: "ok",
       timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-      ...metadata
+      ...shallowMetadata ?? metadata
     };
     return { status: 200, body };
   };

package/dist/integrations/next.cjs

@@ -61,10 +61,12 @@ function httpStatusCode(status) {
 // src/handler.ts
 var RESERVED_METADATA_KEYS = ["status", "timestamp", "checks", "cachedAt"];
 function createHealthcheckHandler(options) {
-  const { registry, resolveDepth, 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.`);
+  const { registry, resolveDepth, metadata = {}, shallowMetadata } = options;
+  for (const bag of [metadata, shallowMetadata ?? {}]) {
+    for (const key of Object.keys(bag)) {
+      if (RESERVED_METADATA_KEYS.includes(key)) {
+        throw new Error(`Metadata key '${key}' is reserved. Use a different key name.`);
+      }
     }
   }
   return async (req) => {
@@ -88,7 +90,7 @@ function createHealthcheckHandler(options) {
     const body = {
       status: "ok",
       timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-      ...metadata
+      ...shallowMetadata ?? metadata
     };
     return { status: 200, body };
   };

package/dist/integrations/next.d.cts

@@ -1,4 +1,4 @@
-import { H as HealthcheckHandlerOptions } from '../handler-TZOgZvY7.cjs';
+import { H as HealthcheckHandlerOptions } from '../handler-C3eTDuSQ.cjs';
 import '../core-Bee03bJm.cjs';
 
 type NextHealthcheckOptions = HealthcheckHandlerOptions;

package/dist/integrations/next.d.ts

@@ -1,4 +1,4 @@
-import { H as HealthcheckHandlerOptions } from '../handler-BvjN4Ot9.js';
+import { H as HealthcheckHandlerOptions } from '../handler-DaFJivGK.js';
 import '../core-Bee03bJm.js';
 
 type NextHealthcheckOptions = HealthcheckHandlerOptions;

package/dist/integrations/next.mjs

@@ -35,10 +35,12 @@ function httpStatusCode(status) {
 // src/handler.ts
 var RESERVED_METADATA_KEYS = ["status", "timestamp", "checks", "cachedAt"];
 function createHealthcheckHandler(options) {
-  const { registry, resolveDepth, 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.`);
+  const { registry, resolveDepth, metadata = {}, shallowMetadata } = options;
+  for (const bag of [metadata, shallowMetadata ?? {}]) {
+    for (const key of Object.keys(bag)) {
+      if (RESERVED_METADATA_KEYS.includes(key)) {
+        throw new Error(`Metadata key '${key}' is reserved. Use a different key name.`);
+      }
     }
   }
   return async (req) => {
@@ -62,7 +64,7 @@ function createHealthcheckHandler(options) {
     const body = {
       status: "ok",
       timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-      ...metadata
+      ...shallowMetadata ?? metadata
     };
     return { status: 200, body };
   };

package/package.json

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