<?php
/**
 * Build/entitlement policy — the SINGLE indirection between the code and "is this a Pro,
 * licensed instance?" (audit seam R1).
 *
 * This is the only place the rest of the plugin asks whether Pro features are unlocked.
 * Every Pro feature site gates on EquaSign_Policy::is_pro(); the functional Pro code is
 * additionally wrapped in build-strip markers and physically removed from the Free build
 * at packaging (tronc v11 §13.2). So in Free the answer is not merely "false at runtime" —
 * the code behind the gate is not there at all. (See build/derive-free.php.)
 *
 * Two-build model (tronc v11 §13, arbitration #1):
 *   - FREE build  : EQUASIGN_BUILD === 'free'. No licence client (removed), no network,
 *                   no volume limit. is_pro() is hardwired false; only teasers are shown.
 *   - PRO build   : EQUASIGN_BUILD === 'pro'. is_pro() reflects the verified licence
 *                   entitlement (fresh or within the expiry grace). No valid key ⇒ the
 *                   instance behaves exactly like Free.
 *
 * Task creation is never volume-limited in either build: the licence gates FEATURES, it
 * never limits task volume. authorize_create() therefore always allows.
 *
 * @package EquaSign
 */

defined( 'ABSPATH' ) || exit;

/**
 * Feature-gating policy.
 */
final class EquaSign_Policy {

	/**
	 * Are the Pro features unlocked on this instance?
	 *
	 * Fail-closed: anything other than a 'pro' build with a genuine, verified, in-date
	 * (fresh or within grace) entitlement returns false — which shows the teasers.
	 *
	 * The EQUASIGN_BUILD check comes FIRST and short-circuits, so a Free build (where the
	 * licence client class is physically absent) never references it. The class_exists()
	 * guard is defence in depth for the same reason.
	 *
	 * @return bool
	 */
	public static function is_pro() {
		if ( 'pro' !== EQUASIGN_BUILD ) {
			return false;
		}
		return false; // Free build: no licence client, never Pro.
	}


	/**
	 * May a signing task be created right now?
	 *
	 * Task creation is never volume-limited in either build (arbitration #1). This seam is
	 * kept so the create transaction (rest/creer) has a single, stable authorisation call
	 * instead of an inline licence branch — and so any future policy (rate limiting, etc.)
	 * has one home.
	 *
	 * @return array{ok:bool,error:string} Always ok in v0.5.x.
	 */
	public static function authorize_create() {
		return array(
			'ok'    => true,
			'error' => '',
		);
	}


	/**
	 * The upgrade call-to-action, shared by the upsell bar and every teaser so all
	 * "get Pro" gateways stay consistent. Returns { label, url, external }; the specific
	 * label and target depend on the build (resolved in the body below).
	 *
	 * The 'external' flag (E2) tells call sites whether to open the link in a new tab: an
	 * outbound target opens in a new tab so the admin is not lost; an in-admin target opens
	 * in the SAME tab.
	 *
	 * @return array{label:string,url:string,external:bool}
	 */
	public static function upgrade_cta() {
		// Free build: the CTA is a plain outbound link to the public "how to install" page.
		// WordPress.org forbids a plugin downloading/installing external premium code, so there
		// is no in-admin installer — the Pro build is obtained from that page. Opens in a new
		// tab (external => true). URL is home-of-EquaSuite based + filterable, never hard-coded.
		return array( 'label' => __( 'Upgrade to Pro', 'equasign' ), 'url' => equasign_pro_page_url(), 'external' => true );
	}
}