<?php
namespace Actirise\Includes\Push;

if ( ! defined( 'ABSPATH' ) ) {
	exit; // Exit if accessed directly
}

/**
 * Contract for a per-type push apply handler.
 *
 * Every push endpoint (`adstxt`, `adstxt-monitoring`, `presized-div`,
 * `website`, `organization`, `cmp-config`) has exactly one handler. The common receive
 * pipeline in `PushController` validates and verifies a notification, then
 * dispatches its `data` payload to the handler that owns the target endpoint.
 * Only `apply()` differs between data types.
 *
 * @link       https://actirise.com
 * @since      4.3.0
 * @package    actirise
 * @subpackage actirise/includes/push
 * @author     actirise <wordpress@actirise.com>
 */
interface PushEndpointHandlerInterface {
	/**
	 * The route slug this handler owns, appended to the push base path
	 * (e.g. `adstxt` for `/wp-json/actirise/v1/push/adstxt`).
	 *
	 * @since 4.3.0
	 * @return string
	 */
	public function endpoint();

	/**
	 * The API event type this handler applies (e.g. `wordpress.adstxt.updated`).
	 *
	 * @since 4.3.0
	 * @return string
	 */
	public function event_type();

	/**
	 * Envelope versions this handler can apply. An otherwise valid envelope with
	 * an unsupported version is answered with 426.
	 *
	 * @since 4.3.0
	 * @return int[]
	 */
	public function supported_versions();

	/**
	 * Apply the event-specific payload.
	 *
	 * The payload shape varies per event type (contract §5): a string for
	 * ads.txt, an object/array for the others, hence the untyped parameter.
	 * Returning false signals an invalid payload or an apply failure and yields
	 * a 400; the event is then not marked processed so the API may retry.
	 *
	 * @since 4.3.0
	 * @param mixed $data The event-specific payload.
	 * @return bool True when the change was applied successfully.
	 */
	public function apply( $data );
}