@brownnrl/tcdc-audit-backend-lib/README.md

Backend library for managing audit trail data

# TCDC Audit Backend Library

## Overview

The **TCDC Audit Backend Library** provides tools to track changes to data records, including field-level modifications, record creation, and deletion events. It is designed for seamless integration with MongoDB and includes features for both user and system-generated audit trails.

The library supports:
- **Field-Level Changes**: Captures old and new values for individual fields.
- **Record-Level Metadata**: Tracks overarching changes with timestamps, user/system information, and optional notes.
- **Utility Functions**: Simplifies the process of creating, updating, and deleting audit trail records.
- **Testing and Extensibility**: Includes robust testing and an extensible schema for customization.

## Getting Started

### Prerequisites
- Node.js (v14+ recommended)
- MongoDB (local or in-memory using `mongodb-memory-server` for testing)

### Installation
1. Clone the repository:
   ```bash
   git clone <repository-url> && cd tcdc-audit-backend-lib
   ```

2. Install dependencies:
   ```bash
   npm install
   ```

3. Compile the library:
   ```bash
   npm run build
   ```

4. Run tests:
   ```bash
   npm test
   ```

## Basic Usage

The library provides utility functions to handle common audit trail operations: `trackCreation`, `trackUpdate`, and `trackDeletion`. These functions generate structured audit records that can be stored in MongoDB.

### Importing Functions
All functions are exported from the same file:
```typescript
import { trackCreation, trackUpdate, trackDeletion } from './src/functions/audit-track-changes';
```

### `trackCreation`
Tracks the initial values of a record when it is created.

**Example Usage**:
```typescript
const auditRecord = trackCreation({
  data: { name: 'John Doe', age: 30 },
  changedBy: { profileId: 'admin123', name: 'Admin User' },
  notes: ['Initial record creation'],
});

console.log(auditRecord);
```

### `trackUpdate`
Tracks changes between the old and new states of a record.

**Example Usage**:
```typescript
const auditRecord = trackUpdate({
  oldState: { name: 'John Doe', age: 30 },
  newState: { name: 'Jane Doe', age: 30 },
  changedBy: { profileId: 'user456', name: 'Editor User' },
  notes: ['Name correction'],
  ignoreKeys: ['age'],
});

console.log(auditRecord);
```

### `trackDeletion`
Logs metadata for a record deletion event.

**Example Usage**:
```typescript
const auditRecord = trackDeletion({
  changedBy: { profileId: 'admin123', name: 'Admin User' },
  notes: ['Record deleted for compliance'],
});

console.log(auditRecord);
```

## Testing

The library uses Jest for unit and integration tests, with `mongodb-memory-server` for testing database interactions.

### Running Tests
1. Run all tests:
   ```bash
   npm test
   ```

2. Run tests in watch mode:
   ```bash
   npm run test:watch
   ```

3. Generate a coverage report:
   ```bash
   npm run test:coverage
   ```

## License

See [LICENSE.txt](LICENSE.txt).

## Documentation

Detailed documentation, including the schema structure and advanced use cases, is available in the `docs/` directory.