<?php
/**
 * Woo Marketplace URL for MarginBeacon Pro upgrade CTA.
 *
 * WordPress.org / Marketplace compliance: placeholders such as `#`, `TODO`,
 * `TBD`, and `example.com` are not active destinations and must be treated as
 * empty. CTA callers MUST treat an empty return as "no Marketplace link yet".
 *
 * @package Kayvandra\MarginBeacon
 */
declare(strict_types=1);

namespace Kayvandra\MarginBeacon\Support;

/**
 * Resolves the public Pro listing URL (empty until Marketplace publish).
 */
final class ProMarketplace {

	/**
	 * Placeholder strings that must never be treated as live upgrade links.
	 *
	 * Adding a value here is a deliberate compliance choice: it prevents
	 * dead or fake destinations from being rendered as active CTAs.
	 *
	 * @return string[]
	 */
	public static function placeholders() {
		return array( '#', 'TODO', 'TBD', 'example.com', 'example.org' );
	}

	/**
	 * Whether a raw URL is a placeholder that must not be rendered as a CTA.
	 *
	 * @param string $raw Raw URL candidate.
	 * @return bool
	 */
	public static function is_placeholder( $raw ) {
		$value = strtolower( trim( (string) $raw ) );
		if ( '' === $value ) {
			return true;
		}
		foreach ( self::placeholders() as $needle ) {
			if ( $value === strtolower( $needle ) ) {
				return true;
			}
		}
		// Any literal containing the example.com host is a placeholder.
		if ( false !== strpos( $value, 'example.com' ) || false !== strpos( $value, 'example.org' ) ) {
			return true;
		}
		return false;
	}

	/**
	 * Marketplace product URL, or empty when not yet listed.
	 *
	 * Set in marginbeacon.php: define( 'AKSMB_PRO_MARKETPLACE_URL', 'https://...' );
	 * Or filter: add_filter( 'aksmb_pro_marketplace_url', fn () => 'https://...' );
	 *
	 * @return string
	 */
	public static function url() {
		$raw = defined( 'AKSMB_PRO_MARKETPLACE_URL' ) ? (string) AKSMB_PRO_MARKETPLACE_URL : '';

		/**
		 * Filter the Woo Marketplace URL for MarginBeacon Pro.
		 *
		 * @param string $url Absolute HTTPS product URL, or empty if not listed yet.
		 */
		$url = apply_filters( 'aksmb_pro_marketplace_url', $raw );

		return self::sanitize( $url );
	}

	/**
	 * Sanitize a raw URL through the same gate that CTA rendering relies on.
	 *
	 * @param mixed $url Raw URL.
	 * @return string Sanitized HTTPS URL, or empty when not renderable.
	 */
	public static function sanitize( $url ) {
		$url = trim( (string) $url );
		if ( '' === $url || self::is_placeholder( $url ) ) {
			return '';
		}
		$escaped = esc_url( $url, array( 'https' ) );
		return is_string( $escaped ) && '' !== $escaped ? $escaped : '';
	}

	/**
	 * @return bool
	 */
	public static function has_url() {
		return '' !== self::url();
	}

	/**
	 * Documentation URL placeholder - not a live endpoint, just for internal linking.
	 *
	 * @return string
	 */
	public static function placeholders_documentation_url() {
		return 'https://kayvandra.com/products/marginbeacon/docs';
	}
}