@edirect/audit-core

Core AuditService orchestrator for the eDirect Audit system. This package provides the AuditService class that coordinates between exporters and instrumentation middleware to produce and dispatch audit events.

Package Role in the Audit System

@edirect/audit-domain       ← Models, Exporter interface
       ↑
@edirect/audit-core         ← You are here (AuditService orchestrator)
       ↑
@edirect/audit-nestjs       ← NestJS DI wrapper around AuditService
       ↑
@edirect/audit-exporter-http-axios   ← Axios HTTP transport
@edirect/audit-exporter-http-fetch   ← Fetch HTTP transport
@edirect/audit-instrumentation-express ← Auto-instrumentation from Express requests

Installation

pnpm add @edirect/audit-core
# or
npm install @edirect/audit-core

You typically don't use @edirect/audit-core directly in application code — use @edirect/audit-nestjs for NestJS apps. This package is useful if you need to use the audit service outside of NestJS.

Usage (standalone)

import { AuditService } from '@edirect/audit-core';
import { HttpAxiosExporter } from '@edirect/audit-exporter-http-axios';

const auditService = new AuditService({
  exporter: new HttpAxiosExporter({
    basePath: 'https://audit.example.com',
    accessToken: process.env.AUDIT_ACCESS_TOKEN,
  }),
  service: 'policy-issuing-service',
  domain: 'policy',
  tenant: 'th-broker',
});

await auditService.audit({
  originType: 'HTTP',
  actorType: 'AGENT',
  actorGroup: 'th-broker-agents',
  actorId: 'user-uuid-123',
  actionCategory: 'DATA_MODIFICATION_EVENT',
  actionKey: 'CREATE',
  targetKey: 'Policy',
  targetId: ['policy-uuid-456'],
  actionDetail: 'Agent created a new motor policy',
  resultKey: 'SUCCESS',
  eventTimestamp: new Date(),
});

AuditService Configuration

| Option | Type | Required | Description | |--------|------|----------|-------------| | exporter | Exporter | Yes | Transport that sends events to the audit backend | | service | string | Yes | Name of the service emitting the event | | domain | string | Yes | Business domain (e.g., 'policy', 'payment') | | tenant | string | Yes | Tenant identifier (e.g., 'th-broker') | | instrumentation | Middleware[] | No | Auto-instrumentation middlewares (e.g., from Express requests) | | disabled | boolean | No | Disable audit emission (default: false) | | throwErrors | boolean | No | Re-throw exporter errors (default: false) | | bulkLimit | number | No | Max events per bulk export call |

BasicAuditRequest

The AuditService.audit() method accepts a BasicAuditRequest, which is a reduced version of AuditRequest — fields like service, domain, tenant, traceId, sessionId, originIpAddress, and originUrl are omitted or made optional because the AuditService fills them in automatically.

type BasicAuditRequest = {
  originType: string;
  actorType: AuditRequestActorType;
  actorGroup: string;
  actorId?: string;
  actionCategory: AuditRequestActionCategory;
  actionKey: AuditRequestActionKey;
  targetKey: string;
  targetId?: string[];
  actionDetail: string;
  actionPayload?: object;
  resultKey: AuditRequestResultKey;
  resultDetail?: string;
  resultPayload?: object;
  eventTimestamp: Date;
};

Related Packages

| Package | Role | |---------|------| | @edirect/audit-domain | AuditRequest model, Exporter interface | | @edirect/audit-nestjs | NestJS AuditModule + AuditService with DI | | @edirect/audit-exporter-http-axios | HTTP exporter via Axios | | @edirect/audit-exporter-http-fetch | HTTP exporter via Fetch API | | @edirect/audit-instrumentation-express | Express request auto-instrumentation |