Merge pull request #58 from lamborghini21/add-health-ready-endpoints

Add /healthz and /readyz endpoints with readiness component reporting

Author: Flamki

README.md

@@ -121,6 +121,32 @@ PORT=3001
 INTERNAL_BASE_URL=https://stellarmind.example.com
 ```
 
+## Operational Health Checks
+
+StellarMind exposes lightweight endpoints for deployment tooling and load balancer probes:
+
+- `GET /healthz`
+  - returns `200` and `status: ok` when the process is alive
+  - no external dependency checks are performed
+- `GET /readyz`
+  - returns `200` when the configured critical components are ready
+  - returns `503` when required configuration is missing
+
+Example `/readyz` response:
+
+```json
+{
+  "status": "ready",
+  "ready": true,
+  "timestamp": "2026-05-28T12:00:00.000Z",
+  "components": {
+    "app": { "ready": true, "description": "Core HTTP server initialized" },
+    "anthropic": { "configured": true, "ready": true, "description": "Anthropic API key is configured for Claude-powered agents" },
+    "x402": { "enabled": true, "ready": true, "description": "x402 payment wallet is configured" }
+  }
+}
+```
+
 ## Available Commands
 
 | Command | Purpose |

src/server.js

@@ -25,6 +25,7 @@ app.use(requestId);
 
 // ─── SSE Event Stream ────────────────────────────────────────
 const sseClients = [];
+let x402MiddlewareReady = false;
 
 function broadcast(event) {
   const data = JSON.stringify(event);
@@ -33,6 +34,55 @@ function broadcast(event) {
   });
 }
 
+function buildReadinessPayload() {
+  const anthropicConfigured = !!config.anthropicApiKey;
+  const x402Enabled = !!config.serverAddress;
+
+  const components = {
+    app: {
+      ready: true,
+      description: 'Core HTTP server initialized',
+    },
+    anthropic: {
+      configured: anthropicConfigured,
+      ready: anthropicConfigured,
+      description: anthropicConfigured
+        ? 'Anthropic API key is configured for Claude-powered agents'
+        : 'Missing Anthropic API key; demo fallback responses are available',
+    },
+    x402: {
+      enabled: x402Enabled,
+      ready: !x402Enabled || (x402MiddlewareReady && !!config.facilitatorUrl),
+      description: x402Enabled
+        ? (x402MiddlewareReady
+            ? 'x402 payment middleware initialized'
+            : 'x402 is enabled but middleware initialization failed')
+        : 'x402 paywall is disabled; premium endpoints are not protected by payments',
+    },
+  };
+
+  const ready = Object.values(components).every(component => component.ready);
+  return {
+    status: ready ? 'ready' : 'not_ready',
+    ready,
+    timestamp: new Date().toISOString(),
+    components,
+  };
+}
+
+app.get('/healthz', (req, res) => {
+  res.json({
+    status: 'ok',
+    uptime: process.uptime(),
+    timestamp: new Date().toISOString(),
+  });
+});
+
+app.get('/readyz', (req, res) => {
+  const payload = buildReadinessPayload();
+  res.status(payload.ready ? 200 : 503).json(payload);
+});
+
 app.get('/api/events', (req, res) => {
   res.setHeader('Content-Type', 'text/event-stream');
   res.setHeader('Cache-Control', 'no-cache');
@@ -96,11 +146,14 @@ if (config.serverAddress) {
         [{ network: config.network, server: stellarScheme }],
       )
     );
+    x402MiddlewareReady = true;
     console.log('✅ x402 payment middleware active');
   } catch (err) {
+    x402MiddlewareReady = false;
     console.warn('⚠️  x402 middleware init failed (non-fatal):', err.message);
   }
 } else {
+  x402MiddlewareReady = false;
   console.warn('⚠️  No SERVER_STELLAR_ADDRESS set — x402 paywall disabled');
 }