npm package: @sandip1046/rubizz-shared-libs
Description: Shared libraries and utilities for Rubizz Hotel Inn microservices
Author: Rubizz Hotel Inn
Latest version: 1.5.0

# Rubizz Shared Libraries

[![npm version](https://img.shields.io/npm/v/@sandip1046/rubizz-shared-libs.svg)](https://www.npmjs.com/package/@sandip1046/rubizz-shared-libs)
[![npm downloads](https://img.shields.io/npm/dm/@sandip1046/rubizz-shared-libs.svg)](https://www.npmjs.com/package/@sandip1046/rubizz-shared-libs)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.3+-blue.svg)](https://www.typescriptlang.org/)

## Overview

The Rubizz Shared Libraries (`@sandip1046/rubizz-shared-libs`) is a common NPM package that provides shared utilities, types, configurations, and services across all Rubizz Hotel Inn microservices. It ensures consistency, reduces code duplication, and provides a centralized location for common functionality.

**📦 Published Package**: [@sandip1046/rubizz-shared-libs](https://www.npmjs.com/package/@sandip1046/rubizz-shared-libs)  
**🔗 GitHub Repository**: [sandip1046/rubizz-shared-libs](https://github.com/sandip1046/rubizz-shared-libs)  
**🚀 Automated Publishing**: GitHub Actions workflow for seamless releases

## Package Structure

```
src/
├── types/           # TypeScript types and interfaces
├── utils/           # Utility functions (including ProtoVerifier)
├── auth/            # Authentication utilities
├── database/        # Database connection utilities
├── logger/          # Logging utilities
├── email/           # Email service utilities
├── validation/      # Validation schemas
├── constants/        # Constants and enums
├── prisma/           # Prisma ORM utilities
├── events/           # Event handling utilities
├── services/         # Service integrations (Redis, etc.)
├── grpc/             # gRPC utilities (HealthCheckService)
├── websocket/        # WebSocket utilities (ConnectionManager)
├── __tests__/        # Test files and setup
└── index.ts          # Main export file

dist/                # Compiled JavaScript output
├── *.js             # Compiled JavaScript files
├── *.d.ts           # TypeScript declaration files
└── *.js.map         # Source maps

.github/
└── workflows/
    └── publish.yml  # Automated publishing workflow
```

## Core Features

### 1. Authentication & Authorization
- JWT token generation and verification
- Password hashing and comparison
- Role-based access control utilities
- Password reset token management

### 2. Database Management
- Prisma client initialization and management
- Database connection pooling
- Health check utilities
- Transaction management

### 3. Redis Integration
- Redis connection management
- Session storage utilities
- Caching helpers
- Message queue operations
- Redis service client for centralized Redis operations
- Support for multiple Redis instances (session, cache, queue)

### 4. Logging System
- Winston-based centralized logging
- Request/response logging middleware
- Error logging utilities
- Service-specific loggers

### 5. Email Services
- Nodemailer integration
- Email template management
- Verification and notification emails
- Brevo API integration

### 6. Validation Schemas
- Joi validation schemas
- Common validation rules
- Request validation utilities
- Error handling

### 7. Utility Functions
- UUID generation
- Date formatting
- String manipulation
- Pagination helpers
- Retry mechanisms
- Email and phone validation
- Random string generation
- Deep cloning and object utilities
- Proto file verification and validation

### 8. gRPC Health Check Service
- Standard gRPC Health Checking Protocol implementation
- Service health status management (SERVING, NOT_SERVING, UNKNOWN)
- Unary health check endpoint
- Streaming health watch endpoint
- Automatic service registration
- Health status tracking and monitoring

### 9. WebSocket Connection Management
- Connection lifecycle management
- Automatic ping/pong health monitoring
- Connection state tracking (CONNECTING, CONNECTED, RECONNECTING, DISCONNECTED, ERROR)
- Token-based reconnection with state preservation
- Automatic cleanup of stale connections
- Connection statistics and monitoring
- User-based connection tracking
- Configurable timeouts and intervals

### 10. Kafka Utilities
- Dead Letter Queue (DLQ) handler with retry logic
- Event schema validation (JSON Schema)
- Exponential backoff retry strategies
- DLQ event tracking and statistics
- Common event types and interfaces
- Event serialization/deserialization helpers

### 11. Error Handling
- Standardized error classes (AppError, BadRequestError, NotFoundError, etc.)
- Error code enumeration
- Error metadata support
- Operational vs programming error distinction
- Error normalization and formatting utilities

### 12. HTTP Client Utilities
- HTTP client with automatic retry and exponential backoff
- Circuit breaker pattern implementation
- Request timeout handling
- Configurable retry strategies
- Circuit breaker state management (CLOSED, OPEN, HALF_OPEN)

### 13. API Response Formatters
- Standardized success/error response formatting
- Paginated response formatters
- Created/updated/deleted response helpers
- Consistent API response structure

### 14. Version Management
- Semantic version parsing and formatting
- Version comparison utilities
- Version range satisfaction checking (^, ~, >=, <=, >, <)
- Version increment utilities (major, minor, patch)

### 15. Resilience & Error Handling
- **Circuit Breaker**: Enhanced circuit breaker with state management (CLOSED, OPEN, HALF_OPEN)
  - Configurable failure thresholds
  - Automatic state transitions
  - Statistics and monitoring
- **Retry Strategies**: Multiple retry strategies with different backoff algorithms
  - Fixed delay retry
  - Exponential backoff
  - Linear backoff
  - Jitter backoff (with randomization)
  - Custom retry predicates
- **Bulkhead Pattern**: Resource isolation to prevent cascading failures
  - Concurrent execution limits
  - Queue management
  - Timeout handling
- **Timeout Utilities**: Operation timeout management
  - Timeout execution wrappers
  - Cancellable timeouts
  - Delay utilities
- **Graceful Degradation**: Fallback strategies for service failures
  - Primary/fallback operations
  - Cache fallback support
  - Default value fallback
  - Custom degradation strategies

### 16. Security Utilities
- **Input Sanitization** (`InputSanitizer`)
  - XSS prevention with DOMPurify
  - HTML entity encoding/decoding
  - SQL injection pattern removal
  - NoSQL injection prevention
  - File path sanitization
  - Email and URL sanitization
  - Recursive object sanitization
- **CSRF Protection** (`CSRFProtection`)
  - Token generation and verification
  - Signed token support
  - Cookie and header-based tokens
  - Express middleware integration
  - Configurable cookie options
- **Security Headers** (`SecurityHeaders`)
  - Content Security Policy (CSP) builder
  - Strict Transport Security (HSTS)
  - X-Frame-Options
  - X-Content-Type-Options
  - X-XSS-Protection
  - Referrer-Policy
  - Permissions-Policy
  - Default security configurations

### 17. Observability & Monitoring
- **Distributed Tracing** (`Tracing`)
  - OpenTelemetry integration
  - W3C traceparent format support
  - Span creation and management
  - Context propagation (extract/inject)
  - Automatic error recording
- **Metrics Collection** (`Metrics`)
  - Counter, Gauge, and Histogram metrics
  - HTTP, gRPC, Database, and Kafka metrics
  - In-memory metric collector
  - Metric aggregation (sum, avg, min, max, count)
  - Custom metric collectors support
- **Application Performance Monitoring** (`APM`)
  - Performance metric recording
  - Service health monitoring
  - Performance statistics (p50, p95, p99)
  - Slow operation detection
  - Error operation tracking
  - Uptime and throughput tracking
- **Alerting** (`Alerting`)
  - Alert rule management
  - Alert creation and resolution
  - Alert acknowledgment
  - Custom alert handlers
  - Cooldown periods
  - Severity levels (critical, warning, info)

### 18. Testing & Quality
- Jest test framework integration
- TypeScript test configuration
- Comprehensive test coverage
- ESLint code quality checks
- Automated testing in CI/CD

## Installation

```bash
# Install the published package
npm install @sandip1046/rubizz-shared-libs

# Or install specific version
npm install @sandip1046/rubizz-shared-libs@^1.0.0

# Or install latest version
npm install @sandip1046/rubizz-shared-libs@latest
```

### Package Information
- **Package Name**: `@sandip1046/rubizz-shared-libs`
- **Current Version**: `1.5.0`
- **Registry**: [npmjs.com](https://www.npmjs.com/package/@sandip1046/rubizz-shared-libs)
- **Size**: ~45 kB (unpacked)
- **Files**: 70+ files included

## Usage

### Basic Setup

```typescript
import { 
  Logger, 
  AuthUtils, 
  DatabaseManager, 
  RedisManager,
  Utils,
  ValidationSchemas,
  BrevoEmailService,
  RedisClient,
  RedisInstanceType,
  RedisOperation,
  HealthCheckService,
  ServingStatus,
  WebSocketConnectionManager,
  ConnectionState,
  ProtoVerifier
} from '@sandip1046/rubizz-shared-libs';

// Initialize logger
const logger = Logger.getInstance('service-name', 'production');

// Initialize authentication
AuthUtils.initialize({
  secret: process.env.JWT_SECRET,
  expiresIn: process.env.JWT_EXPIRES_IN,
  refreshExpiresIn: process.env.JWT_REFRESH_EXPIRES_IN
});

// Initialize database
DatabaseManager.initialize({
  host: process.env.DB_HOST,
  port: parseInt(process.env.DB_PORT),
  database: process.env.DB_NAME,
  username: process.env.DB_USERNAME,
  password: process.env.DB_PASSWORD,
  ssl: process.env.DB_SSL === 'true',
  poolSize: parseInt(process.env.DB_POOL_SIZE)
});

// Initialize Redis
RedisManager.initialize({
  host: process.env.REDIS_HOST,
  port: parseInt(process.env.REDIS_PORT),
  password: process.env.REDIS_PASSWORD,
  db: parseInt(process.env.REDIS_DB),
  retryDelayOnFailover: 100,
  maxRetriesPerRequest: 3
});

// Initialize email service
BrevoEmailService.initialize(
  process.env.BREVO_API_KEY,
  process.env.FROM_EMAIL
);
```

### Authentication Usage

```typescript
// Generate JWT token
const accessToken = AuthUtils.generateAccessToken({
  userId: user.id,
  email: user.email,
  role: user.role
});

// Verify JWT token
const payload = AuthUtils.verifyToken(token);

// Hash password
const hashedPassword = await AuthUtils.hashPassword(password);

// Compare password
const isValid = await AuthUtils.comparePassword(password, hash);
```

### Database Usage

```typescript
// Get database connection
const db = DatabaseManager.getConnection();

// Use Prisma client
const user = await db.user.create({
  data: {
    email: 'user@example.com',
    firstName: 'John',
    lastName: 'Doe'
  }
});

// Health check
const isHealthy = await DatabaseManager.healthCheck();
```

### Redis Usage

```typescript
// Set value
await RedisManager.set('key', 'value', 3600); // 1 hour TTL

// Get value
const value = await RedisManager.get('key');

// Hash operations
await RedisManager.hset('user:123', 'name', 'John');
const name = await RedisManager.hget('user:123', 'name');
```

### Logging Usage

```typescript
// Basic logging
logger.info('User created', { userId: user.id });
logger.error('Database error', error, { query: 'SELECT * FROM users' });

// Request logging middleware
app.use(Logger.createRequestLogger('service-name'));

// Error logging middleware
app.use(Logger.createErrorLogger('service-name'));
```

### Email Usage

```typescript
// Send verification email
await BrevoEmailService.sendVerificationEmail(
  'user@example.com',
  'verification-token'
);

// Send password reset email
await BrevoEmailService.sendPasswordResetEmail(
  'user@example.com',
  'reset-token'
);

// Send custom email
await BrevoEmailService.sendEmail({
  to: 'user@example.com',
  subject: 'Custom Email',
  template: 'custom-template',
  params: { name: 'John' }
});
```

### Validation Usage

```typescript
// Validate request body
const { error, value } = ValidationSchemas.userRegistration.validate(req.body);
if (error) {
  return res.status(400).json({ error: error.details[0].message });
}

// Validate query parameters
const { error, value } = ValidationSchemas.pagination.validate(req.query);
```

### Redis Service Client Usage

```typescript
// Using the Redis Service Client for centralized Redis operations
import { RedisClient, RedisInstanceType } from '@sandip1046/rubizz-shared-libs';

// Initialize Redis client
const redisClient = new RedisClient({
  baseUrl: process.env.REDIS_SERVICE_URL || 'http://localhost:3000/api/v1/redis',
  timeout: 30000,
  retries: 3,
  retryDelay: 1000,
});

// Basic operations
const value = await redisClient.get(RedisInstanceType.CACHE, 'user:123');
await redisClient.set(RedisInstanceType.CACHE, 'user:123', 'John Doe', 3600);

// Hash operations
await redisClient.hset(RedisInstanceType.SESSION, 'session:abc', 'userId', '123');
const userId = await redisClient.hget(RedisInstanceType.SESSION, 'session:abc', 'userId');

// List operations
await redisClient.lpush(RedisInstanceType.QUEUE, 'notifications', 'email', 'sms');
const notification = await redisClient.rpop(RedisInstanceType.QUEUE, 'notifications');

// Health checks
const isHealthy = await redisClient.healthCheck();
const stats = await redisClient.getStats(RedisInstanceType.CACHE);
```

### gRPC Health Check Service Usage

```typescript
import { HealthCheckService, ServingStatus } from '@sandip1046/rubizz-shared-libs';
import * as grpc from '@grpc/grpc-js';

// Initialize health check service
const healthCheckService = new HealthCheckService('my-service', logger);

// Set service status
healthCheckService.setServing(); // Service is healthy
healthCheckService.setNotServing(); // Service is unhealthy
healthCheckService.setUnknown(); // Service status unknown

// Register with gRPC server
const server = new grpc.Server();
healthCheckService.registerHealthService(server);

// Get service status
const status = healthCheckService.getServiceStatus();
console.log('Service status:', status); // SERVING, NOT_SERVING, or UNKNOWN

// Perform health check
const healthStatus = await healthCheckService.performHealthCheck();
console.log('Health status:', healthStatus);
```

**Features:**
- Standard `grpc.health.v1.Health` service implementation
- Supports both unary `Check` and streaming `Watch` methods
- Automatic service registration with gRPC server
- Health status tracking and management
- Compatible with Kubernetes health probes

### WebSocket Connection Manager Usage

```typescript
import { WebSocketConnectionManager, ConnectionState } from '@sandip1046/rubizz-shared-libs';
import { WebSocket } from 'ws';
import { createServer } from 'http';

const httpServer = createServer();
const logger = Logger.getInstance('my-service', 'production');

// Initialize connection manager
const connectionManager = new WebSocketConnectionManager(logger, {
  pingInterval: 30000,        // Send ping every 30 seconds
  pongTimeout: 10000,         // Wait 10 seconds for pong
  connectionTimeout: 60000,   // Consider connection stale after 60 seconds
  maxReconnectAttempts: 5,     // Maximum 5 reconnection attempts
  cleanupInterval: 60000      // Cleanup stale connections every 60 seconds
});

// Register a new connection
const connectionId = 'conn-123';
const ws = new WebSocket('ws://localhost:3000');
connectionManager.registerConnection(connectionId, ws, {
  userId: 'user-456',
  sessionId: 'session-789',
  deviceId: 'device-abc',
  userAgent: 'Mozilla/5.0...',
  ipAddress: '192.168.1.1'
});

// Generate reconnect token
const reconnectToken = connectionManager.generateReconnectToken(connectionId);

// Handle reconnection
const newWs = new WebSocket('ws://localhost:3000');
const reconnectResult = connectionManager.handleReconnection(
  reconnectToken,
  newWs,
  'conn-456' // New connection ID
);

if (reconnectResult && reconnectResult.success) {
  console.log('Reconnection successful:', reconnectResult.connectionId);
  // State is automatically preserved (subscriptions, metadata, etc.)
}

// Get user connections
const userConnections = connectionManager.getUserConnections('user-456');
console.log('User connections:', userConnections);

// Update connection activity
connectionManager.updateActivity(connectionId);

// Get connection statistics
const stats = connectionManager.getStats();
console.log('Connection stats:', stats);
// {
//   totalConnections: 10,
//   connectionsByUser: 5,
//   connectionsByState: {
//     CONNECTING: 0,
//     CONNECTED: 8,
//     RECONNECTING: 1,
//     DISCONNECTED: 0,
//     ERROR: 1
//   },
//   averageConnectionDuration: 1234567
// }

// Remove connection
connectionManager.removeConnection(connectionId, 'User disconnected');

// Shutdown (cleanup all connections)
connectionManager.shutdown();
```

**Features:**
- Automatic ping/pong health monitoring
- Connection state management
- Token-based reconnection with state preservation
- Automatic cleanup of stale connections
- User-based connection tracking
- Connection statistics and monitoring
- Configurable timeouts and intervals

### Proto File Verification Usage

```typescript
import { ProtoVerifier } from '@sandip1046/rubizz-shared-libs';

const logger = Logger.getInstance('proto-verifier', 'development');
const protoVerifier = new ProtoVerifier(logger);

// Discover all .proto files in a directory
protoVerifier.discoverProtoFiles('./proto');

// Verify all proto files
const verifiedInfos = protoVerifier.verifyAllProtoFiles();

// Generate verification report
const report = protoVerifier.generateReport();
console.log(report);

// Check if a proto file has health check service
const protoInfo = protoVerifier.parseProtoFile('./proto/health.proto');
if (protoVerifier.hasHealthCheckService(protoInfo)) {
  console.log('Health check service found');
}
```

**Features:**
- Automatic proto file discovery
- Syntax validation
- Import path validation
- Service and message extraction
- Health check service detection
- Detailed verification reports

### Dead Letter Queue Handler Usage

```typescript
import { DeadLetterQueueHandler, DeadLetterEvent } from '@sandip1046/rubizz-shared-libs';

const logger = Logger.getInstance('my-service', 'production');
const dlqHandler = new DeadLetterQueueHandler(logger, {
  maxRetries: 3,
  retryDelay: 1000,
  retryBackoffMultiplier: 2,
  dlqTopicPrefix: 'dlq.',
  enableAutoRetry: true,
  retryTopicPrefix: 'retry.',
});

// Create DLQ event from failed event
const dlqEvent = dlqHandler.createDeadLetterEvent(
  originalEvent,
  error,
  'order.created',
  0 // retry count
);

// Add to DLQ
dlqHandler.addToDLQ(dlqEvent);

// Check if should retry
if (dlqHandler.shouldRetry(dlqEvent)) {
  const { retryEvent, retryTopic, retryDelay } = dlqHandler.prepareForRetry(dlqEvent);
  
  // Publish to retry topic after delay
  setTimeout(() => {
    await kafkaService.publishEvent(retryTopic, retryEvent);
  }, retryDelay);
}

// Get DLQ statistics
const stats = dlqHandler.getDLQStats();
console.log('DLQ Stats:', stats);

// Get DLQ topic name
const dlqTopic = dlqHandler.getDLQTopicName('order.created');
// Returns: 'dlq.order.created'
```

**Features:**
- Automatic retry with exponential backoff
- Configurable retry strategies per event type
- DLQ event tracking and statistics
- Manual retry and resolution support
- Integration with Kafka topics

### Event Schema Validator Usage

```typescript
import { EventSchemaValidator, EventSchema } from '@sandip1046/rubizz-shared-libs';

const logger = Logger.getInstance('my-service', 'production');
const validator = new EventSchemaValidator(logger, false); // strictMode: false

// Register event schema
const orderSchema: EventSchema = {
  eventType: 'order.created',
  version: '1.0',
  schema: {
    type: 'object',
    required: ['eventId', 'eventType', 'orderId', 'amount'],
    properties: {
      eventId: { type: 'string', format: 'uuid' },
      eventType: { type: 'string', enum: ['order.created'] },
      orderId: { type: 'string' },
      amount: { type: 'number', minimum: 0 },
      status: { type: 'string', enum: ['pending', 'confirmed', 'cancelled'] },
    },
  },
};

validator.registerSchema(orderSchema);

// Validate event
const result = validator.validate(event, 'order.created', '1.0');

if (!result.valid) {
  console.error('Validation errors:', result.errors);
  // Handle validation errors
} else {
  console.log('Event is valid');
  if (result.warnings.length > 0) {
    console.warn('Validation warnings:', result.warnings);
  }
}

// Check if schema exists
if (validator.hasSchema('order.created', '1.0')) {
  const schema = validator.getSchema('order.created', '1.0');
  console.log('Schema found:', schema);
}
```

**Features:**
- JSON Schema validation
- Type checking (string, number, boolean, array, object)
- Format validation (date-time, email, uri, uuid)
- Enum validation
- Number constraints (minimum, maximum)
- String pattern matching
- Array item validation
- Required field checking
- Unknown field warnings

### Common Kafka Event Types

```typescript
import { KafkaEventType, KAFKA_TOPICS, BaseKafkaEvent } from '@sandip1046/rubizz-shared-libs';

// Use predefined event types
const event: BaseKafkaEvent = {
  eventId: 'evt-123',
  eventType: KafkaEventType.ORDER_CREATED,
  serviceName: 'restaurant-service',
  timestamp: new Date().toISOString(),
  version: '1.0',
};

// Use predefined topics
const topic = KAFKA_TOPICS.ORDER_CREATED; // 'order.created'
```

### Error Handling Usage

```typescript
import { 
  AppError, 
  BadRequestError, 
  NotFoundError, 
  ValidationError,
  ErrorHandler,
  ErrorCode 
} from '@sandip1046/rubizz-shared-libs';

// Create custom errors
throw new NotFoundError('User', 'user-123');
throw new BadRequestError('Invalid email format', { field: 'email', value: 'invalid' });
throw new ValidationError('Validation failed', { errors: ['Field required'] });

// Normalize unknown errors
try {
  // some operation
} catch (error) {
  const appError = ErrorHandler.normalizeError(error);
  // Handle appError
}

// Check if error is operational
if (ErrorHandler.isOperationalError(error)) {
  // Safe to expose to client
}

// Format error for API response
const errorResponse = ErrorHandler.formatErrorResponse(error, includeStack);
```

### HTTP Client Usage

```typescript
import { HttpClient, CircuitBreakerState } from '@sandip1046/rubizz-shared-libs';

const logger = Logger.getInstance('my-service', 'production');
const httpClient = new HttpClient(logger, {
  baseURL: 'https://api.example.com',
  timeout: 30000,
  retries: 3,
  retryDelay: 1000,
  enableCircuitBreaker: true,
  circuitBreakerThreshold: 5,
  circuitBreakerTimeout: 60000,
});

// Make requests with automatic retry and circuit breaker
try {
  const response = await httpClient.get('/users');
  console.log(response.data);
} catch (error) {
  console.error('Request failed:', error);
}

// Check circuit breaker state
const state = httpClient.getCircuitBreakerState();
if (state === CircuitBreakerState.OPEN) {
  console.log('Service unavailable - circuit breaker is open');
}

// Manually reset circuit breaker if needed
httpClient.resetCircuitBreakerManually();
```

### API Response Formatter Usage

```typescript
import { ResponseFormatter } from '@sandip1046/rubizz-shared-libs';

// Success response
const successResponse = ResponseFormatter.success(data, 'Operation successful', requestId);

// Error response
const errorResponse = ResponseFormatter.error('Operation failed', 'ERROR_CODE', requestId);

// Paginated response
const paginatedResponse = ResponseFormatter.paginated(
  items,
  page,
  limit,
  total,
  'Items retrieved successfully',
  requestId
);

// Created response (201)
const createdResponse = ResponseFormatter.created(newResource, 'Resource created', requestId);

// Updated response
const updatedResponse = ResponseFormatter.updated(updatedResource, 'Resource updated', requestId);

// Deleted response
const deletedResponse = ResponseFormatter.deleted('Resource deleted', requestId);
```

### Version Management Usage

```typescript
import { VersionManager } from '@sandip1046/rubizz-shared-libs';

// Parse version
const versionInfo = VersionManager.parse('1.2.3-beta.1+build.123');
console.log(versionInfo); // { major: 1, minor: 2, patch: 3, prerelease: 'beta.1', build: 'build.123' }

// Format version
const versionString = VersionManager.format(versionInfo, true); // 'v1.2.3-beta.1+build.123'

// Compare versions
const result = VersionManager.compare('1.2.3', '1.2.4'); // -1 (v1 < v2)
const result2 = VersionManager.compare('2.0.0', '1.9.9'); // 1 (v1 > v2)

// Check version range
VersionManager.satisfies('1.2.3', '^1.0.0'); // true
VersionManager.satisfies('2.0.0', '^1.0.0'); // false
VersionManager.satisfies('1.2.3', '~1.2.0'); // true
VersionManager.satisfies('1.3.0', '~1.2.0'); // false

// Increment version
const nextPatch = VersionManager.increment('1.2.3', 'patch'); // { major: 1, minor: 2, patch: 4 }
const nextMinor = VersionManager.increment('1.2.3', 'minor'); // { major: 1, minor: 3, patch: 0 }
const nextMajor = VersionManager.increment('1.2.3', 'major'); // { major: 2, minor: 0, patch: 0 }

// Get next version string
const nextVersion = VersionManager.getNextVersion('1.2.3', 'patch'); // '1.2.4'
```

### Resilience Utilities Usage

#### Circuit Breaker

```typescript
import { ResilienceCircuitBreaker, ResilienceCircuitBreakerState } from '@sandip1046/rubizz-shared-libs';

const logger = Logger.getInstance('my-service', 'production');
const circuitBreaker = new ResilienceCircuitBreaker(logger, {
  failureThreshold: 5,
  successThreshold: 2,
  timeout: 60000, // 1 minute
  resetTimeout: 300000, // 5 minutes
  monitoringPeriod: 60000, // 1 minute
});

// Execute with circuit breaker protection
try {
  const result = await circuitBreaker.execute(
    () => externalService.call(),
    () => fallbackService.call() // Optional fallback
  );
} catch (error) {
  console.error('Operation failed:', error);
}

// Check circuit breaker state
const state = circuitBreaker.getState();
if (state === CircuitBreakerState.OPEN) {
  console.log('Circuit breaker is open - service unavailable');
}

// Get statistics
const stats = circuitBreaker.getStats();
console.log('Circuit breaker stats:', stats);
```

#### Retry Strategy

```typescript
import { ResilienceRetryStrategy, RetryStrategyType } from '@sandip1046/rubizz-shared-libs';

const logger = Logger.getInstance('my-service', 'production');
const retry = new ResilienceRetryStrategy(logger, {
  maxRetries: 3,
  initialDelay: 1000,
  maxDelay: 30000,
  strategy: RetryStrategyType.EXPONENTIAL,
  retryablePredicate: (error) => {
    // Only retry on network errors
    return error.message.includes('ECONNREFUSED') || error.message.includes('ETIMEDOUT');
  },
  onRetry: (attempt, error, delay) => {
    console.log(`Retry attempt ${attempt} after ${delay}ms`);
  },
});

// Execute with retry
const result = await retry.execute(() => unreliableOperation());
```

#### Bulkhead Pattern

```typescript
import { Bulkhead } from '@sandip1046/rubizz-shared-libs';

const logger = Logger.getInstance('my-service', 'production');
const bulkhead = new Bulkhead(logger, {
  maxConcurrent: 10, // Max 10 concurrent operations
  maxQueueSize: 50, // Max 50 queued operations
  timeout: 30000, // 30 second timeout
});

// Execute with bulkhead isolation
const result = await bulkhead.execute(() => resourceIntensiveOperation());

// Get statistics
const stats = bulkhead.getStats();
console.log('Bulkhead stats:', stats);
```

#### Timeout Utilities

```typescript
import { Timeout } from '@sandip1046/rubizz-shared-libs';

// Execute with timeout
const result = await Timeout.execute(
  () => longRunningOperation(),
  5000, // 5 second timeout
  new Error('Operation timed out')
);

// Create cancellable timeout
const { cancel } = Timeout.createCancellableTimeout(5000, () => {
  console.log('Timeout occurred');
});

// Cancel if needed
cancel();

// Delay execution
await Timeout.delay(1000); // Wait 1 second
```

#### Graceful Degradation

```typescript
import { GracefulDegradation } from '@sandip1046/rubizz-shared-libs';

const logger = Logger.getInstance('my-service', 'production');
const degradation = new GracefulDegradation(logger);

// Using builder pattern
const result = await degradation.execute(
  GracefulDegradation.builder<string>()
    .primary(() => primaryService.getData())
    .fallback(() => backupService.getData())
    .cacheFallback(() => cacheService.getData())
    .defaultValue('default-value')
    .shouldUseFallback((error) => error.message.includes('timeout'))
    .build()
);

// Or direct strategy
const result2 = await degradation.execute({
  primary: () => primaryService.getData(),
  fallback: () => backupService.getData(),
  defaultValue: 'default-value',
});
```

### Security Utilities Usage

#### Input Sanitization

```typescript
import { InputSanitizer } from '@sandip1046/rubizz-shared-libs';

// Sanitize string input
const sanitized = InputSanitizer.sanitizeString(userInput, {
  allowHTML: false,
  maxLength: 1000,
  removeScripts: true,
  removeEventHandlers: true,
});

// Sanitize object recursively
const sanitizedObject = InputSanitizer.sanitizeObject(userData);

// Sanitize SQL input
const safeSQL = InputSanitizer.sanitizeSQL(userInput);

// Sanitize file path
const safePath = InputSanitizer.sanitizeFilePath(userPath);

// Sanitize email
const safeEmail = InputSanitizer.sanitizeEmail(userEmail);

// Sanitize URL
const safeURL = InputSanitizer.sanitizeURL(userURL);

// Sanitize NoSQL input
const safeNoSQL = InputSanitizer.sanitizeNoSQL(userData);

// Encode HTML entities
const encoded = InputSanitizer.encodeHtmlEntities('<script>alert("XSS")</script>');
// Result: &lt;script&gt;alert(&quot;XSS&quot;)&lt;/script&gt;
```

#### CSRF Protection

```typescript
import { CSRFProtection } from '@sandip1046/rubizz-shared-libs';
import cookieParser from 'cookie-parser';

const csrf = new CSRFProtection({
  secret: process.env.CSRF_SECRET || 'your-secret-key',
  cookieName: 'XSRF-TOKEN',
  headerName: 'X-XSRF-TOKEN',
  cookieOptions: {
    httpOnly: false, // Must be false for JavaScript access
    secure: true, // HTTPS only in production
    sameSite: 'strict',
    maxAge: 24 * 60 * 60 * 1000, // 24 hours
  },
});

// In Express app setup
app.use(cookieParser());
app.use(csrf.generateTokenMiddleware()); // Generate token for all requests

// Protect routes
app.post('/api/users', csrf.verifyTokenMiddleware(), (req, res) => {
  // Protected route
});

// Get token for current request (for forms)
app.get('/api/csrf-token', (req, res) => {
  const token = csrf.getToken(req);
  res.json({ csrfToken: token });
});
```

#### Security Headers

```typescript
import { SecurityHeaders } from '@sandip1046/rubizz-shared-libs';

// Use default security headers
app.use(SecurityHeaders.middleware(SecurityHeaders.getDefaultConfig()));

// Custom security headers
app.use(SecurityHeaders.middleware({
  contentSecurityPolicy: {
    defaultSrc: ["'self'"],
    scriptSrc: ["'self'", "'unsafe-inline'", 'https://cdn.example.com'],
    styleSrc: ["'self'", "'unsafe-inline'"],
    imgSrc: ["'self'", 'data:', 'https:'],
    connectSrc: ["'self'", 'https://api.example.com'],
  },
  strictTransportSecurity: {
    maxAge: 31536000, // 1 year
    includeSubDomains: true,
  },
  xFrameOptions: 'DENY',
  xContentTypeOptions: true,
  xXSSProtection: true,
  referrerPolicy: 'strict-origin-when-cross-origin',
}));
```

### Observability & Monitoring Usage

#### Distributed Tracing

```typescript
import { Tracing } from '@sandip1046/rubizz-shared-libs';

// Initialize tracing
Tracing.initialize('rubizz-user-service');

// Start a span
const span = Tracing.startSpan('user-operation', {
  attributes: { 'user.id': '123' },
});

// Execute function within span
const result = await Tracing.withSpan('fetch-user', async (span) => {
  span.setAttribute('user.id', userId);
  return await fetchUser(userId);
});

// Extract trace context from headers
const context = Tracing.extractContext(req.headers);
if (context) {
  // Use context to create child span
  const childSpan = Tracing.createChildSpan('child-operation', context);
}

// Inject trace context into headers
const headers = Tracing.injectContext(context);
```

#### Metrics Collection

```typescript
import { Metrics } from '@sandip1046/rubizz-shared-libs';

// Initialize metrics
Metrics.initialize('rubizz-user-service');

// Record counter
Metrics.counter('requests_total', 1, { endpoint: '/users' });

// Record gauge
Metrics.gauge('active_connections', 42);

// Record histogram
Metrics.histogram('request_duration_seconds', 0.5, { method: 'GET' });

// Record HTTP request metrics
Metrics.httpRequest('GET', '/users', 200, 150, { userId: '123' });

// Record gRPC request metrics
Metrics.grpcRequest('UserService', 'GetUser', 0, 50);

// Record database query metrics
Metrics.dbQuery('SELECT', 'users', 25, true);

// Get and aggregate metrics
const allMetrics = Metrics.getMetrics();
const requestCount = Metrics.aggregate('requests_total', 'sum');
```

#### Application Performance Monitoring

```typescript
import { APM } from '@sandip1046/rubizz-shared-libs';

// Initialize APM
APM.initialize({
  serviceName: 'rubizz-user-service',
  environment: 'production',
  version: '1.0.0',
});

// Measure operation performance
const result = await APM.measure('fetch-user', async () => {
  return await fetchUser(userId);
}, { userId });

// Record performance metric manually
APM.recordPerformance('database-query', 150, true, undefined, {
  query: 'SELECT * FROM users',
});

// Get service health
const health = APM.getServiceHealth();
console.log(health.status); // 'healthy' | 'degraded' | 'unhealthy'

// Get performance statistics
const stats = APM.getPerformanceStats('fetch-user');
console.log(stats.p95); // 95th percentile duration

// Get slow operations
const slowOps = APM.getSlowOperations(1000, 10); // Operations > 1s

// Get error operations
const errors = APM.getErrorOperations(10);
```

#### Alerting

```typescript
import { Alerting } from '@sandip1046/rubizz-shared-libs';

// Register alert handler
Alerting.registerHandler({
  handle: async (alert) => {
    // Send email, Slack notification, etc.
    console.log(`Alert: ${alert.name} - ${alert.message}`);
  },
});

// Register alert rule
Alerting.registerRule({
  id: 'high-error-rate',
  name: 'High Error Rate',
  condition: {
    metric: 'error_rate',
    operator: 'gt',
    threshold: 0.1, // 10%
    duration: 60000, // 1 minute
    aggregation: 'avg',
  },
  severity: 'critical',
  enabled: true,
  cooldown: 300000, // 5 minutes
});

// Create alert manually
Alerting.createAlert(
  'Service Down',
  'User service is not responding',
  'critical',
  'health-check',
  { service: 'user-service' }
);

// Check rules against metric values
const metricValues = new Map([
  ['error_rate', 0.15],
  ['response_time', 5000],
]);
Alerting.checkRules(metricValues);

// Get active alerts
const activeAlerts = Alerting.getActiveAlerts('critical');

// Resolve alert
Alerting.resolveAlert(alertId);

// Acknowledge alert
Alerting.acknowledgeAlert(alertId, 'admin@example.com');
```

## Development

### Prerequisites
- Node.js 18+
- TypeScript 5.3+
- NPM 9+

### Setup
```bash
# Install dependencies
npm install

# Set up environment variables
cp env.example .env
# Edit .env with your database credentials

# Generate Prisma client
npx prisma generate

# Run database migrations
npx prisma migrate dev --name init

# Build the package
npm run build

# Run tests
npm test

# Lint code
npm run lint

# Fix linting issues
npm run lint:fix
```

### Database Setup
```bash
# Generate Prisma client (after schema changes)
npx prisma generate

# Create and apply migrations
npx prisma migrate dev --name migration_name

# Reset database (development only)
npx prisma migrate reset

# Deploy migrations to production
npx prisma migrate deploy

# View database in Prisma Studio
npx prisma studio
```

### Building
```bash
npm run build
```

This will compile TypeScript to JavaScript and generate type definitions in the `dist/` directory.

## Dependencies

### Production Dependencies
- `jsonwebtoken` - JWT token handling
- `bcryptjs` - Password hashing
- `joi` - Validation schemas
- `uuid` - UUID generation
- `moment` - Date manipulation
- `lodash` - Utility functions
- `axios` - HTTP client
- `redis` - Redis client
- `winston` - Logging
- `@prisma/client` - Database ORM
- `nodemailer` - Email service
- `@grpc/grpc-js` - gRPC client/server
- `@grpc/proto-loader` - Protocol buffer loader
- `ws` - WebSocket client/server

### Development Dependencies
- `@types/*` - TypeScript type definitions (including `@types/ws`)
- `typescript` - TypeScript compiler
- `jest` - Testing framework
- `ts-jest` - TypeScript Jest transformer
- `eslint` - Code linting
- `@typescript-eslint/*` - TypeScript ESLint rules

## Version Management

The package follows semantic versioning (semver):
- **Major** (1.0.0 → 2.0.0): Breaking changes
- **Minor** (1.0.0 → 1.1.0): New features, backward compatible
- **Patch** (1.0.0 → 1.0.1): Bug fixes, backward compatible

### Automated Publishing

The package uses GitHub Actions for automated publishing:

#### Method 1: Tag-based Publishing (Recommended)
```bash
# Create and push a tag
git tag v1.0.1
git push origin v1.0.1
```

#### Method 2: Manual Publishing via GitHub Actions
1. Go to [Actions](https://github.com/sandip1046/rubizz-shared-libs/actions)
2. Select "Publish to NPM" workflow
3. Click "Run workflow"
4. Choose version type (patch/minor/major)
5. Click "Run workflow"

#### Method 3: Manual Publishing
```bash
# Build and publish manually
npm run build
npm publish --access public
```

### Publishing Workflow

The GitHub Actions workflow automatically:
- ✅ Installs dependencies
- ✅ Runs tests (if configured)
- ✅ Runs linting (if configured)
- ✅ Builds the package
- ✅ Publishes to NPM
- ✅ Creates GitHub release
- ✅ Updates version in package.json

## Deployment

### Render Deployment

The package is designed to work seamlessly with Render:

1. **No Special Configuration Required**: Render automatically installs NPM packages during build
2. **Environment Variables**: Ensure all services have required environment variables
3. **Version Pinning**: Services can pin to specific versions for stability

### Service Integration

All Rubizz microservices are configured to use this package:

```bash
# In each service's package.json
{
  "dependencies": {
    "@sandip1046/rubizz-shared-libs": "^1.0.0"
  }
}
```

### Updating Services

To update all services to use the latest version:

```bash
# Run the update script
cd Server
.\update-services.ps1

# Or manually in each service
npm install @sandip1046/rubizz-shared-libs@latest
```

## Troubleshooting

### Common Issues

#### Package Installation Issues
```bash
# Clear npm cache
npm cache clean --force

# Reinstall package
npm install @sandip1046/rubizz-shared-libs@latest

# Check installed version
npm list @sandip1046/rubizz-shared-libs
```

#### TypeScript Compilation Issues
```bash
# Ensure TypeScript is properly configured
npm run build

# Check for missing dependencies
npm install

# Verify type definitions
npm run build -- --noEmit
```

#### Import Issues
```typescript
// Correct import
import { Logger, AuthUtils } from '@sandip1046/rubizz-shared-libs';

// Incorrect import (old package name)
import { Logger } from 'rubizz-shared-libs'; // ❌
```

### Debug Commands

```bash
# Check package contents
npm pack @sandip1046/rubizz-shared-libs
tar -tzf sandip1046-rubizz-shared-libs-1.0.0.tgz

# Verify package.json
npm view @sandip1046/rubizz-shared-libs

# Check registry
npm config get registry
```

## Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes
4. Add tests for new features
5. Update documentation
6. Ensure all tests pass (`npm test`)
7. Run linting (`npm run lint`)
8. Commit your changes (`git commit -m 'Add amazing feature'`)
9. Push to the branch (`git push origin feature/amazing-feature`)
10. Open a Pull Request

### Development Workflow

```bash
# Clone the repository
git clone https://github.com/sandip1046/rubizz-shared-libs.git
cd rubizz-shared-libs

# Install dependencies
npm install

# Make your changes
# ... edit files ...

# Run tests
npm test

# Run linting
npm run lint

# Build the package
npm run build

# Test the build
npm pack
```

## License

MIT License - see [LICENSE](LICENSE) file for details.

## Support

- **📧 Issues**: [GitHub Issues](https://github.com/sandip1046/rubizz-shared-libs/issues)
- **📚 Documentation**: [NPM Package](https://www.npmjs.com/package/@sandip1046/rubizz-shared-libs)
- **🔗 Repository**: [GitHub Repository](https://github.com/sandip1046/rubizz-shared-libs)
- **📋 Changelog**: [GitHub Releases](https://github.com/sandip1046/rubizz-shared-libs/releases)

## Changelog

### v1.5.0 (2025-01-XX)
- ✨ **NEW**: Observability & Monitoring
  - Distributed Tracing (`Tracing`) - OpenTelemetry integration with W3C traceparent format support
  - Metrics Collection (`Metrics`) - Counter, Gauge, and Histogram metrics with aggregation
  - Application Performance Monitoring (`APM`) - Performance tracking, health monitoring, and statistics
  - Alerting (`Alerting`) - Alert rule management, creation, resolution, and custom handlers
- 📦 Added `@opentelemetry/api` and `@opentelemetry/semantic-conventions` dependencies
- 📚 Enhanced documentation with observability best practices and usage examples
- 🔧 Improved monitoring and observability capabilities across microservices

### v1.4.0 (2025-01-XX)
- ✨ **NEW**: Security Utilities
  - Input Sanitization (`InputSanitizer`) - XSS prevention, SQL/NoSQL injection protection
  - CSRF Protection (`CSRFProtection`) - Token-based CSRF protection with Express middleware
  - Security Headers (`SecurityHeaders`) - Comprehensive security headers management
- 📦 Added `isomorphic-dompurify` dependency for XSS prevention
- 📚 Enhanced documentation with security best practices
- 🔧 Improved input validation and sanitization

### v1.3.0 (2025-01-XX)
- ✨ **NEW**: Resilience Utilities
  - Enhanced Circuit Breaker (`ResilienceCircuitBreaker`) with state management and statistics
  - Multiple Retry Strategies (`ResilienceRetryStrategy`) - Fixed, Exponential, Linear, Jitter
  - Bulkhead Pattern for resource isolation
  - Timeout utilities for operation timeouts
  - Graceful Degradation with fallback strategies
- 📚 Enhanced documentation with resilience patterns
- 🔧 Improved error handling and resilience patterns

### v1.2.0 (2025-01-XX)
- ✨ **NEW**: Error Handling Utilities (`AppError`, `ErrorHandler`)
  - Standardized error classes (BadRequestError, NotFoundError, ValidationError, etc.)
  - Error code enumeration
  - Error metadata support
  - Operational vs programming error distinction
  - Error normalization and formatting utilities
- ✨ **NEW**: HTTP Client (`HttpClient`)
  - Automatic retry with exponential backoff
  - Circuit breaker pattern implementation
  - Request timeout handling
  - Configurable retry strategies
  - Circuit breaker state management
- ✨ **NEW**: API Response Formatters (`ResponseFormatter`)
  - Standardized success/error response formatting
  - Paginated response formatters
  - Created/updated/deleted response helpers
  - Consistent API response structure
- ✨ **NEW**: Version Management (`VersionManager`)
  - Semantic version parsing and formatting
  - Version comparison utilities
  - Version range satisfaction checking
  - Version increment utilities
- 📚 Enhanced documentation with new utilities
- 🔧 Improved type definitions and exports

### v1.1.0 (2025-01-XX)
- ✨ **NEW**: WebSocket Connection Manager (`WebSocketConnectionManager`)
  - Connection lifecycle management
  - Automatic ping/pong health monitoring
  - Token-based reconnection with state preservation
  - Connection state tracking
  - Automatic cleanup of stale connections
  - Connection statistics and monitoring
- ✨ **NEW**: gRPC Health Check Service (`HealthCheckService`)
  - Standard `grpc.health.v1.Health` protocol implementation
  - Unary and streaming health check endpoints
  - Service status management (SERVING, NOT_SERVING, UNKNOWN)
  - Automatic service registration
- ✨ **NEW**: Proto File Verifier (`ProtoVerifier`)
  - Automatic proto file discovery
  - Syntax and import validation
  - Service and message extraction
  - Health check service detection
  - Detailed verification reports
- ✨ **NEW**: Kafka Dead Letter Queue Handler (`DeadLetterQueueHandler`)
  - DLQ event management and tracking
  - Automatic retry with exponential backoff
  - Configurable retry strategies per event type
  - DLQ statistics and monitoring
  - Integration with Kafka topics
- ✨ **NEW**: Event Schema Validator (`EventSchemaValidator`)
  - JSON Schema validation for Kafka events
  - Type, format, and constraint validation
  - Schema registration and management
  - Validation error reporting
- ✨ **NEW**: Common Kafka Event Types (`KafkaEventType`, `KAFKA_TOPICS`)
  - Predefined event types and topics
  - Type-safe event interfaces
  - Common event structures
- 📦 Added `ws` and `@types/ws` dependencies
- 📦 Added `@grpc/grpc-js` and `@grpc/proto-loader` dependencies
- 📚 Updated documentation with new features
- 🔧 Enhanced exports and type definitions

### v1.0.0 (2024-10-09)
- 🎉 Initial release
- ✅ Complete NPM package setup
- ✅ GitHub Actions automated publishing
- ✅ TypeScript support with full type definitions
- ✅ Jest testing framework integration
- ✅ ESLint code quality checks
- ✅ Redis service client integration
- ✅ Comprehensive utility functions
- ✅ Authentication and authorization utilities
- ✅ Database management utilities
- ✅ Logging system with Winston
- ✅ Email service integration
- ✅ Validation schemas with Joi
- ✅ All 15 microservices updated to use the package