wizinsight/README.md

A lightweight performance monitoring & health tracking library for hyperwiz with Discord alerts and smart request optimization. Track API requests, monitor endpoint health, and get instant alerts when issues arise.

# 🔍 wizinsight

[![npm version](https://img.shields.io/npm/v/wizinsight.svg?style=flat-square)](https://www.npmjs.com/package/wizinsight)
[![npm downloads](https://img.shields.io/npm/dm/wizinsight.svg?style=flat-square)](https://www.npmjs.com/package/wizinsight)
[![bundle size](https://img.shields.io/bundlephobia/minzip/wizinsight?style=flat-square)](https://bundlephobia.com/package/wizinsight)
[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue?style=flat-square)](https://www.typescriptlang.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
[![Discord](https://img.shields.io/badge/Discord-Integration-7289da?style=flat-square&logo=discord)](https://discord.com/)

⚡ A lightweight performance monitoring & health tracking library with Discord alerts and smart request optimization. Track your API requests, monitor health, and get instant alerts when issues arise.

## ✨ Features

- 📊 **Request Metrics** - Track performance of individual API requests
- 🏥 **Health Monitoring** - Monitor multiple API endpoints with automatic alerts
- 🔔 **Discord Integration** - Get instant notifications when APIs go down
- ⚡ **Zero Configuration** - Works out of the box with sensible defaults
- 🛡️ **TypeScript Support** - Full type safety and IntelliSense

## 🚀 Quick Start

### 📦 Installation
```bash
npm install wizinsight
```

### 💻 Basic Usage
```ts
import { createClient } from 'your-http-client'
import { initMetricsInterceptor } from 'wizinsight'

// Create your HTTP client
const client = createClient('https://api.example.com')

// Enable automatic metrics tracking ✨
initMetricsInterceptor(client)

// All requests are now automatically tracked! 🎯
const users = await client.get('/users')
```

## 📊 Request Metrics

📈 Track the performance of your API requests with detailed timing and error information.

### ⭐ What You Get Automatically

Every API request now logs:
- ✅ Request method and URL
- ⏱️ Response time (duration)
- 📊 HTTP status code
- 📦 Request/response sizes (optional)
- ❌ Detailed error information

### 📋 Basic Monitoring
```ts
import { createClient } from 'your-http-client'
import { initMetricsInterceptor } from 'wizinsight'

const client = createClient('https://api.example.com')
initMetricsInterceptor(client)

// Console output:
// ✅ GET /users - 245ms - 200 OK
// ✅ POST /users - 180ms - 201 Created
// ❌ GET /invalid - 1200ms - 404 Not Found
```

### 🎨 Custom Logging
```ts
initMetricsInterceptor(client, {
  onRequestEnd: (metrics) => {
    console.log(`🚀 ${metrics.method} ${metrics.url} took ${metrics.duration}ms`)
  },
  
  onRequestError: (metrics) => {
    console.error(`💥 ${metrics.method} ${metrics.url} failed: ${metrics.errorMessage}`)
  }
})
```

### ⚠️ Performance Alerts
```ts
initMetricsInterceptor(client, {
  onRequestEnd: (metrics) => {
    // Alert on slow requests
    if (metrics.duration > 1000) {
      console.warn(`🐌 Slow request: ${metrics.method} ${metrics.url} took ${metrics.duration}ms`)
    }
    
    // Alert on errors
    if (metrics.status >= 400) {
      console.error(`❌ Error: ${metrics.method} ${metrics.url} returned ${metrics.status}`)
    }
  }
})
```

### 📊 Collect All Metrics
```ts
initMetricsInterceptor(client, {
  collectRequestSize: true,
  collectResponseSize: true,
  
  onRequestEnd: (metrics) => {
    console.log(`📊 ${metrics.method} ${metrics.url}`)
    console.log(`   ⏱️  Duration: ${metrics.duration}ms`)
    console.log(`   📊 Status: ${metrics.status}`)
    console.log(`   📦 Request: ${metrics.requestSize} bytes`)
    console.log(`   📦 Response: ${metrics.responseSize} bytes`)
  }
})
```

### 📈 Custom Analytics Dashboard
```ts
const performanceData = {
  totalRequests: 0,
  averageResponseTime: 0,
  errorCount: 0
}

initMetricsInterceptor(client, {
  onRequestEnd: (metrics) => {
    performanceData.totalRequests++
    
    // Calculate average response time
    performanceData.averageResponseTime = 
      (performanceData.averageResponseTime + metrics.duration) / 2
    
    // Count errors
    if (metrics.status >= 400) {
      performanceData.errorCount++
    }
    
    console.table(performanceData)
  }
})
```

## 🏥 Health Monitoring

Monitor the health of multiple API endpoints with automatic alerts and status tracking.

### Why Health Monitoring?

- 🔍 **Proactive Monitoring** - Catch issues before users do
- 📢 **Instant Alerts** - Get notified immediately when APIs go down
- 📊 **Status Tracking** - Keep track of API health over time
- 🛡️ **Prevent Downtime** - Identify and fix issues quickly

### Basic Health Monitoring
```ts
import { initHealthMonitor, getHealthStatus } from 'wizinsight'

// Simple health monitoring
initHealthMonitor({
  targets: [
    { name: 'User API', url: 'https://api.example.com/users' },
    { name: 'Auth API', url: 'https://auth.example.com/health' },
    { name: 'Database', url: 'https://db.example.com/ping' }
  ]
})

// Check current health status
const health = getHealthStatus()
console.log(health)
```

### Simple Request Examples
```ts
// GET request (default)
{ name: 'API', url: 'https://api.example.com/health' }

// POST with JSON body
{ 
  name: 'GraphQL', 
  url: 'https://api.example.com/graphql',
  method: 'POST',
  body: { query: '{ __typename }' }
}

// POST with headers
{ 
  name: 'Auth', 
  url: 'https://api.example.com/auth',
  method: 'POST',
  body: { token: 'test' },
  headers: { 'Authorization': 'Bearer test' }
}

// With timeout
{ 
  name: 'Slow API', 
  url: 'https://api.example.com/slow',
  timeout: 5000
}
```

### Real API Testing Examples
```ts
// Test login with real credentials
{
  name: 'Login API',
  url: 'https://api.example.com/login',
  method: 'POST',
  body: { username: 'realuser', password: 'realpass' },
  expectedStatus: 200
}

// Test registration
{
  name: 'Register API',
  url: 'https://api.example.com/register',
  method: 'POST',
  body: { 
    email: 'test@example.com', 
    password: 'testpass',
    name: 'Test User'
  },
  expectedStatus: 201
}

// Test protected endpoint with token
{
  name: 'User Profile',
  url: 'https://api.example.com/user/profile',
  method: 'GET',
  headers: { 'Authorization': 'Bearer your-token-here' },
  expectedStatus: 200
}
```

**Example Output:**
```json
{
  "https://api.example.com/users": {
    "lastChecked": 1703123456789,
    "lastStatus": 200,
    "isHealthy": true
  },
  "https://auth.example.com/health": {
    "lastChecked": 1703123456789,
    "lastStatus": 503,
    "isHealthy": false,
    "lastError": "Expected 200, got 503"
  }
}
```

### Health Monitoring with Discord Alerts
```ts
initHealthMonitor({
  targets: [
    { name: 'Production API', url: 'https://api.production.com/health' },
    { name: 'Staging API', url: 'https://api.staging.com/health' }
  ],
  interval: 30000, // Check every 30 seconds
  discordWebhook: 'https://discord.com/api/webhooks/your-webhook-url',
  alertCooldown: 600000 // 10 minutes between alerts
})
```

**Discord Alert Example:**
```
🚨 Health Check Failed: Production API
API endpoint is not responding as expected

🔗 URL: https://api.production.com/health
📊 Status: 503
⏱️ Response Time: 245ms
🎯 Expected: 200
❌ Error: Expected 200, got 503
```

### Advanced Configuration
```ts
initHealthMonitor({
  targets: [
    // Simple GET request
    { name: 'Health Check', url: 'https://api.example.com/health' },
    
    // POST with JSON body
    {
      name: 'GraphQL API',
      url: 'https://api.example.com/graphql',
      method: 'POST',
      body: { query: '{ __typename }' }
    },
    
    // POST with custom headers
    {
      name: 'Auth API',
      url: 'https://api.example.com/auth/verify',
      method: 'POST',
      body: { token: 'test-token' },
      headers: { 'Authorization': 'Bearer test-token' }
    },
    
    // POST with string body
    {
      name: 'File Upload',
      url: 'https://api.example.com/upload',
      method: 'POST',
      body: 'test-data',
      headers: { 'Content-Type': 'text/plain' }
    },
    
    // With timeout
    {
      name: 'Slow API',
      url: 'https://api.example.com/slow',
      timeout: 5000
    }
  ],
  interval: 60000, // 1 minute
  discordWebhook: process.env.DISCORD_WEBHOOK_URL,
  alertCooldown: 900000 // 15 minutes
})
```

### Programmatic Health Checks
```ts
// Check if any services are down
const health = getHealthStatus()
const unhealthyServices = Object.entries(health).filter(([url, status]) => !status.isHealthy)

if (unhealthyServices.length > 0) {
  console.log('❌ Unhealthy services detected:')
  unhealthyServices.forEach(([url, status]) => {
    console.log(`   - ${url}: ${status.lastError}`)
  })
} else {
  console.log('✅ All services are healthy!')
}
```

### Stop Health Monitoring
```ts
import { stopHealthMonitor } from 'wizinsight'

// Stop monitoring when shutting down your app
stopHealthMonitor()
```

## ⚙️ Configuration Options

### Metrics Interceptor Options

| Option | Description | Default |
|--------|-------------|---------|
| `onRequestStart` | Called when request starts | - |
| `onRequestEnd` | Called when request completes | - |
| `onRequestError` | Called when request fails | - |
| `collectRequestSize` | Track request payload size | `false` |
| `collectResponseSize` | Track response payload size | `false` |

### Health Monitor Options

| Option | Description | Default |
|--------|-------------|---------|
| `targets` | Array of API endpoints to monitor | **Required** |
| `interval` | Health check interval in milliseconds | `60000` (60s) |
| `discordWebhook` | Discord webhook URL for alerts | - |
| `alertCooldown` | Time between alerts in milliseconds | `900000` (15m) |

### Health Target Configuration

| Option | Description | Default |
|--------|-------------|---------|
| `name` | Display name for the API | **Required** |
| `url` | API endpoint URL | **Required** |
| `method` | HTTP method for health check | `GET` |
| `body` | Request body (any type) | - |
| `headers` | Request headers | - |
| `expectedStatus` | Expected HTTP status code | `200` |
| `timeout` | Request timeout in milliseconds | - |


## 🛠️ Development

```bash
# Install dependencies
npm install

# Build the library
npm run build

# Development mode with watch
npm run dev

# Type checking
npm run type-check
```

## 📝 Examples

### Real-World Usage
```ts
// In your main application file
import { createClient } from 'hyperwiz'
import { initMetricsInterceptor, initHealthMonitor } from 'wizinsight'

// Set up API client with metrics
const client = createClient('https://api.yourcompany.com')
initMetricsInterceptor(client, {
  onRequestEnd: (metrics) => {
    if (metrics.duration > 1000) {
      console.warn(`Slow API call: ${metrics.url}`)
    }
  }
})

// Set up simple health monitoring
initHealthMonitor({
  targets: [
    // Basic health check
    { name: 'Main API', url: 'https://api.yourcompany.com/health' },
    
    // Test login
    {
      name: 'Login Service',
      url: 'https://api.yourcompany.com/login',
      method: 'POST',
      body: { username: 'healthuser', password: 'healthpass' },
      expectedStatus: 200
    },
    
    // Test registration
    {
      name: 'Registration',
      url: 'https://api.yourcompany.com/register',
      method: 'POST',
      body: { 
        email: 'health@test.com', 
        password: 'testpass',
        name: 'Health Test User'
      },
      expectedStatus: 201
    },
    
    // Test protected endpoint
    {
      name: 'User Profile',
      url: 'https://api.yourcompany.com/user/profile',
      method: 'GET',
      headers: { 'Authorization': 'Bearer your-token-here' },
      expectedStatus: 200
    }
  ],
  interval: 30000,
  discordWebhook: process.env.DISCORD_WEBHOOK_URL
})
```

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## 📄 License

MIT License - see the [LICENSE](LICENSE) file for details.