🔍 wizinsight

⚡ 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

npm install wizinsight

💻 Basic Usage

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

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

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

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

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

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

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

// 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

// 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: '[email protected]', 
    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:

{
  "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

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

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

// 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

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

# 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

// 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: '[email protected]', 
        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 file for details.