<?php
/**
 * Postomatic Plugin - Product Source contract.
 *
 * @package  Postomatic
 * @category Plugin
 * @license  GPL-2.0-or-later https://www.gnu.org/licenses/gpl-2.0.html
 * @link     https://buildomatics.com/postomatics
 * @since    1.3.0
 */

namespace Postomatic\Api;

// Exit if accessed directly.
if ( ! defined( 'ABSPATH' ) ) {
	exit;
}

/**
 * Product_Source_Interface.
 *
 * Every supported e-commerce platform (WooCommerce, Easy Digital Downloads,
 * SureCart, ...) implements this contract so the rest of the plugin (AJAX
 * handlers, admin templates, AutoPilot) can work with "products" without
 * knowing which shop plugin actually stores them.
 *
 * @since 1.3.0
 */
interface Product_Source_Interface {

	/**
	 * Whether the shop plugin backing this source is active on this site.
	 *
	 * Implementations must rely on the shop plugin's own documented
	 * functions/classes/post types rather than guessing based on generic
	 * conventions (e.g. a post type simply named "product") — that is what
	 * previously caused this feature to misfire on sites that use an
	 * unrelated plugin defining a "product" post type of their own.
	 *
	 * @return bool
	 */
	public static function is_active(): bool;

	/**
	 * Machine-readable identifier for this platform (e.g. "woocommerce").
	 *
	 * @return string
	 */
	public function get_platform_key(): string;

	/**
	 * Human-readable label for this platform (e.g. "WooCommerce").
	 *
	 * @return string
	 */
	public function get_platform_label(): string;

	/**
	 * Whether the store currently has at least one published product.
	 *
	 * @return bool
	 */
	public function has_products(): bool;

	/**
	 * Retrieve a page of products in Postomatic's normalized product shape.
	 *
	 * @param string $search   Optional search term to filter by product name.
	 * @param int    $page     Page number (1-indexed).
	 * @param int    $per_page Number of products per page.
	 *
	 * @return array{products: array<int, array<string, mixed>>, pagination: array{total:int, per_page:int, current_page:int, total_pages:int}}
	 */
	public function get_products( string $search = '', int $page = 1, int $per_page = 20 ): array;
}
