@ceon-oy/monitor-sdk 1.0.1

package/README.md

@@ -0,0 +1,261 @@
+# Ceon Monitor - SDK
+
+Lightweight client SDK for sending errors and messages to the Ceon Monitor service.
+
+## Installation
+
+```bash
+# From GitHub
+npm install github:ceon-oy/ceon-monitor-sdk
+```
+
+Or add to your `package.json`:
+
+```json
+{
+  "dependencies": {
+    "@ceon/monitor-sdk": "github:ceon-oy/ceon-monitor-sdk"
+  }
+}
+```
+
+## Related
+
+- [Ceon Monitor](https://github.com/ceon-oy/ceon-monitor) - Main monitoring server and dashboard
+
+## Quick Start
+
+```typescript
+import { MonitorClient } from '@ceon/monitor-sdk';
+
+// Initialize the client
+const monitor = new MonitorClient({
+  apiKey: process.env.MONITOR_API_KEY!,
+  endpoint: 'https://monitor.example.com',
+  environment: process.env.NODE_ENV,
+});
+
+// Capture an error
+try {
+  await riskyOperation();
+} catch (error) {
+  await monitor.captureError(error as Error, {
+    route: '/api/users',
+    method: 'POST',
+    statusCode: 500,
+  });
+}
+
+// Capture a message
+await monitor.captureMessage('User signed up', 'INFO', {
+  metadata: { userId: '123', plan: 'premium' },
+});
+
+// Flush and close before shutdown
+await monitor.close();
+```
+
+## Configuration
+
+```typescript
+interface MonitorClientConfig {
+  apiKey: string;           // Your project API key
+  endpoint: string;         // Monitor service URL
+  environment?: string;     // Environment name (default: 'production')
+  batchSize?: number;       // Errors to batch before sending (default: 10)
+  flushIntervalMs?: number; // Auto-flush interval in ms (default: 5000)
+}
+```
+
+## API
+
+### `MonitorClient`
+
+#### `constructor(config: MonitorClientConfig)`
+
+Creates a new monitor client instance.
+
+```typescript
+const monitor = new MonitorClient({
+  apiKey: 'cm_your_api_key_here',
+  endpoint: 'https://monitor.example.com',
+  environment: 'production',
+  batchSize: 10,
+  flushIntervalMs: 5000,
+});
+```
+
+#### `captureError(error: Error, context?: ErrorContext): Promise<void>`
+
+Captures an error and queues it for sending.
+
+```typescript
+await monitor.captureError(error, {
+  severity: 'ERROR',        // DEBUG, INFO, WARNING, ERROR, CRITICAL
+  route: '/api/users',      // API route or page path
+  method: 'POST',           // HTTP method
+  statusCode: 500,          // HTTP status code
+  userAgent: req.headers['user-agent'],
+  ip: req.ip,
+  requestId: req.id,
+  metadata: {               // Any additional data
+    userId: '123',
+    action: 'create_user',
+  },
+});
+```
+
+#### `captureMessage(message: string, severity?: Severity, context?: ErrorContext): Promise<void>`
+
+Captures a log message.
+
+```typescript
+await monitor.captureMessage('Payment processed', 'INFO', {
+  metadata: { orderId: '456', amount: 99.99 },
+});
+```
+
+#### `flush(): Promise<void>`
+
+Immediately sends all queued errors. Called automatically based on `flushIntervalMs` and `batchSize`.
+
+```typescript
+await monitor.flush();
+```
+
+#### `close(): Promise<void>`
+
+Flushes remaining errors and stops the client. Call this before your application shuts down.
+
+```typescript
+await monitor.close();
+```
+
+## Usage Examples
+
+### Express.js Error Handler
+
+```typescript
+import { MonitorClient } from '@ceon/monitor-sdk';
+import { ErrorRequestHandler } from 'express';
+
+const monitor = new MonitorClient({
+  apiKey: process.env.MONITOR_API_KEY!,
+  endpoint: process.env.MONITOR_ENDPOINT!,
+  environment: process.env.NODE_ENV,
+});
+
+export const errorHandler: ErrorRequestHandler = (err, req, res, next) => {
+  monitor.captureError(err, {
+    route: req.path,
+    method: req.method,
+    statusCode: res.statusCode || 500,
+    userAgent: req.headers['user-agent'],
+    ip: req.ip,
+    metadata: {
+      query: req.query,
+      body: req.body,
+    },
+  });
+
+  res.status(500).json({ error: 'Internal server error' });
+};
+
+// Graceful shutdown
+process.on('SIGTERM', async () => {
+  await monitor.close();
+  process.exit(0);
+});
+```
+
+### Next.js API Route
+
+```typescript
+import { MonitorClient } from '@ceon/monitor-sdk';
+import { NextRequest, NextResponse } from 'next/server';
+
+const monitor = new MonitorClient({
+  apiKey: process.env.MONITOR_API_KEY!,
+  endpoint: process.env.MONITOR_ENDPOINT!,
+  environment: process.env.NODE_ENV,
+});
+
+export async function POST(req: NextRequest) {
+  try {
+    const body = await req.json();
+    // ... handle request
+    return NextResponse.json({ success: true });
+  } catch (error) {
+    await monitor.captureError(error as Error, {
+      route: '/api/example',
+      method: 'POST',
+      statusCode: 500,
+    });
+    return NextResponse.json({ error: 'Internal error' }, { status: 500 });
+  }
+}
+```
+
+### Integration with Existing Logger
+
+```typescript
+import { MonitorClient } from '@ceon/monitor-sdk';
+
+const monitor = new MonitorClient({
+  apiKey: process.env.MONITOR_API_KEY!,
+  endpoint: process.env.MONITOR_ENDPOINT!,
+});
+
+// Wrap your existing logger
+export function logError(message: string, error?: Error, context?: object) {
+  // Your existing logging
+  console.error(message, error);
+
+  // Also send to monitor
+  if (error) {
+    monitor.captureError(error, { metadata: context });
+  } else {
+    monitor.captureMessage(message, 'ERROR', { metadata: context });
+  }
+}
+```
+
+## Batching Behavior
+
+The SDK batches errors to reduce network overhead:
+
+1. Errors are queued locally
+2. Queue is flushed when:
+   - `batchSize` errors are queued (default: 10)
+   - `flushIntervalMs` milliseconds pass (default: 5000ms)
+   - `flush()` is called manually
+   - `close()` is called
+
+For serverless/edge environments where the process may terminate quickly, consider:
+- Setting `batchSize: 1` to send immediately
+- Calling `await monitor.flush()` at the end of each request
+
+## Building
+
+```bash
+npm install
+npm run build    # Build for production
+npm run dev      # Watch mode for development
+```
+
+## Types
+
+```typescript
+type Severity = 'DEBUG' | 'INFO' | 'WARNING' | 'ERROR' | 'CRITICAL';
+
+interface ErrorContext {
+  severity?: Severity;
+  route?: string;
+  method?: string;
+  statusCode?: number;
+  userAgent?: string;
+  ip?: string;
+  requestId?: string;
+  metadata?: Record<string, unknown>;
+}
+```

package/dist/index.d.mts

@@ -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 };