<?php
/**
 * Gateway Functions Interface
 *
 * This interface defines the contract that all gateway classes must implement
 * to provide OTP sending, validation, and notification functionality.
 *
 * @package miniorange-sms-order-notification-otp-verification/objects
 */

namespace WCSMSOTP\Objects;

if ( ! defined( 'ABSPATH' ) ) {
	exit; // Exit if accessed directly.
}

/**
 * Gateway Functions Interface
 *
 * This interface defines the contract that all gateway classes must implement
 * to provide OTP sending, validation, and notification functionality.
 */
interface IGatewayFunctions {

	/**
	 * Register add-ons.
	 *
	 * Registers all available add-ons with the gateway system.
	 *
	 * @return void
	 */
	public function register_addons();

	/**
	 * Flush cache.
	 *
	 * Clears any cached gateway configuration or data.
	 *
	 * @return void
	 */
	public function flush_cache();

	/**
	 * Validate license key.
	 *
	 * Validates the provided license key against the gateway service.
	 *
	 * @param array $post POST values containing license key data.
	 * @return bool Whether the license key is valid.
	 */
	public function vlk( $post );

	/**
	 * Hourly sync.
	 *
	 * Performs hourly synchronization tasks with the gateway.
	 *
	 * @return void
	 */
	public function hourly_sync();

	/**
	 * Check minimum customer license version.
	 *
	 * Verifies that the customer's license meets the minimum version requirements.
	 *
	 * @return bool Whether the license version meets requirements.
	 */
	public function mclv();

	/**
	 * Check if gateway is configured.
	 *
	 * @return bool Whether the gateway is properly configured.
	 */
	public function is_gateway_config();

	/**
	 * Check if miniOrange gateway.
	 *
	 * @return bool Whether this is the miniOrange gateway.
	 */
	public function is_mg();

	/**
	 * Get application name.
	 *
	 * @return string The application name.
	 */
	public function get_application_name();

	/**
	 * Custom WordPress mail from name.
	 *
	 * Filters the email from name used by WordPress.
	 *
	 * @param string $original_email_from Original email from name.
	 * @return string Modified email from name.
	 */
	public function custom_wp_mail_from_name( $original_email_from );

	/**
	 * Configure SMS template.
	 *
	 * @param array $posted POST values containing SMS template configuration.
	 * @return bool Whether the configuration was saved successfully.
	 */
	public function mo_configure_sms_template( $posted );

	/**
	 * Configure email template.
	 *
	 * @param array $posted POST values containing email template configuration.
	 * @return bool Whether the configuration was saved successfully.
	 */
	public function mo_configure_email_template( $posted );

	/**
	 * Calls the Gateway specific mo_send_otp_token function
	 *
	 * @param string $auth_type  OTP Type - EMAIL or SMS.
	 * @param string $email     Email Address of the user.
	 * @param string $phone     Phone Number of the user.
	 * @return array
	 */
	public function mo_send_otp_token( $auth_type, $email, $phone );

	/**
	 * Calls the Gateway specific mo_send_notif
	 *
	 * @param \WCSMSOTP\Objects\NotificationSettings $settings Notification settings object.
	 * @return string Response from the gateway.
	 */
	public function mo_send_notif( NotificationSettings $settings );

	/**
	 * Calls the Gateway specific mo_validate_otp_token
	 *
	 * @param string $tx_id Transaction ID from session.
	 * @param string $otp_token OTP Token to validate.
	 * @return array
	 */
	public function mowc_validate_otp_token( $tx_id, $otp_token );

	/**
	 * Get config page pointers.
	 *
	 * Returns configuration page pointers or help text for the gateway settings page.
	 *
	 * @return array|string Configuration page pointers or help text.
	 */
	public function get_config_page_pointers();
}
