@ceon-oy/monitor-sdk 1.0.12 → 1.0.14

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)
@@ -132,6 +133,111 @@ const monitor = new MonitorClient({
 });
 ```
 
+## Initialization Patterns by Runtime
+
+The SDK initialization pattern depends on your application's runtime environment:
+
+### Long-Running Servers (Express, Fastify, plain Node.js)
+
+Traditional Node.js servers run as persistent processes. Use explicit initialization and graceful shutdown:
+
+```typescript
+// lib/monitor.ts
+import { MonitorClient } from '@ceon-oy/monitor-sdk';
+
+let monitor: MonitorClient | null = null;
+
+export function initializeMonitor() {
+  if (!monitor) {
+    monitor = new MonitorClient({
+      apiKey: process.env.CEON_MONITOR_API_KEY!,
+      endpoint: process.env.CEON_MONITOR_ENDPOINT!,
+      environment: process.env.NODE_ENV,
+      trackDependencies: true,
+      autoAudit: true,
+    });
+  }
+  return monitor;
+}
+
+export function getMonitor() {
+  if (!monitor) {
+    throw new Error('Monitor not initialized. Call initializeMonitor() first.');
+  }
+  return monitor;
+}
+
+// index.ts
+import { initializeMonitor, getMonitor } from './lib/monitor';
+
+const monitor = initializeMonitor();
+
+// Graceful shutdown - ensures queued errors are sent before exit
+process.on('SIGTERM', async () => {
+  console.log('Shutting down gracefully...');
+  await getMonitor().close();
+  process.exit(0);
+});
+
+process.on('SIGINT', async () => {
+  console.log('Shutting down gracefully...');
+  await getMonitor().close();
+  process.exit(0);
+});
+```
+
+**Why?** Long-running servers need:
+- Single instance to avoid memory leaks
+- Graceful shutdown to flush queued errors before exit
+- Process signal handlers for clean termination
+
+### Next.js / Serverless / Edge Functions
+
+Serverless environments handle lifecycle automatically. Create the client directly:
+
+```typescript
+// lib/monitor.ts
+import { MonitorClient } from '@ceon-oy/monitor-sdk';
+
+export const monitor = new MonitorClient({
+  apiKey: process.env.CEON_MONITOR_API_KEY!,
+  endpoint: process.env.CEON_MONITOR_ENDPOINT!,
+  environment: process.env.NODE_ENV,
+  batchSize: 1,  // Send immediately (no batching for short-lived functions)
+});
+```
+
+**Why no explicit shutdown?**
+- Each request is isolated and short-lived
+- The platform handles process lifecycle
+- No persistent process to clean up
+- Set `batchSize: 1` to send errors immediately (don't wait for batch)
+
+For API routes that need guaranteed delivery:
+```typescript
+// app/api/something/route.ts
+import { monitor } from '@/lib/monitor';
+
+export async function POST(request: Request) {
+  try {
+    // ... your logic
+  } catch (error) {
+    monitor.captureError(error as Error);
+    await monitor.flush();  // Ensure error is sent before response
+  }
+}
+```
+
+### Summary Table
+
+| Environment | Initialize Pattern | Graceful Shutdown | batchSize |
+|-------------|-------------------|-------------------|-----------|
+| Express/Fastify/Node.js | `initializeMonitor()` + singleton | Yes (SIGTERM/SIGINT handlers) | Default (10) |
+| Next.js (App Router) | Direct instantiation | No | 1 (recommended) |
+| Next.js (API Routes) | Direct instantiation | No, but call `flush()` | 1 (recommended) |
+| Vercel/AWS Lambda | Direct instantiation | No, but call `flush()` | 1 (required) |
+| Docker/Kubernetes | `initializeMonitor()` + singleton | Yes (for graceful pod termination) | Default (10) |
+
 ## Features
 
 ### Error Capture
@@ -193,7 +299,7 @@ await monitor.reportTechnologies([
 
 ### Vulnerability Auditing
 
-Run npm audit and send results to the monitoring server:
+Scan your dependencies for security vulnerabilities and report them to Ceon Monitor.
 
 ```typescript
 // Basic audit
@@ -211,6 +317,18 @@ await monitor.auditDependencies({
 });
 ```
 
+#### Supported Package Managers
+
+The SDK automatically detects your package manager based on lock files:
+
+| Package Manager | Detection | Audit Command |
+|-----------------|-----------|---------------|
+| **npm** | `package-lock.json` (default) | `npm audit --json` |
+| **yarn** | `yarn.lock` | `yarn audit --json` |
+| **pnpm** | `pnpm-lock.yaml` | `npm audit --json` (compatibility) |
+
+No configuration needed - the SDK auto-detects and uses the appropriate audit command.
+
 #### Automatic Auditing (Recommended)
 
 Enable `autoAudit: true` to let the SDK automatically scan for vulnerabilities based on the interval configured in the Ceon Monitor dashboard:
@@ -738,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,6 +41,8 @@ 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;
 }
 interface TechnologyItem {
     name: string;
@@ -164,6 +166,7 @@ declare class MonitorClient {
     private excludePatterns;
     private compiledExcludePatterns;
     private auditPaths?;
+    private includeDevDependencies;
     private maxQueueSize;
     private maxRetries;
     private retryCount;

package/dist/index.d.ts

@@ -41,6 +41,8 @@ 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;
 }
 interface TechnologyItem {
     name: string;
@@ -164,6 +166,7 @@ declare class MonitorClient {
     private excludePatterns;
     private compiledExcludePatterns;
     private auditPaths?;
+    private includeDevDependencies;
     private maxQueueSize;
     private maxRetries;
     private retryCount;

package/dist/index.js

@@ -116,6 +116,7 @@ var MonitorClient = class {
     });
     this.autoAudit = config.autoAudit || false;
     this.auditPaths = config.auditPaths;
+    this.includeDevDependencies = config.includeDevDependencies ?? false;
     this.startFlushTimer();
     if (this.trackDependencies) {
       this.syncDependencies().catch((err) => {
@@ -488,10 +489,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)) {

package/dist/index.mjs

@@ -80,6 +80,7 @@ var MonitorClient = class {
     });
     this.autoAudit = config.autoAudit || false;
     this.auditPaths = config.auditPaths;
+    this.includeDevDependencies = config.includeDevDependencies ?? false;
     this.startFlushTimer();
     if (this.trackDependencies) {
       this.syncDependencies().catch((err) => {
@@ -452,10 +453,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)) {

package/package.json

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