Activity Logs

NapX PMS maintains an immutable activity audit trail for every significant platform event. Logs are written automatically by the ActivityLogListenerService, which subscribes to 18 domain events across reservations, guests, properties, access codes, tasks, transactions, and notifications.

Endpoints

Method	Path	Description
GET	/v1/activity-logs	List audit log entries; filterable by entity, actor, action, and date

Response Shape

Each activity log entry includes:

Field	Type	Description
id	uuid	Log entry ID
tenantId	uuid	Owning tenant
actorId	uuid | null	User who performed the action; null for system-generated entries
action	string	Event action (e.g. reservation.created)
targetType	string	Type of entity affected (e.g. reservation)
targetId	uuid | null	ID of the affected entity
status	string	Outcome status (e.g. success)
occurredAt	ISO 8601 string	When the event occurred

System Events and Nullable actorId

actorId is nullable. Automated workflows — such as a BullMQ processor completing a notification job, a housekeeping task triggered on checkout, or a background sync — produce log entries with actorId: null. These entries also contain:

{
  "actorId": null,
  "metadata": { "actorType": "system" }
}

This accurately models the authorship of automated actions without requiring a sentinel UUID.

Query Filters

The GET /v1/activity-logs endpoint supports the following query parameters:

Parameter	Description
targetType	Filter by target entity type (e.g. reservation)
targetId	Filter by target entity ID
action	Filter by action string (e.g. reservation.created)
actorId	Filter by actor user ID
limit	Number of records to return
offset	Pagination offset

Automatic Capture

Activity logs are written automatically for the following event categories:

• Reservation lifecycle (created, updated, confirmed, checked in/out, cancelled, no-show)
• Guest and property changes
• Access code provisioning and revocation
• Task creation and status transitions
• Transaction captures and failures
• Notification deliveries

Application code does not call the activity log service directly in most cases. The listener pattern ensures every covered event generates an audit entry without coupling domain services to the logging infrastructure.

Security Model

• Every request requires Authorization: Bearer <session-token>.
• Tenant context is derived from validated auth claims; callers only see logs for their tenant.
• Log entries are never deleted or updated through the public API.

Error Handling

• 401 Unauthorized when the bearer token is missing or invalid.
• 403 Forbidden when the authenticated session lacks valid tenant scope.

Example

GET /v1/activity-logs?targetType=reservation&targetId=0d2d70e1-aeab-432f-ae94-9f3f5a42ba55&limit=20
Authorization: Bearer <session-token>

See the API reference for the detailed endpoint contract.