@od-oneapp/ai-platform 0.1.0

package/src/server/routes/QUICK_START.md

@@ -0,0 +1,327 @@
+# Health Check Quick Start Guide
+
+Get started with the health check endpoint in 5 minutes.
+
+## Installation
+
+The health check module is located at:
+
+```
+@od-oneapp/ai-platform/src/internal/routes
+```
+
+Import the functions:
+
+```typescript
+import {
+  checkHealth,
+  createHealthCheckHandler,
+  createNextHealthCheckHandler,
+  createHealthCheckMiddleware
+} from "@od-oneapp/ai-platform";
+```
+
+## Next.js Example (Most Common)
+
+**File: `app/api/health/route.ts`**
+
+```typescript
+import { createNextHealthCheckHandler } from "@od-oneapp/ai-platform";
+
+export const GET = createNextHealthCheckHandler({
+  enableDatabase: true,
+  enableRedis: true,
+  enableAIProvider: true,
+  enableMemory: true
+});
+```
+
+That's it! Your endpoint is now at `GET /api/health`
+
+## Express Example
+
+**File: `src/routes/health.ts`**
+
+```typescript
+import express from "express";
+import { createHealthCheckHandler } from "@od-oneapp/ai-platform";
+
+const router = express.Router();
+
+router.get(
+  "/health",
+  createHealthCheckHandler({
+    enableDatabase: true,
+    enableRedis: true,
+    enableAIProvider: true,
+    enableMemory: true
+  })
+);
+
+export default router;
+```
+
+Add to your app:
+
+```typescript
+import healthRouter from "./routes/health";
+app.use(healthRouter);
+```
+
+## Environment Variables
+
+Set these for the health check to work:
+
+```bash
+# Required for database checks
+DATABASE_URL=postgresql://user:pass@localhost:5432/db
+
+# Optional for Redis checks
+REDIS_URL=redis://localhost:6379/0
+
+# Optional for monitoring
+NODE_ENV=production
+```
+
+## Test It
+
+```bash
+# In development
+curl http://localhost:3000/api/health
+
+# Expected response (healthy)
+{
+  "status": "healthy",
+  "timestamp": "2024-01-29T12:34:56.789Z",
+  "version": "1.0.0",
+  "environment": "development",
+  "uptime": 1234.5,
+  "responseTime": 127,
+  "checks": {
+    "database": { "connected": true, "status": "up", "latency": 12 },
+    "redis": { "connected": true, "status": "up", "latency": 5 },
+    "aiProvider": { "available": true, "status": "up", "latency": 150 },
+    "memory": { "heapUsed": 52428800, "heapTotal": 209715200, "heapUsedPercent": 25.0, "status": "ok" }
+  }
+}
+```
+
+## Status Codes
+
+| Status    | HTTP Code | Meaning                               |
+| --------- | --------- | ------------------------------------- |
+| healthy   | 200       | All systems operational               |
+| degraded  | 200       | Core works, some features unavailable |
+| unhealthy | 503       | Critical failure, restart pod         |
+
+## Kubernetes Deployment
+
+Add to your deployment YAML:
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: my-app
+spec:
+  template:
+    spec:
+      containers:
+        - name: app
+          livenessProbe:
+            httpGet:
+              path: /api/health
+              port: 3000
+            initialDelaySeconds: 30
+            periodSeconds: 10
+          readinessProbe:
+            httpGet:
+              path: /api/health
+              port: 3000
+            initialDelaySeconds: 10
+            periodSeconds: 5
+```
+
+## Monitoring Integration
+
+Send health metrics to Datadog every 30 seconds:
+
+```typescript
+import { checkHealth } from "@od-oneapp/ai-platform";
+
+setInterval(async () => {
+  const health = await checkHealth({
+    enableDatabase: true,
+    enableRedis: true,
+    enableAIProvider: true,
+    enableMemory: true
+  });
+
+  // Send to Datadog
+  await fetch("https://api.datadoghq.com/api/v1/series", {
+    method: "POST",
+    headers: { "DD-API-KEY": process.env.DATADOG_API_KEY },
+    body: JSON.stringify({
+      series: [
+        {
+          metric: "app.health.status",
+          points: [[Date.now() / 1000, health.status === "healthy" ? 1 : 0]],
+          tags: ["env:production"]
+        }
+      ]
+    })
+  });
+}, 30000);
+```
+
+## Advanced: Custom Checks
+
+Add application-specific checks:
+
+```typescript
+import { checkHealth } from "@od-oneapp/ai-platform";
+import type { ComponentHealth } from "@od-oneapp/ai-platform";
+
+async function checkSearchIndex(): Promise<ComponentHealth> {
+  try {
+    const res = await fetch("http://elasticsearch:9200/_cluster/health");
+    const data = await res.json();
+    return {
+      status: data.status === "green" ? "up" : "degraded",
+      available: data.status !== "red"
+    };
+  } catch (error) {
+    return { status: "down", available: false, error: "Connection failed" };
+  }
+}
+
+const health = await checkHealth({
+  enableDatabase: true,
+  enableRedis: true,
+  enableMemory: true,
+  customChecks: [{ name: "elasticsearch", check: checkSearchIndex }]
+});
+```
+
+## Troubleshooting
+
+### Health check always shows "unhealthy"
+
+1. Check DATABASE_URL is set: `echo $DATABASE_URL`
+2. Verify database is running: `psql -U user -d db -c "SELECT 1"`
+3. Check database credentials in connection string
+
+### Response time is slow (>500ms)
+
+1. Check database performance: `EXPLAIN ANALYZE SELECT 1`
+2. Verify connection pool isn't exhausted
+3. Check network latency to Redis/database
+4. Reduce number of custom checks
+
+### Redis connection fails
+
+Redis is optional. If not needed, disable it:
+
+```typescript
+createHealthCheckHandler({
+  enableRedis: false, // Skip Redis checks
+  enableDatabase: true,
+  enableMemory: true
+});
+```
+
+### Need to skip database checks
+
+```typescript
+createHealthCheckHandler({
+  enableDatabase: false, // Skip DB checks
+  enableRedis: true,
+  enableMemory: true
+});
+```
+
+## Monitoring Dashboard
+
+Useful metrics to track:
+
+```
+- health.status (1=healthy, 0=unhealthy)
+- health.response_time_ms (should be <500ms)
+- health.database.latency_ms (should be <50ms)
+- health.redis.latency_ms (should be <10ms)
+- health.memory.heap_percent (should be <80%)
+```
+
+## Common Configurations
+
+### Minimal (memory only)
+
+```typescript
+createHealthCheckHandler({
+  enableDatabase: false,
+  enableRedis: false,
+  enableAIProvider: false,
+  enableMemory: true
+});
+```
+
+### Production (all checks)
+
+```typescript
+createHealthCheckHandler({
+  enableDatabase: true,
+  enableRedis: true,
+  enableAIProvider: true,
+  enableMemory: true,
+  includeSensitiveDetails: false,
+  timeoutMs: 5000
+});
+```
+
+### High Performance (skip optional)
+
+```typescript
+createHealthCheckHandler({
+  enableDatabase: true,
+  enableMemory: true,
+  enableRedis: false,
+  enableAIProvider: false,
+  checkTimeoutMs: 1000
+});
+```
+
+## Performance Tips
+
+1. **Cache results**: Health checks query multiple services
+2. **Use connection pools**: Don't create new connections per check
+3. **Set timeouts**: Prevent hanging on slow services
+4. **Skip optional services**: Not all checks are critical
+5. **Monitor the monitor**: Track health check latency
+
+## Files Reference
+
+| File                    | Purpose                |
+| ----------------------- | ---------------------- |
+| `health-check.ts`       | Main implementation    |
+| `health-check.types.ts` | TypeScript definitions |
+| `index.ts`              | Exports                |
+| `HEALTH_CHECK.md`       | Full documentation     |
+| `examples.ts`           | More examples          |
+| `health-check.test.ts`  | Tests                  |
+
+## Next Steps
+
+1. ✅ Copy implementation to your project
+2. ✅ Add environment variables
+3. ✅ Create endpoint in your app
+4. ✅ Test with `curl http://localhost:3000/api/health`
+5. ✅ Add Kubernetes probes
+6. ✅ Set up monitoring dashboard
+7. ✅ Configure alerting
+
+## Get Help
+
+- Read full guide: [HEALTH_CHECK.md](./HEALTH_CHECK.md)
+- View examples: [examples.ts](./examples.ts)
+- Check tests: [health-check.test.ts](./health-check.test.ts)
+- Full reference: [README.md](./README.md)

