@scanwarp/core 0.1.0

package/dist/correlator.d.ts

@@ -0,0 +1,24 @@
+import type { Event, ProviderStatus } from './types.js';
+export interface CorrelationResult {
+    shouldCorrelate: boolean;
+    correlationGroup?: string;
+    existingIncidentId?: string;
+    reason?: string;
+}
+export declare class Correlator {
+    /**
+     * Analyzes if a new event should be correlated with existing events/incidents
+     */
+    correlate(newEvent: Event, recentEvents: Event[], openIncidents: Array<{
+        id: string;
+        events: string[];
+        correlation_group?: string;
+    }>, providerStatuses: ProviderStatus[]): Promise<CorrelationResult>;
+    private checkProviderOutage;
+    private findSameEndpoint;
+    private extractEndpoint;
+    private isCheckoutEndpoint;
+    private correlatePaymentAndCheckout;
+    private checkMultipleMonitorFailures;
+    private findIncidentWithEvent;
+}

package/dist/correlator.js

@@ -0,0 +1,173 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Correlator = void 0;
+class Correlator {
+    /**
+     * Analyzes if a new event should be correlated with existing events/incidents
+     */
+    async correlate(newEvent, recentEvents, openIncidents, providerStatuses) {
+        // Rule 1: Check if this is part of a provider outage
+        const providerOutage = this.checkProviderOutage(newEvent, providerStatuses);
+        if (providerOutage) {
+            return {
+                shouldCorrelate: true,
+                correlationGroup: `provider-${providerOutage.provider}`,
+                reason: `${providerOutage.provider} is experiencing ${providerOutage.status}`,
+            };
+        }
+        // Rule 2: Same URL/endpoint within 5 minutes
+        const sameEndpoint = this.findSameEndpoint(newEvent, recentEvents);
+        if (sameEndpoint) {
+            const incident = this.findIncidentWithEvent(sameEndpoint.id, openIncidents);
+            if (incident) {
+                return {
+                    shouldCorrelate: true,
+                    correlationGroup: incident.correlation_group || `endpoint-${this.extractEndpoint(newEvent)}`,
+                    existingIncidentId: incident.id,
+                    reason: 'Same endpoint affected within 5 minutes',
+                };
+            }
+        }
+        // Rule 3: Stripe payment failure + server 500 on checkout endpoint within 2 minutes
+        if (newEvent.source === 'stripe' || this.isCheckoutEndpoint(newEvent)) {
+            const correlated = this.correlatePaymentAndCheckout(newEvent, recentEvents);
+            if (correlated) {
+                const incident = this.findIncidentWithEvent(correlated.id, openIncidents);
+                if (incident) {
+                    return {
+                        shouldCorrelate: true,
+                        correlationGroup: incident.correlation_group || 'payment-checkout-failure',
+                        existingIncidentId: incident.id,
+                        reason: 'Payment failure correlated with checkout endpoint error',
+                    };
+                }
+                return {
+                    shouldCorrelate: true,
+                    correlationGroup: 'payment-checkout-failure',
+                    reason: 'Payment failure correlated with checkout endpoint error',
+                };
+            }
+        }
+        // Rule 4: Multiple monitors failing at once (3+ within 2 minutes)
+        const multipleFailures = this.checkMultipleMonitorFailures(newEvent, recentEvents);
+        if (multipleFailures.length >= 2) {
+            // Check if there's already an incident for this burst
+            const burstIncident = openIncidents.find((inc) => inc.correlation_group?.startsWith('multi-failure-'));
+            if (burstIncident) {
+                return {
+                    shouldCorrelate: true,
+                    correlationGroup: burstIncident.correlation_group,
+                    existingIncidentId: burstIncident.id,
+                    reason: 'Part of multi-monitor failure burst',
+                };
+            }
+            return {
+                shouldCorrelate: true,
+                correlationGroup: `multi-failure-${Date.now()}`,
+                reason: `${multipleFailures.length + 1} monitors failing simultaneously`,
+            };
+        }
+        // No correlation found
+        return { shouldCorrelate: false };
+    }
+    checkProviderOutage(event, providerStatuses) {
+        // Map event sources to provider names
+        const providerMap = {
+            vercel: 'vercel',
+            supabase: 'supabase',
+            stripe: 'stripe',
+            github: 'github',
+        };
+        const provider = providerMap[event.source];
+        if (!provider)
+            return null;
+        const status = providerStatuses.find((p) => p.provider === provider);
+        if (status && (status.status === 'degraded' || status.status === 'outage')) {
+            return status;
+        }
+        return null;
+    }
+    findSameEndpoint(newEvent, recentEvents) {
+        const fiveMinutesAgo = new Date(Date.now() - 5 * 60 * 1000);
+        const newEndpoint = this.extractEndpoint(newEvent);
+        if (!newEndpoint)
+            return null;
+        return (recentEvents.find((event) => {
+            if (event.created_at < fiveMinutesAgo)
+                return false;
+            if (event.id === newEvent.id)
+                return false;
+            const endpoint = this.extractEndpoint(event);
+            return endpoint === newEndpoint;
+        }) || null);
+    }
+    extractEndpoint(event) {
+        // Try to extract URL from monitor or raw_data
+        if (event.monitor_id && event.raw_data?.url) {
+            return String(event.raw_data.url);
+        }
+        // Try to extract from message (basic pattern matching)
+        const urlMatch = event.message.match(/https?:\/\/[^\s]+/);
+        if (urlMatch) {
+            return urlMatch[0];
+        }
+        // Extract path from message like "POST /api/checkout failed"
+        const pathMatch = event.message.match(/\/(api|checkout|webhook|auth)\/[^\s]*/);
+        if (pathMatch) {
+            return pathMatch[0];
+        }
+        return null;
+    }
+    isCheckoutEndpoint(event) {
+        const endpoint = this.extractEndpoint(event);
+        if (!endpoint)
+            return false;
+        return (endpoint.includes('/checkout') ||
+            endpoint.includes('/payment') ||
+            endpoint.includes('/stripe'));
+    }
+    correlatePaymentAndCheckout(newEvent, recentEvents) {
+        const twoMinutesAgo = new Date(Date.now() - 2 * 60 * 1000);
+        // If this is a stripe event, look for recent checkout errors
+        if (newEvent.source === 'stripe') {
+            return (recentEvents.find((event) => {
+                if (event.created_at < twoMinutesAgo)
+                    return false;
+                if (event.source === 'stripe')
+                    return false;
+                return this.isCheckoutEndpoint(event) && event.type === 'error';
+            }) || null);
+        }
+        // If this is a checkout error, look for recent stripe failures
+        if (this.isCheckoutEndpoint(newEvent) && newEvent.type === 'error') {
+            return (recentEvents.find((event) => {
+                if (event.created_at < twoMinutesAgo)
+                    return false;
+                return event.source === 'stripe' && event.type === 'error';
+            }) || null);
+        }
+        return null;
+    }
+    checkMultipleMonitorFailures(newEvent, recentEvents) {
+        if (newEvent.type !== 'down' && newEvent.type !== 'error')
+            return [];
+        const twoMinutesAgo = new Date(Date.now() - 2 * 60 * 1000);
+        return recentEvents.filter((event) => {
+            if (event.created_at < twoMinutesAgo)
+                return false;
+            if (event.id === newEvent.id)
+                return false;
+            if (event.type !== 'down' && event.type !== 'error')
+                return false;
+            // Must be from different monitors
+            if (event.monitor_id && newEvent.monitor_id && event.monitor_id === newEvent.monitor_id) {
+                return false;
+            }
+            return true;
+        });
+    }
+    findIncidentWithEvent(eventId, incidents) {
+        return incidents.find((inc) => inc.events.includes(eventId)) || null;
+    }
+}
+exports.Correlator = Correlator;

