@ceon-oy/monitor-sdk 1.0.1

package/dist/index.d.ts

@@ -0,0 +1,241 @@
+type Severity = 'DEBUG' | 'INFO' | 'WARNING' | 'ERROR' | 'CRITICAL';
+type TechnologyType = 'FRAMEWORK' | 'LIBRARY' | 'DATABASE' | 'RUNTIME' | 'TOOL' | 'OTHER';
+type SecurityCategory = 'AUTHENTICATION' | 'AUTHORIZATION' | 'RATE_LIMIT' | 'INPUT_VALIDATION' | 'SUSPICIOUS_ACTIVITY';
+type SecuritySeverity = 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL';
+interface DependencySource {
+    path: string;
+    environment: string;
+}
+interface MonitorClientConfig {
+    /** API key for authentication (required, format: cm_xxx) */
+    apiKey: string;
+    /** Endpoint URL for the monitoring server (required, must be HTTP/HTTPS) */
+    endpoint: string;
+    /** Environment label (default: 'production') */
+    environment?: string;
+    /** Number of errors to batch before sending (default: 10, min: 1) */
+    batchSize?: number;
+    /** Interval in ms between automatic flushes (default: 5000, min: 1000) */
+    flushIntervalMs?: number;
+    /** Whether to track package.json dependencies (default: false) */
+    trackDependencies?: boolean;
+    /** Path to package.json for dependency tracking */
+    packageJsonPath?: string;
+    /** Multiple dependency sources with environment labels */
+    dependencySources?: DependencySource[];
+    /** Glob patterns for packages to exclude from tracking */
+    excludePatterns?: string[];
+    /** Maximum queue size to prevent memory exhaustion (default: 1000) */
+    maxQueueSize?: number;
+    /** Maximum retry attempts for failed sends (default: 3) */
+    maxRetries?: number;
+    /** Request timeout in ms (default: 10000) */
+    requestTimeoutMs?: number;
+}
+interface TechnologyItem {
+    name: string;
+    version: string;
+    type?: TechnologyType;
+}
+interface ErrorContext {
+    severity?: Severity;
+    route?: string;
+    method?: string;
+    statusCode?: number;
+    userAgent?: string;
+    ip?: string;
+    requestId?: string;
+    metadata?: Record<string, unknown>;
+}
+interface ErrorPayload {
+    severity: Severity;
+    message: string;
+    stack?: string;
+    environment: string;
+    route?: string;
+    method?: string;
+    statusCode?: number;
+    userAgent?: string;
+    ip?: string;
+    requestId?: string;
+    metadata?: Record<string, unknown>;
+}
+interface SecurityEventInput {
+    eventType: string;
+    category: SecurityCategory;
+    severity: SecuritySeverity;
+    ip?: string;
+    identifier?: string;
+    endpoint?: string;
+    userAgent?: string;
+    metadata?: Record<string, unknown>;
+}
+interface SecurityEventPayload extends SecurityEventInput {
+    environment: string;
+}
+interface BruteForceDetectionResult {
+    detected: boolean;
+    pattern: string;
+    count: number;
+    threshold: number;
+    timeWindowMinutes: number;
+    ip?: string;
+    identifier?: string;
+}
+type VulnerabilitySeverity = 'info' | 'low' | 'moderate' | 'high' | 'critical';
+interface VulnerabilityItem {
+    packageName: string;
+    severity: VulnerabilitySeverity;
+    title: string;
+    url?: string;
+    vulnerableRange?: string;
+    installedVersion?: string;
+    patchedVersions?: string;
+    path?: string;
+    recommendation?: string;
+    cwe?: string[];
+    cvss?: number;
+    isFixable?: boolean;
+    isDirect?: boolean;
+}
+interface AuditResult {
+    environment: string;
+    totalDeps: number;
+    vulnerabilities: VulnerabilityItem[];
+    scanDurationMs: number;
+}
+interface AuditSummary {
+    scanId: string;
+    processed: number;
+    resolved: number;
+    summary: {
+        critical: number;
+        high: number;
+        moderate: number;
+        low: number;
+        info: number;
+    };
+}
+
+declare class MonitorClient {
+    private apiKey;
+    private endpoint;
+    private environment;
+    private batchSize;
+    private flushIntervalMs;
+    private queue;
+    private flushTimer;
+    private isClosed;
+    private trackDependencies;
+    private packageJsonPath?;
+    private dependencySources?;
+    private excludePatterns;
+    private maxQueueSize;
+    private maxRetries;
+    private retryCount;
+    private isFlushInProgress;
+    private requestTimeoutMs;
+    constructor(config: MonitorClientConfig);
+    captureError(error: Error, context?: ErrorContext): Promise<void>;
+    captureMessage(message: string, severity?: Severity, context?: ErrorContext): Promise<void>;
+    flush(): Promise<void>;
+    private getErrorKey;
+    close(): Promise<void>;
+    private enqueue;
+    /**
+     * Fetch with timeout to prevent hanging requests
+     */
+    private fetchWithTimeout;
+    private sendSingle;
+    private sendBatch;
+    private startFlushTimer;
+    private stopFlushTimer;
+    syncDependencies(): Promise<void>;
+    syncTechnologies(technologies: TechnologyItem[]): Promise<void>;
+    private readPackageJson;
+    private readPackageJsonFromPath;
+    private shouldExclude;
+    private sendTechnologies;
+    private sendTechnologiesWithEnvironment;
+    /**
+     * Capture a security event (auth failures, rate limits, suspicious activity, etc.)
+     * Returns brute force warning if pattern is detected
+     */
+    captureSecurityEvent(input: SecurityEventInput): Promise<{
+        warning?: BruteForceDetectionResult;
+    }>;
+    /**
+     * Capture a login failure event (convenience method)
+     */
+    captureLoginFailure(options: {
+        ip?: string;
+        identifier?: string;
+        endpoint?: string;
+        userAgent?: string;
+        reason?: string;
+        authMethod?: 'password' | 'magic_link' | 'oauth' | 'azure_ad' | 'google' | 'other';
+    }): Promise<{
+        warning?: BruteForceDetectionResult;
+    }>;
+    /**
+     * Capture a successful login event
+     */
+    captureLoginSuccess(options: {
+        ip?: string;
+        identifier?: string;
+        endpoint?: string;
+        userAgent?: string;
+        authMethod?: 'password' | 'magic_link' | 'oauth' | 'azure_ad' | 'google' | 'other';
+    }): Promise<void>;
+    /**
+     * Capture a rate limit event
+     */
+    captureRateLimit(options: {
+        ip?: string;
+        identifier?: string;
+        endpoint?: string;
+        userAgent?: string;
+        limit?: number;
+        window?: string;
+    }): Promise<void>;
+    /**
+     * Capture an authorization failure (user tried to access unauthorized resource)
+     */
+    captureAuthorizationFailure(options: {
+        ip?: string;
+        identifier?: string;
+        endpoint?: string;
+        userAgent?: string;
+        resource?: string;
+        action?: string;
+    }): Promise<void>;
+    /**
+     * Check if an IP or identifier has triggered brute force detection
+     */
+    checkBruteForce(options: {
+        ip?: string;
+        identifier?: string;
+        timeWindowMinutes?: number;
+        threshold?: number;
+    }): Promise<BruteForceDetectionResult>;
+    /**
+     * Run npm audit and send results to the monitoring server.
+     * This scans the project for known vulnerabilities in dependencies.
+     *
+     * @param options.projectPath - Path to the project directory (defaults to cwd)
+     * @param options.environment - Environment label (defaults to client environment)
+     * @returns Audit summary with vulnerability counts
+     */
+    auditDependencies(options?: {
+        projectPath?: string;
+        environment?: string;
+    }): Promise<AuditSummary | null>;
+    /**
+     * Parse npm audit JSON output into vulnerability items
+     */
+    private parseNpmAuditOutput;
+    private getFixVersion;
+    private getRecommendation;
+}
+
+export { type AuditResult, type AuditSummary, type BruteForceDetectionResult, type DependencySource, type ErrorContext, type ErrorPayload, MonitorClient, type MonitorClientConfig, type SecurityCategory, type SecurityEventInput, type SecurityEventPayload, type SecuritySeverity, type Severity, type TechnologyItem, type TechnologyType, type VulnerabilityItem, type VulnerabilitySeverity };