<?php

namespace Fotogenic_AI;

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

/**
 * Product query adapter — plain-array contract, no WC types.
 */
interface ProductQueryAdapter {

	/**
	 * Scan published parent Products in stable ascending-ID pages.
	 *
	 * @param array $args Keys: after_id, high_water_id, limit; optional search, category, and stock_status.
	 * @return array{items: array, total: int, nextAfterId: int, done: bool, highWaterId: int, available: bool}
	 */
	public function scan_products( array $args ): array;

	/**
	 * List/search products.
	 *
	 * @param array $args Keys: status, limit, page, orderby, order, paginate; optional search, category, stock_status, exclude IDs, and offset.
	 * @return array{items: array, totalItems: int, totalPages: int}
	 */
	public function list_products( array $args ): array;

	/**
	 * List/search exact variations belonging to one authorized parent Product.
	 *
	 * @param int   $parent_product_id Parent Product ID.
	 * @param array $args              Keys: limit, page; optional search and stock.
	 * @return array{items: array, totalItems: int, totalPages: int}|\WP_Error
	 */
	public function list_product_variations( int $parent_product_id, array $args );

	/**
	 * Get product summary for list/cache.
	 *
	 * @param int $product_id Product ID.
	 * @return array|null|\WP_Error Canonical source item with Product metadata and exact target snapshot; null if not found; WP_Error when backend unavailable (e.g. woocommerce_not_active).
	 */
	public function get_product_summary( int $product_id );

	/**
	 * Get full product and image context for Studio.
	 *
	 * @param int $product_id Product ID.
	 * @return array|\WP_Error Same shape as Rest_Studio::build_product_context; WP_Error on failure.
	 */
	public function get_product_context( int $product_id );
}
