<?php
namespace Actirise\Includes\Push\Handler;

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

use Actirise\Includes\Push\PushEndpointHandlerInterface;
use ActiriseAdmin\Includes\Core as AdminCore;

/**
 * Applies `wordpress.organization.updated` (contract §5.5).
 *
 * The `data` payload is the organization resource — `{@id, name, hasBilling,
 * country.code}`. The apply reuses the same writer as the polling fallback,
 * ActiriseAdmin\Includes\Core::check_organization_fields(), so both paths derive
 * and persist the same options (`billing-status` from `hasBilling`,
 * `organization-country` from `country.code`). The billing reminder banner reads
 * those options, so it reflects the pushed state on the next admin render.
 *
 * The organization UUID is no longer pushed (contract §5.5), so it is neither
 * expected in the payload nor written here. The `@id` identity binding is
 * enforced centrally by the US 2 pipeline ({@see \Actirise\Includes\Push\PushController})
 * before dispatch, so it is not repeated here.
 *
 * @link       https://actirise.com
 * @since      4.3.0
 * @package    actirise
 * @subpackage actirise/includes/push/handler
 * @author     actirise <wordpress@actirise.com>
 */
final class OrganizationPushHandler implements PushEndpointHandlerInterface {
	/**
	 * Field the shared apply relies on to derive the billing state; a payload
	 * missing it carries no applicable organization change and is rejected before
	 * the apply runs. `country` is intentionally not required — the shared apply
	 * only updates `organization-country` when a code is present.
	 *
	 * @since 4.3.0
	 * @var string[]
	 */
	const REQUIRED_FIELDS = array( 'hasBilling' );

	/**
	 * {@inheritDoc}
	 *
	 * @since 4.3.0
	 * @return string
	 */
	public function endpoint() {
		return 'organization';
	}

	/**
	 * {@inheritDoc}
	 *
	 * @since 4.3.0
	 * @return string
	 */
	public function event_type() {
		return 'wordpress.organization.updated'; // phpcs:ignore WordPress.WP.CapitalPDangit.MisspelledInText -- Actirise API event-type identifier.
	}

	/**
	 * {@inheritDoc}
	 *
	 * @since 4.3.0
	 * @return int[]
	 */
	public function supported_versions() {
		return array( 1 );
	}

	/**
	 * Apply an organization-info update.
	 *
	 * The payload must be an object carrying at least the field the shared apply
	 * relies on ({@see self::REQUIRED_FIELDS}); anything else is a schema error
	 * rejected with a 400 by the controller. Rejecting an incomplete payload also
	 * guards the reused writer: an empty argument makes check_organization_fields()
	 * fetch from the API (the page-load GET this story removes), so a push must
	 * never reach it empty.
	 *
	 * @since 4.3.0
	 * @param mixed $data The organization resource payload (contract §5.5).
	 * @return bool True when the update was applied.
	 */
	public function apply( $data ) {
		if ( ! is_array( $data ) ) {
			return false;
		}

		foreach ( self::REQUIRED_FIELDS as $field ) {
			if ( ! isset( $data[ $field ] ) ) {
				return false;
			}
		}

		/** @var array<string, mixed> $data The verified organization resource (contract §5.5). */
		AdminCore::check_organization_fields( $data );

		return true;
	}
}