@bernierllc/nevar-audit-logger

Structured execution audit logger for the Nevar rules engine with granular per-rule, per-trigger, and per-action log level control.

Installation

npm install @bernierllc/nevar-audit-logger

Usage

import { AuditLogger } from '@bernierllc/nevar-audit-logger';
import { InMemoryStorageAdapter } from '@bernierllc/nevar-storage';

const storage = new InMemoryStorageAdapter();

const logger = new AuditLogger(storage, {
  defaultLevel: 'all',
  overrides: {
    byRule: { 'rule-123': 'errors_only' },
    byTrigger: { 'user.created': 'matches_only' },
    byAction: { 'send-email': 'all' },
  },
});

// Log an execution entry (filtered by resolved log level)
await logger.log({
  triggerKey: 'user.created',
  ruleId: 'rule-456',
  status: 'matched',
  timestamp: new Date(),
  payload: { email: '[email protected]' },
});

// Update configuration at runtime
logger.updateConfig({ defaultLevel: 'errors_only' });

LogLevelResolver

Use LogLevelResolver directly when you need to resolve log levels without writing to storage:

import { LogLevelResolver } from '@bernierllc/nevar-audit-logger';

const resolver = new LogLevelResolver({
  defaultLevel: 'all',
  overrides: { byTrigger: { 'order.placed': 'errors_only' } },
});

const level = resolver.resolve({ triggerKey: 'order.placed' });
const shouldWrite = resolver.shouldLog(level, 'error'); // true

API

AuditLogger

Structured execution logger that writes log entries through a StorageWriter, filtering based on resolved log levels.

• constructor(storage: StorageWriter, config?: Partial<AuditLoggerConfig>) - Create a logger with a storage writer and optional config
• log(entry: ExecutionLogEntry): Promise<void> - Log an entry if the resolved level permits it
• updateConfig(config: Partial<AuditLoggerConfig>): void - Update log level configuration at runtime

LogLevelResolver

Resolves the effective log level using a fallback chain: byRule -> byTrigger -> byAction -> defaultLevel.

• constructor(config: AuditLoggerConfig) - Create a resolver with config
• resolve(context: ResolveContext): LogLevel - Resolve the effective log level for a context
• shouldLog(level: LogLevel, status: string): boolean - Determine if an entry should be logged at the given level
• updateConfig(config: AuditLoggerConfig): void - Update configuration

StorageWriter (interface)

Minimal interface for writing log entries. Matches the writeLog method from NevarStorageAdapter.

• writeLog(entry: ExecutionLogEntry): Promise<void>

ResolveContext (type)

Context used for log level resolution: { ruleId?: string; triggerKey?: string; actionType?: string }.

Integration Documentation

Logger Integration

This package is itself the logging layer for the Nevar rules engine. It integrates with @bernierllc/logger indirectly through the storage adapter that persists log entries. Service packages that consume nevar-audit-logger should use @bernierllc/logger for their own structured application logging alongside the audit trail this package provides.

NeverHub Integration

This package supports optional integration with @bernierllc/neverhub-adapter. When NeverHub is available, the audit logger can be registered for discovery and monitoring, enabling centralized visibility into log level configurations and audit throughput. Graceful degradation is supported when NeverHub is not present.

License

Copyright (c) 2025 Bernier LLC. All rights reserved.