@shieldpress/tracker 1.0.0

package/dist/tracker-BJBniOSu.d.ts

@@ -0,0 +1,379 @@
+/** Configuration options for ShieldPress Tracker */
+interface TrackerConfig {
+    /** API key from ShieldPress dashboard */
+    apiKey: string;
+    /** Site ID registered in ShieldPress */
+    siteId: string;
+    /** ShieldPress API base URL */
+    apiUrl?: string;
+    /** Reporting interval in seconds (default: 60) */
+    reportInterval?: number;
+    /** Enable system metrics collection — CPU, RAM, disk (default: true) */
+    systemMetrics?: boolean;
+    /** Enable HTTP request tracking (default: true) */
+    httpTracking?: boolean;
+    /** Enable error tracking (default: true) */
+    errorTracking?: boolean;
+    /** Enable security monitoring (default: true) */
+    securityTracking?: boolean;
+    /** Enable dependency vulnerability audit (default: true) */
+    depAudit?: boolean;
+    /** Dependency audit interval in seconds (default: 3600 = 1 hour) */
+    depAuditInterval?: number;
+    /** Enable runtime performance tracking — event loop lag, GC (default: true) */
+    runtimeMetrics?: boolean;
+    /** Enable environment security scan (default: true) */
+    envSecurity?: boolean;
+    /** Enable uptime heartbeat (default: true) */
+    heartbeat?: boolean;
+    /** Custom app name for identification */
+    appName?: string;
+    /** App version string */
+    appVersion?: string;
+    /** Environment label (e.g. production, staging) */
+    environment?: string;
+    /** Custom tags for filtering */
+    tags?: Record<string, string>;
+    /** Paths to ignore from HTTP tracking (glob patterns) */
+    ignorePaths?: string[];
+    /** Max error events buffered before flush (default: 100) */
+    maxErrorBuffer?: number;
+    /** Max security events buffered before flush (default: 500) */
+    maxSecurityBuffer?: number;
+    /** Debug mode — logs to console (default: false) */
+    debug?: boolean;
+}
+/** Resolved config with defaults applied */
+interface ResolvedConfig extends Required<Omit<TrackerConfig, 'tags'>> {
+    tags: Record<string, string>;
+}
+/** System-level metrics snapshot */
+interface SystemMetrics {
+    cpuPercent: number;
+    cpuCount: number;
+    memUsedMb: number;
+    memTotalMb: number;
+    memPercent: number;
+    heapUsedMb: number;
+    heapTotalMb: number;
+    externalMb: number;
+    rss: number;
+    uptimeSeconds: number;
+    loadAvg: [number, number, number];
+    platform: string;
+    nodeVersion: string;
+    pid: number;
+    osName: string;
+    osVersion: string;
+    osKernel: string;
+    osArch: string;
+    osRelease: string;
+    diskUsedGb: number;
+    diskTotalGb: number;
+    diskPercent: number;
+    publicIp: string;
+    privateIp: string;
+    hostname: string;
+    ppid: number;
+    uid: number | null;
+    cwd: string;
+    execPath: string;
+    nodeArgs: string;
+}
+/** Aggregated HTTP metrics for a reporting window */
+interface HttpMetrics {
+    totalRequests: number;
+    totalErrors: number;
+    avgResponseMs: number;
+    p50ResponseMs: number;
+    p95ResponseMs: number;
+    p99ResponseMs: number;
+    maxResponseMs: number;
+    statusCodes: Record<string, number>;
+    topPaths: PathMetric[];
+    requestsPerSecond: number;
+}
+/** Per-path HTTP metrics */
+interface PathMetric {
+    path: string;
+    method: string;
+    count: number;
+    avgMs: number;
+    p95Ms: number;
+    errorCount: number;
+}
+/** Error event captured by the tracker */
+interface ErrorEvent {
+    message: string;
+    stack?: string;
+    type: string;
+    timestamp: string;
+    url?: string;
+    method?: string;
+    statusCode?: number;
+    meta?: Record<string, unknown>;
+}
+/** Security event severity levels */
+type SecuritySeverity = "critical" | "high" | "medium" | "low" | "info";
+/** Types of security events */
+type SecurityEventType = "auth_failure" | "auth_brute_force" | "rate_limit_hit" | "suspicious_path" | "sql_injection" | "xss_attempt" | "command_injection" | "oversized_payload" | "invalid_content_type" | "bot_detected" | "cors_violation" | "csrf_violation" | "api_key_exposed" | "sensitive_data_exposed" | "custom";
+/** Individual security event */
+interface SecurityEvent {
+    type: SecurityEventType;
+    severity: SecuritySeverity;
+    message: string;
+    timestamp: string;
+    ip?: string;
+    userAgent?: string;
+    url?: string;
+    method?: string;
+    payload?: string;
+    meta?: Record<string, unknown>;
+}
+/** Aggregated security metrics for a reporting window */
+interface SecurityMetrics {
+    totalEvents: number;
+    bySeverity: Record<SecuritySeverity, number>;
+    byType: Record<string, number>;
+    topOffendingIps: Array<{
+        ip: string;
+        count: number;
+        types: string[];
+    }>;
+    events: SecurityEvent[];
+}
+/** Vulnerability found in a dependency */
+interface DepVulnerability {
+    package: string;
+    installedVersion: string;
+    severity: "critical" | "high" | "moderate" | "low";
+    title: string;
+    url?: string;
+    patchedVersions?: string;
+    cwe?: string[];
+}
+/** Dependency audit result */
+interface DepAuditResult {
+    totalDeps: number;
+    totalVulnerabilities: number;
+    bySeverity: Record<string, number>;
+    vulnerabilities: DepVulnerability[];
+    outdatedCount: number;
+    lastAuditAt: string;
+}
+/** Event loop and GC metrics */
+interface RuntimeMetrics {
+    eventLoopLagMs: number;
+    eventLoopLagP99Ms: number;
+    activeHandles: number;
+    activeRequests: number;
+    gcPausesMsTotal: number;
+    gcPausesCount: number;
+    heapSpaces?: HeapSpaceInfo[];
+}
+/** V8 heap space detail */
+interface HeapSpaceInfo {
+    name: string;
+    sizeMb: number;
+    usedMb: number;
+    availableMb: number;
+}
+/** Environment security check result */
+interface EnvSecurityReport {
+    nodeVersion: string;
+    nodeVersionSecure: boolean;
+    npmVersion?: string;
+    frameworkName?: string;
+    frameworkVersion?: string;
+    securityHeaders: SecurityHeaderCheck[];
+    envVarWarnings: string[];
+    tlsVersions?: string[];
+    debugModeEnabled: boolean;
+    sourceMapExposed: boolean;
+    v8Version?: string;
+    uvVersion?: string;
+    opensslVersion?: string;
+    zlibVersion?: string;
+    icuVersion?: string;
+    nodeEnv?: string;
+    tz?: string;
+    memoryLimitMb?: number | null;
+    port?: number | null;
+    host?: string;
+    dnsServers?: string[];
+}
+/** Security header check result */
+interface SecurityHeaderCheck {
+    header: string;
+    present: boolean;
+    value?: string;
+    recommendation?: string;
+}
+/** Full report payload sent to ShieldPress API */
+interface ReportPayload {
+    siteId: string;
+    appName: string;
+    appVersion: string;
+    environment: string;
+    tags: Record<string, string>;
+    timestamp: string;
+    system?: SystemMetrics;
+    http?: HttpMetrics;
+    errors?: ErrorEvent[];
+    security?: SecurityMetrics;
+    depAudit?: DepAuditResult;
+    runtime?: RuntimeMetrics;
+    envSecurity?: EnvSecurityReport;
+    heartbeat?: boolean;
+}
+
+declare class HttpCollector {
+    private records;
+    private windowStart;
+    record(req: {
+        path: string;
+        method: string;
+        statusCode: number;
+        durationMs: number;
+    }): void;
+    flush(): HttpMetrics | null;
+    private _flush;
+}
+
+declare class ErrorCollector {
+    private buffer;
+    private maxBuffer;
+    constructor(maxBuffer: number);
+    capture(error: Error | string, meta?: {
+        url?: string;
+        method?: string;
+        statusCode?: number;
+        [key: string]: unknown;
+    }): void;
+    flush(): ErrorEvent[];
+    get size(): number;
+}
+
+declare class SecurityCollector {
+    private events;
+    private maxBuffer;
+    private ipCounter;
+    constructor(maxBuffer: number);
+    /** Record a security event directly */
+    record(event: Omit<SecurityEvent, "timestamp">): void;
+    /** Analyze an incoming HTTP request for security threats */
+    analyzeRequest(req: {
+        url: string;
+        method: string;
+        headers: Record<string, string | string[] | undefined>;
+        body?: string;
+        ip?: string;
+        query?: Record<string, unknown>;
+    }): void;
+    private _analyzeRequest;
+    /** Analyze response for sensitive data leaks */
+    analyzeResponse(data: {
+        url: string;
+        statusCode: number;
+        body?: string;
+        headers?: Record<string, string>;
+    }): void;
+    /** Record an authentication failure */
+    recordAuthFailure(data: {
+        ip?: string;
+        userAgent?: string;
+        url?: string;
+        method?: string;
+        reason?: string;
+    }): void;
+    /** Record a rate limit event */
+    recordRateLimit(data: {
+        ip?: string;
+        url?: string;
+        method?: string;
+        limit?: number;
+    }): void;
+    /** Record a CORS violation */
+    recordCorsViolation(data: {
+        ip?: string;
+        origin?: string;
+        url?: string;
+    }): void;
+    /** Record a custom security event */
+    recordCustom(type: SecurityEventType, severity: SecuritySeverity, message: string, meta?: Record<string, unknown>): void;
+    /** Flush and return aggregated security metrics */
+    flush(): SecurityMetrics | null;
+    private trackIp;
+    private checkBruteForce;
+}
+
+declare class ShieldPressTracker {
+    readonly config: ResolvedConfig;
+    readonly httpCollector: HttpCollector;
+    readonly errorCollector: ErrorCollector;
+    readonly securityCollector: SecurityCollector;
+    private logger;
+    private reporter;
+    private depAuditCollector;
+    private envSecurityCollector;
+    private timer;
+    private lagTimer;
+    private started;
+    private headersChecked;
+    constructor(userConfig: TrackerConfig);
+    /** Start the tracker — begins periodic reporting */
+    start(): this;
+    /** Stop the tracker */
+    stop(): void;
+    /** Manually record an HTTP request */
+    recordRequest(data: {
+        path: string;
+        method: string;
+        statusCode: number;
+        durationMs: number;
+    }): void;
+    /** Analyze an incoming request for security threats */
+    analyzeRequest(req: {
+        url: string;
+        method: string;
+        headers: Record<string, string | string[] | undefined>;
+        body?: string;
+        ip?: string;
+        query?: Record<string, unknown>;
+    }): void;
+    /** Analyze a response for security issues (headers, data leaks) */
+    analyzeResponse(data: {
+        url: string;
+        statusCode: number;
+        headers?: Record<string, string>;
+        body?: string;
+    }): void;
+    /** Record an authentication failure */
+    recordAuthFailure(data: {
+        ip?: string;
+        userAgent?: string;
+        url?: string;
+        method?: string;
+        reason?: string;
+    }): void;
+    /** Record a rate limit event */
+    recordRateLimit(data: {
+        ip?: string;
+        url?: string;
+        method?: string;
+        limit?: number;
+    }): void;
+    /** Record a CORS violation */
+    recordCorsViolation(data: {
+        ip?: string;
+        origin?: string;
+        url?: string;
+    }): void;
+    /** Manually capture an error */
+    captureError(error: Error | string, meta?: Record<string, unknown>): void;
+    /** Flush all collected data and send report */
+    flush(): Promise<boolean>;
+    private shouldIgnorePath;
+}
+
+export { type DepAuditResult as D, type EnvSecurityReport as E, type HeapSpaceInfo as H, type PathMetric as P, type ResolvedConfig as R, ShieldPressTracker as S, type TrackerConfig as T, type SystemMetrics as a, type RuntimeMetrics as b, type SecurityHeaderCheck as c, type ReportPayload as d, type DepVulnerability as e, ErrorCollector as f, type ErrorEvent as g, HttpCollector as h, type HttpMetrics as i, SecurityCollector as j, type SecurityEvent as k, type SecurityEventType as l, type SecurityMetrics as m, type SecuritySeverity as n };

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@shieldpress/tracker",
+  "version": "1.0.0",
+  "description": "Website tracking & monitoring SDK for Node.js, Next.js, Express — reports metrics to ShieldPress",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    },
+    "./express": {
+      "types": "./dist/express.d.ts",
+      "import": "./dist/express.mjs",
+      "require": "./dist/express.js"
+    },
+    "./nextjs": {
+      "types": "./dist/nextjs.d.ts",
+      "import": "./dist/nextjs.mjs",
+      "require": "./dist/nextjs.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "shieldpress",
+    "monitoring",
+    "tracking",
+    "uptime",
+    "nodejs",
+    "nextjs",
+    "express",
+    "apm",
+    "metrics",
+    "performance"
+  ],
+  "author": "ShieldPress",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/express": "^5.0.6",
+    "@types/node": "^22.0.0",
+    "next": "^16.2.10",
+    "tsup": "^8.4.0",
+    "typescript": "^5.7.0"
+  },
+  "peerDependencies": {
+    "express": ">=4.0.0",
+    "next": ">=13.0.0"
+  },
+  "peerDependenciesMeta": {
+    "next": {
+      "optional": true
+    },
+    "express": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/shieldpress/tracker"
+  }
+}