<?php

namespace SugarCalendarBookings\Abilities;

use WP_Error;

/**
 * Contract every Sugar Calendar Bookings ability implements.
 *
 * Concrete abilities are resolved through the DI container by AbilityRegistrar
 * and registered against the WordPress Abilities API on the
 * `wp_abilities_api_init` hook.
 *
 * @since 1.5.0
 */
interface AbilityInterface {

	/**
	 * Get the ability slug, without the namespace prefix.
	 *
	 * @since 1.5.0
	 *
	 * @return string
	 */
	public function get_name(): string;

	/**
	 * Get the human-readable label.
	 *
	 * @since 1.5.0
	 *
	 * @return string
	 */
	public function get_label(): string;

	/**
	 * Get the human-readable description.
	 *
	 * @since 1.5.0
	 *
	 * @return string
	 */
	public function get_description(): string;

	/**
	 * Get the JSON Schema describing accepted input.
	 *
	 * @since 1.5.0
	 *
	 * @return array
	 */
	public function get_input_schema(): array;

	/**
	 * Get the JSON Schema describing the response.
	 *
	 * @since 1.5.0
	 *
	 * @return array
	 */
	public function get_output_schema(): array;

	/**
	 * Execute the ability with validated input.
	 *
	 * @since 1.5.0
	 *
	 * @param mixed $input Input data validated against the input schema.
	 *
	 * @return array|WP_Error
	 */
	public function execute( $input );

	/**
	 * Permission gate.
	 *
	 * @since 1.5.0
	 *
	 * @return true|WP_Error True when allowed, WP_Error otherwise.
	 */
	public function check_permission();

	/**
	 * Annotation flags surfaced to MCP / abilities consumers.
	 *
	 * @since 1.5.0
	 *
	 * @return array
	 */
	public function get_annotations(): array;

	/**
	 * Whether the ability is exposed via the REST API.
	 *
	 * @since 1.5.0
	 *
	 * @return bool
	 */
	public function show_in_rest(): bool;

	/**
	 * Whether the ability is publicly listed for MCP clients.
	 *
	 * @since 1.5.0
	 *
	 * @return bool
	 */
	public function is_mcp_public(): bool;
}
