<?php
/**
 * Storage of listings. The WordPress implementation is ListingRepository.
 *
 * @package Tidelist
 */

namespace Tidelist\Data;

/**
 * Listing storage.
 */
interface ListingStore {

	/**
	 * One listing.
	 *
	 * @param int $id Listing ID.
	 * @return array|null Row, or null.
	 */
	public function find( int $id ): ?array;

	/**
	 * The listing of one shop item on one marketplace account.
	 *
	 * @param int      $product_id   Product ID (the parent product for variations).
	 * @param int|null $variation_id Variation ID, or null for a simple product.
	 * @param string   $channel      Channel ID.
	 * @param int      $account_id   Account ID.
	 */
	public function find_for_item( int $product_id, ?int $variation_id, string $channel, int $account_id ): ?array;

	/**
	 * Inserts a listing.
	 *
	 * @param array $fields Fields (product_id and channel are required).
	 * @return int New listing ID.
	 * @throws \InvalidArgumentException On invalid data or a duplicate item.
	 */
	public function insert( array $fields ): int;

	/**
	 * Updates a listing.
	 *
	 * @param int   $id     Listing ID.
	 * @param array $fields Fields to change.
	 * @throws \InvalidArgumentException On invalid data.
	 */
	public function update( int $id, array $fields ): void;

	/**
	 * Listings, newest first.
	 *
	 * @param array $filters Optional: status (string|string[]), channel, account_id, product_id.
	 * @param int   $limit   Maximum rows (0 = all).
	 * @param int   $offset  Rows to skip.
	 * @return array<int, array>
	 */
	public function all( array $filters = array(), int $limit = 0, int $offset = 0 ): array;

	/**
	 * Number of listings per status.
	 *
	 * @return array<string, int>
	 */
	public function count_by_status(): array;
}