<?php
/**
 * Value object representing the outcome of one external provider scan.
 *
 * @package MediaRightsAudit\External
 */

namespace MediaRightsAudit\External;

if ( ! defined( 'ABSPATH' ) ) {
	exit;
}

/**
 * Immutable result returned by AbstractProvider::scan().
 */
class ScanResult {

	/**
	 * Number of pages / images where the attachment was found.
	 *
	 * @var int
	 */
	private int $match_count;

	/**
	 * Top domains where matches were found (domain → occurrence count), max 10.
	 *
	 * @var array<string, int>
	 */
	private array $top_domains;

	/**
	 * Full decoded API response for storage.
	 *
	 * @var array<mixed, mixed>
	 */
	private array $raw_response;

	/**
	 * Constructs a new scan result.
	 *
	 * @param int                 $match_count  Number of pages or images found.
	 * @param array<string, int>  $top_domains  Domain → count map.
	 * @param array<mixed, mixed> $raw_response Full decoded API payload.
	 */
	public function __construct( int $match_count, array $top_domains, array $raw_response ) {
		$this->match_count  = $match_count;
		$this->top_domains  = $top_domains;
		$this->raw_response = $raw_response;
	}

	/**
	 * Returns the number of matching pages or images found.
	 *
	 * @return int
	 */
	public function match_count(): int {
		return $this->match_count;
	}

	/**
	 * Returns the top-domain occurrence map (domain → count), max 10 entries.
	 *
	 * @return array<string, int>
	 */
	public function top_domains(): array {
		return $this->top_domains;
	}

	/**
	 * Returns the full decoded API response payload.
	 *
	 * @return array<mixed, mixed>
	 */
	public function raw_response(): array {
		return $this->raw_response;
	}
}