#Alepha - Api Audits

#Installation

Part of the alepha package. Import from alepha/api/audits.

npm install alepha

#Overview

Provides audit logging API endpoints for Alepha applications.

This module includes:

• Audit log CRUD operations
• Filtering and searching audit events
• Audit statistics and analytics
• $audit primitive for domain-specific audit types

 1// In your app module 2import { AlephaApiAudits } from "alepha/api/audits"; 3  4const App = $module({ 5  name: "app", 6  services: [AlephaApiAudits, ...], 7}); 8  9// Create domain-specific audit types10class PaymentAudits {11  audit = $audit({12    type: "payment",13    actions: ["create", "refund", "cancel"],14  });15 16  async onPaymentCreated(paymentId: string, userId: string) {17    await this.audit.log("create", {18      userId,19      resourceType: "payment",20      resourceId: paymentId,21    });22  }23}

#API Reference

#Primitives

Primitives are functions that define and configure various aspects of your application. They follow the convention of starting with $ and return configured primitive instances.

For more details, see the Primitives documentation.

#$audit()

Options for creating an audit type primitive. / export interface AuditPrimitiveOptions { /** Unique audit type identifier (e.g., "auth", "payment", "order"). / type: string;

/** Human-readable description of this audit type. / description?: string;

/** List of allowed actions for this audit type. / actions: string[]; }

/** Audit type primitive for registering domain-specific audit events.

Provides a type-safe way to define and log audit events within a specific domain.

 1class PaymentAudits { 2  audit = $audit({ 3    type: "payment", 4    description: "Payment-related audit events", 5    actions: ["create", "refund", "cancel", "dispute"], 6  }); 7  8  async logPaymentCreated(paymentId: string, userId: string, amount: number) { 9    await this.audit.log("create", {10      userId,11      resourceType: "payment",12      resourceId: paymentId,13      description: `Payment of ${amount} created`,14      metadata: { amount },15    });16  }17}

/ export class AuditPrimitive extends Primitive { protected readonly auditService = $inject(AuditService);

/** The audit type identifier. / public get type(): string { return this.options.type; }

/** The audit type description. / public get description(): string | undefined { return this.options.description; }

/** The allowed actions for this audit type. / public get actions(): string[] { return this.options.actions; }

/** Log an audit event for this type. / public async log( action: string, options: AuditLogOptions = {}, ): Promise { await this.auditService.record(this.options.type, action, options); }

/** Log a successful audit event. / public async logSuccess( action: string, options: Omit<AuditLogOptions, "success"> = {}, ): Promise { await this.log(action, { ...options, success: true }); }

/** Log a failed audit event. / public async logFailure( action: string, errorMessage: string, options: Omit<AuditLogOptions, "success" | "errorMessage"> = {}, ): Promise { await this.log(action, { ...options, success: false, errorMessage }); }

/** Called during initialization to register this audit type. / protected onInit(): void { const definition: AuditTypeDefinition = { type: this.options.type, description: this.options.description, actions: this.options.actions, }; this.auditService.registerType(definition); } }

/** Options for logging an audit event. / export interface AuditLogOptions { severity?: "info" | "warning" | "critical"; userId?: string; userRealm?: string; userEmail?: string; resourceType?: string; resourceId?: string; description?: string; metadata?: Record<string, unknown>; ipAddress?: string; userAgent?: string; sessionId?: string; requestId?: string; success?: boolean; errorMessage?: string; }

/** Create an audit type primitive.

1class OrderAudits {2  audit = $audit({3    type: "order",4    description: "Order management events",5    actions: ["create", "update", "cancel", "fulfill", "ship"],6  });7}