@ciq-dev/neoiq-foundation-node 1.0.0-beta.1 → 1.0.1-beta.0

package/README.md

@@ -20,9 +20,13 @@ Node.js observability foundation for CommerceIQ services. Integrates with **Grou
 - **Traces**: Automatic span creation for HTTP requests (incoming & outgoing)
 - **Metrics**: HTTP request counts, durations, errors + custom business metrics
 - **Logs**: Structured JSON logs with automatic trace context (traceId, spanId, correlationId)
+- **Selective Enablement**: Enable only the features you need
+- **Type-Safe Configuration**: Zod validation with helpful error messages
 - **Fastify Plugin**: One-line integration for request lifecycle
 - **HTTP Client**: Axios wrapper with retry, circuit breaker, and trace propagation
 
+---
+
 ## Quick Start
 
 ### 1. Install
@@ -31,7 +35,7 @@ Node.js observability foundation for CommerceIQ services. Integrates with **Grou
 npm install @ciq-dev/neoiq-foundation-node
 
 # Peer dependencies
-npm install @opentelemetry/api @opentelemetry/sdk-node @opentelemetry/sdk-metrics \
+npm install zod @opentelemetry/api @opentelemetry/sdk-node @opentelemetry/sdk-metrics \
   @opentelemetry/exporter-trace-otlp-grpc @opentelemetry/exporter-metrics-otlp-grpc \
   @opentelemetry/auto-instrumentations-node @opentelemetry/resources @opentelemetry/semantic-conventions \
   pino pino-pretty axios axios-retry opossum fastify-plugin
@@ -40,22 +44,26 @@ npm install @opentelemetry/api @opentelemetry/sdk-node @opentelemetry/sdk-metric
 ### 2. Initialize (First Line of the App)
 
 ```typescript
-import { init, logger, observabilityPlugin } from '@ciq-dev/neoiq-foundation-node';
+import { createFoundation } from '@ciq-dev/neoiq-foundation-node';
 
-// Must be called BEFORE other imports
-init({
-  serviceName: 'neoiq-auth-service',
+// Create foundation instance (must be called BEFORE other imports)
+const foundation = createFoundation({
+  serviceName: 'auth-service',
   serviceVersion: '1.0.0',
 });
+
+// Export for use in other files
+export { foundation };
 ```
 
 ### 3. Add Fastify Plugin
 
 ```typescript
 import Fastify from 'fastify';
+import { foundation } from './foundation';
 
 const app = Fastify();
-app.register(observabilityPlugin, { serviceName: 'neoiq-auth-service' });
+app.register(foundation.fastifyPlugin);
 ```
 
 ### 4. Set Environment Variable in Kubernetes
@@ -70,32 +78,149 @@ That's it! Traces and metrics will flow to Groundcover.
 
 ---
 
+## Selective Feature Enablement
+
+Enable only the features you need for lightweight deployments:
+
+```typescript
+import { createFoundation } from '@ciq-dev/neoiq-foundation-node';
+
+// Full observability (default)
+const foundation = createFoundation({
+  serviceName: 'auth-service',
+});
+
+// Logging only (lightweight mode)
+const foundation = createFoundation({
+  serviceName: 'simple-worker',
+  features: {
+    tracing: false,
+    metrics: false,
+    logging: true,
+  },
+});
+
+// Custom auto-instrumentation
+const foundation = createFoundation({
+  serviceName: 'api-gateway',
+  features: {
+    tracing: true,
+    metrics: true,
+    autoInstrumentation: {
+      http: true,
+      fastify: true,
+      mongodb: false,  // Not using MongoDB
+      redis: false,    // Not using Redis
+      pg: true,        // Using PostgreSQL
+    },
+  },
+});
+```
+
+---
+
 ## API Reference
 
-### `init(options)`
+### `createFoundation(options)`
 
-Initialize OpenTelemetry. **Must be called before other imports.**
+Create a foundation instance with full observability capabilities.
 
 ```typescript
-init({
-  serviceName: 'my-service',           // Required
-  serviceVersion: '1.0.0',             // Default: '1.0.0'
-  environment: 'production',           // Default: 'development'
-  otlpEndpoint: 'http://...:4317',     // Default: cluster OTEL Collector
-  logLevel: 'info',                    // 'debug' | 'info' | 'warn' | 'error'
-  metricsIntervalMs: 5000,             // Default: 5000 (5 seconds)
+import { createFoundation } from '@ciq-dev/neoiq-foundation-node';
+
+const foundation = createFoundation({
+  // Required
+  serviceName: 'my-service',
+  
+  // Optional
+  serviceVersion: '1.0.0',        // Default: '1.0.0' or $SERVICE_VERSION
+  environment: 'production',       // Default: 'development' or $NODE_ENV
+  
+  // Feature toggles
+  features: {
+    tracing: true,                 // Enable distributed tracing
+    metrics: true,                 // Enable metrics collection
+    logging: true,                 // Enable structured logging
+    autoInstrumentation: {         // Fine-grained control
+      http: true,
+      fastify: true,
+      express: true,
+      mongodb: true,
+      pg: true,
+      mysql: true,
+      redis: true,
+      ioredis: true,
+      fs: false,                   // Disabled by default (noisy)
+      dns: false,                  // Disabled by default
+    },
+  },
+  
+  // OTEL configuration
+  otel: {
+    endpoint: 'http://...:4317',   // Default: cluster OTEL Collector
+    metricsIntervalMs: 5000,       // Default: 5000 (5 seconds)
+    traceSampleRate: 1.0,          // Default: 1.0 (100%)
+  },
+  
+  // Logging configuration
+  logging: {
+    level: 'info',                 // 'debug' | 'info' | 'warn' | 'error'
+    prettyPrint: false,            // Auto-detect from environment
+  },
 });
 ```
 
