<?php

namespace Fotogenic_AI;

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

/**
 * Post query adapter — plain-array contract for WordPress posts.
 */
interface PostQueryAdapter {

    /**
     * List/search posts.
     *
     * @param string $q        Search query (title or ID).
     * @param int    $page     Page number (1-based).
     * @param int    $per_page Items per page.
     * @return array{items: array, totalItems: int, totalPages: int}
     */
    public function list_posts( string $q, int $page, int $per_page ): array;

    /**
     * Get post summary for list/cache.
     *
     * @param int $post_id Post ID.
     * @return array|null|\WP_Error Canonical source item with Post metadata and exact target snapshot; null if not found; WP_Error on failure.
     */
    public function get_post_summary( int $post_id );

}
