<?php
/**
 * Batch request statuses returned by the API.
 *
 * @package AIContentByParallax
 */

namespace AIContentByParallax\Enums;

defined( 'ABSPATH' ) || exit;

/**
 * Normalized set of supported batch request status strings.
 */
enum BatchRequestStatus: string {
	case NEW              = 'new';
	case INPROGRESS       = 'inprogress';
	case COMPLETE         = 'complete';
	case ERROR            = 'error';
	case CANCELLED        = 'cancelled';
	case PENDING          = 'pending';
	case COMPLETED        = 'completed';
	case READY            = 'ready';
	case READY_FOR_REVIEW = 'ready_for_review';

	/**
	 * Map API status strings to enum cases.
	 *
	 * @param string $api_status The raw status string from the API.
	 * @return BatchRequestStatus|null The corresponding enum case, or null if unrecognized.
	 */
	public static function from_api_status( string $api_status ): ?self {
		return match ( strtolower( $api_status ) ) {
			'new'              => self::NEW,
			'inprogress'       => self::INPROGRESS,
			'complete'         => self::COMPLETE,
			'error'            => self::ERROR,
			'cancelled'        => self::CANCELLED,
			'completed'        => self::COMPLETED,
			'ready'            => self::READY,
			'ready_for_review' => self::READY_FOR_REVIEW,
			default            => null,
		};
	}

	/**
	 * Map API numeric status codes to enum cases (used in API v1).
	 *
	 * @param int $api_code The numeric status code from the API.
	 * @return BatchRequestStatus|null The corresponding enum case, or null if unrecognized.
	 */
	public static function from_api_code( int $api_code ): ?self {
		return match ( $api_code ) {
			0 => self::NEW,
			1 => self::INPROGRESS,
			2 => self::COMPLETE,
			3 => self::ERROR,
			4 => self::CANCELLED,
			default => null,
		};
	}

	/**
	 * Convert the enum case to a human-readable label.
	 *
	 * @param self $enum_case The enum case to convert.
	 * @return string The human-readable label for the given enum case.
	 */
	public static function to_human_readable( self $enum_case ): string { // phpcs:ignore PHPCompatibility.FunctionDeclarations.NewParamTypeDeclarations.SelfOutsideClassScopeFound -- enum scope is class-like; plugin requires PHP 8.1+
		return match ( $enum_case ) {
			self::NEW              => __( 'New', 'ai-content-by-parallax' ),
			self::INPROGRESS       => __( 'In Progress', 'ai-content-by-parallax' ),
			self::COMPLETE         => __( 'Complete', 'ai-content-by-parallax' ),
			self::ERROR            => __( 'Error', 'ai-content-by-parallax' ),
			self::CANCELLED        => __( 'Cancelled', 'ai-content-by-parallax' ),
			self::PENDING          => __( 'Pending', 'ai-content-by-parallax' ),
			self::COMPLETED        => __( 'Completed', 'ai-content-by-parallax' ),
			self::READY            => __( 'Ready', 'ai-content-by-parallax' ),
			self::READY_FOR_REVIEW => __( 'Ready for Review', 'ai-content-by-parallax' ),
		};
	}

	/**
	 * Get an array of all enum case values.
	 *
	 * @return array An array of all enum case values.
	 */
	public static function options_array(): array {
		return array_map( fn( $enum_case ) => $enum_case->value, self::cases() );
	}

	/**
	 * Statuses that indicate a batch request is finished and should not be polled again.
	 *
	 * Covers both v1 spellings ('complete', 'error') and v2 ('completed', 'failed')
	 * plus 'cancelled', so records stored under either API version are excluded.
	 *
	 * @return string[]
	 */
	public static function terminal_statuses(): array {
		return array(
			self::COMPLETE->value,
			self::COMPLETED->value,
			self::ERROR->value,
			self::CANCELLED->value,
			// 'failed' is a legacy DB value from v1 that predates the enum.
			'failed',
		);
	}

	/**
	 * Statuses for which optimized data may be available from the API
	 * and row hydration should be attempted (step 4 in detail tables).
	 *
	 * Includes active processing states because partial results may be
	 * available while the batch is still running.
	 *
	 * @return string[]
	 */
	public static function api_fetchable(): array {
		return array(
			self::INPROGRESS->value,
			self::COMPLETE->value,
			self::COMPLETED->value,
			self::READY->value,
			self::READY_FOR_REVIEW->value,
			// Legacy v1 value that may still exist in DB rows.
			'processing',
		);
	}

	/**
	 * Statuses for which rows should be marked 'ready' for import
	 * even if no optimized data was found (step 5 in detail tables).
	 *
	 * @return string[]
	 */
	public static function hydration_eligible(): array {
		return array( self::COMPLETED->value, self::COMPLETE->value, self::READY->value, self::READY_FOR_REVIEW->value );
	}
}