@nuvix/audit

A comprehensive audit logging library for Nuvix applications, providing structured event tracking and querying capabilities.

Features

• 🔍 Comprehensive Audit Logging: Track user actions, resource access, and system events
• 📊 Flexible Querying: Search and filter audit logs by user, resource, event type, and time
• 🔄 Batch Operations: Efficiently log multiple events at once
• 🧹 Cleanup Utilities: Remove old audit logs to manage storage
• 📦 Multiple Module Formats: ESM and CommonJS support
• 🔒 Type Safe: Full TypeScript support with comprehensive type definitions

Installation

npm install @nuvix/audit
# or
bun install @nuvix/audit
# or
yarn add @nuvix/audit

Usage

Basic Setup

import { Audit } from "@nuvix/audit";
import { Database } from "@nuvix/database";

const database = new Database(/* your database config */);
const audit = new Audit(database);

// Setup the audit collection (run once)
await audit.setup();

Logging Events

// Method 1: Individual parameters
await audit.log(
  "user123", // userId
  "login", // event
  "auth", // resource
  "Mozilla/5.0...", // userAgent
  "192.168.1.1", // ip
  "US", // location
  { loginMethod: "password" }, // optional data
);

// Method 2: Event object
await audit.log({
  userId: "user123",
  event: "document_created",
  resource: "documents/doc456",
  userAgent: "Mozilla/5.0...",
  ip: "192.168.1.1",
  location: "US",
  data: { documentType: "pdf", size: 1024 },
});

Batch Logging

const events = [
  {
    userId: "user123",
    event: "page_view",
    resource: "/dashboard",
    userAgent: "Mozilla/5.0...",
    ip: "192.168.1.1",
    location: "US",
  },
  // ... more events
];

await audit.logBatch(events);

Querying Logs

import { Query } from "@nuvix/database";

// Get all logs for a user
const userLogs = await audit.getLogsByUser("user123");

// Get logs with additional filters
const recentLogs = await audit.getLogsByUser("user123", [
  Query.greaterThan("time", "2024-01-01T00:00:00.000Z"),
  Query.limit(50),
]);

// Get logs by resource
const resourceLogs = await audit.getLogsByResource("documents/doc456");

// Get logs by user and specific events
const loginLogs = await audit.getLogsByUserAndEvents("user123", [
  "login",
  "logout",
]);

// Count logs
const loginCount = await audit.countLogsByUser("user123", [
  Query.equal("event", ["login"]),
]);

Cleanup Old Logs

// Remove logs older than a specific date
const cutoffDate = "2023-12-31T23:59:59.999Z";
await audit.cleanup(cutoffDate);

API Reference

Class: Audit

Constructor

• new Audit(database: Database) - Creates a new Audit instance

Methods

Setup

• setup(): Promise<void> - Creates the audit collection with required attributes and indexes

Logging

• log(auditEvent: AuditEvent): Promise<boolean> - Log a single audit event
• log(userId, event, resource, userAgent, ip, location, data?): Promise<boolean> - Log with individual parameters
• logBatch(events: AuditEvent[]): Promise<boolean> - Log multiple events in batch

Querying

• getLogsByUser(userId: string, queries?: Query[]): Promise<Document[]> - Get logs for a specific user
• countLogsByUser(userId: string, queries?: Query[]): Promise<number> - Count logs for a specific user
• getLogsByResource(resource: string, queries?: Query[]): Promise<Document[]> - Get logs for a specific resource
• countLogsByResource(resource: string, queries?: Query[]): Promise<number> - Count logs for a specific resource
• getLogsByUserAndEvents(userId: string, events: string[], queries?: Query[]): Promise<Document[]> - Get logs for user and specific events
• countLogsByUserAndEvents(userId: string, events: string[], queries?: Query[]): Promise<number> - Count logs for user and specific events
• getLogsByResourceAndEvents(resource: string, events: string[], queries?: Query[]): Promise<Document[]> - Get logs for resource and specific events
• countLogsByResourceAndEvents(resource: string, events: string[], queries?: Query[]): Promise<number> - Count logs for resource and specific events

Maintenance

• cleanup(datetime: string): Promise<boolean> - Remove logs older than the specified datetime

Interface: AuditEvent

interface AuditEvent {
  userId: string; // ID of the user performing the action
  event: string; // Type of event (e.g., 'login', 'create', 'delete')
  resource: string; // Resource being accessed (e.g., 'users', 'documents/123')
  userAgent: string; // User agent string from the request
  ip: string; // IP address of the user
  location: string; // Geographic location (country code, city, etc.)
  timestamp: string; // ISO 8601 timestamp
  data?: Record<string, any>; // Additional event-specific data
}

Development

Building

# Install dependencies
bun install

# Build for production (ESM + CJS)
bun run build

# Build and watch for changes
bun run build:watch

# Type checking
bun run type-check

# Clean build artifacts
bun run clean

Running in Development

# Run the development version
bun run dev

Module Formats

This package provides both ESM and CommonJS builds:

• ESM: dist/index.esm.js (default for import)
• CommonJS: dist/index.cjs.js (default for require)
• Types: dist/types/index.d.ts

Requirements

• TypeScript 5.x
• @nuvix/database ^1.0.3-alpha.3

License

ISC