Audit Pro

Audit Pro is an advanced audit logging and trail package for Node.js applications that supports multiple databases with dynamic columns, log levels, and customizable console logs. It enables developers to log, retrieve, and manage audit events easily and efficiently.

Table of Contents

• Audit Pro
  • Table of Contents
  • Installation
    • Storage Dependencies
  • Getting Started
    • Basic Setup
  • Usage
    • Using Storage Instance to Log Events
    • Logging Events
    • Fetching Logs
    • Updating Logs
    • Deleting Logs
    • Counting Logs
  • API Documentation
    • AuditLogger
      • Constructor
      • Methods
    • Storage Interfaces
    • ConsoleLogger
      • Constructor
      • Methods
    • Available Log Levels
    • Viewing Logs
  • Customizing Console Logs
  • Examples
  • Testing
  • License

Installation

To install the audit-pro package, use npm:

npm install audit-pro

Storage Dependencies

Depending on which storage type you plan to use, you may need to install additional dependencies:

• Sequelize (for SQL databases): If you intend to use Sequelize for SQL-based storage (e.g., MySQL, PostgreSQL), you must install sequelize and a corresponding SQL driver (e.g., mysql2, pg).

  npm install sequelize 

• MongoDB: If you are using MongoDB as your storage, install the mongodb package.

  npm install mongodb

Getting Started

To start using Audit Pro, you need to create instances of the AuditLogger, the storage implementations (like SequelizeStorage or FileStorage), and the ConsoleLogger.

Basic Setup

import { SequelizeStorage, LogLevel, AuditLogInterface } from 'audit-pro';
import { DataTypes, Model, ModelAttributes, Sequelize } from 'sequelize';


// Setup your database connection
const sequelizeInstance = new Sequelize('mysql://user:password@localhost:3306/audit', {
  logging: false,
});

// Create storage and logger instances
const storage = new SequelizeStorage(sequelizeInstance, 'AuditLogs', {});
const logger = new ConsoleLogger(true); // true enables console logging

// Create an AuditLogger instance
const auditLogger = new AuditLogger(storage, logger);

OR

Using Storage Instance to Log Events
// Define dynamic columns (if any)
const dynamicColumns: Partial<ModelAttributes<Model<AuditLogInterface>, AuditLogInterface>> = {
    additionalInfo: {
        type: DataTypes.STRING,
        allowNull: true,
    },
};
// Create the storage instance with the necessary table name and dynamic columns
const storage = new SequelizeStorage(sequelizeInstance, 'AuditLogs', dynamicColumns);

Usage

Using Storage Instance to Log Events

You can also directly use the storage instance to log events. This is particularly useful if you want to log without going through the AuditLogger instance.

// Create the storage instance with the necessary table name and dynamic columns
const storage = new SequelizeStorage(sequelizeInstance, 'AuditLogs', dynamicColumns);

// Example of logging an event
const logEvent: AuditLogInterface = {
    id: 'unique-log-id',
    userId: 'user123',
    action: 'User Login',
    logLevel: LogLevel.INFO,
    timestamp: new Date(),
    metadata: { ipAddress: '192.168.1.1' },
    additionalInfo: 'extra information'
    // more custom fields on the dynamic column
}; 

// Log the event directly using the storage instance
await storage.logEvent(logEvent);

Logging Events

To log an event, use the logEvent method. The method accepts an AuditLogInterface object.

const log: AuditLogInterface = {
  id: 'unique-log-id',
  userId: 'user123',
  action: 'User Login',
  logLevel: LogLevel.INFO,
  timestamp: new Date(),
  metadata: { ipAddress: '192.168.1.1' },
  //any additional fields
};

// Log the event
await auditLogger.logEvent(log);

Fetching Logs

You can retrieve logs with specific filters using the fetchLogs method.

const logs = await auditLogger.fetchLogs({ userId: 'user123' });
console.log(logs);

Updating Logs

To update an existing log, use the updateLog method.

