AuditService

Overview

AuditService provides read-only access to booking state-transition history and audit logs. Every status change on a booking is recorded as a BookingStateTransition, enabling full traceability of the booking lifecycle.

import { AuditService } from '@roomkit/nestjs';

Methods

getBookingHistory

Get the full state-transition history for a booking, sorted chronologically (oldest first).

async getBookingHistory(bookingId: string): Promise<BookingStateTransition[]>

Parameter	Type	Description
`bookingId`	`string`	The booking ID to retrieve history for

const history = await auditService.getBookingHistory('booking-1');

for (const transition of history) {
    console.log(
        `${transition.fromStatus ?? '(new)'} → ${transition.toStatus}` +
        ` by ${transition.triggeredBy} at ${transition.timestamp.toISOString()}`
    );
}
// (new) → pending by user-1 at 2026-03-01T09:00:00.000Z
// pending → confirmed by admin-1 at 2026-03-01T09:15:00.000Z

queryAuditLog

Query state transitions within a time range with cursor-based pagination.

async queryAuditLog(
    timeRange: { start: Date; end: Date },
    pagination: Pagination,
): Promise<PaginatedResult<BookingStateTransition>>

Parameter	Type	Description
`timeRange`	`{ start: Date; end: Date }`	Time range to query within
`pagination`	`Pagination`	Cursor-based pagination options

const result = await auditService.queryAuditLog(
    {
        start: new Date('2026-03-01'),
        end: new Date('2026-03-31'),
    },
    { cursor: undefined, limit: 50 },
);

console.log(`Found ${result.data.length} transitions`);
if (result.nextCursor) {
    // Fetch next page
    const nextPage = await auditService.queryAuditLog(
        { start: new Date('2026-03-01'), end: new Date('2026-03-31') },
        { cursor: result.nextCursor, limit: 50 },
    );
}

BookingStateTransition

interface BookingStateTransition {
    bookingId: string;
    fromStatus: string | null;  // null for the initial creation
    toStatus: string;
    triggeredBy: string;        // user or system identifier
    reason: string | null;      // optional reason for the transition
    timestamp: Date;
}