<?php

namespace Fotogenic_AI;

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

/**
 * Media query adapter — plain-array contract for Media Library list and summary.
 */
interface MediaQueryAdapter {

	/**
	 * List/search media (attachments, images only).
	 *
	 * @param string $q        Search query (e.g. title).
	 * @param int    $page     Page number (1-based).
	 * @param int    $per_page Items per page.
	 * @return array{items: array<int, array{id:int,label:string,imageUrl:string,sourceAttachmentId:int,target:array,width:int,height:int,mime:string,bytes:int,eligible:bool,eligibilityReason:string}>, totalItems: int, totalPages: int}
	 */
	public function list_media( string $q, int $page, int $per_page ): array;

	/**
	 * Get media summary for list/cache.
	 *
	 * @param int $id Attachment ID.
	 * @return array|null|\WP_Error Browser-safe item with dimensions, MIME, bytes, and workflow eligibility; null if not found; WP_Error on failure.
	 */
	public function get_media_summary( int $id );

}
