<?php
/**
 * Base REST controller.
 *
 * @package Kordiam
 */

declare( strict_types=1 );

namespace Kordiam\Rest;

use Kordiam\Auth\RequestAuthenticator;
use Kordiam\Support\Config;
use WP_Error;
use WP_REST_Controller;
use WP_REST_Request;

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

/**
 * Shared behaviour for the plugin's REST controllers.
 *
 * Routes are registered under kordiam/v1 and the legacy wp-desk-net/v1. The alias is
 * permanent: existing sites are configured against it on the Kordiam side.
 */
abstract class AbstractController extends WP_REST_Controller {

	/**
	 * Authenticator backing the permission callbacks.
	 *
	 * @var RequestAuthenticator
	 */
	protected RequestAuthenticator $authenticator;

	/**
	 * Constructing a controller.
	 *
	 * @param RequestAuthenticator|null $authenticator Authenticator to use, or null for a default one.
	 */
	public function __construct( ?RequestAuthenticator $authenticator = null ) {
		$this->namespace     = Config::REST_NAMESPACE;
		$this->authenticator = $authenticator ?? new RequestAuthenticator();
	}

	/**
	 * Declaring this controller's routes.
	 *
	 * Not an abstract register_routes(): core's is concrete, and re-declaring it abstract is a fatal error.
	 *
	 * @return array<string, array<string, mixed>> Route path => arguments for register_rest_route().
	 */
	abstract protected function routes(): array;

	/**
	 * Registering this controller's routes under every namespace.
	 */
	public function register_routes() {
		foreach ( $this->routes() as $route => $args ) {
			$this->register_in_both_namespaces( $route, $args );
		}
	}

	/**
	 * Listing the namespaces routes are registered under.
	 *
	 * @return string[] Namespaces.
	 */
	public static function namespaces(): array {
		return array( Config::REST_NAMESPACE, Config::REST_NAMESPACE_LEGACY );
	}

	/**
	 * Registering one route under every namespace.
	 *
	 * @param string                   $route Route pattern, without a namespace.
	 * @param array<string|int, mixed> $args  Route arguments, as register_rest_route() takes them.
	 */
	protected function register_in_both_namespaces( string $route, array $args ): void {
		foreach ( self::namespaces() as $namespace ) {
			register_rest_route( $namespace, $route, $args );
		}
	}

	/**
	 * Permission callback requiring a valid access token.
	 *
	 * @param WP_REST_Request<array<string, mixed>>|WP_REST_Request $request Incoming request.
	 *
	 * @return true|WP_Error True when authorised, otherwise a 401.
	 */
	public function require_token( $request ) {
		return $this->authenticator->authorize_token( $request );
	}

	/**
	 * Permission callback requiring valid API credentials.
	 *
	 * @param WP_REST_Request<array<string, mixed>>|WP_REST_Request $request Incoming request.
	 *
	 * @return true|WP_Error True when authorised, otherwise a 401.
	 */
	public function require_credentials( $request ) {
		return $this->authenticator->authorize_credentials( $request );
	}
}