<?php
/**
 * Reporting API transport contract.
 *
 * @package AdPix\Analytics
 */

declare( strict_types = 1 );

namespace AdPix\Analytics\Contracts;

use AdPix\Analytics\Http\Response;

defined( 'ABSPATH' ) || exit;

/**
 * Runs a report against the AdPix reporting API.
 *
 * Kept apart from the two S2S transports because it is a different service, reached at a different
 * host, with a different credential and different consequences. The collector takes a server key
 * that can write to the whole property; the reporting API takes a read-only token that cannot write
 * anything at all. Giving them one interface would have invited one implementation, and then a
 * single bug could have sent the write credential to the wrong host.
 */
interface ReportTransportInterface {

	/**
	 * Run one report function.
	 *
	 * @param string              $function Report function name, e.g. `geo` or `timeseries`.
	 * @param array<string,mixed> $body     Request body: date_range, metrics, breakdown_by, limit.
	 * @return Response
	 */
	public function report( string $function, array $body = array() ): Response;

	/**
	 * List the properties the token can read.
	 *
	 * Only asked when a report comes back "not found", which on this API means the property is
	 * outside the token's reach — and the list is what tells the owner which one it does reach.
	 *
	 * @return Response
	 */
	public function properties(): Response;
}