<?php
/**
 * Where a channel's categories and category attributes come from, and how they are loaded and cached.
 *
 * @package Tidelist
 */

namespace Tidelist\Channel;

/**
 * Category and attribute source of one channel.
 */
interface Taxonomy {

	/**
	 * The categories known now (the loaded list, else a short built-in list; may be empty).
	 */
	public function index(): CategoryIndex;

	/**
	 * Whether the full category list has been loaded from the marketplace.
	 */
	public function is_live(): bool;

	/**
	 * State of a running refresh ('nodes' => list, 'requests' => int, 'error' => string), or null.
	 */
	public function refresh_state(): ?array;

	/**
	 * Forgets the loaded list and prepares a refresh (the background job then calls crawl_step()).
	 */
	public function begin_refresh(): void;

	/**
	 * Runs one step of the refresh.
	 *
	 * @param int $budget Requests in this step.
	 * @return array|null State after the step ('done', 'error', 'nodes', 'requests'), or null when no refresh runs.
	 */
	public function crawl_step( int $budget ): ?array;

	/**
	 * The marketplace's own category suggestions for a title.
	 *
	 * @param string $title Advert title or product name.
	 * @return array<int, array{id:int|string, path:string, photos_limit:int}>
	 * @throws \Tidelist\Channel\Exception\ChannelException On marketplace errors.
	 */
	public function suggest( string $title ): array;

	/**
	 * Attribute definitions of a category (code, label, validation, allowed values).
	 *
	 * @param int|string $category_id Category ID.
	 */
	public function attributes( $category_id ): array;
}