@aichatwar/shared 1.0.146 → 1.0.148

package/build/events/userEvents.d.ts

@@ -10,6 +10,7 @@ interface UserCreatedEvent extends BaseEvent {
         version: number;
         isAgent?: boolean;
         ownerUserId?: string;
+        role?: 'user' | 'admin';
     };
 }
 interface UserUpdatedEvent extends BaseEvent {
@@ -19,6 +20,7 @@ interface UserUpdatedEvent extends BaseEvent {
         email: string;
         status: UserStatus;
         version: number;
+        role?: 'user' | 'admin';
     };
 }
 interface UserSingedInEvent extends BaseEvent {

package/build/index.d.ts

@@ -7,10 +7,13 @@ export * from "./errors/requestValidationError";
 export * from "./middlewares/error-handler";
 export * from "./middlewares/jwt-extractor";
 export * from "./middlewares/login-required";
+export * from "./middlewares/require-role";
 export * from "./middlewares/validate-request";
 export * from "./observability/logger";
 export * from "./observability/correlation";
 export * from "./observability/express";
+export * from "./observability/tracing";
+export * from "./observability/third-party-logging";
 export * from "./events/nats/baseListener";
 export * from "./events/nats/basePublisher";
 export * from "./events/kafka/baseListener";

package/build/index.js

@@ -23,11 +23,14 @@ __exportStar(require("./errors/requestValidationError"), exports);
 __exportStar(require("./middlewares/error-handler"), exports);
 __exportStar(require("./middlewares/jwt-extractor"), exports);
 __exportStar(require("./middlewares/login-required"), exports);
+__exportStar(require("./middlewares/require-role"), exports);
 __exportStar(require("./middlewares/validate-request"), exports);
 // Observability (Phase 1)
 __exportStar(require("./observability/logger"), exports);
 __exportStar(require("./observability/correlation"), exports);
 __exportStar(require("./observability/express"), exports);
+__exportStar(require("./observability/tracing"), exports);
+__exportStar(require("./observability/third-party-logging"), exports);
 __exportStar(require("./events/nats/baseListener"), exports);
 __exportStar(require("./events/nats/basePublisher"), exports);
 __exportStar(require("./events/kafka/baseListener"), exports);

package/build/middlewares/jwt-extractor.d.ts

@@ -1,7 +1,8 @@
 import { Request, Response, NextFunction } from "express";
-interface JwtPayload {
+export interface JwtPayload {
     id: string;
     email: string;
+    role?: 'user' | 'admin';
 }
 declare global {
     namespace Express {

package/build/middlewares/require-role.d.ts

@@ -0,0 +1,21 @@
+import { Request, Response, NextFunction } from 'express';
+/**
+ * Middleware to require a specific role or roles
+ * Must be used after extractJWTPayload and loginRequired middleware
+ *
+ * @param allowedRoles - Single role string or array of role strings
+ * @returns Express middleware function
+ *
+ * @example
+ * router.get('/admin/users', extractJWTPayload, loginRequired, requireRole('admin'), handler);
+ * router.get('/moderator/content', extractJWTPayload, loginRequired, requireRole(['admin', 'moderator']), handler);
+ */
+export declare const requireRole: (allowedRoles: string | string[]) => (req: Request, res: Response, next: NextFunction) => void;
+/**
+ * Convenience middleware to require admin role
+ * Must be used after extractJWTPayload and loginRequired middleware
+ *
+ * @example
+ * router.get('/admin/users', extractJWTPayload, loginRequired, requireAdmin, handler);
+ */
+export declare const requireAdmin: (req: Request, res: Response, next: NextFunction) => void;

package/build/middlewares/require-role.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.requireAdmin = exports.requireRole = void 0;
+const notAuthorizedError_1 = require("../errors/notAuthorizedError");
+/**
+ * Middleware to require a specific role or roles
+ * Must be used after extractJWTPayload and loginRequired middleware
+ *
+ * @param allowedRoles - Single role string or array of role strings
+ * @returns Express middleware function
+ *
+ * @example
+ * router.get('/admin/users', extractJWTPayload, loginRequired, requireRole('admin'), handler);
+ * router.get('/moderator/content', extractJWTPayload, loginRequired, requireRole(['admin', 'moderator']), handler);
+ */
+const requireRole = (allowedRoles) => {
+    return (req, res, next) => {
+        if (!req.jwtPayload) {
+            throw new notAuthorizedError_1.NotAuthorizedError(['Authentication required']);
+        }
+        const roles = Array.isArray(allowedRoles) ? allowedRoles : [allowedRoles];
+        const userRole = req.jwtPayload.role || 'user'; // Default to 'user' if role not set
+        if (!roles.includes(userRole)) {
+            throw new notAuthorizedError_1.NotAuthorizedError(['Insufficient permissions']);
+        }
+        next();
+    };
+};
+exports.requireRole = requireRole;
+/**
+ * Convenience middleware to require admin role
+ * Must be used after extractJWTPayload and loginRequired middleware
+ *
+ * @example
+ * router.get('/admin/users', extractJWTPayload, loginRequired, requireAdmin, handler);
+ */
+exports.requireAdmin = (0, exports.requireRole)('admin');

package/build/observability/third-party-logging.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Standardized logging for 3rd-party API calls
+ *
+ * This module provides helpers for logging:
+ * - Retry attempts (WARN level)
+ * - Final failures (ERROR level)
+ * - Rate limits (WARN/ERROR based on impact)
+ * - Unmasked error details (stack traces, status codes, request IDs)
+ * - Correlation IDs for traceability
+ *
+ * Best practices:
+ * - Each retry: log as WARN with attempt, backoff, reason
+ * - Final failure: log as ERROR with full error context
+ * - Rate limits: log as WARN or ERROR depending on user impact
+ */
+export interface ThirdPartyErrorContext {
+    /** Provider name (e.g., 'openai', 'anthropic', 'cohere') */
+    provider: string;
+    /** Operation name (e.g., 'generateResponse', 'createAgent') */
+    operation: string;
+    /** HTTP status code if available */
+    statusCode?: number;
+    /** Error type/class */
+    errorType?: string;
+    /** Error message */
+    errorMessage: string;
+    /** Full error object (for stack trace) */
+    error: any;
+    /** Whether this error is retryable */
+    retryable?: boolean;
+    /** Request ID from upstream service if available */
+    requestId?: string;
+    /** Rate limit headers if available */
+    rateLimitHeaders?: {
+        limit?: string;
+        remaining?: string;
+        reset?: string;
+    };
+    /** Additional metadata */
+    metadata?: Record<string, any>;
+}
+export interface RetryAttemptContext {
+    /** Provider name */
+    provider: string;
+    /** Operation name */
+    operation: string;
+    /** Current attempt number (1-indexed) */
+    attempt: number;
+    /** Maximum number of attempts */
+    maxAttempts: number;
+    /** Backoff delay in milliseconds */
+    backoffMs: number;
+    /** Reason for retry */
+    reason: string;
+    /** Previous error that triggered retry */
+    previousError?: any;
+    /** HTTP status code from previous attempt */
+    previousStatusCode?: number;
+}
+/**
+ * Log a retry attempt for a 3rd-party API call
+ *
+ * This should be called BEFORE each retry attempt.
+ * Logs at WARN level as per observability best practices.
+ *
+ * @param context Retry attempt context
+ */
+export declare function logRetryAttempt(context: RetryAttemptContext): void;
+/**
+ * Log a final failure for a 3rd-party API call
+ *
+ * This should be called when all retries are exhausted or when a non-retryable error occurs.
+ * Logs at ERROR level with full unmasked error details.
+ *
+ * @param context Error context
+ */
+export declare function logThirdPartyError(context: ThirdPartyErrorContext): void;
+/**
+ * Log a successful 3rd-party API call
+ *
+ * @param provider Provider name
+ * @param operation Operation name
+ * @param durationMs Duration in milliseconds
+ * @param metadata Additional metadata (e.g., token usage, request ID)
+ */
+export declare function logThirdPartySuccess(provider: string, operation: string, durationMs: number, metadata?: Record<string, any>): void;
+/**
+ * Extract error context from a caught error
+ *
+ * Handles various error types:
+ * - Axios errors (with response.status, response.data)
+ * - OpenAI SDK errors (with status, message)
+ * - Anthropic SDK errors (with status, message)
+ * - Generic errors
+ *
+ * @param error Error object
+ * @param provider Provider name
+ * @param operation Operation name
+ * @returns Error context
+ */
+export declare function extractErrorContext(error: any, provider: string, operation: string): ThirdPartyErrorContext;

package/build/observability/third-party-logging.js

@@ -0,0 +1,212 @@
+"use strict";
+/**
+ * Standardized logging for 3rd-party API calls
+ *
+ * This module provides helpers for logging:
+ * - Retry attempts (WARN level)
+ * - Final failures (ERROR level)
+ * - Rate limits (WARN/ERROR based on impact)
+ * - Unmasked error details (stack traces, status codes, request IDs)
+ * - Correlation IDs for traceability
+ *
+ * Best practices:
+ * - Each retry: log as WARN with attempt, backoff, reason
+ * - Final failure: log as ERROR with full error context
+ * - Rate limits: log as WARN or ERROR depending on user impact
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.logRetryAttempt = logRetryAttempt;
+exports.logThirdPartyError = logThirdPartyError;
+exports.logThirdPartySuccess = logThirdPartySuccess;
+exports.extractErrorContext = extractErrorContext;
+const logger_1 = require("./logger");
+const correlation_1 = require("./correlation");
+const tracing_1 = require("./tracing");
+/**
+ * Log a retry attempt for a 3rd-party API call
+ *
+ * This should be called BEFORE each retry attempt.
+ * Logs at WARN level as per observability best practices.
+ *
+ * @param context Retry attempt context
+ */
+function logRetryAttempt(context) {
+    var _a, _b, _c, _d, _e, _f;
+    const correlationId = (0, correlation_1.getCorrelationId)();
+    (0, logger_1.logger)().warn({
+        message: '3rd-party API retry attempt',
+        provider: context.provider,
+        operation: context.operation,
+        attempt: context.attempt,
+        maxAttempts: context.maxAttempts,
+        backoffMs: context.backoffMs,
+        reason: context.reason,
+        previousStatusCode: context.previousStatusCode,
+        correlationId,
+        // Include previous error details (unmasked) for debugging
+        previousError: context.previousError ? {
+            type: ((_b = (_a = context.previousError) === null || _a === void 0 ? void 0 : _a.constructor) === null || _b === void 0 ? void 0 : _b.name) || typeof context.previousError,
+            message: (_c = context.previousError) === null || _c === void 0 ? void 0 : _c.message,
+            status: ((_d = context.previousError) === null || _d === void 0 ? void 0 : _d.status) || ((_e = context.previousError) === null || _e === void 0 ? void 0 : _e.statusCode),
+            code: (_f = context.previousError) === null || _f === void 0 ? void 0 : _f.code,
+            // Don't include full stack in retry log (will be in final error log)
+        } : undefined,
+    });
+    // Add retry attempt to span
+    (0, tracing_1.addSpanAttributes)({
+        [`${context.provider}.retry.attempt`]: context.attempt,
+        [`${context.provider}.retry.reason`]: context.reason,
+    });
+}
+/**
+ * Log a final failure for a 3rd-party API call
+ *
+ * This should be called when all retries are exhausted or when a non-retryable error occurs.
+ * Logs at ERROR level with full unmasked error details.
+ *
+ * @param context Error context
+ */
+function logThirdPartyError(context) {
+    var _a, _b, _c;
+    const correlationId = (0, correlation_1.getCorrelationId)();
+    // Determine log level: ERROR for failures, WARN for rate limits that don't block user
+    const isRateLimit = context.statusCode === 429;
+    const logLevel = isRateLimit && !context.retryable ? 'warn' : 'error';
+    // Build error log entry with unmasked details
+    const errorLog = Object.assign({ message: `3rd-party API ${context.operation} failed`, provider: context.provider, operation: context.operation, errorType: context.errorType || ((_b = (_a = context.error) === null || _a === void 0 ? void 0 : _a.constructor) === null || _b === void 0 ? void 0 : _b.name) || 'UnknownError', errorMessage: context.errorMessage, statusCode: context.statusCode, retryable: context.retryable, correlationId, 
+        // Include full error object for stack trace (unmasked)
+        err: context.error, 
+        // Include request ID if available (for upstream debugging)
+        requestId: context.requestId, 
+        // Include rate limit headers if available
+        rateLimit: context.rateLimitHeaders }, (context.metadata || {}));
+    // Log at appropriate level
+    if (logLevel === 'error') {
+        (0, logger_1.logger)().error(errorLog);
+    }
+    else {
+        (0, logger_1.logger)().warn(errorLog);
+    }
+    // Record exception in OpenTelemetry span
+    if (context.error instanceof Error) {
+        (0, tracing_1.recordSpanException)(context.error);
+    }
+    else {
+        // Create Error object if not already one
+        const errorObj = new Error(context.errorMessage);
+        if ((_c = context.error) === null || _c === void 0 ? void 0 : _c.stack) {
+            errorObj.stack = context.error.stack;
+        }
+        (0, tracing_1.recordSpanException)(errorObj);
+    }
+    // Add error attributes to span
+    (0, tracing_1.addSpanAttributes)({
+        [`${context.provider}.error`]: true,
+        [`${context.provider}.error.type`]: context.errorType || 'UnknownError',
+        [`${context.provider}.error.status_code`]: context.statusCode || 0,
+        [`${context.provider}.error.retryable`]: context.retryable || false,
+    });
+}
+/**
+ * Log a successful 3rd-party API call
+ *
+ * @param provider Provider name
+ * @param operation Operation name
+ * @param durationMs Duration in milliseconds
+ * @param metadata Additional metadata (e.g., token usage, request ID)
+ */
+function logThirdPartySuccess(provider, operation, durationMs, metadata) {
+    const correlationId = (0, correlation_1.getCorrelationId)();
+    (0, logger_1.logger)().info(Object.assign({ message: `3rd-party API ${operation} succeeded`, provider,
+        operation, duration_ms: durationMs, correlationId }, (metadata || {})));
+    // Add success attributes to span
+    (0, tracing_1.addSpanAttributes)({
+        [`${provider}.success`]: true,
+        [`${provider}.duration_ms`]: durationMs,
+    });
+}
+/**
+ * Extract error context from a caught error
+ *
+ * Handles various error types:
+ * - Axios errors (with response.status, response.data)
+ * - OpenAI SDK errors (with status, message)
+ * - Anthropic SDK errors (with status, message)
+ * - Generic errors
+ *
+ * @param error Error object
+ * @param provider Provider name
+ * @param operation Operation name
+ * @returns Error context
+ */
+function extractErrorContext(error, provider, operation) {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l;
+    // Extract status code from various error formats
+    let statusCode;
+    let requestId;
+    let rateLimitHeaders;
+    // Handle Axios errors
+    if (error.response) {
+        statusCode = error.response.status;
+        requestId = ((_a = error.response.headers) === null || _a === void 0 ? void 0 : _a['x-request-id']) || ((_b = error.response.headers) === null || _b === void 0 ? void 0 : _b['request-id']);
+        rateLimitHeaders = {
+            limit: (_c = error.response.headers) === null || _c === void 0 ? void 0 : _c['x-ratelimit-limit'],
+            remaining: (_d = error.response.headers) === null || _d === void 0 ? void 0 : _d['x-ratelimit-remaining'],
+            reset: (_e = error.response.headers) === null || _e === void 0 ? void 0 : _e['x-ratelimit-reset'],
+        };
+    }
+    // Handle OpenAI/Anthropic SDK errors
+    else if (error.status) {
+        statusCode = error.status;
+        requestId = error.request_id || error.requestId;
+    }
+    // Handle HTTP errors with statusCode
+    else if (error.statusCode) {
+        statusCode = error.statusCode;
+    }
+    // Determine if error is retryable
+    const retryable = isRetryableError(statusCode, error.code);
+    // Extract error message
+    const errorMessage = error.message ||
+        ((_h = (_g = (_f = error.response) === null || _f === void 0 ? void 0 : _f.data) === null || _g === void 0 ? void 0 : _g.error) === null || _h === void 0 ? void 0 : _h.message) ||
+        ((_k = (_j = error.response) === null || _j === void 0 ? void 0 : _j.data) === null || _k === void 0 ? void 0 : _k.message) ||
+        'Unknown error';
+    return {
+        provider,
+        operation,
+        statusCode,
+        errorType: ((_l = error.constructor) === null || _l === void 0 ? void 0 : _l.name) || error.type || 'UnknownError',
+        errorMessage,
+        error,
+        retryable,
+        requestId,
+        rateLimitHeaders,
+        metadata: {
+            code: error.code,
+            type: error.type,
+        },
+    };
+}
+/**
+ * Determine if an error is retryable based on status code and error code
+ *
+ * @param statusCode HTTP status code
+ * @param errorCode Error code (e.g., 'ECONNREFUSED', 'ETIMEDOUT')
+ * @returns true if error is retryable
+ */
+function isRetryableError(statusCode, errorCode) {
+    // Retryable HTTP status codes
+    if (statusCode === 429 || statusCode === 500 || statusCode === 502 || statusCode === 503 || statusCode === 504) {
+        return true;
+    }
+    // Retryable network errors
+    if (errorCode === 'ECONNREFUSED' || errorCode === 'ETIMEDOUT' || errorCode === 'ENOTFOUND') {
+        return true;
+    }
+    // Non-retryable: authentication, invalid requests, not found
+    if (statusCode === 401 || statusCode === 400 || statusCode === 404) {
+        return false;
+    }
+    // Default to retryable for unknown errors (conservative approach)
+    return true;
+}

package/build/observability/tracing.d.ts

@@ -0,0 +1,51 @@
+/**
+ * OpenTelemetry tracing setup with Azure Monitor exporter
+ *
+ * This module initializes OpenTelemetry SDK with:
+ * - Azure Monitor exporter for Application Insights
+ * - Auto-instrumentation for HTTP, MongoDB, Redis, Kafka
+ * - Correlation ID propagation
+ * - Service name and version from environment
+ */
+import { NodeSDK } from '@opentelemetry/sdk-node';
+import { Span } from '@opentelemetry/api';
+/**
+ * Initialize OpenTelemetry SDK with Azure Monitor exporter
+ *
+ * Environment variables:
+ * - APPLICATIONINSIGHTS_CONNECTION_STRING: Azure Application Insights connection string
+ * - SERVICE_NAME: Service name (default: 'unknown-service')
+ * - APP_VERSION: Service version (default: 'unknown')
+ * - OTEL_SERVICE_NAME: OpenTelemetry service name (falls back to SERVICE_NAME)
+ * - OTEL_LOG_LEVEL: OpenTelemetry log level (default: 'info')
+ *
+ * @returns NodeSDK instance or null if initialization fails
+ */
+export declare function initializeTracing(): NodeSDK | null;
+/**
+ * Shutdown OpenTelemetry SDK gracefully
+ * Call this during service shutdown
+ */
+export declare function shutdownTracing(): Promise<void>;
+/**
+ * Get the current active span
+ * @returns Active span or undefined
+ */
+export declare function getActiveSpan(): Span | undefined;
+/**
+ * Create a new span for an operation
+ * @param name Span name
+ * @param fn Function to execute within the span
+ * @returns Result of the function
+ */
+export declare function withSpan<T>(name: string, fn: (span: Span) => Promise<T> | T): Promise<T>;
+/**
+ * Add attributes to the current active span
+ * @param attributes Key-value pairs to add
+ */
+export declare function addSpanAttributes(attributes: Record<string, string | number | boolean>): void;
+/**
+ * Record an exception on the current active span
+ * @param error Error to record
+ */
+export declare function recordSpanException(error: Error): void;

package/build/observability/tracing.js

@@ -0,0 +1,211 @@
+"use strict";
+/**
+ * OpenTelemetry tracing setup with Azure Monitor exporter
+ *
+ * This module initializes OpenTelemetry SDK with:
+ * - Azure Monitor exporter for Application Insights
+ * - Auto-instrumentation for HTTP, MongoDB, Redis, Kafka
+ * - Correlation ID propagation
+ * - Service name and version from environment
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.initializeTracing = initializeTracing;
+exports.shutdownTracing = shutdownTracing;
+exports.getActiveSpan = getActiveSpan;
+exports.withSpan = withSpan;
+exports.addSpanAttributes = addSpanAttributes;
+exports.recordSpanException = recordSpanException;
+const sdk_node_1 = require("@opentelemetry/sdk-node");
+const auto_instrumentations_node_1 = require("@opentelemetry/auto-instrumentations-node");
+const monitor_opentelemetry_exporter_1 = require("@azure/monitor-opentelemetry-exporter");
+const resources_1 = require("@opentelemetry/resources");
+const semantic_conventions_1 = require("@opentelemetry/semantic-conventions");
+const api_1 = require("@opentelemetry/api");
+const correlation_1 = require("./correlation");
+const logger_1 = require("./logger");
+let sdk = null;
+/**
+ * Initialize OpenTelemetry SDK with Azure Monitor exporter
+ *
+ * Environment variables:
+ * - APPLICATIONINSIGHTS_CONNECTION_STRING: Azure Application Insights connection string
+ * - SERVICE_NAME: Service name (default: 'unknown-service')
+ * - APP_VERSION: Service version (default: 'unknown')
+ * - OTEL_SERVICE_NAME: OpenTelemetry service name (falls back to SERVICE_NAME)
+ * - OTEL_LOG_LEVEL: OpenTelemetry log level (default: 'info')
+ *
+ * @returns NodeSDK instance or null if initialization fails
+ */
+function initializeTracing() {
+    // Skip if already initialized
+    if (sdk) {
+        (0, logger_1.logger)().warn({ message: 'OpenTelemetry SDK already initialized' });
+        return sdk;
+    }
+    const connectionString = process.env.APPLICATIONINSIGHTS_CONNECTION_STRING;
+    const serviceName = process.env.OTEL_SERVICE_NAME || process.env.SERVICE_NAME || 'unknown-service';
+    const serviceVersion = process.env.APP_VERSION || 'unknown';
+    // If no connection string, skip initialization (useful for local dev)
+    if (!connectionString) {
+        (0, logger_1.logger)().warn({
+            message: 'OpenTelemetry initialization skipped: APPLICATIONINSIGHTS_CONNECTION_STRING not set',
+            serviceName,
+        });
+        return null;
+    }
+    try {
+        // Create Azure Monitor trace exporter
+        const traceExporter = new monitor_opentelemetry_exporter_1.AzureMonitorTraceExporter({
+            connectionString,
+        });
+        // Create resource with service metadata
+        const resource = (0, resources_1.resourceFromAttributes)({
+            [semantic_conventions_1.SemanticResourceAttributes.SERVICE_NAME]: serviceName,
+            [semantic_conventions_1.SemanticResourceAttributes.SERVICE_VERSION]: serviceVersion,
+            [semantic_conventions_1.SemanticResourceAttributes.DEPLOYMENT_ENVIRONMENT]: process.env.NODE_ENV || 'development',
+        });
+        // Initialize SDK with auto-instrumentation
+        sdk = new sdk_node_1.NodeSDK({
+            resource,
+            traceExporter,
+            instrumentations: [
+                (0, auto_instrumentations_node_1.getNodeAutoInstrumentations)({
+                    // Enable HTTP instrumentation (Express, etc.)
+                    '@opentelemetry/instrumentation-http': {
+                        enabled: true,
+                    },
+                    // Enable MongoDB instrumentation
+                    '@opentelemetry/instrumentation-mongodb': {
+                        enabled: true,
+                    },
+                    // Enable Redis instrumentation (if using ioredis or node-redis)
+                    '@opentelemetry/instrumentation-redis': {
+                        enabled: true,
+                    },
+                    // Enable Kafka instrumentation
+                    '@opentelemetry/instrumentation-kafkajs': {
+                        enabled: true,
+                    },
+                    // Disable fs instrumentation (too noisy)
+                    '@opentelemetry/instrumentation-fs': {
+                        enabled: false,
+                    },
+                }),
+            ],
+        });
+        // Start the SDK
+        sdk.start();
+        (0, logger_1.logger)().info({
+            message: 'OpenTelemetry SDK initialized successfully',
+            serviceName,
+            serviceVersion,
+            exporter: 'AzureMonitor',
+        });
+        return sdk;
+    }
+    catch (error) {
+        (0, logger_1.logger)().error({
+            err: error,
+            message: 'Failed to initialize OpenTelemetry SDK',
+            serviceName,
+        });
+        return null;
+    }
+}
+/**
+ * Shutdown OpenTelemetry SDK gracefully
+ * Call this during service shutdown
+ */
+function shutdownTracing() {
+    return __awaiter(this, void 0, void 0, function* () {
+        if (sdk) {
+            try {
+                yield sdk.shutdown();
+                (0, logger_1.logger)().info({ message: 'OpenTelemetry SDK shut down successfully' });
+                sdk = null;
+            }
+            catch (error) {
+                (0, logger_1.logger)().error({
+                    err: error,
+                    message: 'Error shutting down OpenTelemetry SDK',
+                });
+            }
+        }
+    });
+}
+/**
+ * Get the current active span
+ * @returns Active span or undefined
+ */
+function getActiveSpan() {
+    return api_1.trace.getActiveSpan();
+}
+/**
+ * Create a new span for an operation
+ * @param name Span name
+ * @param fn Function to execute within the span
+ * @returns Result of the function
+ */
+function withSpan(name, fn) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const tracer = api_1.trace.getTracer(process.env.SERVICE_NAME || 'unknown-service', process.env.APP_VERSION || 'unknown');
+        return tracer.startActiveSpan(name, (span) => __awaiter(this, void 0, void 0, function* () {
+            try {
+                // Add correlation ID to span attributes
+                const correlationId = (0, correlation_1.getCorrelationId)();
+                if (correlationId) {
+                    span.setAttribute('correlation.id', correlationId);
+                }
+                const result = yield fn(span);
+                span.setStatus({ code: api_1.SpanStatusCode.OK });
+                return result;
+            }
+            catch (error) {
+                span.setStatus({
+                    code: api_1.SpanStatusCode.ERROR,
+                    message: error.message,
+                });
+                span.recordException(error);
+                throw error;
+            }
+            finally {
+                span.end();
+            }
+        }));
+    });
+}
+/**
+ * Add attributes to the current active span
+ * @param attributes Key-value pairs to add
+ */
+function addSpanAttributes(attributes) {
+    const span = getActiveSpan();
+    if (span) {
+        Object.entries(attributes).forEach(([key, value]) => {
+            span.setAttribute(key, value);
+        });
+    }
+}
+/**
+ * Record an exception on the current active span
+ * @param error Error to record
+ */
+function recordSpanException(error) {
+    const span = getActiveSpan();
+    if (span) {
+        span.recordException(error);
+        span.setStatus({
+            code: api_1.SpanStatusCode.ERROR,
+            message: error.message,
+        });
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aichatwar/shared",
-  "version": "1.0.146",
+  "version": "1.0.148",
   "main": "./build/index.js",
   "typs": "./build/index.d.ts",
   "files": [
@@ -28,6 +28,12 @@
     "express-validator": "^7.2.1"
   },
   "dependencies": {
+    "@azure/monitor-opentelemetry-exporter": "^1.0.0-beta.32",
+    "@opentelemetry/api": "^1.8.0",
+    "@opentelemetry/auto-instrumentations-node": "^0.69.0",
+    "@opentelemetry/resources": "^2.5.1",
+    "@opentelemetry/semantic-conventions": "^1.24.0",
+    "@opentelemetry/sdk-node": "^0.212.0",
     "jsonwebtoken": "^9.0.2",
     "kafkajs": "^2.2.4",
     "mongoose-update-if-current": "^1.4.0",