await auditLogger.updateLog('unique-log-id', { action: 'Updated Action' });

Deleting Logs

You can delete logs by using the deleteLog method.

await auditLogger.deleteLog('unique-log-id');

Counting Logs

To count logs based on specific filters, use the countLogs method.

const count = await auditLogger.countLogs({ userId: 'user123' });
console.log(`Total logs for user123: ${count}`);

API Documentation

AuditLogger

The AuditLogger class is the main entry point for logging events.

Constructor

new AuditLogger(storage: StorageInterface, logger: ConsoleLogger)

• storage: An instance of a storage implementation (e.g., SequelizeStorage, FileStorage).
• logger: An instance of ConsoleLogger for logging to the console.

Methods

• logEvent(log: AuditLogInterface): Promise<void>
• fetchLogs(filter: object): Promise<AuditLogInterface[]>
• fetchLog(filter: object): Promise<AuditLogInterface>
• updateLog(id: string, updates: object): Promise<void>
• deleteLog(id: string): Promise<void>
• countLogs(filter: object): Promise<number>

Storage Interfaces

Implement your storage interface by extending StorageInterface. The main methods to implement are:

• logEvent(log: AuditLogInterface): Promise<void>
• fetchLogs(filter: object): Promise<AuditLogInterface[]>
• updateLog(id: string, updates: object): Promise<void>
• deleteLog(id: string): Promise<void>
• countLogs(filter: object): Promise<number>

ConsoleLogger

The ConsoleLogger class is used for logging events to the console.

Constructor

new ConsoleLogger(isEnabled: boolean)

• isEnabled: Boolean indicating whether console logging is enabled.

Methods

• getIsEnabled(): boolean
• logEventToConsole(log: AuditLogInterface): void
• colorize(message: string, color: Color): string

Available Log Levels

• LogLevel.INFO
• LogLevel.WARN
• LogLevel.ERROR
• LogLevel.DEBUG
• LogLevel.CUSTOM

Viewing Logs

You can use the LogViewer class to fetch and display logs from any storage implementation. Here’s an example:

import { LogViewer, ConsoleLogger } from 'audit-pro';

const consoleLogger = new ConsoleLogger(true); // Enable colorized console logging

// Assuming you have configured one or more storages
const logViewer = new LogViewer([storage], consoleLogger);

// View logs based on filters (e.g., userId)
logViewer.viewLogs({ userId: 'user123' });

Customizing Console Logs

Audit-Pro allows you to customize the console output with different colors:

import { ConsoleLogger } from 'audit-pro';

// Enable colorized logs
const consoleLogger = new ConsoleLogger(true);

// Log events to the console
consoleLogger.logEventToConsole({
    id: 'unique-log-id',
    userId: 'user123',
    action: 'User Login',
    logLevel: LogLevel.INFO,
    timestamp: new Date(),
    metadata: { ipAddress: '192.168.1.1' },
});

Examples

Here’s a simple example of how to use Audit Pro in an Express.js application.

import express from 'express';
import { AuditLogger, ConsoleLogger, SequelizeStorage } from 'audit-pro';
import { Sequelize } from 'sequelize';

const app = express();
const sequelizeInstance = new Sequelize('mysql://user:password@localhost:3306/audit', {
  logging: false,
});
const storage = new SequelizeStorage(sequelizeInstance, 'AuditLogs', {});
const logger = new ConsoleLogger(true);
const auditLogger = new AuditLogger(storage, logger);

app.post('/login', async (req, res) => {
  // Simulating a login action
  const log: AuditLogInterface = {
    id: 'unique-log-id',
    userId: req.body.userId,
    action: 'User Login',
    logLevel: LogLevel.INFO,
    timestamp: new Date(),
    metadata: { ipAddress: req.ip },
  };

  await auditLogger.logEvent(log);
  res.send('Login logged!');
});

app.listen(3000, () => {
  console.log('Server is running on port 3000');
});

Testing

To run the tests for Audit Pro, ensure you have Jest installed. Run the following command:

npm test

License

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