breadcrumb-the-shire/core/Service/Audit/UserLifecycleAuditDashboardInterface.php

<?php

namespace MintyPHP\Service\Audit;

/**
 * Read-only counterpart to UserLifecycleAuditInterface for dashboard / KPI queries.
 *
 * Implemented by the audit module's UserLifecycleAuditDashboardService when active.
 * Falls back to NullUserLifecycleAuditDashboard when the audit module is disabled.
 */
interface UserLifecycleAuditDashboardInterface
{
    /**
     * Latest automatic (system-triggered) lifecycle run, or null when none recorded.
     *
     * @return array{created_at:string,status:string,action:string}|null
     */
    public function lastRun(): ?array;

    /**
     * Count successful (or status-filtered) audit-log events for a single action within the last $days.
     */
    public function actionCountInWindow(string $action, int $days, string $status = 'success'): int;

    /**
     * Aggregated count per action within the last $days, filtered by status.
     *
     * @return array<string, int>
     */
    public function summaryByAction(int $days, string $status = 'success'): array;
}