vigil-ai

v1.0.0

Published

a month ago

AI-powered website health intelligence — SSL, security headers, performance, and AI analysis in one call.

Downloads

141

0High
0Medium
0Low

rest_api

ai website-health uptime ssl security performance monitoring vigil pulseboard

🚨 Vigil AI

AI-powered website health intelligence — SSL, security headers, performance, and AI analysis in one call.

Monitor website uptime, SSL certificates, security headers, performance metrics, and get AI-powered insights — all from a single TypeScript package with zero dependencies.

✨ Features

Vigil AI provides 6 powerful functions to analyze websites comprehensively:

| Function | Purpose | Free Limit/mo | Use Case | |----------|---------|--------------|----------| | checkStatus() | ⚡ Uptime & response time | 50,000 | Lightweight health checks | | checkSSL() | 🔒 SSL certificate validation | 20,000 | Certificate expiry alerts | | analyzePerformance() | 📊 Full page-load metrics | 1,000 | Performance monitoring | | securityScan() | 🛡️ Security headers & tech detection | 1,000 | Security audits | | aiAnalyze() | 🤖 AI summary + recommendations | 100 | In-depth analysis | | fullReport() | 📋 Complete everything report | 50 | Comprehensive audits |

📦 Installation

npm install vigil-ai

Requires Node.js 18+ or a browser with native fetch support.

🚀 Quick Start

1. Get Your API Key

Generate a free API key (no signup required):

import { generateApiKey } from 'vigil-ai';

const { apiKey } = await generateApiKey();
console.log('Your key:', apiKey); // Save this!

Or visit: https://pulseboard.haseeb.work/vigil-ai

2. Check Website Status

import { checkStatus } from 'vigil-ai';

const result = await checkStatus('https://example.com', {
  apiKey: 'vigil_live_...',
});

console.log(result);
// Output:
// {
//   url: 'https://example.com',
//   domain: 'example.com',
//   up: true,
//   statusCode: 200,
//   responseTimeMs: 145
// }

3. Verify SSL Certificate

import { checkSSL } from 'vigil-ai';

const ssl = await checkSSL('https://example.com', {
  apiKey: 'vigil_live_...',
});

console.log(ssl);
// Output:
// {
//   url: 'https://example.com',
//   domain: 'example.com',
//   ssl: {
//     valid: true,
//     issuer: 'Let\'s Encrypt',
//     validFrom: '2024-01-15T10:30:00Z',
//     validTo: '2025-01-15T10:30:00Z',
//     daysUntilExpiry: 200
//   }
// }

4. Analyze Performance

import { analyzePerformance } from 'vigil-ai';

const perf = await analyzePerformance('https://example.com', {
  apiKey: 'vigil_live_...',
});

console.log(perf);
// Output:
// {
//   url: 'https://example.com',
//   domain: 'example.com',
//   responseTimeMs: 245,
//   statusCode: 200
// }

5. Security Scan

import { securityScan } from 'vigil-ai';

const scan = await securityScan('https://example.com', {
  apiKey: 'vigil_live_...',
});

console.log(scan);
// Output:
// {
//   url: 'https://example.com',
//   domain: 'example.com',
//   statusCode: 200,
//   securityHeaders: {
//     hasHsts: true,
//     hasCsp: true,
//     hasXFrameOptions: true,
//     hasXContentTypeOptions: true,
//     hasReferrerPolicy: true,
//     hasPermissionsPolicy: false,
//     score: 85
//   },
//   technologies: ['React', 'Node.js', 'Nginx'],
//   botProtection: {
//     detected: true,
//     provider: 'Cloudflare'
//   }
// }

6. AI Analysis with Recommendations

import { aiAnalyze } from 'vigil-ai';

const analysis = await aiAnalyze('https://example.com', {
  apiKey: 'vigil_live_...',
});

console.log(analysis);
// Output:
// {
//   analysis: {
//     url: 'https://example.com',
//     domain: 'example.com',
//     responseTimeMs: 245,
//     statusCode: 200,
//     ssl: { valid: true, daysUntilExpiry: 200, ... },
//     securityHeaders: { hasHsts: true, ... },
//     dns: { aRecords: ['93.184.216.34'], resolvedIp: '93.184.216.34' },
//     technologies: ['React', 'Node.js'],
//     serverHeader: 'Apache/2.4.41',
//     botProtection: { detected: true, provider: 'Cloudflare' }
//   },
//   aiSummary: 'Excellent website. HSTS enabled, modern stack...',
//   aiRecommendations: [
//     'Enable CSP header for XSS protection',
//     'Add Permissions-Policy for feature isolation'
//   ],
//   securityScore: 87
// }

7. Full Report

import { fullReport } from 'vigil-ai';