package/dist/diagnoser.d.ts

@@ -0,0 +1,26 @@
+import type { Event, Monitor, DiagnosisResult } from './types.js';
+interface DiagnoserConfig {
+    apiKey: string;
+    model?: string;
+}
+interface DiagnosisContext {
+    events: Event[];
+    monitor?: Monitor;
+    recentHistory?: Array<{
+        timestamp: Date;
+        status: string;
+        message: string;
+    }>;
+}
+export declare class Diagnoser {
+    private client;
+    private model;
+    constructor(config: DiagnoserConfig);
+    diagnose(context: DiagnosisContext): Promise<DiagnosisResult>;
+    private getSystemPrompt;
+    private buildPrompt;
+    private sanitizeRawData;
+    private parseResponse;
+    private normalizeSeverity;
+}
+export {};

package/dist/diagnoser.js

@@ -0,0 +1,159 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Diagnoser = void 0;
+const sdk_1 = __importDefault(require("@anthropic-ai/sdk"));
+class Diagnoser {
+    client;
+    model;
+    constructor(config) {
+        this.client = new sdk_1.default({
+            apiKey: config.apiKey,
+        });
+        this.model = config.model || 'claude-sonnet-4-20250514';
+    }
+    async diagnose(context) {
+        const prompt = this.buildPrompt(context);
+        const response = await this.client.messages.create({
+            model: this.model,
+            max_tokens: 2000,
+            temperature: 0.3,
+            system: this.getSystemPrompt(),
+            messages: [
+                {
+                    role: 'user',
+                    content: prompt,
+                },
+            ],
+        });
+        const content = response.content[0];
+        if (content.type !== 'text') {
+            throw new Error('Unexpected response type from Claude');
+        }
+        return this.parseResponse(content.text);
+    }
+    getSystemPrompt() {
+        return `You are a senior engineering mentor helping developers who built their application using AI coding tools like Cursor or Claude Code. These developers may not have deep infrastructure knowledge or be familiar with reading stack traces.
+
+Your job is to:
+1. Explain what went wrong in plain, conversational English (no jargon)
+2. Explain WHY it happened in a way a non-expert can understand
+3. Provide a clear, actionable fix in plain language
+4. Write a ready-to-paste prompt they can give to their AI coding assistant to fix the issue
+
+Think of yourself as a patient mentor who's explaining a production issue to someone smart but new to production systems.
+
+IMPORTANT RULES:
+- NO technical jargon without explanation
+- NO raw stack traces in your response
+- Use analogies when helpful
+- Be encouraging, not condescending
+- Focus on "what to do" not "what you did wrong"
+
+Respond in this exact JSON format:
+{
+  "root_cause": "1-2 sentence plain English explanation of what broke",
+  "severity": "critical|warning|info",
+  "suggested_fix": "Plain English explanation of how to fix it (2-4 sentences)",
+  "fix_prompt": "A complete, copy-pasteable prompt for Cursor/Claude Code that will fix this issue"
+}
+
+The fix_prompt should be detailed and include:
+- What file(s) to modify
+- What specific changes to make
+- Any environment variables or config needed
+- How to test the fix
+
+Make the fix_prompt actionable enough that an AI coding assistant can implement it without asking follow-up questions.`;
+    }
+    buildPrompt(context) {
+        const { events, monitor, recentHistory } = context;
+        let prompt = '## Production Issue Detected\n\n';
+        // Add monitor context if available
+        if (monitor) {
+            prompt += `**Service:** ${monitor.url}\n`;
+            prompt += `**Current Status:** ${monitor.status}\n\n`;
+        }
+        // Add event information
+        prompt += `**Recent Events:**\n`;
+        for (const event of events) {
+            prompt += `- [${event.type.toUpperCase()}] ${event.message}\n`;
+            prompt += `  Severity: ${event.severity} | Time: ${event.created_at.toISOString()}\n`;
+            if (event.raw_data) {
+                const sanitizedData = this.sanitizeRawData(event.raw_data);
+                if (Object.keys(sanitizedData).length > 0) {
+                    prompt += `  Details: ${JSON.stringify(sanitizedData, null, 2)}\n`;
+                }
+            }
+            prompt += '\n';
+        }
+        // Add recent history if available
+        if (recentHistory && recentHistory.length > 0) {
+            prompt += `\n**Recent History (last 24 hours):**\n`;
+            for (const item of recentHistory.slice(0, 10)) {
+                prompt += `- ${item.timestamp.toISOString()}: ${item.status} - ${item.message}\n`;
+            }
+            prompt += '\n';
+        }
+        prompt += '\nPlease diagnose this issue and provide a fix.';
+        return prompt;
+    }
+    sanitizeRawData(data) {
+        const sanitized = {};
+        // Include relevant fields, exclude sensitive or verbose ones
+        const relevantFields = [
+            'statusCode',
+            'responseTime',
+            'error',
+            'url',
+            'method',
+            'level',
+            'message',
+            'type',
+            'source',
+        ];
+        for (const field of relevantFields) {
+            if (field in data) {
+                sanitized[field] = data[field];
+            }
+        }
+        return sanitized;
+    }
+    parseResponse(text) {
+        try {
+            // Try to extract JSON from the response
+            const jsonMatch = text.match(/\{[\s\S]*\}/);
+            if (!jsonMatch) {
+                throw new Error('No JSON found in response');
+            }
+            const parsed = JSON.parse(jsonMatch[0]);
+            return {
+                root_cause: parsed.root_cause || 'Unable to determine root cause',
+                severity: this.normalizeSeverity(parsed.severity),
+                suggested_fix: parsed.suggested_fix || 'No fix suggested',
+                fix_prompt: parsed.fix_prompt || 'No fix prompt provided',
+            };
+        }
+        catch (error) {
+            // Fallback if parsing fails
+            console.error('Failed to parse diagnosis response:', error);
+            return {
+                root_cause: 'Failed to parse diagnosis from AI response',
+                severity: 'warning',
+                suggested_fix: text.substring(0, 500),
+                fix_prompt: 'Unable to generate fix prompt. Please review the raw diagnosis and consult your AI coding assistant.',
+            };
+        }
+    }
+    normalizeSeverity(severity) {
+        const normalized = severity.toLowerCase();
+        if (normalized === 'critical')
+            return 'critical';
+        if (normalized === 'warning')
+            return 'warning';
+        return 'info';
+    }
+}
+exports.Diagnoser = Diagnoser;

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from './types.js';
+export * from './diagnoser.js';
+export * from './correlator.js';

