<?php
/**
 * Result value object for {@see GetLogsSummaryUseCase::execute()}.
 *
 * Phase 11 slice 11d immutable VO that wraps the §12.3
 * `GET /clb/v1/logs/summary` response `data` shape documented in
 * `specifications/rest-api-spec.md`. The VO carries two axes:
 *
 *   - `counts`: a PSR-3 level → row-count map sourced from
 *     {@see \CommerceLinkBuilder\Infrastructure\Persistence\LogRepository::countByLevel()}.
 *     Levels with zero occurrences are omitted (the repository
 *     contract guarantees this; the VO does not re-pad).
 *
 *   - `recent`: the masked recent-entries slice projected through
 *     {@see \CommerceLinkBuilder\Application\Logs\LogMasker::maskRecord()},
 *     newest-first per the repository's ordering contract.
 *
 * @package CommerceLinkBuilder\Application\Logs\UseCase
 */

declare(strict_types=1);

namespace CommerceLinkBuilder\Application\Logs\UseCase;

/**
 * Immutable result of {@see GetLogsSummaryUseCase::execute()}.
 *
 * See the file-level docblock for the §12.3 envelope shape and
 * the relationship between `recent` and the
 * {@see \CommerceLinkBuilder\Application\Logs\LogMasker} pipeline.
 */
final class GetLogsSummaryResult {

	/**
	 * PSR-3 level → row-count map (zero-occurrence levels omitted).
	 *
	 * @var array<string, int>
	 */
	private array $counts;

	/**
	 * Masked recent-entries slice in newest-first order.
	 *
	 * @var list<array<string, mixed>>
	 */
	private array $recent;

	/**
	 * Construct the result with explicit values for every axis.
	 *
	 * @param array<string, int>         $counts PSR-3 level → row-count map.
	 * @param list<array<string, mixed>> $recent Masked recent-entries slice.
	 */
	public function __construct( array $counts, array $recent ) {
		$this->counts = $counts;
		$this->recent = array_values( $recent );
	}

	/**
	 * PSR-3 level → row-count map.
	 *
	 * @return array<string, int>
	 */
	public function counts(): array {
		return $this->counts;
	}

	/**
	 * Masked recent-entries slice in newest-first order.
	 *
	 * @return list<array<string, mixed>>
	 */
	public function recent(): array {
		return $this->recent;
	}

	/**
	 * Render the §12.3 success envelope `data` shape:
	 *
	 *   `array(
	 *       'counts' => array<string, int>,
	 *       'recent' => list<array<string, mixed>>,
	 *   )`
	 *
	 * @return array{
	 *     counts: array<string, int>,
	 *     recent: list<array<string, mixed>>,
	 * }
	 */
	public function toArray(): array {
		return array(
			'counts' => $this->counts,
			'recent' => $this->recent,
		);
	}
}
