@sentienguard/apm 1.0.6 → 1.0.8

package/README.md

@@ -11,7 +11,10 @@ npm install @sentienguard/apm
 ## Quick Start
 
 ```js
-// Add this as the FIRST import in your app
+// If using dotenv, import it first
+import 'dotenv/config';
+
+// Then import the SDK (before other app modules for best instrumentation coverage)
 import '@sentienguard/apm';
 
 // Your app code
@@ -56,6 +59,7 @@ All configuration is via environment variables:
 For better route extraction, add the middleware:
 
 ```js
+import 'dotenv/config'; // if using dotenv
 import '@sentienguard/apm';
 import { expressMiddleware, expressErrorMiddleware } from '@sentienguard/apm';
 import express from 'express';
@@ -75,6 +79,7 @@ app.use(expressErrorMiddleware());
 ### Fastify
 
 ```js
+import 'dotenv/config'; // if using dotenv
 import '@sentienguard/apm';
 import { fastifyPlugin, fastifyErrorHandler } from '@sentienguard/apm';
 import Fastify from 'fastify';

package/package.json

@@ -1,12 +1,14 @@
 {
   "name": "@sentienguard/apm",
-  "version": "1.0.6",
+  "version": "1.0.8",
   "description": "SentienGuard APM SDK - Minimal, production-safe application performance monitoring",
   "main": "src/index.js",
+  "types": "src/index.d.ts",
   "type": "module",
   "browser": "./src/browser.js",
   "exports": {
     ".": {
+      "types": "./src/index.d.ts",
       "browser": "./src/browser.js",
       "default": "./src/index.js"
     }

package/src/config.js

@@ -2,87 +2,93 @@
  * SDK Configuration
  * Environment-driven configuration with sensible defaults.
  * No config → SDK disables itself silently.
+ *
+ * Config is loaded lazily (at initialize() time, not import time)
+ * so that dotenv or other env loaders can run first.
  */
 
-const config = {
-  // API key for authentication (required)
-  apiKey: process.env.SENTIENGUARD_APM_KEY || '',
-
-  // Service name (required for data to be meaningful)
-  service: process.env.SENTIENGUARD_SERVICE || '',
-
-  // Environment (production, staging, development)
-  environment: process.env.SENTIENGUARD_ENV || 'production',
-
-  // Backend endpoint for data ingestion
-  // Production: https://sentienguard-dev.the-algo.com/api/v1/apm/ingest
-  // Local: http://localhost:4000/api/v1/apm/ingest
-  endpoint: process.env.SENTIENGUARD_ENDPOINT || 'https://sentienguard-dev.the-algo.com/api/v1/apm/ingest',
-
-  // Flush interval in seconds (default: 10s)
-  flushInterval: parseInt(process.env.SENTIENGUARD_FLUSH_INTERVAL, 10) || 10,
-
-  // Max unique routes to track per service (prevents memory bloat)
-  maxRoutes: parseInt(process.env.SENTIENGUARD_MAX_ROUTES, 10) || 100,
-
-  // Max payload size in bytes (prevent oversized payloads)
-  maxPayloadSize: parseInt(process.env.SENTIENGUARD_MAX_PAYLOAD_SIZE, 10) || 1024 * 1024, // 1MB
-
-  // Enable/disable SDK (auto-disabled if no API key)
-  enabled: process.env.SENTIENGUARD_ENABLED !== 'false',
+let configLoaded = false;
 
-  // Debug mode (logs SDK activity)
-  debug: process.env.SENTIENGUARD_DEBUG === 'true',
-
-  // MongoDB monitoring configuration
+const config = {
+  apiKey: '',
+  service: '',
+  environment: 'production',
+  endpoint: 'https://sentienguard-dev.the-algo.com/api/v1/apm/ingest',
+  flushInterval: 10,
+  maxRoutes: 100,
+  maxPayloadSize: 1024 * 1024,
+  enabled: true,
+  debug: false,
   mongodb: {
-    // Enable/disable MongoDB instrumentation (default: true)
-    enabled: process.env.SENTIENGUARD_MONGODB_ENABLED !== 'false',
-    // Slow query threshold in milliseconds (default: 100ms)
-    slowQueryMs: parseInt(process.env.SENTIENGUARD_MONGODB_SLOW_QUERY_MS, 10) || 100,
-    // Interval for collecting pool stats in milliseconds (default: 10s)
-    poolStatsInterval: parseInt(process.env.SENTIENGUARD_MONGODB_POOL_INTERVAL, 10) || 10000
+    enabled: true,
+    slowQueryMs: 100,
+    poolStatsInterval: 10000
   },
-
-  // Circuit breaker configuration
   circuitBreaker: {
-    // Enable/disable circuit breaker (default: false - opt-in)
-    enabled: process.env.SENTIENGUARD_CIRCUIT_BREAKER_ENABLED === 'true',
-    // Timeout for operations in milliseconds (default: 3s)
-    timeout: parseInt(process.env.SENTIENGUARD_CIRCUIT_TIMEOUT_MS, 10) || 3000,
-    // Error threshold percentage to trip circuit (default: 50%)
-    errorThresholdPercentage: parseInt(process.env.SENTIENGUARD_CIRCUIT_ERROR_THRESHOLD, 10) || 50,
-    // Time to wait before attempting recovery in milliseconds (default: 30s)
-    resetTimeout: parseInt(process.env.SENTIENGUARD_CIRCUIT_RESET_TIMEOUT, 10) || 30000,
-    // Minimum requests before calculating error percentage (default: 5)
-    volumeThreshold: parseInt(process.env.SENTIENGUARD_CIRCUIT_VOLUME_THRESHOLD, 10) || 5
+    enabled: false,
+    timeout: 3000,
+    errorThresholdPercentage: 50,
+    resetTimeout: 30000,
+    volumeThreshold: 5
   },
-
-  // OpenAI monitoring configuration
   openai: {
-    // Enable/disable OpenAI instrumentation (default: true)
-    enabled: process.env.SENTIENGUARD_OPENAI_ENABLED !== 'false',
-    // Track token usage (default: true)
-    trackTokens: process.env.SENTIENGUARD_OPENAI_TRACK_TOKENS !== 'false',
-    // Track estimated costs (default: true)
-    trackCosts: process.env.SENTIENGUARD_OPENAI_TRACK_COSTS !== 'false',
-    // Slow API call threshold in milliseconds (default: 5000ms / 5s)
-    slowCallMs: parseInt(process.env.SENTIENGUARD_OPENAI_SLOW_CALL_MS, 10) || 5000
+    enabled: true,
+    trackTokens: true,
+    trackCosts: true,
+    slowCallMs: 5000
   }
 };
 
 /**
- * Check if SDK is properly configured and should be active
+ * Load configuration from environment variables.
+ * Called lazily on first use (e.g., from initialize() or isEnabled()).
+ * Safe to call multiple times — only reads env vars once.
+ */
+export function loadConfig({ force = false } = {}) {
+  if (configLoaded && !force) return;
+  configLoaded = true;
+
+  config.apiKey = process.env.SENTIENGUARD_APM_KEY || '';
+  config.service = process.env.SENTIENGUARD_SERVICE || '';
+  config.environment = process.env.SENTIENGUARD_ENV || 'production';
+  config.endpoint = process.env.SENTIENGUARD_ENDPOINT || 'https://sentienguard-dev.the-algo.com/api/v1/apm/ingest';
+  config.flushInterval = parseInt(process.env.SENTIENGUARD_FLUSH_INTERVAL, 10) || 10;
+  config.maxRoutes = parseInt(process.env.SENTIENGUARD_MAX_ROUTES, 10) || 100;
+  config.maxPayloadSize = parseInt(process.env.SENTIENGUARD_MAX_PAYLOAD_SIZE, 10) || 1024 * 1024;
+  config.enabled = process.env.SENTIENGUARD_ENABLED !== 'false';
+  config.debug = process.env.SENTIENGUARD_DEBUG === 'true';
+
+  config.mongodb.enabled = process.env.SENTIENGUARD_MONGODB_ENABLED !== 'false';
+  config.mongodb.slowQueryMs = parseInt(process.env.SENTIENGUARD_MONGODB_SLOW_QUERY_MS, 10) || 100;
+  config.mongodb.poolStatsInterval = parseInt(process.env.SENTIENGUARD_MONGODB_POOL_INTERVAL, 10) || 10000;
+
+  config.circuitBreaker.enabled = process.env.SENTIENGUARD_CIRCUIT_BREAKER_ENABLED === 'true';
+  config.circuitBreaker.timeout = parseInt(process.env.SENTIENGUARD_CIRCUIT_TIMEOUT_MS, 10) || 3000;
+  config.circuitBreaker.errorThresholdPercentage = parseInt(process.env.SENTIENGUARD_CIRCUIT_ERROR_THRESHOLD, 10) || 50;
+  config.circuitBreaker.resetTimeout = parseInt(process.env.SENTIENGUARD_CIRCUIT_RESET_TIMEOUT, 10) || 30000;
+  config.circuitBreaker.volumeThreshold = parseInt(process.env.SENTIENGUARD_CIRCUIT_VOLUME_THRESHOLD, 10) || 5;
+
+  config.openai.enabled = process.env.SENTIENGUARD_OPENAI_ENABLED !== 'false';
+  config.openai.trackTokens = process.env.SENTIENGUARD_OPENAI_TRACK_TOKENS !== 'false';
+  config.openai.trackCosts = process.env.SENTIENGUARD_OPENAI_TRACK_COSTS !== 'false';
+  config.openai.slowCallMs = parseInt(process.env.SENTIENGUARD_OPENAI_SLOW_CALL_MS, 10) || 5000;
+}
+
+/**
+ * Check if SDK is properly configured and should be active.
+ * Triggers lazy config load if not yet loaded.
  */
 export function isEnabled() {
-  // SDK disables itself silently if no API key or service name
+  loadConfig();
   return config.enabled && !!config.apiKey && !!config.service;
 }
 
 /**
- * Get validated configuration
+ * Get validated configuration.
+ * Triggers lazy config load if not yet loaded.
  */
 export function getConfig() {
+  loadConfig();
   return { ...config };
 }
 

package/src/index.d.ts

@@ -0,0 +1,102 @@
+/**
+ * SentienGuard APM SDK TypeScript Declarations
+ */
+
+// Configuration types
+export interface ApmConfig {
+  apiKey?: string;
+  service?: string;
+  environment?: string;
+  endpoint?: string;
+  flushInterval?: number;
+  maxRoutes?: number;
+  maxPayloadSize?: number;
+  enabled?: boolean;
+  debug?: boolean;
+}
+
+export interface BrowserApmConfig {
+  apiKey: string;
+  service: string;
+  endpoint?: string;
+  environment?: string;
+  flushInterval?: number;
+  debug?: boolean;
+}
+
+export interface ApmStatus {
+  enabled: boolean;
+  initialized: boolean;
+  config: {
+    service: string;
+    environment: string;
+    flushInterval: number;
+  };
+  stats: {
+    requestMetrics?: number;
+    dependencyMetrics?: number;
+    webVitals?: number;
+    jsErrors?: number;
+  };
+}
+
+// Core functions
+export function initialize(options?: BrowserApmConfig): void;
+export function init(options?: BrowserApmConfig): void;
+export function shutdown(): Promise<void>;
+export function getStatus(): ApmStatus;
+export function flush(): Promise<void>;
+export function getConfig(): ApmConfig;
+export function isEnabled(): boolean;
+
+// Express middleware (no-ops in browser)
+export function expressMiddleware(): (req: any, res: any, next: any) => void;
+export function expressErrorMiddleware(): (err: any, req: any, res: any, next: any) => void;
+
+// Fastify plugin (no-ops in browser)
+export function fastifyPlugin(): any;
+export function fastifyErrorHandler(): any;
+
+// Route utilities (no-ops in browser)
+export function normalizeRoute(route: string): string;
+export function extractRoute(req: any): string;
+export const RouteRegistry: any;
+
+// Aggregator
+export function getAggregator(): any;
+
+// MongoDB instrumentation (no-ops in browser)
+export function instrumentMongoDB(): void;
+
+// OpenAI instrumentation (no-ops in browser)
+export function instrumentOpenAI(): void;
+
+// Circuit breaker (no-ops in browser)
+export function createBreaker(fn: any): any;
+export function wrapMongoOperation(fn: any): any;
+export function getBreakerStats(): any;
+
+// Default export
+declare const SentienGuard: {
+  init: typeof init;
+  initialize: typeof initialize;
+  shutdown: typeof shutdown;
+  getStatus: typeof getStatus;
+  flush: typeof flush;
+  getConfig: typeof getConfig;
+  isEnabled: typeof isEnabled;
+  getAggregator: typeof getAggregator;
+  expressMiddleware: typeof expressMiddleware;
+  expressErrorMiddleware: typeof expressErrorMiddleware;
+  fastifyPlugin: typeof fastifyPlugin;
+  fastifyErrorHandler: typeof fastifyErrorHandler;
+  normalizeRoute: typeof normalizeRoute;
+  extractRoute: typeof extractRoute;
+  instrumentMongoDB: typeof instrumentMongoDB;
+  instrumentOpenAI: typeof instrumentOpenAI;
+  createBreaker: typeof createBreaker;
+  wrapMongoOperation: typeof wrapMongoOperation;
+  getBreakerStats: typeof getBreakerStats;
+};
+
+export default SentienGuard;

package/src/index.js

@@ -19,7 +19,7 @@
  * No config → SDK disables itself silently.
  */
 
-import config, { isEnabled, debug, getConfig } from './config.js';
+import config, { isEnabled, debug, getConfig, loadConfig } from './config.js';
 import { instrumentHttp, expressMiddleware, fastifyPlugin } from './instrumentation.js';
 import { instrumentDependencies } from './dependencies.js';
 import { startErrorCapture, expressErrorMiddleware, fastifyErrorHandler } from './errors.js';
@@ -42,6 +42,9 @@ function initialize() {
     return;
   }
 
+  // Load config from env vars (lazy — allows dotenv to load first)
+  loadConfig();
+
   // Check if SDK should be enabled
   if (!isEnabled()) {
     // Silently disable - this is expected behavior
@@ -146,9 +149,22 @@ function getStatus() {
   };
 }
 
-// Auto-initialize on import
+// Phase 1: Immediately patch http/https (config-independent, must happen before servers are created)
+instrumentHttp();
+instrumentDependencies();
+
+// Phase 2: Try full initialization (works if env vars are already set at system/process level)
 initialize();
 
+// Phase 3: If init failed (env vars not loaded yet, e.g. dotenv.config() hasn't run),
+// retry after the importing module's synchronous code completes
+if (!isInitialized) {
+  process.nextTick(() => {
+    loadConfig({ force: true });
+    initialize();
+  });
+}
+
 // Export for advanced usage
 export {
   // Core functions