package/dist/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./types.js"), exports);
+__exportStar(require("./diagnoser.js"), exports);
+__exportStar(require("./correlator.js"), exports);

package/dist/types.d.ts

@@ -0,0 +1,115 @@
+export interface Monitor {
+    id: string;
+    project_id: string;
+    url: string;
+    check_interval_seconds: number;
+    last_checked_at?: Date;
+    status: 'up' | 'down' | 'unknown';
+    created_at: Date;
+}
+export type EventSource = 'monitor' | 'vercel' | 'stripe' | 'supabase' | 'github' | 'provider-status';
+export interface Event {
+    id: string;
+    project_id: string;
+    monitor_id?: string;
+    type: 'error' | 'slow' | 'down' | 'up';
+    source: EventSource;
+    message: string;
+    raw_data?: Record<string, unknown>;
+    severity: 'low' | 'medium' | 'high' | 'critical';
+    created_at: Date;
+}
+export interface EventStats {
+    monitor_id: string;
+    avg_response_time?: number;
+    total_checks: number;
+    error_count: number;
+    last_error_at?: Date;
+    updated_at: Date;
+}
+export interface VercelLogDrainPayload {
+    source: string;
+    deploymentId: string;
+    message: string;
+    timestamp: number;
+    type: 'stdout' | 'stderr' | 'request' | 'response';
+    level?: 'info' | 'warn' | 'error' | 'debug';
+    [key: string]: unknown;
+}
+export interface WebhookPayload {
+    event: string;
+    service: string;
+    data: Record<string, unknown>;
+    timestamp: string;
+}
+export interface Incident {
+    id: string;
+    project_id: string;
+    events: string[];
+    correlation_group?: string;
+    status: 'open' | 'investigating' | 'resolved';
+    diagnosis_text?: string;
+    diagnosis_fix?: string;
+    severity: 'critical' | 'warning' | 'info';
+    fix_prompt?: string;
+    created_at: Date;
+    resolved_at?: Date;
+}
+export interface DiagnosisResult {
+    root_cause: string;
+    severity: 'critical' | 'warning' | 'info';
+    suggested_fix: string;
+    fix_prompt: string;
+}
+export interface ProviderStatus {
+    provider: string;
+    status: 'operational' | 'degraded' | 'outage';
+    last_checked_at: Date;
+    details?: string;
+}
+export interface StripeWebhookEvent {
+    id: string;
+    type: string;
+    data: {
+        object: Record<string, unknown>;
+    };
+    [key: string]: unknown;
+}
+export interface GitHubWebhookEvent {
+    action?: string;
+    workflow_run?: {
+        conclusion: string;
+        name: string;
+        html_url: string;
+    };
+    alert?: {
+        number: number;
+        state: string;
+        html_url: string;
+    };
+    [key: string]: unknown;
+}
+export interface ProviderEvent {
+    source: EventSource;
+    type: Event['type'];
+    message: string;
+    severity: Event['severity'];
+    raw_data: Record<string, unknown>;
+}
+export interface MonitoringConfig {
+    id: string;
+    serviceName: string;
+    endpoint: string;
+    interval: number;
+    createdAt: Date;
+    updatedAt: Date;
+}
+export interface MonitoringEvent {
+    id: string;
+    configId: string;
+    status: 'success' | 'failure';
+    responseTime?: number;
+    statusCode?: number;
+    errorMessage?: string;
+    timestamp: Date;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@scanwarp/core",
+  "version": "0.1.0",
+  "description": "Shared types and logic for ScanWarp monitoring",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "monitoring",
+    "observability",
+    "ai",
+    "claude",
+    "diagnosis",
+    "production",
+    "incidents"
+  ],
+  "author": "ScanWarp",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/scanwarp/scanwarp.git",
+    "directory": "packages/core"
+  },
+  "bugs": {
+    "url": "https://github.com/scanwarp/scanwarp/issues"
+  },
+  "homepage": "https://scanwarp.com",
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "typescript": "^5.3.3"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.74.0"
+  }
+}