-### `logger`
+### Foundation Instance
 
-Structured logger with automatic trace context injection.
+The foundation instance provides access to all observability features:
 
 ```typescript
-import { logger } from '@ciq-dev/neoiq-foundation-node';
+// Logging
+foundation.logger.info({ userId: '123' }, 'User logged in');
+foundation.logger.error({ error: err.message }, 'Failed to process');
+
+// Metrics
+const meter = foundation.getMeter('my-service');
+const counter = meter.createCounter('logins.total');
+counter.add(1, { provider: 'workos' });
+
+// Tracing
+const tracer = foundation.getTracer();
+tracer.startActiveSpan('validateToken', (span) => {
+  // ... do work
+  span.end();
+});
+
+// HTTP Client
+const client = foundation.createHttpClient({
+  baseURL: 'http://user-service:3000',
+  serviceName: 'user-service',
+});
 
-logger.info({ userId: '123' }, 'User logged in');
-logger.error({ error: err.message }, 'Failed to process');
+// Fastify Plugin
+app.register(foundation.fastifyPlugin);
+
+// Shutdown
+await foundation.shutdown();
+
+// Check features
+console.log(foundation.features);
+// { tracing: true, metrics: true, logging: true }
+```
+
+### `foundation.logger`
+
+Structured logger with automatic trace context injection.
+
+```typescript
+foundation.logger.info({ userId: '123' }, 'User logged in');
+foundation.logger.error({ error: err.message }, 'Failed to process');
+foundation.logger.warn({ attempt: 3 }, 'Retry attempt');
+foundation.logger.debug({ payload: data }, 'Processing request');
+
+// Child logger for component-specific logging
+const authLogger = foundation.logger.child({ component: 'auth' });
+authLogger.info({}, 'Auth module initialized');
 ```
 
 **Log Output:**
@@ -103,7 +228,7 @@ logger.error({ error: err.message }, 'Failed to process');
 {
   "level": "info",
   "time": 1703318400000,
-  "service": "neoiq-auth-service",
+  "service": "auth-service",
   "traceId": "abc123...",
   "spanId": "def456...",
   "correlationId": "req-789",
@@ -112,14 +237,12 @@ logger.error({ error: err.message }, 'Failed to process');
 }
 ```
 
-### `getMeter(name, version?)`
+### `foundation.getMeter(name, version?)`
 
 Get a meter for custom metrics.
 
 ```typescript
-import { getMeter } from '@ciq-dev/neoiq-foundation-node';
-
-const meter = getMeter('neoiq-auth-service');
+const meter = foundation.getMeter('auth-service');
 
 // Counter
 const counter = meter.createCounter('logins.total');
@@ -128,19 +251,19 @@ counter.add(1, { provider: 'workos' });
 // Histogram
 const histogram = meter.createHistogram('token.validation.duration');
 histogram.record(150, { status: 'success' });
+
+// Observable Gauge
+meter.createObservableGauge('active_sessions', {}, (result) => {
+  result.observe(getActiveSessions());
+});
 ```
 
-### `observabilityPlugin`
+### `foundation.fastifyPlugin`
 
 Fastify plugin for automatic request handling.
 
 ```typescript
-import { observabilityPlugin } from '@ciq-dev/neoiq-foundation-node';
-
-app.register(observabilityPlugin, {
-  serviceName: 'my-service',
-  excludeRoutes: ['/health', '/metrics'],
-});
+app.register(foundation.fastifyPlugin);
 ```
 
 **Automatically:**
@@ -148,19 +271,27 @@ app.register(observabilityPlugin, {
 - Creates OpenTelemetry spans for each request
 - Logs request received/completed with full context
 - Records HTTP metrics (http.server.requests.total, http.server.request.duration)
+- Skips health check endpoints (/health, /healthz, /ready, /live)
 
-### `createHttpClient(options)`
+### `foundation.createHttpClient(options)`
 
 Create an Axios client with full observability.
 
 ```typescript