const report = await fullReport('https://example.com', {
  apiKey: 'vigil_live_...',
});

console.log(report);
// Returns same structure as aiAnalyze()
// (reserved for future enhancements like historical comparisons)

Convenience Alias

import { analyzeSite } from 'vigil-ai';

// Shorthand for fullReport()
const result = await analyzeSite('https://example.com', {
  apiKey: 'vigil_live_...',
});

📚 API Reference

Types

export interface VigilOptions {
  /** Your Vigil API key (required) */
  apiKey: string;
  /** Override API base URL (optional, for testing) */
  baseUrl?: string;
  /** Suppress console usage stats (default: false) */
  silent?: boolean;
}

export interface StatusResult {
  url: string;
  domain: string;
  up: boolean;
  statusCode: number;
  responseTimeMs: number;
}

export interface SslResult {
  url: string;
  domain: string;
  ssl: {
    valid: boolean;
    issuer?: string;
    validFrom?: string;
    validTo?: string;
    daysUntilExpiry?: number;
    error?: string;
  };
}

export interface PerformanceResult {
  url: string;
  domain: string;
  responseTimeMs: number;
  statusCode: number;
}

export interface SecurityScanResult {
  url: string;
  domain: string;
  statusCode: number;
  securityHeaders: {
    hasHsts: boolean;
    hasCsp: boolean;
    hasXFrameOptions: boolean;
    hasXContentTypeOptions: boolean;
    hasReferrerPolicy: boolean;
    hasPermissionsPolicy: boolean;
    score: number;
  };
  technologies: string[];
  botProtection: {
    detected: boolean;
    provider?: string;
    note?: string;
  };
}

export interface FullAnalysisResult {
  analysis: {
    url: string;
    domain: string;
    responseTimeMs: number;
    statusCode: number;
    ssl: SslResult['ssl'];
    securityHeaders: SecurityScanResult['securityHeaders'];
    dns: { aRecords: string[]; resolvedIp?: string; error?: string };
    technologies: string[];
    serverHeader?: string;
    botProtection: SecurityScanResult['botProtection'];
  };
  aiSummary: string;
  aiRecommendations: string[];
  securityScore: number;
}

export interface UsageInfo {
  endpoint: string;
  used: number;
  limit: number;
  remaining: number;
}

Functions

checkStatus()

function checkStatus(url: string, options: VigilOptions): Promise<StatusResult>

Checks if a website is online and measures response time. Cheapest endpoint — 50,000 free calls/month.

checkSSL()

function checkSSL(url: string, options: VigilOptions): Promise<SslResult>

Validates SSL certificate, checks expiry, and extracts issuer info. 20,000 free calls/month.

analyzePerformance()

function analyzePerformance(url: string, options: VigilOptions): Promise<PerformanceResult>

Performs full GET request to measure page-load performance. 1,000 free calls/month.

securityScan()

function securityScan(url: string, options: VigilOptions): Promise<SecurityScanResult>

Scans security headers (CSP, HSTS, X-Frame-Options, etc.) and detects technologies. 1,000 free calls/month.

aiAnalyze()

function aiAnalyze(url: string, options: VigilOptions): Promise<FullAnalysisResult>

Full site analysis + AI-generated summary, security score, and recommendations. 100 free calls/month.

fullReport()

function fullReport(url: string, options: VigilOptions): Promise<FullAnalysisResult>

Flagship "everything" endpoint. Same as aiAnalyze() today but reserved for future enhancements. 50 free calls/month.

analyzeSite()

function analyzeSite(url: string, options: VigilOptions): Promise<FullAnalysisResult>

Convenience alias for fullReport(). Use when you need the complete analysis.

generateApiKey()

function generateApiKey(baseUrl?: string): Promise<GenerateApiKeyResult>

Generate a new free API key without signup. Returns once; save immediately. Rate-limited per IP.

📊 Usage Limits

All limits reset monthly. Free tier includes:

| Endpoint | Monthly Limit | Cost per Extra | Tier | |----------|---------------|----------------|------| | check-status | 50,000 | $0.0001 | 🆓 Most generous | | check-ssl | 20,000 | $0.0005 | 🆓 Good for SSL monitoring | | analyze-performance | 1,000 | $0.01 | 🆓 Per full page load | | security-scan | 1,000 | $0.01 | 🆓 Per security audit | | ai-analyze | 100 | $0.50 | 💎 Premium AI insights | | full-report | 50 | $1.00 | 💎 Most comprehensive |

Exceeded quota? See Upgrade to Pro for higher limits or contact support.

⚠️ Error Handling

Vigil AI throws errors with detailed information:

import { aiAnalyze, VigilApiError } from 'vigil-ai';

