@firebreak/vitals 1.2.0 → 1.2.2

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@firebreak/vitals",
-  "version": "1.2.0",
+  "version": "1.2.2",
   "description": "Deep healthcheck endpoints following the HEALTHCHECK_SPEC format",
   "type": "module",
   "exports": {
@@ -88,9 +88,9 @@
     "lint": "tsc --noEmit"
   },
   "peerDependencies": {
-    "pg": ">=8.0.0",
+    "express": ">=4.0.0",
     "ioredis": ">=5.0.0",
-    "express": ">=4.0.0"
+    "pg": ">=8.0.0"
   },
   "peerDependenciesMeta": {
     "pg": {
@@ -104,17 +104,45 @@
     }
   },
   "devDependencies": {
-    "tsup": "^8.0.0",
-    "typescript": "^5.5.0",
-    "vitest": "^2.0.0",
-    "@types/node": "^22.0.0",
     "@types/express": "^5.0.0",
+    "@types/node": "^22.0.0",
     "@types/pg": "^8.0.0",
-    "ioredis": "^5.0.0",
+    "@types/supertest": "^6.0.0",
     "express": "^4.21.0",
+    "ioredis": "^5.0.0",
     "pg": "^8.13.0",
     "supertest": "^7.0.0",
-    "@types/supertest": "^6.0.0"
+    "tsup": "^8.0.0",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0"
+  },
+  "overrides": {
+    "array-flatten": "npm:@socketregistry/array-flatten@^1",
+    "es-define-property": "npm:@socketregistry/es-define-property@^1",
+    "es-set-tostringtag": "npm:@socketregistry/es-set-tostringtag@^1",
+    "function-bind": "npm:@socketregistry/function-bind@^1",
+    "gopd": "npm:@socketregistry/gopd@^1",
+    "has-symbols": "npm:@socketregistry/has-symbols@^1",
+    "has-tostringtag": "npm:@socketregistry/has-tostringtag@^1",
+    "hasown": "npm:@socketregistry/hasown@^1",
+    "object-assign": "npm:@socketregistry/object-assign@^1",
+    "safe-buffer": "npm:@socketregistry/safe-buffer@^1",
+    "safer-buffer": "npm:@socketregistry/safer-buffer@^1",
+    "side-channel": "npm:@socketregistry/side-channel@^1"
+  },
+  "resolutions": {
+    "array-flatten": "npm:@socketregistry/array-flatten@^1",
+    "es-define-property": "npm:@socketregistry/es-define-property@^1",
+    "es-set-tostringtag": "npm:@socketregistry/es-set-tostringtag@^1",
+    "function-bind": "npm:@socketregistry/function-bind@^1",
+    "gopd": "npm:@socketregistry/gopd@^1",
+    "has-symbols": "npm:@socketregistry/has-symbols@^1",
+    "has-tostringtag": "npm:@socketregistry/has-tostringtag@^1",
+    "hasown": "npm:@socketregistry/hasown@^1",
+    "object-assign": "npm:@socketregistry/object-assign@^1",
+    "safe-buffer": "npm:@socketregistry/safe-buffer@^1",
+    "safer-buffer": "npm:@socketregistry/safer-buffer@^1",
+    "side-channel": "npm:@socketregistry/side-channel@^1"
   },
   "engines": {
     "node": ">=20.0.0"