naga-audit-service

A comprehensive audit service library for NestJS applications with MongoDB support. This library provides a complete audit trail solution that can track changes to your data with full metadata support.

Features

• 🔍 Dynamic Schema Support: Automatically creates audit collections based on your data structure
• 📊 MongoDB Integration: Built on top of Mongoose for robust database operations
• 🔗 Inter-Service Communication: Built-in HTTP client for communicating with other services
• 📄 Pagination Support: Efficient data retrieval with built-in pagination
• 🎯 TypeScript Support: Full TypeScript support with type definitions
• 📝 Comprehensive Logging: Integrated Winston logger for detailed audit logs
• 🛡️ Error Handling: Robust error handling with custom exceptions
• 📋 Validation: Built-in validation using class-validator
• 🔧 Configurable: Easy configuration through environment variables

Installation

npm install naga-audit-service

Quick Start

1. Configure and Start the Service

import { NoukhaAuditLog } from 'naga-audit-service';

// Configure and automatically start the audit log service
await NoukhaAuditLog.configure({
  dbUrl: 'mongodb://localhost:27017/your-database',
  configServiceUrl: 'http://your-config-service:3000', // optional
  logLevel: 'info' // optional
});

// The service will automatically:
// ✅ Connect to MongoDB
// ✅ Initialize all components
// ✅ Start the audit service
// ✅ Set up graceful shutdown handlers

2. Alternative: Use Service Starter

import { startAuditService } from 'naga-audit-service';

// Start the service with configuration
await startAuditService({
  dbUrl: 'mongodb://localhost:27017/your-database',
  configServiceUrl: 'http://your-config-service:3000',
  logLevel: 'info'
});

3. Import the Module

import { Module } from '@nestjs/common';
import { NoukhaAuditLog } from 'naga-audit-service';

@Module({
  imports: [
    NoukhaAuditLog.getModule(),
    // ... other modules
  ],
})
export class AppModule {}

4. Use the Audit Service

import { Injectable } from '@nestjs/common';
import { AuditService } from 'naga-audit-service';

@Injectable()
export class YourService {
  constructor(private readonly auditService: AuditService) {}

  async createAuditRecord() {
    const auditData = {
      collectionName: 'users',
      action: 'CREATE',
      userId: 'user123',
      serviceName: 'user-service',
      metaData: {
        ipAddress: '192.168.1.1',
        userAgent: 'Mozilla/5.0...',
        // ... any additional metadata
      }
    };

    return await this.auditService.transformAndInsert(auditData);
  }

  async getAuditHistory(collectionName: string) {
    return await this.auditService.getAuditByCollectionName(collectionName, {
      skip: 0,
      limit: 10,
      sort: { createdAt: -1 }
    });
  }
}

API Reference

AuditService

transformAndInsert(createAuditDto: CreateAuditDto)

Creates a new audit record in the specified collection.

Parameters:

• createAuditDto: Object containing audit data
  • collectionName: Name of the collection to audit
  • action: Action performed (CREATE, UPDATE, DELETE, etc.)
  • userId: ID of the user performing the action
  • serviceName: Name of the service
  • metaData: Additional metadata object

getAuditByCollectionName(collectionName: string, query?: QueryOptions)

Retrieves audit records from a specific collection with pagination support.

Parameters:

• collectionName: Name of the collection to query
• query: Optional query parameters
  • skip: Number of records to skip
  • limit: Number of records to return
  • filter: MongoDB filter object
  • projection: MongoDB projection object
  • sort: MongoDB sort object

CreateAuditDto

interface CreateAuditDto {
  collectionName: string;
  action: string;
  userId: string;
  serviceName: string;
  prevsState?: Record<string, any>;
  newState?: Record<string, any>;
  metaData?: Record<string, any>;
  [key: string]: any; // Additional custom fields
}

Configuration & Auto-Start

Configuration Options

| Option | Type | Required | Description | Default | |--------|------|----------|-------------|---------| | dbUrl | string | ✅ | MongoDB connection string | - | | configServiceUrl | string | ❌ | Config service URL for collection validation | http://localhost:3000 | | logLevel | string | ❌ | Logging level | info |

Note: This package is designed to be environment-agnostic. All configuration is provided programmatically through the NoukhaAuditLog.configure() method, ensuring no environment variables are required or included in the package.

Automatic Service Startup

When you call NoukhaAuditLog.configure() or startAuditService(), the service automatically:

1. Connects to MongoDB using the provided dbUrl
2. Initializes all components (logging, HTTP client, pagination, etc.)
3. Starts the audit service and makes it ready for use
4. Sets up graceful shutdown handlers for SIGINT and SIGTERM
5. Provides status checking methods to verify service readiness

Collection Configuration

The audit service validates collections against a configuration service. Make sure your config service provides collection configurations in the following format:

interface CollectionConfig {
  serviceName: string;
  collections: string[];
  collectionsConfigId: string;
}

Advanced Usage

Custom Audit Module

import { Module } from '@nestjs/common';
import { AuditModule } from 'naga-audit-service';

@Module({
  imports: [
    AuditModule,
    // ... other required modules
  ],
  controllers: [YourAuditController],
  providers: [YourAuditService],
})
export class CustomAuditModule {}

Alternative Configuration Method

You can also configure the module directly without using the static configuration:

import { Module } from '@nestjs/common';
import { NagaAuditServiceModule } from 'naga-audit-service';

@Module({
  imports: [
    NagaAuditServiceModule.forRoot({
      dbUrl: 'mongodb://localhost:27017/your-database',
      configServiceUrl: 'http://your-config-service:3000',
      logLevel: 'info'
    }),
    // ... other modules
  ],
})
export class AppModule {}

Service Status & Control

import { NoukhaAuditLog, startAuditService, stopAuditService } from 'naga-audit-service';

// Check if service is ready
if (NoukhaAuditLog.isServiceReady()) {
  console.log('✅ Service is ready');
}

// Wait for service to be ready
await NoukhaAuditLog.waitForReady();

// Stop the service
await stopAuditService();

Using Individual Components

import { 
  AuditService, 
  LoggerService, 
  PaginationService,
  HttpClientService 
} from 'naga-audit-service';

@Injectable()
export class CustomService {
  constructor(
    private readonly auditService: AuditService,
    private readonly logger: LoggerService,
    private readonly pagination: PaginationService,
    private readonly httpClient: HttpClientService,
  ) {}
}

Error Handling

The library includes comprehensive error handling:

import { 
  BadRequestException, 
  NotFoundException, 
  BadGatewayException 
} from '@nestjs/common';

try {
  await this.auditService.transformAndInsert(auditData);
} catch (error) {
  if (error instanceof BadRequestException) {
    // Handle validation errors
  } else if (error instanceof NotFoundException) {
    // Handle collection not found
  } else if (error instanceof BadGatewayException) {
    // Handle service communication errors
  }
}

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For support, email [email protected] or create an issue in the GitHub repository.