<?php
/**
 * Shared names and lookups.
 *
 * @package CreatorAssistantCategories
 */

declare( strict_types=1 );

namespace CreatorAssistantCategories;

use CreatorAssistantHub\Features\Post_Vectorizer\Post_Summary;

if ( ! defined( 'ABSPATH' ) ) {
	exit;
}

/**
 * Option names, hooks and the few lookups every class needs.
 */
final class Config {

	public const SETTINGS_OPTION = 'creator_assistant_categories_settings';
	public const RUN_OPTION      = 'creator_assistant_categories_run';
	public const MANAGED_META    = 'creator_assistant_categories_managed';
	public const PROTECTED_META  = 'creator_assistant_categories_protected';
	public const PRIMARY_META    = '_creator_assistant_categories_primary';
	public const LOCK            = 'creator_assistant_categories';
	public const NAME_HOOK       = 'creator_assistant_categories_name_tree';
	public const CHECK_HOOK      = 'creator_assistant_categories_check_run';

	/**
	 * The post types this plugin clusters: those Hub summarizes that also have
	 * the category taxonomy. Pages and custom types without categories would
	 * only create categories nobody can assign.
	 *
	 * @return string[]
	 */
	public static function category_post_types(): array {
		return array_values(
			array_filter(
				Post_Summary::get_supported_post_types(),
				static function ( $post_type ): bool {
					// Hub merges third-party filter results without sanitizing them:
					// a null or an array here must be skipped, not raise a TypeError
					// (this runs on every post save via is_categorizable_post()).
					return is_string( $post_type ) && is_object_in_taxonomy( $post_type, 'category' ); // @phpstan-ignore function.alreadyNarrowedType (Hub documents string[] but the filter can return anything)
				}
			)
		);
	}

	/**
	 * Whether a post can be placed in a category by this plugin: published,
	 * and of a clustered post type.
	 *
	 * @param int $post_id Post ID.
	 *
	 * @return bool
	 */
	public static function is_categorizable_post( int $post_id ): bool {
		return ( self::categorizable_post_checker() )( $post_id );
	}

	/**
	 * The same test as is_categorizable_post(), with the post types read
	 * once: for loops over many posts, where reading them per post would run
	 * Hub's post type filters every time.
	 *
	 * @return callable fn( int $post_id ): bool.
	 */
	public static function categorizable_post_checker(): callable {
		$types = array_flip( self::category_post_types() );

		return static function ( int $post_id ) use ( $types ): bool {
			$post = get_post( $post_id );

			return null !== $post && 'publish' === $post->post_status && isset( $types[ $post->post_type ] );
		};
	}

	/**
	 * The real name of Hub's summary collection on this site.
	 *
	 * @return string
	 */
	public static function summary_collection(): string {
		return Post_Summary::get_collection_name();
	}

	/**
	 * Options for the naming request to OpenAI.
	 *
	 * @return array{model: string, reasoning_effort: string, timeout: int}
	 */
	public static function llm_options(): array {
		/**
		 * Filters the OpenAI options used to name the categories. The model must
		 * support OpenAI's Structured Outputs in strict mode.
		 *
		 * @param array $options Default gpt-5.4-mini, medium effort, 120 seconds.
		 */
		$options = (array) apply_filters(
			'creator_assistant_categories_llm_options',
			array(
				'model'            => 'gpt-5.4-mini',
				'reasoning_effort' => 'medium',
				'timeout'          => 120, // phpcs:ignore WordPressVIPMinimum.Performance.RemoteRequestTimeout.timeout_timeout -- reasoning model, runs in the background cron, never in a visitor's request.
			)
		);

		// Same defaults as Links: the filter may return anything, so each value is
		// read defensively instead of trusting the array shape.
		return array(
			'model'            => (string) ( $options['model'] ?? 'gpt-5.4-mini' ),
			'reasoning_effort' => (string) ( $options['reasoning_effort'] ?? 'medium' ),
			'timeout'          => max( 1, (int) ( $options['timeout'] ?? 120 ) ),
		);
	}
}