wizinsight

🔍 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: '[e-mail]', 
    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: '[e-mail]', 
        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.