-import { createHttpClient } from '@ciq-dev/neoiq-foundation-node';
-
-const userClient = createHttpClient({
+const userClient = foundation.createHttpClient({
   baseURL: 'http://user-service:3000',
   serviceName: 'user-service',
   timeout: 10000,
-  retry: { retries: 3 },
+  retry: {
+    retries: 3,
+    retryDelay: 1000,
+    retryStatusCodes: [408, 429, 500, 502, 503, 504],
+  },
+  circuitBreaker: {
+    enabled: true,
+    resetTimeout: 30000,
+    errorThresholdPercentage: 50,
+  },
 });
 
 const response = await userClient.get('/api/users/123');
@@ -174,16 +305,14 @@ const response = await userClient.get('/api/users/123');
 - Retries on 5xx errors with exponential backoff
 - Circuit breaker protection
 
-### `shutdown()`
+### `foundation.shutdown()`
 
 Gracefully shutdown OTEL providers. Call on application shutdown.
 
 ```typescript
-import { shutdown } from '@ciq-dev/neoiq-foundation-node';
-
 process.on('SIGTERM', async () => {
   await app.close();
-  await shutdown(); // Flush telemetry
+  await foundation.shutdown(); // Flush telemetry
 });
 ```
 
@@ -192,47 +321,54 @@ process.on('SIGTERM', async () => {
 ## Complete Example
 
 ```typescript
-// src/index.ts
-
-// STEP 1: Initialize OTEL (must be first!)
-import { init, logger, getMeter, observabilityPlugin, createHttpClient, shutdown } from '@ciq-dev/neoiq-foundation-node';
+// src/foundation.ts
+import { createFoundation } from '@ciq-dev/neoiq-foundation-node';
 
-init({ serviceName: 'neoiq-auth-service' });
+export const foundation = createFoundation({
+  serviceName: 'auth-service',
+  environment: process.env.NODE_ENV as 'development' | 'production',
+});
+```
 
-// STEP 2: Import dependencies
+```typescript
+// src/index.ts
 import Fastify from 'fastify';
+import { foundation } from './foundation';
 
 const app = Fastify();
 
-// STEP 3: Register plugin
-app.register(observabilityPlugin, { serviceName: 'neoiq-auth-service' });
+// Register observability plugin
+app.register(foundation.fastifyPlugin);
 
-// STEP 4: Create HTTP clients
-const userClient = createHttpClient({
-  baseURL: process.env.USER_SERVICE_URL,
+// Create HTTP clients
+const userClient = foundation.createHttpClient({
+  baseURL: process.env.USER_SERVICE_URL!,
   serviceName: 'user-service',
 });
 
-// STEP 5: Custom metrics
-const meter = getMeter('neoiq-auth-service');
+// Custom metrics
+const meter = foundation.getMeter('auth-service');
 const loginCounter = meter.createCounter('auth.logins.total');
 
-// STEP 6: Routes
+// Routes
 app.post('/api/v1/auth/login', async (req, reply) => {
-  const { provider } = req.body as any;
+  const { provider } = req.body as { provider: string };
   
   loginCounter.add(1, { provider });
-  logger.info({ provider }, 'Login attempt');
+  foundation.logger.info({ provider }, 'Login attempt');
   
-  return { success: true };
+  // Call user service (trace context automatically propagated)
+  const { data: user } = await userClient.get('/api/users/me');
+  
+  return { success: true, user };
 });
 
-// STEP 7: Start with graceful shutdown
+// Start with graceful shutdown
 app.listen({ port: 3000 });
 
 process.on('SIGTERM', async () => {
   await app.close();
-  await shutdown(); // Flush telemetry
+  await foundation.shutdown();
 });
 ```
 
@@ -243,8 +379,8 @@ process.on('SIGTERM', async () => {
 | Variable | Description | Default |
 |----------|-------------|---------|
 | `OTEL_EXPORTER_OTLP_ENDPOINT` | OTEL Collector URL | `http://otel-stack-deployment-collector.observability.svc.cluster.local:4317` |
-| `OTEL_SERVICE_VERSION` | Service version | `1.0.0` |
-| `OTEL_ENVIRONMENT` | Deployment environment | `development` |
+| `SERVICE_VERSION` | Service version | `1.0.0` |
+| `NODE_ENV` | Environment | `development` |
 | `LOG_LEVEL` | Log level | `info` |
 
 ---
@@ -272,6 +408,25 @@ process.on('SIGTERM', async () => {
 
 ---
 
+## Project Structure
+
+```
+src/
+├── index.ts                    # Main exports
+├── config.ts                   # Zod configuration schemas
+├── foundation.ts               # createFoundation() entry point
+├── features/
+│   ├── context.ts              # AsyncLocalStorage context manager
+│   ├── logging.ts              # Pino logger setup
+│   ├── tracing.ts              # OTEL trace provider
+│   └── metrics.ts              # OTEL meter provider
+└── integrations/
+    ├── fastify-plugin.ts       # Fastify observability plugin
+    └── http-client.ts          # Axios wrapper with observability
+```
+
+---
+
 ## Development
 
 ```bash
@@ -283,6 +438,12 @@ npm run build
 
 # Type check
 npm run typecheck
+
+# Lint
+npm run lint
+
+# Format
+npm run prettier:write
 ```
 
 ---
@@ -290,4 +451,3 @@ npm run typecheck
 ## License
 
 MIT
-