<?php
/**
 * Notification Scope
 *
 * Decides which completed conversations produce an email notification.
 *
 * Owners differ on what they want in their inbox: some read every conversation as
 * proof the agent is being used, others only want to hear about someone worth
 * calling back. This is a preference, not a defect, so it is a setting rather than
 * a rule — and it is deliberately the ONLY thing this class knows about. It takes
 * plain values and returns a bool, so the decision is testable without WordPress.
 *
 * @link       https://github.com/sitestaffr/sitestaffr-plugin
 * @since      1.40.0
 *
 * @package    SiteStaffr
 * @subpackage SiteStaffr/includes
 */

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

/**
 * Which conversations are worth an email.
 *
 * @since 1.40.0
 */
class SiteStaffr_Notification_Scope {

	/**
	 * Email for every completed conversation. The default, and what every install
	 * did before this setting existed.
	 *
	 * @var string
	 */
	const SCOPE_ALL = 'all';

	/**
	 * Email only for conversations that captured a qualified lead.
	 *
	 * @var string
	 */
	const SCOPE_QUALIFIED = 'qualified';

	/**
	 * Settings key holding the chosen scope.
	 *
	 * @var string
	 */
	const SETTING_KEY = 'notification_scope';

	/**
	 * Whether a conversation should send an email notification.
	 *
	 * Fails OPEN in every ambiguous case. A missing, corrupt or unrecognised scope
	 * sends the email, because the cost of an unwanted email is an annoyance and the
	 * cost of a suppressed one is a lost lead.
	 *
	 * @since  1.40.0
	 * @param  mixed $scope             Configured scope value.
	 * @param  bool  $is_qualified_lead Whether the conversation captured a qualified lead.
	 * @param  bool  $is_manual         Whether this is an explicit "Email Conversation" action.
	 * @return bool
	 */
	public static function should_notify( $scope, $is_qualified_lead, $is_manual = false ) {
		// An explicit human action always sends — the same carve-out the
		// test-conversation skip already makes. If someone clicks send, it sends.
		if ( $is_manual ) {
			return true;
		}

		if ( self::SCOPE_QUALIFIED !== self::sanitize( $scope ) ) {
			return true;
		}

		return (bool) $is_qualified_lead;
	}

	/**
	 * Reduce any stored value to a known scope.
	 *
	 * @since  1.40.0
	 * @param  mixed $scope Raw value from settings or a form post.
	 * @return string       One of the SCOPE_* constants; SCOPE_ALL for anything unrecognised.
	 */
	public static function sanitize( $scope ) {
		return ( is_string( $scope ) && self::SCOPE_QUALIFIED === $scope )
			? self::SCOPE_QUALIFIED
			: self::SCOPE_ALL;
	}

	/**
	 * Read the configured scope out of the plugin settings array.
	 *
	 * @since  1.40.0
	 * @param  array $settings The `sitestaffr_settings` option.
	 * @return string
	 */
	public static function from_settings( $settings ) {
		return self::sanitize(
			( is_array( $settings ) && isset( $settings[ self::SETTING_KEY ] ) )
				? $settings[ self::SETTING_KEY ]
				: null
		);
	}
}
