<?php
/**
 * What syncing needs a workspace to be able to do.
 *
 * @package SharelyAI
 */

namespace SharelyAI;

defined( 'ABSPATH' ) || exit;

/**
 * The operations Sync and Roles depend on, named apart from how they are done.
 *
 * `Knowledge` is the real implementation and stays `final`. The interface exists
 * so a test can supply a workspace that lives in memory — which is the only way
 * to assert the thing that actually matters about sync, that the replacement item
 * exists before the old one is deleted. A mock at the HTTP level cannot show
 * that; an in-memory workspace can.
 *
 * Keeping it an interface rather than letting tests subclass the real class also
 * means the stand-in cannot quietly drift out of step: change a signature here
 * and both stop compiling.
 */
interface KnowledgeApi {

	/**
	 * Creates one item, describes it, and tags it.
	 *
	 * @param array{title:string, content:string, url:string, language:string} $document The page.
	 * @param string[]                                                         $role_ids Sharely role ids.
	 *
	 * @return array{ok:bool, id:string, code:string, message:string}
	 */
	public function create( array $document, array $role_ids ): array;

	/**
	 * Sets which roles may see an item, replacing the set.
	 *
	 * @param string   $knowledge_id The item.
	 * @param string[] $role_ids     Sharely role ids.
	 *
	 * @return array{ok:bool, status:int, data:mixed, code:string, message:string}
	 */
	public function replace_roles( string $knowledge_id, array $role_ids ): array;

	/**
	 * Deletes one item. Already gone is not a failure.
	 *
	 * @param string $knowledge_id The item.
	 *
	 * @return array{ok:bool, status:int, data:mixed, code:string, message:string}
	 */
	public function delete( string $knowledge_id ): array;

	/**
	 * Every item in the workspace.
	 *
	 * @param int $page_size How many per request.
	 *
	 * @return array{ok:bool, items:array<int, array<string, mixed>>, code:string, message:string}
	 */
	public function list_all( int $page_size = 500 ): array;

	/**
	 * What the platform holds.
	 *
	 * @return array{ok:bool, status:int, data:mixed, code:string, message:string}
	 */
	public function stats(): array;

	/**
	 * Finds a workspace role by the id this connector knows it as.
	 *
	 * @param string $customer_role_id e.g. `wp:anonymous`.
	 *
	 * @return array{ok:bool, id:string, code:string, message:string}
	 */
	public function find_role( string $customer_role_id ): array;

	/**
	 * Creates a workspace role.
	 *
	 * @param string $name             What a person calls it.
	 * @param string $customer_role_id What this connector calls it.
	 *
	 * @return array{ok:bool, id:string, code:string, message:string}
	 */
	public function create_role( string $name, string $customer_role_id ): array;
}