package/src/server/routes/README.md

@@ -0,0 +1,357 @@
+# AI Platform Internal Routes
+
+This package contains internal route handlers for the AI Platform, following the VERCEL_AI_SDK_V6_PATTERNS.md standards.
+
+## Overview
+
+The internal routes module provides production-ready route handlers and middleware for AI platform applications,
+including comprehensive health check endpoint patterns.
+
+## Directory Structure
+
+```
+src/internal/routes/
+├── README.md                      # This file
+├── HEALTH_CHECK.md               # Comprehensive health check documentation
+├── index.ts                      # Main exports
+├── health-check.ts               # Health check implementation
+├── health-check.types.ts         # TypeScript type definitions
+├── health-check.test.ts          # Test suite
+└── examples.ts                   # Usage examples for different frameworks
+```
+
+## Files
+
+### `health-check.ts`
+
+Main implementation file containing:
+
+- `checkHealth()`: Core health check function
+- `createHealthCheckHandler()`: Express/generic handler factory
+- `createNextHealthCheckHandler()`: Next.js 13+ handler
+- `createHealthCheckMiddleware()`: Express middleware factory
+
+### `health-check.types.ts`
+
+Comprehensive TypeScript type definitions:
+
+- `ServiceStatus`: Status levels (healthy, degraded, unhealthy)
+- `ComponentHealth`: Individual service status
+- `DatabaseHealth`: Database-specific checks
+- `RedisHealth`: Redis-specific checks
+- `AIProviderHealth`: AI model provider checks
+- `MemoryHealth`: Memory usage information
+- `HealthCheckConfig`: Configuration interface
+- `HealthCheckResult`: Response format
+
+### `index.ts`
+
+Barrel export file for all public APIs and types.
+
+### `HEALTH_CHECK.md`
+
+Detailed documentation including:
+
+- Quick start guides
+- Complete API reference
+- Configuration options
+- Usage examples
+- Best practices and anti-patterns
+- Kubernetes integration
+- Load balancer setup
+- Monitoring integration
+- Troubleshooting guide
+
+### `health-check.test.ts`
+
+Comprehensive test suite covering:
+
+- Basic health check functionality
+- All component checks (database, Redis, AI provider, memory)
+- Handler creation and execution
+- Middleware behavior
+- Status determination logic
+- Configuration options
+- Performance characteristics
+- Error handling
+
+### `examples.ts`
+
+Real-world usage examples:
+
+- Next.js 13+ Route Handlers
+- Express.js integration
+- Express middleware setup
+- Direct function calls
+- Custom health checks
+- Kubernetes deployment
+- Nginx load balancer config
+- Monitoring and alerting
+- Testing patterns
+- Environment configuration
+
+## Quick Start
+
+### Next.js
+
+```typescript
+// app/api/health/route.ts
+import { createNextHealthCheckHandler } from "@od-oneapp/ai-platform";
+
+export const GET = createNextHealthCheckHandler({
+  enableDatabase: true,
+  enableRedis: true,
+  enableAIProvider: true,
+  enableMemory: true
+});
+```
+
+### Express
+
+```typescript
+import express from "express";
+import { createHealthCheckHandler } from "@od-oneapp/ai-platform";
+
+const app = express();
+
+app.get(
+  "/health",
+  createHealthCheckHandler({
+    enableDatabase: true,
+    enableRedis: true,
+    enableAIProvider: true,
+    enableMemory: true
+  })
+);
+```
+
+## Key Features
+
+### Comprehensive Health Checks
+
+- **Database**: PostgreSQL connectivity and pool status
+- **Redis**: Connection and memory usage
+- **AI Providers**: OpenAI, Anthropic, Gemini availability
+- **Memory**: Heap usage and thresholds
+- **Custom**: Support for application-specific checks
+
+### Status Levels
+
+- **healthy** (HTTP 200): All critical dependencies operational
+- **degraded** (HTTP 200): Core works, some features unavailable
+- **unhealthy** (HTTP 503): Critical failure, cannot serve requests
+
+### Framework Support
+
+- Next.js 13+ Route Handlers
+- Express.js and compatible frameworks
+- Generic request/response handlers
+- Middleware pattern support
+
+### Production Features
+
+- Configurable timeouts with defaults
+- Parallel check execution
+- Result caching support
+- Custom check integration
+- Memory usage thresholds
+- Sensitive error suppression in production
+- Proper HTTP status codes for load balancers
+- Version and environment information
+- Response time tracking
+
+## Configuration
+
+```typescript
+interface HealthCheckConfig {
+  // Enable/disable specific checks
+  enableDatabase?: boolean;
+  enableRedis?: boolean;
+  enableAIProvider?: boolean;
+  enableMemory?: boolean;
+
+  // Custom checks
+  customChecks?: Array<{
+    name: string;
+    check: () => Promise<ComponentHealth>;
+  }>;
+
+  // Timeouts (milliseconds)
+  timeoutMs?: number; // Overall (default: 5000)
+  checkTimeoutMs?: number; // Per-check (default: 2000)
+
+  // Connection strings (uses env vars by default)
+  databaseUrl?: string;
+  redisUrl?: string;
+  aiGatewayUrl?: string;
+
+  // Memory thresholds
+  memoryWarningThreshold?: number; // (default: 80%)
+  memoryCriticalThreshold?: number; // (default: 90%)
+
+  // Response options
+  includeSensitiveDetails?: boolean;
+  version?: string;
+}
+```
+
+## Response Format
+
+```json
+{
+  "status": "healthy",
+  "timestamp": "2024-01-29T12:34:56.789Z",
+  "version": "1.0.0",
+  "environment": "production",
+  "uptime": 86400.123,
+  "responseTime": 245,
+  "checks": {
+    "database": {
+      "connected": true,
+      "status": "up",
+      "latency": 12
+    },
+    "redis": {
+      "connected": true,
+      "status": "up",
+      "latency": 5
+    },
+    "aiProvider": {
+      "available": true,
+      "status": "up",
+      "latency": 150
+    },
+    "memory": {
+      "heapUsed": 52428800,
+      "heapTotal": 209715200,
+      "heapUsedPercent": 25.0,
+      "status": "ok"
+    }
+  }
+}
+```
+
+## Best Practices
+
+1. **Keep Checks Fast**: Complete in <5 seconds
+2. **Use Connection Pools**: Reuse connections
+3. **Timeout Properly**: Set aggressive timeouts
+4. **Return Proper Status Codes**: 503 for unhealthy
+5. **Include Response Time**: Track performance
+6. **Version Information**: Verify deployments
+7. **Parallel Execution**: Run checks concurrently
+8. **Cache Results**: For frequent monitoring
+9. **Sensitive Data**: Disable in production
+10. **Monitor the Monitor**: Track health check metrics
+
+## Integration Patterns
+
+### Kubernetes
+
+- Liveness probe: `/health` (30s delay, 10s period)
+- Readiness probe: `/health` (10s delay, 5s period)
+- Startup probe: `/health` (for slow startups)
+
+### Load Balancing
+
+- Nginx health checks: `health_check uri=/health interval=10s`
+- AWS ALB: Target group health check path
+- HAProxy: Check configuration
+
+### Monitoring
+
+- Datadog: Send metrics from response
+- Prometheus: Expose metrics endpoint
+- PagerDuty: Alert on unhealthy status
+- Slack: Notify on status changes
+
+## Testing
+
+Run the test suite:
+
+```bash
+npm test -- health-check.test.ts
+```
+
+The test suite covers:
+
+- All component checks
+- Status determination
+- Handler creation and execution
+- Configuration options
+- Performance characteristics
+- Error handling and edge cases
+
+## Examples
+
+Comprehensive examples are available in `examples.ts`:
+
+- `nextAppRouterExample`: Next.js 13+ Route Handler
+- `expressExample`: Express.js handler
+- `expressMiddlewareExample`: Express middleware
+- `directCallExample`: Direct function usage
+- `customChecksExample`: Adding custom checks
+- `kubernetesExample`: K8s deployment config
+- `nginxLoadBalancerExample`: Nginx configuration
+- `monitoringIntegrationExample`: Datadog/Sentry integration
+- `testingExample`: Test patterns
+- `envConfigExample`: Environment setup
+
+## Related Documentation
+
+- [HEALTH_CHECK.md](./HEALTH_CHECK.md) - Detailed documentation
+- [VERCEL_AI_SDK_V6_PATTERNS.md](../../VERCEL_AI_SDK_V6_PATTERNS.md) - Pattern reference
+- [examples.ts](./examples.ts) - Code examples
+
+## Exports
+
+```typescript
+// Functions
+export { checkHealth };
+export { createHealthCheckHandler };
+export { createNextHealthCheckHandler };
+export { createHealthCheckMiddleware };
+
+// Types
+export type {
+  HealthCheckConfig,
+  HealthCheckResult,
+  HealthCheckMiddlewareOptions,
+  DatabaseHealth,
+  RedisHealth,
+  AIProviderHealth,
+  MemoryHealth,
+  ComponentHealth,
+  HealthChecks,
+  ServiceStatus,
+  RequestHandler
+};
+```
+
+## Performance
+
+Typical response times:
+
+- Memory checks only: 1-5ms
+- With database check: 10-50ms
+- With all checks: 50-200ms
+- With custom checks: 100-500ms (depends on custom check latency)
+
+## Anti-Patterns
+
+❌ Long-running checks (>5 seconds) ❌ Creating new DB connections per check ❌ No timeout on external service checks ❌
+Returning 200 for unhealthy state ❌ Exposing sensitive errors in production ❌ Not checking critical dependencies ❌
+Complex business logic in health checks ❌ Skipping health checks in production
+
+## Support
+
+For issues or questions:
+
+1. Check [HEALTH_CHECK.md](./HEALTH_CHECK.md) troubleshooting section
+2. Review [examples.ts](./examples.ts) for usage patterns
+3. Check test cases in [health-check.test.ts](./health-check.test.ts)
+4. Refer to [VERCEL_AI_SDK_V6_PATTERNS.md](../../VERCEL_AI_SDK_V6_PATTERNS.md)
+
+## License
+
+See main repository license.