<?php
/**
 * Product URL repository contract.
 *
 * @package Affilun\Infrastructure\Persistence
 */

declare(strict_types=1);

namespace Affilun\Infrastructure\Persistence;

/**
 * Persistence port for URLs attached to an affilun product.
 */
interface ProductUrlRepository {

	/**
	 * Persist a product URL record.
	 *
	 * @param ProductUrlRecord $record URL record.
	 */
	public function save( ProductUrlRecord $record ): ProductUrlRecord;

	/**
	 * Find a URL record by database id.
	 *
	 * @param int $id Database row id.
	 */
	public function findById( int $id ): ?ProductUrlRecord;

	/**
	 * Find URL records attached to a product.
	 *
	 * @param int $productId Product id.
	 *
	 * @return list<ProductUrlRecord>
	 */
	public function findByProductId( int $productId ): array;

	/**
	 * Find a product URL row by product, provider, and URL hash.
	 *
	 * @param int    $productId    Product id.
	 * @param string $providerType Provider namespace.
	 * @param string $urlHash      Normalized URL hash.
	 */
	public function findByProductProviderUrl( int $productId, string $providerType, string $urlHash ): ?ProductUrlRecord;

	/**
	 * Find a URL row by provider-side item id.
	 *
	 * @param string $providerType   Provider namespace.
	 * @param string $providerItemId Provider-side item identifier.
	 */
	public function findByProviderItem( string $providerType, string $providerItemId ): ?ProductUrlRecord;

	/**
	 * Delete a URL row by database id.
	 *
	 * @param int $id Database row id.
	 */
	public function delete( int $id ): bool;

	/**
	 * Delete URL rows for a product/provider pair.
	 *
	 * @param int    $productId    Product id.
	 * @param string $providerType Provider namespace.
	 */
	public function deleteByProductAndProvider( int $productId, string $providerType ): int;

	/**
	 * Count stored URL rows.
	 */
	public function count(): int;
}
