@ceon-oy/monitor-sdk 1.0.13 → 1.0.15

package/README.md

@@ -17,6 +17,7 @@ Lightweight client SDK for integrating with the Ceon Monitor service. Provides e
   - [Next.js](#nextjs)
   - [React (Monolithic)](#react-monolithic)
   - [React (Separate Server/Client)](#react-separate-serverclient)
+- [Real-World Example: Full-Stack Monitoring](#real-world-example-full-stack-monitoring)
 - [API Reference](#api-reference)
 - [Batching Behavior](#batching-behavior)
 - [Building](#building)
@@ -855,6 +856,127 @@ root.render(
 );
 ```
 
+## Real-World Example: Full-Stack Monitoring
+
+This example shows how the Ceon Hours project monitors both server and client code from a single SDK installation on the server.
+
+**Project Structure:**
+```
+ceon-projects/
+├── ceon-hours-api/          # Express server (SDK installed here)
+│   ├── package.json
+│   └── lib/config/monitor-setup.js
+└── ceon-hours-web-app/      # React client (no SDK needed)
+    └── package.json
+```
+
+**1. Monitor Setup (`ceon-hours-api/lib/config/monitor-setup.js`):**
+
+```javascript
+const { MonitorClient } = require("@ceon-oy/monitor-sdk");
+
+let monitor = null;
+
+function initializeMonitor() {
+  if (process.env.CEON_MONITOR_API_KEY) {
+    monitor = new MonitorClient({
+      apiKey: process.env.CEON_MONITOR_API_KEY,
+      endpoint: process.env.CEON_MONITOR_ENDPOINT || "https://ceonmonitor.com",
+      environment: "server",
+      trackDependencies: true,
+      autoAudit: true,
+      // Track dependencies from both server AND client
+      dependencySources: [
+        { path: "./package.json", environment: "server" },
+        { path: "../ceon-hours-web-app/package.json", environment: "client" },
+      ],
+      // Audit vulnerabilities in both
+      auditPaths: [
+        { path: ".", environment: "server" },
+        { path: "../ceon-hours-web-app", environment: "client" },
+      ],
+    });
+    console.log("[CeonMonitor] SDK initialized");
+  }
+  return monitor;
+}
+
+function getMonitor() {
+  return monitor;
+}
+
+module.exports = { initializeMonitor, getMonitor };
+```
+
+**2. Initialize in Server Entry (`ceon-hours-api/index.js`):**
+
+```javascript
+const { initializeMonitor, getMonitor } = require("./lib/config/monitor-setup");
+
+// Initialize at startup
+const monitor = initializeMonitor();
+
+// Export for middleware
+module.exports.getMonitor = getMonitor;
+
+// Graceful shutdown
+process.on("SIGTERM", async () => {
+  console.log("[CeonMonitor] Flushing pending errors...");
+  if (monitor) await monitor.flush();
+  process.exit(0);
+});
+```
+
+**3. Error Handler Middleware (`ceon-hours-api/lib/middleware/errorHandler.js`):**
+
+```javascript
+const { getMonitor } = require("../config/monitor-setup");
+
+const errorHandler = (error, req, res, next) => {
+  const monitor = getMonitor();
+  if (monitor && error.status >= 400) {
+    monitor.captureError(error, {
+      route: req.path,
+      method: req.method,
+      statusCode: error.status || 500,
+      userAgent: req.get("user-agent"),
+      ip: req.ip,
+      severity: error.status >= 500 ? "ERROR" : "WARNING",
+    }).catch(console.error);
+  }
+
+  res.status(error.status || 500).json({ error: error.message });
+};
+
+module.exports = errorHandler;
+```
+
+**4. Environment Variables (`.env`):**
+
+```bash
+# Get API key from https://ceonmonitor.com dashboard
+CEON_MONITOR_API_KEY=your-project-api-key
+
+# Endpoint options:
+# - Production: https://ceonmonitor.com
+# - Local dev: http://localhost:4040
+# - Docker dev: http://host.docker.internal:4040
+CEON_MONITOR_ENDPOINT=https://ceonmonitor.com
+```
+
+### Important: Relative Path Requirements
+
+The `dependencySources` and `auditPaths` use **relative paths** from the server's working directory. For multi-project monitoring to work:
+
+1. **Directory structure must match** - The client project must be at the expected relative path (e.g., `../ceon-hours-web-app`)
+2. **Both projects must be present** - If the client folder doesn't exist, only server dependencies will be tracked
+3. **npm must be available** - Vulnerability auditing requires npm to be installed
+
+**Troubleshooting:** If client dependencies aren't being tracked on other machines:
+- Verify the relative path is correct for that machine's directory structure
+- Check that the client's `package.json` exists at the expected path
+- The SDK will log warnings if paths are invalid
+
 ## API Reference
 
 ### `MonitorClient`

package/dist/index.d.mts

@@ -41,11 +41,16 @@ interface MonitorClientConfig {
     autoAudit?: boolean;
     /** Multiple directories to audit for vulnerabilities (runs npm audit in each) */
     auditPaths?: AuditPath[];
+    /** Include devDependencies when tracking dependencies (default: false) */
+    includeDevDependencies?: boolean;
+    /** Enable fetching latest versions from npm registry (default: true) */
+    versionCheckEnabled?: boolean;
 }
 interface TechnologyItem {
     name: string;
     version: string;
     type?: TechnologyType;
+    latestVersion?: string;
 }
 interface ErrorContext {
     severity?: Severity;
@@ -164,6 +169,7 @@ declare class MonitorClient {
     private excludePatterns;
     private compiledExcludePatterns;
     private auditPaths?;
+    private includeDevDependencies;
     private maxQueueSize;
     private maxRetries;
     private retryCount;
@@ -175,6 +181,7 @@ declare class MonitorClient {
     private lastScanTime;
     private lastKnownScanRequestedAt;
     private lastKnownTechScanRequestedAt;
+    private versionCheckEnabled;
     constructor(config: MonitorClientConfig);
     /**
      * Security: Validate and sanitize metadata to prevent oversized payloads
@@ -226,10 +233,24 @@ declare class MonitorClient {
     private startFlushTimer;
     private stopFlushTimer;
     syncDependencies(): Promise<void>;
+    /**
+     * Enrich technologies with latest version information from npm registry.
+     * Only runs if versionCheckEnabled is true.
+     */
+    private enrichWithLatestVersions;
     syncTechnologies(technologies: TechnologyItem[]): Promise<void>;
     private readPackageJson;
     private readPackageJsonFromPath;
     private shouldExclude;
+    /**
+     * Fetch the latest version of a package from npm registry.
+     * Returns null if the package cannot be found or the request fails.
+     */
+    private fetchLatestVersion;
+    /**
+     * Fetch latest versions for multiple packages in parallel with concurrency limit.
+     */
+    private fetchLatestVersions;
     private sendTechnologies;
     private sendTechnologiesWithEnvironment;
     /**

package/dist/index.d.ts

@@ -41,11 +41,16 @@ interface MonitorClientConfig {
     autoAudit?: boolean;
     /** Multiple directories to audit for vulnerabilities (runs npm audit in each) */
     auditPaths?: AuditPath[];
+    /** Include devDependencies when tracking dependencies (default: false) */
+    includeDevDependencies?: boolean;
+    /** Enable fetching latest versions from npm registry (default: true) */
+    versionCheckEnabled?: boolean;
 }
 interface TechnologyItem {
     name: string;
     version: string;
     type?: TechnologyType;
+    latestVersion?: string;
 }
 interface ErrorContext {
     severity?: Severity;
@@ -164,6 +169,7 @@ declare class MonitorClient {
     private excludePatterns;
     private compiledExcludePatterns;
     private auditPaths?;
+    private includeDevDependencies;
     private maxQueueSize;
     private maxRetries;
     private retryCount;
@@ -175,6 +181,7 @@ declare class MonitorClient {
     private lastScanTime;
     private lastKnownScanRequestedAt;
     private lastKnownTechScanRequestedAt;
+    private versionCheckEnabled;
     constructor(config: MonitorClientConfig);
     /**
      * Security: Validate and sanitize metadata to prevent oversized payloads
@@ -226,10 +233,24 @@ declare class MonitorClient {
     private startFlushTimer;
     private stopFlushTimer;
     syncDependencies(): Promise<void>;
+    /**
+     * Enrich technologies with latest version information from npm registry.
+     * Only runs if versionCheckEnabled is true.
+     */
+    private enrichWithLatestVersions;
     syncTechnologies(technologies: TechnologyItem[]): Promise<void>;
     private readPackageJson;
     private readPackageJsonFromPath;
     private shouldExclude;
+    /**
+     * Fetch the latest version of a package from npm registry.
+     * Returns null if the package cannot be found or the request fails.
+     */
+    private fetchLatestVersion;
+    /**
+     * Fetch latest versions for multiple packages in parallel with concurrency limit.
+     */
+    private fetchLatestVersions;
     private sendTechnologies;
     private sendTechnologiesWithEnvironment;
     /**

package/dist/index.js

@@ -116,6 +116,8 @@ var MonitorClient = class {
     });
     this.autoAudit = config.autoAudit || false;
     this.auditPaths = config.auditPaths;
+    this.includeDevDependencies = config.includeDevDependencies ?? false;
+    this.versionCheckEnabled = config.versionCheckEnabled ?? true;
     this.startFlushTimer();
     if (this.trackDependencies) {
       this.syncDependencies().catch((err) => {
@@ -436,17 +438,40 @@ var MonitorClient = class {
         for (const source of this.dependencySources) {
           const technologies = await this.readPackageJsonFromPath(source.path);
           if (technologies.length === 0) continue;
-          await this.sendTechnologiesWithEnvironment(technologies, source.environment);
+          const enrichedTechnologies = await this.enrichWithLatestVersions(technologies);
+          await this.sendTechnologiesWithEnvironment(enrichedTechnologies, source.environment);
         }
       } else {
         const technologies = await this.readPackageJson();
         if (technologies.length === 0) return;
-        await this.sendTechnologies(technologies);
+        const enrichedTechnologies = await this.enrichWithLatestVersions(technologies);
+        await this.sendTechnologies(enrichedTechnologies);
       }
     } catch (err) {
       console.error("[MonitorClient] Failed to sync dependencies:", err);
     }
   }
+  /**
+   * Enrich technologies with latest version information from npm registry.
+   * Only runs if versionCheckEnabled is true.
+   */
+  async enrichWithLatestVersions(technologies) {
+    if (!this.versionCheckEnabled) {
+      return technologies;
+    }
+    try {
+      console.log(`[MonitorClient] Fetching latest versions for ${technologies.length} packages...`);
+      const packageNames = technologies.map((t) => t.name);
+      const latestVersions = await this.fetchLatestVersions(packageNames);
+      return technologies.map((tech) => ({
+        ...tech,
+        latestVersion: latestVersions.get(tech.name) || void 0
+      }));
+    } catch (err) {
+      console.warn("[MonitorClient] Failed to fetch latest versions, continuing without:", err instanceof Error ? err.message : String(err));
+      return technologies;
+    }
+  }
   async syncTechnologies(technologies) {
     await this.sendTechnologies(technologies);
   }
@@ -488,10 +513,7 @@ var MonitorClient = class {
       }
       const packageJson = JSON.parse(fs.readFileSync(normalizedPath, "utf-8"));
       const technologies = [];
-      const deps = {
-        ...packageJson.dependencies,
-        ...packageJson.devDependencies
-      };
+      const deps = this.includeDevDependencies ? { ...packageJson.dependencies, ...packageJson.devDependencies } : { ...packageJson.dependencies };
       for (const [name, version] of Object.entries(deps)) {
         if (typeof version === "string") {
           if (this.shouldExclude(name)) {
@@ -516,6 +538,44 @@ var MonitorClient = class {
     }
     return false;
   }
+  /**
+   * Fetch the latest version of a package from npm registry.
+   * Returns null if the package cannot be found or the request fails.
+   */
+  async fetchLatestVersion(packageName) {
+    try {
+      const encodedName = encodeURIComponent(packageName).replace("%40", "@");
+      const response = await fetch(`https://registry.npmjs.org/${encodedName}`, {
+        headers: { "Accept": "application/json" },
+        signal: AbortSignal.timeout(5e3)
+      });
+      if (!response.ok) return null;
+      const data = await response.json();
+      return data["dist-tags"]?.latest || null;
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Fetch latest versions for multiple packages in parallel with concurrency limit.
+   */
+  async fetchLatestVersions(packageNames) {
+    const results = /* @__PURE__ */ new Map();
+    const concurrencyLimit = 5;
+    for (let i = 0; i < packageNames.length; i += concurrencyLimit) {
+      const batch = packageNames.slice(i, i + concurrencyLimit);
+      const batchResults = await Promise.all(
+        batch.map(async (name) => ({
+          name,
+          version: await this.fetchLatestVersion(name)
+        }))
+      );
+      for (const { name, version } of batchResults) {
+        results.set(name, version);
+      }
+    }
+    return results;
+  }
   async sendTechnologies(technologies) {
     await this.sendTechnologiesWithEnvironment(technologies, this.environment);
   }

package/dist/index.mjs

@@ -80,6 +80,8 @@ var MonitorClient = class {
     });
     this.autoAudit = config.autoAudit || false;
     this.auditPaths = config.auditPaths;
+    this.includeDevDependencies = config.includeDevDependencies ?? false;
+    this.versionCheckEnabled = config.versionCheckEnabled ?? true;
     this.startFlushTimer();
     if (this.trackDependencies) {
       this.syncDependencies().catch((err) => {
@@ -400,17 +402,40 @@ var MonitorClient = class {
         for (const source of this.dependencySources) {
           const technologies = await this.readPackageJsonFromPath(source.path);
           if (technologies.length === 0) continue;
-          await this.sendTechnologiesWithEnvironment(technologies, source.environment);
+          const enrichedTechnologies = await this.enrichWithLatestVersions(technologies);
+          await this.sendTechnologiesWithEnvironment(enrichedTechnologies, source.environment);
         }
       } else {
         const technologies = await this.readPackageJson();
         if (technologies.length === 0) return;
-        await this.sendTechnologies(technologies);
+        const enrichedTechnologies = await this.enrichWithLatestVersions(technologies);
+        await this.sendTechnologies(enrichedTechnologies);
       }
     } catch (err) {
       console.error("[MonitorClient] Failed to sync dependencies:", err);
     }
   }
+  /**
+   * Enrich technologies with latest version information from npm registry.
+   * Only runs if versionCheckEnabled is true.
+   */
+  async enrichWithLatestVersions(technologies) {
+    if (!this.versionCheckEnabled) {
+      return technologies;
+    }
+    try {
+      console.log(`[MonitorClient] Fetching latest versions for ${technologies.length} packages...`);
+      const packageNames = technologies.map((t) => t.name);
+      const latestVersions = await this.fetchLatestVersions(packageNames);
+      return technologies.map((tech) => ({
+        ...tech,
+        latestVersion: latestVersions.get(tech.name) || void 0
+      }));
+    } catch (err) {
+      console.warn("[MonitorClient] Failed to fetch latest versions, continuing without:", err instanceof Error ? err.message : String(err));
+      return technologies;
+    }
+  }
   async syncTechnologies(technologies) {
     await this.sendTechnologies(technologies);
   }
@@ -452,10 +477,7 @@ var MonitorClient = class {
       }
       const packageJson = JSON.parse(fs.readFileSync(normalizedPath, "utf-8"));
       const technologies = [];
-      const deps = {
-        ...packageJson.dependencies,
-        ...packageJson.devDependencies
-      };
+      const deps = this.includeDevDependencies ? { ...packageJson.dependencies, ...packageJson.devDependencies } : { ...packageJson.dependencies };
       for (const [name, version] of Object.entries(deps)) {
         if (typeof version === "string") {
           if (this.shouldExclude(name)) {
@@ -480,6 +502,44 @@ var MonitorClient = class {
     }
     return false;
   }
+  /**
+   * Fetch the latest version of a package from npm registry.
+   * Returns null if the package cannot be found or the request fails.
+   */
+  async fetchLatestVersion(packageName) {
+    try {
+      const encodedName = encodeURIComponent(packageName).replace("%40", "@");
+      const response = await fetch(`https://registry.npmjs.org/${encodedName}`, {
+        headers: { "Accept": "application/json" },
+        signal: AbortSignal.timeout(5e3)
+      });
+      if (!response.ok) return null;
+      const data = await response.json();
+      return data["dist-tags"]?.latest || null;
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Fetch latest versions for multiple packages in parallel with concurrency limit.
+   */
+  async fetchLatestVersions(packageNames) {
+    const results = /* @__PURE__ */ new Map();
+    const concurrencyLimit = 5;
+    for (let i = 0; i < packageNames.length; i += concurrencyLimit) {
+      const batch = packageNames.slice(i, i + concurrencyLimit);
+      const batchResults = await Promise.all(
+        batch.map(async (name) => ({
+          name,
+          version: await this.fetchLatestVersion(name)
+        }))
+      );
+      for (const { name, version } of batchResults) {
+        results.set(name, version);
+      }
+    }
+    return results;
+  }
   async sendTechnologies(technologies) {
     await this.sendTechnologiesWithEnvironment(technologies, this.environment);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ceon-oy/monitor-sdk",
-  "version": "1.0.13",
+  "version": "1.0.15",
   "description": "Client SDK for Ceon Monitor - Error tracking, health monitoring, security events, and vulnerability scanning",
   "author": "Ceon",
   "license": "MIT",