try {
  const result = await aiAnalyze('https://example.com', {
    apiKey: 'vigil_live_...',
  });
} catch (error) {
  const err = error as VigilApiError;
  
  if (err.status === 401) {
    console.error('Invalid API key');
  } else if (err.code === 'QUOTA_EXCEEDED') {
    console.error(`Monthly limit exceeded. Used: ${err.usage?.used}/${err.usage?.limit}`);
  } else if (err.status === 500) {
    console.error('Server error. Try again later.');
  } else {
    console.error('Unknown error:', err.message);
  }
}

Common Error Codes

| Status | Code | Meaning | |--------|------|---------| | 400 | INVALID_URL | URL format is invalid | | 401 | UNAUTHORIZED | Missing or invalid API key | | 403 | QUOTA_EXCEEDED | Monthly limit reached | | 404 | ENDPOINT_NOT_FOUND | Endpoint doesn't exist | | 429 | RATE_LIMITED | Too many requests from your IP | | 500 | INTERNAL_ERROR | Server error |

Usage Notifications

By default, the package displays console warnings when:

✅ You've used 80%+ of your monthly quota
✅ You've reached 100% of your monthly quota

Suppress these with:

const result = await checkStatus('https://example.com', {
  apiKey: 'vigil_live_...',
  silent: true, // No console output
});

🆙 Upgrade to Pro

Need more capacity? Check your current usage and explore Pro plans:

👉 https://pulseboard.haseeb.work/vigil-ai/upgrade

Pro includes:

🚀 10-100x higher limits per endpoint
📧 Email alerts for expiring SSL certs
📈 Historical reports & trend analysis
🔐 Custom webhooks
👥 Team management

💻 Environment Variables (Optional)

# Override the default API base URL (for local testing)
export VIGIL_AI_API_URL="http://localhost:3000/api/vigil"

Then use in code:

import { checkStatus } from 'vigil-ai';

const result = await checkStatus('https://example.com', {
  apiKey: 'vigil_live_...',
});
// Automatically uses VIGIL_AI_API_URL if set

🔧 Zero Dependencies

Vigil AI uses only built-in Node.js APIs (no axios, no node-fetch):

✅ Native fetch (Node 18+)
✅ Built-in JSON parsing
✅ TypeScript types only

Result: Fast startup, small bundle, zero surprises.

📖 Examples

Monitor Multiple Sites

import { checkStatus } from 'vigil-ai';

const urls = [
  'https://example.com',
  'https://github.com',
  'https://stackoverflow.com',
];

const options = { apiKey: 'vigil_live_...' };

const results = await Promise.all(
  urls.map(url => checkStatus(url, options))
);

results.forEach(r => {
  console.log(`${r.domain}: ${r.up ? '✅' : '❌'} (${r.responseTimeMs}ms)`);
});

SSL Certificate Monitoring

import { checkSSL } from 'vigil-ai';

const ssl = await checkSSL('https://example.com', {
  apiKey: 'vigil_live_...',
});

if (ssl.ssl.valid && ssl.ssl.daysUntilExpiry! < 30) {
  console.warn(`⚠️  Certificate expires in ${ssl.ssl.daysUntilExpiry} days!`);
} else if (!ssl.ssl.valid) {
  console.error(`❌ Invalid certificate: ${ssl.ssl.error}`);
}

Security Audit

import { securityScan } from 'vigil-ai';

const scan = await securityScan('https://example.com', {
  apiKey: 'vigil_live_...',
});

console.log(`🛡️  Security Score: ${scan.securityHeaders.score}/100`);
console.log(`📦 Tech Stack: ${scan.technologies.join(', ')}`);
console.log(`🤖 Bot Protection: ${scan.botProtection.detected ? scan.botProtection.provider : 'None'}`);

Dashboard Integration

import { analyzeSite } from 'vigil-ai';

async function generateDashboard(url: string, apiKey: string) {
  const report = await analyzeSite(url, { apiKey });
  
  return {
    status: report.analysis.statusCode === 200 ? 'online' : 'offline',
    ssl: {
      valid: report.analysis.ssl.valid,
      daysLeft: report.analysis.ssl.daysUntilExpiry,
    },
    performance: report.analysis.responseTimeMs,
    security: {
      score: report.securityScore,
      summary: report.aiSummary,
      recommendations: report.aiRecommendations,
    },
  };
}

📝 License

MIT © Haseeb

🔗 Links

| Link | Purpose | |------|---------| | 🏠 Website | Homepage & Dashboard | | 📦 npm | Package registry | | 💻 GitHub | Source code | | 🆙 Upgrade | Pro plans & limits | | 🐛 Issues | Bug reports & features |

🙋 Support

📧 Issues? Open a GitHub issue
💬 Questions? Check the docs
🚀 Need Pro features? Upgrade here

Happy monitoring! 🚨✨