@edirect/audit-domain

Domain models, interfaces, and abstractions for the eDirect Audit system. This is the foundational package that all other @edirect/audit-* packages depend on. It defines the canonical AuditRequest shape, actor/action/result enumerations, and the Exporter interface.

Package Role in the Audit System

@edirect/audit-domain       ← You are here (models, interfaces, Exporter contract)
       ↑
@edirect/audit-core         ← AuditService orchestrator, BasicAuditRequest
       ↑
@edirect/audit-nestjs       ← NestJS AuditModule + AuditService DI wrapper
       ↑
@edirect/audit-exporter-http-axios   ← HTTP exporter (Axios transport)
@edirect/audit-exporter-http-fetch   ← HTTP exporter (Fetch transport)
@edirect/audit-instrumentation-express ← Express middleware auto-instrumentation

Installation

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

In most cases you won't install this package directly — it is pulled in as a peer dependency by the other audit packages.

Core Model: AuditRequest

The AuditRequest interface is the canonical audit event shape:

interface AuditRequest {
  // Context
  traceId?:          string;                      // Links to OpenTelemetry trace
  tenant:            string;                      // e.g., 'th-broker', 'orange-eu'
  service:           string;                      // e.g., 'policy-issuing-service'
  domain:            string;                      // e.g., 'policy', 'quote'
  sessionId?:        string;                      // Frontend session identifier
  originIpAddress?:  string;                      // Client IP
  originType:        string;                      // How the action was triggered
  originUrl?:        string;                      // Endpoint that triggered the action

  // Actor
  actorType:         AuditRequestActorType;       // Who triggered the action
  actorGroup:        string;                      // Realm/group of the actor
  actorId?:          string;                      // UUID of the actor

  // Action
  actionCategory:    AuditRequestActionCategory;  // Category of the event
  actionKey:         AuditRequestActionKey;        // CRUD or login action
  targetKey:         string;                      // Entity type affected
  targetId?:         string[];                    // IDs of affected entities
  actionDetail:      string;                      // Human-readable description (no PII)
  actionPayload?:    object;                      // Detailed payload (may contain PII)

  // Result
  resultKey:         AuditRequestResultKey;       // Outcome of the action
  resultDetail?:     string;                      // Human-readable result (no PII)
  resultPayload?:    object;                      // Result payload (may contain PII)

  // Timestamp
  eventTimestamp:    Date;                        // When the event occurred
}

Type Enumerations

AuditRequestActorType

| Value | Description | |-------|-------------| | 'ANONYMOUS' | Unauthenticated user | | 'AGENT' | Insurance agent | | 'CUSTOMER' | End customer | | 'INTERNAL' | Internal system/service | | 'INTEGRATION' | Third-party integration | | 'AUTOMATION' | Automated process or bot |

AuditRequestActionCategory

| Value | Description | |-------|-------------| | 'DATA_ACCESS_EVENT' | Read-only data access | | 'DATA_MODIFICATION_EVENT' | Create, update, or delete | | 'AUTHENTICATION_EVENT' | Login, logout, token operations | | 'INFORMATIONAL_EVENT' | System events, notifications |

AuditRequestActionKey

'CREATE' | 'READ' | 'UPDATE' | 'DELETE' | 'LOGIN' | 'LOGOUT' | 'OTHER'

AuditRequestResultKey

'SUCCESS' | 'FAIL' | 'PARTIAL_SUCCESS'

Exporter Interface

The Exporter interface must be implemented by any transport layer:

interface Exporter {
  export(data: AuditRequest): Promise<void>;
  bulkExport(data: AuditRequest[]): Promise<void>;
}

Implementations: HttpAxiosExporter (from @edirect/audit-exporter-http-axios), HttpFetchExporter (from @edirect/audit-exporter-http-fetch).

Middleware Interface

The Middleware interface allows plugging request-level instrumentation into the audit pipeline:

interface Middleware {
  process(options: unknown, request: Request): Partial<AuditRequest>;
}

Implementations: InstrumentationExpress (from @edirect/audit-instrumentation-express).