<?php
/**
 * Core implementation for Agent Zappy.
 *
 * This file is loaded by the root plugin bootstrap so GitHub source ZIPs
 * are detected as valid WordPress plugin packages.
 *
 * @package AgentZappy
 */

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

if ( ! defined( 'AGENT_ZAPPY_PLUGIN_FILE' ) ) {
	define( 'AGENT_ZAPPY_PLUGIN_FILE', __FILE__ );
}

if ( ! class_exists( 'Agent_Zappy_Plugin' ) ) {
	/**
	 * Main plugin class.
	 */
	final class Agent_Zappy_Plugin {
		private const OPTION_KEY = 'agent_zappy_options';
		private const LEGACY_OPTION_KEY = 'za_woocommerce_whatsapp_widget_options';
		private const MENU_SLUG  = 'agent-zappy';
		private const API_URL       = 'https://api.agentzappy.com/manager/woocommerce/webhook/v2/product';
		// Migration comparison only: no assets or executable code are loaded from this URL.
		private const LEGACY_API_URL = 'https://i2lujtsr7l.execute-api.ap-southeast-1.amazonaws.com/woocommerce/webhook/v2/product';
		private const SYNC_META_KEY = '_agent_zappy_last_availability_sync';
		private const SYNC_VERSION_META_KEY = '_agent_zappy_sync_version';
		private const DEBUG_LOG_OPTION = 'agent_zappy_webhook_debug';
		private const LEGACY_DEBUG_LOG_OPTION = 'za_woocommerce_whatsapp_widget_webhook_debug';
		private const UPDATE_HISTORY_OPTION = 'agent_zappy_update_history';
		private const LEGACY_UPDATE_HISTORY_OPTION = 'za_woocommerce_whatsapp_widget_update_history';
		private const ASYNC_HOOK    = 'agent_zappy_process_async_update';
		private const ASYNC_GROUP   = 'agent_zappy';
		private const ASYNC_MAX_ATTEMPTS = 3;
		private const API_KEY_MASK = '••••••••••••••••';
		private const VERSION      = '1.2.9';
		/** @var array<int, bool> Variation IDs already queued during this request. */
		private static $queued_variation_syncs = array();
		/** @var array<int, array<int, mixed>> Latest admin/API update for each product in this request. */
		private static $pending_immediate_updates = array();
		/** @var bool Whether the end-of-request delivery callback has been registered. */
		private static $immediate_flush_registered = false;

		/**
		 * Boot the plugin hooks.
		 */
		public static function init(): void {
			self::migrate_legacy_storage();
			self::migrate_default_api_url();
			add_action( 'before_woocommerce_init', array( __CLASS__, 'declare_woocommerce_compatibility' ) );
			add_action( 'admin_menu', array( __CLASS__, 'add_settings_page' ) );
			add_action( 'admin_init', array( __CLASS__, 'register_settings' ) );
			add_action( 'admin_init', array( __CLASS__, 'process_webhook_debug_actions' ) );
			add_action( 'admin_init', array( __CLASS__, 'process_update_history_actions' ) );
			add_action( 'wp_enqueue_scripts', array( __CLASS__, 'enqueue_assets' ) );
			add_action( 'admin_enqueue_scripts', array( __CLASS__, 'enqueue_admin_assets' ) );
			add_action( 'wp_footer', array( __CLASS__, 'render_widget' ) );
			add_action( 'admin_notices', array( __CLASS__, 'render_woocommerce_missing_notice' ) );
			add_action( 'add_meta_boxes_product', array( __CLASS__, 'add_product_availability_meta_box' ) );
			add_action( 'woocommerce_product_set_stock_status', array( __CLASS__, 'sync_product_stock_status' ), 10, 3 );
			add_action( 'woocommerce_variation_set_stock_status', array( __CLASS__, 'sync_product_stock_status' ), 10, 3 );
			add_action( 'woocommerce_product_object_updated_props', array( __CLASS__, 'sync_product_update' ), 10, 2 );
			add_action( 'woocommerce_save_product_variation', array( __CLASS__, 'sync_saved_variation' ), 20, 1 );
			add_action( 'woocommerce_update_product_variation', array( __CLASS__, 'sync_saved_variation' ), 20, 1 );
			add_action( 'woocommerce_new_product_variation', array( __CLASS__, 'sync_saved_variation' ), 20, 1 );
			add_action( 'woocommerce_reduce_order_stock', array( __CLASS__, 'sync_order_stock_statuses' ), 20, 1 );
			add_action( self::ASYNC_HOOK, array( __CLASS__, 'process_async_update' ), 10, 6 );
			add_filter( 'plugin_action_links_' . plugin_basename( self::get_plugin_file() ), array( __CLASS__, 'add_settings_link' ) );
		}

		/**
		 * Copy settings and histories from the plugin's previous technical slug.
		 * Legacy data is retained as a rollback-safe backup.
		 */
		private static function migrate_legacy_storage(): void {
			$legacy_options = get_option( self::LEGACY_OPTION_KEY, null );
			if ( null === get_option( self::OPTION_KEY, null ) && is_array( $legacy_options ) ) {
				add_option( self::OPTION_KEY, $legacy_options, '', false );
			}

			$legacy_debug = get_option( self::LEGACY_DEBUG_LOG_OPTION, null );
			if ( null === get_option( self::DEBUG_LOG_OPTION, null ) && is_array( $legacy_debug ) ) {
				add_option( self::DEBUG_LOG_OPTION, $legacy_debug, '', false );
			}

			$legacy_history = get_option( self::LEGACY_UPDATE_HISTORY_OPTION, null );
			if ( null === get_option( self::UPDATE_HISTORY_OPTION, null ) && is_array( $legacy_history ) ) {
				add_option( self::UPDATE_HISTORY_OPTION, $legacy_history, '', false );
			}
		}

		/**
		 * Move sites using the previous plugin default to the current production URL.
		 * Custom endpoint overrides are deliberately left unchanged.
		 */
		private static function migrate_default_api_url(): void {
			$options = get_option( self::OPTION_KEY, array() );
			if ( ! is_array( $options ) || empty( $options['api_url'] ) || self::LEGACY_API_URL !== $options['api_url'] ) {
				return;
			}

			$options['api_url'] = self::API_URL;
			update_option( self::OPTION_KEY, $options );
		}

		/**
		 * Remove pending background actions when the plugin is deactivated.
		 */
		public static function deactivate(): void {
			if ( function_exists( 'as_unschedule_all_actions' ) ) {
				as_unschedule_all_actions( self::ASYNC_HOOK, array(), self::ASYNC_GROUP );
			}

			wp_clear_scheduled_hook( self::ASYNC_HOOK );
		}

		/**
		 * Declare compatibility with WooCommerce features when WooCommerce is active.
		 */
		public static function declare_woocommerce_compatibility(): void {
			if ( class_exists( 'Automattic\\WooCommerce\\Utilities\\FeaturesUtil' ) ) {
				\Automattic\WooCommerce\Utilities\FeaturesUtil::declare_compatibility( 'custom_order_tables', self::get_plugin_file(), true );
			}
		}

		/**
		 * Show a clear admin notice when WooCommerce is not active.
		 */
		public static function render_woocommerce_missing_notice(): void {
			if ( class_exists( 'WooCommerce' ) || ! current_user_can( 'activate_plugins' ) ) {
				return;
			}

			?>
			<div class="notice notice-warning">
				<p>
					<strong><?php esc_html_e( 'Agent Zappy is ready to install on your WooCommerce store.', 'agent-zappy' ); ?></strong>
					<?php esc_html_e( 'Please install and activate WooCommerce for full store compatibility. You can manage the WhatsApp chat button from the Agent Zappy menu in the left admin panel.', 'agent-zappy' ); ?>
				</p>
			</div>
			<?php
		}

		/**
		 * Register the Agent Zappy top-level admin menu page.
		 */
		public static function add_settings_page(): void {
			add_menu_page(
				__( 'Agent Zappy', 'agent-zappy' ),
				__( 'Agent Zappy', 'agent-zappy' ),
				'manage_options',
				self::MENU_SLUG,
				array( __CLASS__, 'render_settings_page' ),
				'dashicons-whatsapp',
				56
			);
		}

		/**
		 * Register plugin settings.
		 */
		public static function register_settings(): void {
			register_setting(
				self::MENU_SLUG,
				self::OPTION_KEY,
				array(
					'type'              => 'array',
					'sanitize_callback' => array( __CLASS__, 'sanitize_options' ),
					'default'           => self::get_default_options(),
				)
			);
		}

		/**
		 * Sanitize settings submitted from the admin page.
		 *
		 * @param mixed $options Raw options.
		 * @return array<string, string>
		 */
		public static function sanitize_options( $options ): array {
			if ( ! is_array( $options ) ) {
				$options = array();
			}

			$defaults  = self::get_default_options();
			$current   = self::get_options();
			$sanitized = array();

			$sanitized['phone'] = isset( $options['phone'] ) ? preg_replace( '/[^0-9]/', '', (string) $options['phone'] ) : $current['phone'];

			$position = isset( $options['position'] ) ? sanitize_key( (string) $options['position'] ) : $current['position'];
			if ( ! array_key_exists( $position, self::get_positions() ) ) {
				$position = $defaults['position'];
			}
			$sanitized['position'] = $position;

			$sanitized['message'] = isset( $options['message'] ) ? sanitize_textarea_field( (string) $options['message'] ) : $current['message'];

			$api_key = isset( $options['api_key'] ) ? sanitize_text_field( (string) $options['api_key'] ) : '';
			$sanitized['api_key'] = '' !== $api_key && self::API_KEY_MASK !== $api_key ? $api_key : $current['api_key'];

			$api_url = isset( $options['api_url'] ) ? esc_url_raw( (string) $options['api_url'] ) : null;
			if ( null === $api_url ) {
				$sanitized['api_url'] = $current['api_url'];
			} elseif ( '' !== $api_url && 'https' === wp_parse_url( $api_url, PHP_URL_SCHEME ) ) {
				$sanitized['api_url'] = $api_url;
			} else {
				$sanitized['api_url'] = $current['api_url'];
				add_settings_error( self::OPTION_KEY, 'agent_zappy_invalid_api_url', __( 'The product webhook must be a valid HTTPS URL.', 'agent-zappy' ), 'error' );
			}

			$auto_sync = isset( $options['auto_sync'] ) ? sanitize_key( (string) $options['auto_sync'] ) : $current['auto_sync'];
			$sanitized['auto_sync'] = 'no' === $auto_sync ? 'no' : 'yes';

			$auto_sync_price = isset( $options['auto_sync_price'] ) ? sanitize_key( (string) $options['auto_sync_price'] ) : $current['auto_sync_price'];
			$sanitized['auto_sync_price'] = 'yes' === $auto_sync_price ? 'yes' : 'no';

			$debug_enabled = isset( $options['debug_enabled'] ) ? sanitize_key( (string) $options['debug_enabled'] ) : $current['debug_enabled'];
			$sanitized['debug_enabled'] = 'yes' === $debug_enabled ? 'yes' : 'no';

			return $sanitized;
		}

		/**
		 * Clear saved webhook debug entries from the settings screen.
		 */
		public static function process_webhook_debug_actions(): void {
			if ( ! isset( $_POST['agent_zappy_clear_webhook_debug'] ) || ! current_user_can( 'manage_options' ) ) {
				return;
			}

			check_admin_referer( 'agent_zappy_clear_webhook_debug', 'agent_zappy_clear_webhook_debug_nonce' );
			update_option( self::DEBUG_LOG_OPTION, array(), false );
			self::add_admin_message( __( 'Webhook debug history cleared.', 'agent-zappy' ), 'success' );
		}

		/**
		 * Clear the customer-friendly product update history.
		 */
		public static function process_update_history_actions(): void {
			if ( ! isset( $_POST['agent_zappy_clear_update_history'] ) || ! current_user_can( 'manage_options' ) ) {
				return;
			}

			check_admin_referer( 'agent_zappy_clear_update_history', 'agent_zappy_clear_update_history_nonce' );
			update_option( self::UPDATE_HISTORY_OPTION, array(), false );
			self::add_admin_message( __( 'Recent product update history cleared.', 'agent-zappy' ), 'success' );
		}

		/**
		 * Add the Agent Zappy availability box to WooCommerce products.
		 */
		public static function add_product_availability_meta_box(): void {
			add_meta_box(
				'agent-zappy-product-availability',
				__( 'Agent Zappy Availability', 'agent-zappy' ),
				array( __CLASS__, 'render_product_availability_meta_box' ),
				'product',
				'side',
				'high'
			);
		}

		/**
		 * Render the Agent Zappy WooCommerce product availability box.
		 *
		 * @param WP_Post $post Product post.
		 */
		public static function render_product_availability_meta_box( $post ): void {
			if ( ! function_exists( 'wc_get_product' ) ) {
				esc_html_e( 'WooCommerce is required to send product availability updates.', 'agent-zappy' );
				return;
			}

			$product = wc_get_product( $post->ID );
			if ( ! $product ) {
				esc_html_e( 'Unable to load this WooCommerce product.', 'agent-zappy' );
				return;
			}

			$product_identifier   = self::get_product_id_for_api( $product );
			$stock_status         = $product->get_stock_status();
			$last_sync            = get_post_meta( $post->ID, self::SYNC_META_KEY, true );
			$product_settings_url = admin_url( 'admin.php?page=' . self::MENU_SLUG );
			?>
			<p><?php esc_html_e( 'Agent Zappy sends this WooCommerce product ID in the webhook JSON field named id.', 'agent-zappy' ); ?></p>
			<p>
				<strong><?php esc_html_e( 'WooCommerce product ID:', 'agent-zappy' ); ?></strong>
				<?php echo esc_html( $product_identifier ); ?>
			</p>
			<p>
				<strong><?php esc_html_e( 'WooCommerce stock:', 'agent-zappy' ); ?></strong>
				<?php echo esc_html( $stock_status ); ?>
			</p>
			<?php if ( is_array( $last_sync ) && ! empty( $last_sync['message'] ) ) : ?>
				<p class="agent-zappy-last-sync agent-zappy-last-sync--<?php echo esc_attr( sanitize_html_class( $last_sync['status'] ?? 'info' ) ); ?>">
					<strong><?php esc_html_e( 'Last Agent Zappy sync:', 'agent-zappy' ); ?></strong><br />
					<?php echo esc_html( (string) $last_sync['message'] ); ?>
					<?php if ( ! empty( $last_sync['time'] ) ) : ?>
						<br /><span><?php echo esc_html( (string) $last_sync['time'] ); ?></span>
					<?php endif; ?>
				</p>
			<?php endif; ?>
			<p class="description"><?php esc_html_e( 'Automatic background sync runs when WooCommerce stock or price changes, including purchase-driven stock reductions.', 'agent-zappy' ); ?></p>
			<p class="description">
				<?php
				echo wp_kses_post(
					sprintf(
						/* translators: %s: Agent Zappy settings URL. */
						__( 'API key is saved in <a href="%s">Agent Zappy settings</a>.', 'agent-zappy' ),
						esc_url( $product_settings_url )
					)
				);
				?>
			</p>
			<?php
		}

		/**
		 * Send a WooCommerce product update to the Agent Zappy webhook.
		 *
		 * @param string $product_identifier WooCommerce product or variation ID.
		 * @param string $stock_status WooCommerce stock status.
		 * @param int    $timeout Request timeout in seconds.
		 * @param bool   $retry_timeout Whether to retry one timeout within this request.
		 * @return true|WP_Error
		 */
		private static function send_product_update( string $product_identifier, string $stock_status, ?int $price_minor_units = null, int $timeout = 15, bool $retry_timeout = true ) {
			if ( '' === $product_identifier ) {
				return new WP_Error( 'agent_zappy_missing_product_id', __( 'Enter the WooCommerce product ID before sending an update.', 'agent-zappy' ) );
			}

			if ( '' === $stock_status ) {
				return new WP_Error( 'agent_zappy_missing_stock_status', __( 'Choose a WooCommerce stock status before sending an update.', 'agent-zappy' ) );
			}

			$options = self::get_options();
			$api_key = self::get_saved_api_key();
			$api_url = $options['api_url'];

			if ( '' === $api_key ) {
				return new WP_Error( 'agent_zappy_missing_api_key', __( 'Add and save your Agent Zappy API key before sending an update.', 'agent-zappy' ) );
			}

			if ( '' === $api_url ) {
				return new WP_Error( 'agent_zappy_missing_api_url', __( 'Add and save the Agent Zappy product webhook URL before sending an update.', 'agent-zappy' ) );
			}

			if ( 'https' !== wp_parse_url( $api_url, PHP_URL_SCHEME ) || false === wp_http_validate_url( $api_url ) ) {
				return new WP_Error( 'agent_zappy_unsafe_api_url', __( 'The Agent Zappy product webhook must be a safe HTTPS URL.', 'agent-zappy' ) );
			}

			$payload = array(
				'id'           => $product_identifier,
				'stock_status' => $stock_status,
			);

			if ( null !== $price_minor_units ) {
				$payload['price'] = $price_minor_units;
			}

			$request_args = array(
				'timeout'             => max( 1, min( 15, $timeout ) ),
				'redirection'         => 0,
				'reject_unsafe_urls'  => true,
				'limit_response_size' => 100000,
				'headers' => array(
					'x-wc-zappy'   => $api_key,
					'Content-Type' => 'application/json',
					'Accept'       => 'application/json',
				),
				'body'    => wp_json_encode( $payload ),
			);

			$response = self::send_availability_request( $api_url, $request_args, $retry_timeout );

			if ( is_wp_error( $response ) ) {
				self::record_webhook_debug( $api_url, $payload, 0, '', $response->get_error_message() );
				self::record_update_history( $payload, false );
				return new WP_Error(
					'agent_zappy_request_failed',
					sprintf(
						/* translators: %s: WordPress HTTP API error message. */
						__( 'Agent Zappy API request failed: %s', 'agent-zappy' ),
						$response->get_error_message()
					)
				);
			}

			$status_code   = wp_remote_retrieve_response_code( $response );
			$response_body = wp_remote_retrieve_body( $response );
			self::record_webhook_debug( $api_url, $payload, $status_code, $response_body );

			if ( $status_code < 200 || $status_code >= 300 ) {
				self::record_update_history( $payload, false );
				return new WP_Error(
					'agent_zappy_request_rejected',
					sprintf(
						/* translators: 1: HTTP status code, 2: API response body. */
						__( 'Agent Zappy API rejected the update. HTTP %1$d. Response: %2$s', 'agent-zappy' ),
						$status_code,
						$response_body ? wp_strip_all_tags( $response_body ) : __( 'No response body.', 'agent-zappy' )
					),
					array( 'status_code' => $status_code )
				);
			}

			self::record_update_history( $payload, true );
			return true;
		}

		/**
		 * Store a simple, bounded history of product webhook deliveries.
		 * This intentionally excludes the endpoint, API key, and response body.
		 *
		 * @param array<string, mixed> $payload Request JSON payload.
		 * @param bool                 $successful Whether the endpoint accepted the update.
		 */
		private static function record_update_history( array $payload, bool $successful ): void {
			$entries = get_option( self::UPDATE_HISTORY_OPTION, array() );
			if ( ! is_array( $entries ) ) {
				$entries = array();
			}

			$entry = array(
				'time'         => current_time( 'mysql' ),
				'product_id'   => sanitize_text_field( (string) ( $payload['id'] ?? '' ) ),
				'stock_status' => sanitize_key( (string) ( $payload['stock_status'] ?? '' ) ),
				'successful'   => $successful,
			);

			if ( isset( $payload['price'] ) ) {
				$entry['price'] = (int) $payload['price'];
			}

			array_unshift( $entries, $entry );
			update_option( self::UPDATE_HISTORY_OPTION, array_slice( $entries, 0, 20 ), false );
		}

		/**
		 * Get the latest customer-friendly product update entries.
		 *
		 * @return array<int, array<string, mixed>>
		 */
		private static function get_update_history_entries(): array {
			$entries = get_option( self::UPDATE_HISTORY_OPTION, array() );
			return is_array( $entries ) ? array_slice( $entries, 0, 20 ) : array();
		}

		/**
		 * Get a friendly label for a WooCommerce stock status.
		 *
		 * @param string $stock_status WooCommerce stock status.
		 */
		private static function get_stock_status_label( string $stock_status ): string {
			$labels = array(
				'instock'     => __( 'In stock', 'agent-zappy' ),
				'outofstock'  => __( 'Out of stock', 'agent-zappy' ),
				'onbackorder' => __( 'On backorder', 'agent-zappy' ),
			);

			return $labels[ $stock_status ] ?? ucwords( str_replace( array( '-', '_' ), ' ', $stock_status ) );
		}

		/**
		 * Explain a webhook price in both API units and store-currency format.
		 *
		 * @param int $price_minor_units Price sent to the API.
		 */
		private static function get_sent_price_label( int $price_minor_units ): string {
			$decimals       = function_exists( 'wc_get_price_decimals' ) ? max( 0, (int) wc_get_price_decimals() ) : 2;
			$display_amount = $price_minor_units / pow( 10, $decimals );
			$formatted      = function_exists( 'wc_price' )
				? wp_specialchars_decode( wp_strip_all_tags( wc_price( $display_amount ) ), ENT_QUOTES )
				: number_format_i18n( $display_amount, $decimals );

			if ( 2 === $decimals ) {
				$unit = _n( 'cent', 'cents', abs( $price_minor_units ), 'agent-zappy' );
			} else {
				$unit = __( 'smallest currency units', 'agent-zappy' );
			}

			return sprintf(
				/* translators: 1: integer sent to API, 2: cents or smallest currency units, 3: formatted WooCommerce price. */
				__( 'Price sent: %1$s %2$s (%3$s)', 'agent-zappy' ),
				number_format_i18n( $price_minor_units, 0 ),
				$unit,
				$formatted
			);
		}

		/**
		 * Store a bounded history of webhook activity for administrators.
		 * The authentication header is deliberately never included.
		 *
		 * @param string               $api_url Endpoint URL.
		 * @param array<string, mixed> $payload Request JSON payload.
		 * @param int                  $status_code HTTP response status, or zero for transport errors.
		 * @param string               $response_body Response body.
		 * @param string               $error Transport error, if any.
		 */
		private static function record_webhook_debug( string $api_url, array $payload, int $status_code, string $response_body = '', string $error = '' ): void {
			$options = self::get_options();
			if ( 'yes' !== $options['debug_enabled'] ) {
				return;
			}

			$entries = get_option( self::DEBUG_LOG_OPTION, array() );
			if ( ! is_array( $entries ) ) {
				$entries = array();
			}

			array_unshift(
				$entries,
				array(
					'time'          => current_time( 'mysql' ),
					'url'           => esc_url_raw( $api_url ),
					'payload'       => $payload,
					'status_code'   => $status_code,
					'response_body' => substr( wp_strip_all_tags( $response_body ), 0, 4000 ),
					'error'         => sanitize_text_field( $error ),
				)
			);

			update_option( self::DEBUG_LOG_OPTION, array_slice( $entries, 0, 20 ), false );
		}

		/**
		 * Get recent webhook debug entries.
		 *
		 * @return array<int, array<string, mixed>>
		 */
		private static function get_webhook_debug_entries(): array {
			$entries = get_option( self::DEBUG_LOG_OPTION, array() );
			return is_array( $entries ) ? $entries : array();
		}

		/**
		 * Send the API request with one timeout retry for transient network issues.
		 *
		 * @param string               $api_url Endpoint URL.
		 * @param array<string, mixed> $request_args WP HTTP API args.
		 * @param bool                 $retry_timeout Whether to retry one timeout.
		 * @return array<string, mixed>|WP_Error
		 */
		private static function send_availability_request( string $api_url, array $request_args, bool $retry_timeout = true ) {
			$response = wp_safe_remote_post( $api_url, $request_args );

			if ( $retry_timeout && is_wp_error( $response ) && self::is_timeout_error( $response ) ) {
				$response = wp_safe_remote_post( $api_url, $request_args );
			}

			return $response;
		}

		/**
		 * Determine whether a WP error represents a request timeout.
		 *
		 * @param WP_Error $error Request error.
		 * @return bool
		 */
		private static function is_timeout_error( WP_Error $error ): bool {
			if ( 'http_request_timeout' === $error->get_error_code() ) {
				return true;
			}

			return false !== stripos( $error->get_error_message(), 'cURL error 28' );
		}

		/**
		 * Automatically sync Agent Zappy when WooCommerce stock status changes.
		 *
		 * @param int             $product_id Product or variation ID.
		 * @param string          $stock_status WooCommerce stock status.
		 * @param WC_Product|null $product Product object when WooCommerce provides it.
		 */
		public static function sync_product_stock_status( $product_id, $stock_status, $product = null ): void {
			if ( ! $product && function_exists( 'wc_get_product' ) ) {
				$product = wc_get_product( $product_id );
			}

			if ( ! $product || ! is_a( $product, 'WC_Product' ) ) {
				return;
			}

			self::sync_product_availability( $product, (string) $stock_status );
		}

		/**
		 * Sync a variation saved through the WooCommerce product-editor variation panel.
		 *
		 * @param int $variation_id WooCommerce variation ID.
		 */
		public static function sync_saved_variation( $variation_id ): void {
			$variation_id = (int) $variation_id;
			if ( isset( self::$queued_variation_syncs[ $variation_id ] ) ) {
				return;
			}

			if ( ! function_exists( 'wc_get_product' ) ) {
				return;
			}

			$variation = wc_get_product( $variation_id );
			if ( ! $variation || ! is_a( $variation, 'WC_Product_Variation' ) ) {
				return;
			}

			$options = self::get_options();
			if ( 'yes' !== $options['auto_sync'] || '' === self::get_saved_api_key() || '' === $options['api_url'] ) {
				return;
			}

			self::$queued_variation_syncs[ $variation_id ] = true;
			self::sync_product_availability( $variation, (string) $variation->get_stock_status() );
		}

		/**
		 * Sync line-item product availability after WooCommerce reduces stock for an order.
		 *
		 * This protects the purchase flow even when a store configuration/plugin reduces
		 * stock quantity to out of stock without separately firing the stock-status action.
		 *
		 * @param WC_Order $order WooCommerce order whose stock was reduced.
		 */
		public static function sync_order_stock_statuses( $order ): void {
			if ( ! $order || ! is_a( $order, 'WC_Order' ) ) {
				return;
			}

			foreach ( $order->get_items() as $item ) {
				if ( ! is_a( $item, 'WC_Order_Item_Product' ) ) {
					continue;
				}

				$product = $item->get_product();
				if ( ! $product || ! is_a( $product, 'WC_Product' ) ) {
					continue;
				}

				$stock_status = (string) $product->get_stock_status();
				if ( 'outofstock' !== $stock_status ) {
					continue;
				}

				self::sync_product_availability( $product, $stock_status );
			}
		}


		/**
		 * Sync stock status and price changes saved through a WooCommerce product object.
		 *
		 * @param WC_Product       $product Product object.
		 * @param array<int,mixed> $updated_props Updated properties.
		 */
		public static function sync_product_update( $product, array $updated_props ): void {
			if ( ! $product || ! is_a( $product, 'WC_Product' ) ) {
				return;
			}

			$options     = self::get_options();
			$updated_props = array_map( 'strval', $updated_props );
			$stock_props = array( 'stock_status', 'stock_quantity', 'manage_stock' );
			if ( 'yes' === $options['auto_sync'] && 0 < count( array_intersect( $stock_props, $updated_props ) ) ) {
				self::sync_product_availability( $product, (string) $product->get_stock_status() );
				return;
			}

			if ( 'yes' !== $options['auto_sync_price'] || '' === self::get_saved_api_key() || '' === $options['api_url'] ) {
				return;
			}

			$price_props = array( 'price', 'regular_price', 'sale_price' );
			if ( 0 === count( array_intersect( $price_props, $updated_props ) ) ) {
				return;
			}

			$product_id         = (int) $product->get_id();
			$product_identifier = self::get_product_id_for_api( $product );
			$stock_status       = (string) $product->get_stock_status();
			$price_minor_units  = self::to_price_minor_units( (float) $product->get_price() );
			self::enqueue_async_update( $product_id, $product_identifier, $stock_status, $price_minor_units );
		}

		/**
		 * Sync a WooCommerce product stock status to Agent Zappy.
		 *
		 * @param WC_Product $product WooCommerce product.
		 * @param string     $stock_status WooCommerce stock status.
		 */
		private static function sync_product_availability( $product, string $stock_status ): void {
			$options = self::get_options();
			if ( 'yes' !== $options['auto_sync'] || '' === self::get_saved_api_key() || '' === $options['api_url'] ) {
				return;
			}

			$product_id         = (int) $product->get_id();
			$product_identifier = self::get_product_id_for_api( $product );

			$price_minor_units = self::to_price_minor_units( (float) $product->get_price() );
			self::enqueue_async_update( $product_id, $product_identifier, $stock_status, $price_minor_units );
		}

		/**
		 * Queue an async availability/price update to avoid blocking user flows.
		 *
		 * @param int         $product_id Product ID.
		 * @param string      $product_identifier WooCommerce product or variation ID.
		 * @param string      $stock_status WooCommerce stock status.
		 * @param int|null    $price_minor_units Optional price in the store currency's minor units.
		 */
		private static function enqueue_async_update( int $product_id, string $product_identifier, string $stock_status, ?int $price_minor_units ): void {
			$sync_version = (int) get_post_meta( $product_id, self::SYNC_VERSION_META_KEY, true ) + 1;
			update_post_meta( $product_id, self::SYNC_VERSION_META_KEY, $sync_version );
			$args = array( $product_id, $product_identifier, $stock_status, $price_minor_units, 1, $sync_version );

			if ( self::should_deliver_immediately() ) {
				self::$pending_immediate_updates[ $product_id ] = $args;
				if ( ! self::$immediate_flush_registered ) {
					self::$immediate_flush_registered = true;
					add_action( 'shutdown', array( __CLASS__, 'flush_immediate_updates' ), 20 );
				}

				self::record_availability_sync_result( $product_id, 'info', __( 'Agent Zappy will send this update as soon as WooCommerce finishes saving.', 'agent-zappy' ) );
				return;
			}

			$scheduled = false;

			if ( function_exists( 'as_enqueue_async_action' ) ) {
				$scheduled = 0 < (int) as_enqueue_async_action( self::ASYNC_HOOK, $args, self::ASYNC_GROUP );
			} else {
				$scheduled = (bool) wp_schedule_single_event( time() + 1, self::ASYNC_HOOK, $args );
			}

			if ( ! $scheduled ) {
				self::record_availability_sync_result( $product_id, 'error', __( 'Agent Zappy could not queue the webhook update.', 'agent-zappy' ) );
				return;
			}

			self::record_availability_sync_result(
				$product_id,
				'info',
				sprintf(
					/* translators: %s: WooCommerce product ID. */
					__( 'Queued background sync for WooCommerce product ID %s.', 'agent-zappy' ),
					$product_identifier
				)
			);
		}

		/**
		 * Deliver admin and REST product saves without depending on WP-Cron.
		 * Repeated WooCommerce hooks are collapsed to the final state per product.
		 */
		public static function flush_immediate_updates(): void {
			$updates = self::$pending_immediate_updates;
			self::$pending_immediate_updates = array();

			foreach ( $updates as $update ) {
				list( $product_id, $product_identifier, $stock_status, $price_minor_units, $attempt, $sync_version ) = $update;
				if ( (int) get_post_meta( $product_id, self::SYNC_VERSION_META_KEY, true ) !== $sync_version ) {
					continue;
				}

				$result = self::send_product_update( $product_identifier, $stock_status, $price_minor_units, 5, false );
				if ( is_wp_error( $result ) ) {
					if ( self::should_retry_async_error( $result ) ) {
						self::schedule_async_retry( $product_id, $product_identifier, $stock_status, $price_minor_units, $attempt + 1, $sync_version );
						self::record_availability_sync_result( $product_id, 'info', __( 'The immediate update could not connect. Agent Zappy queued an automatic retry.', 'agent-zappy' ) );
						continue;
					}

					self::record_availability_sync_result( $product_id, 'error', $result->get_error_message() );
					continue;
				}

				self::record_availability_sync_result(
					$product_id,
					'success',
					sprintf(
						/* translators: %s: WooCommerce product or variation ID. */
						__( 'Agent Zappy sent the latest update for product ID %s.', 'agent-zappy' ),
						$product_identifier
					)
				);
			}
		}

		/**
		 * Determine whether this request should deliver immediately after saving.
		 */
		private static function should_deliver_immediately(): bool {
			if ( function_exists( 'wp_doing_cron' ) && wp_doing_cron() ) {
				return false;
			}

			return is_admin()
				|| ( function_exists( 'wp_doing_ajax' ) && wp_doing_ajax() )
				|| ( defined( 'REST_REQUEST' ) && REST_REQUEST );
		}

		/**
		 * Process a queued async availability/price update.
		 *
		 * @param int      $product_id Product ID.
		 * @param string   $product_identifier WooCommerce product or variation ID.
		 * @param string   $stock_status WooCommerce stock status.
		 * @param int|null $price_minor_units Optional price in the store currency's minor units.
		 * @param int      $sync_version Product sync version used to discard stale jobs.
		 */
		public static function process_async_update( int $product_id, string $product_identifier, string $stock_status, ?int $price_minor_units = null, int $attempt = 1, int $sync_version = 0 ): void {
			if ( 0 !== $sync_version && (int) get_post_meta( $product_id, self::SYNC_VERSION_META_KEY, true ) !== $sync_version ) {
				return;
			}

			// Jobs queued before the webhook contract used yes/no availability values.
			// Reload the product so those jobs send the current native WooCommerce state.
			if ( in_array( $stock_status, array( 'yes', 'no' ), true ) && function_exists( 'wc_get_product' ) ) {
				$product = wc_get_product( $product_id );
				if ( $product && is_a( $product, 'WC_Product' ) ) {
					$product_identifier = self::get_product_id_for_api( $product );
					$stock_status       = (string) $product->get_stock_status();
					$price_minor_units  = self::to_price_minor_units( (float) $product->get_price() );
				}
			}

			$result = self::send_product_update( $product_identifier, $stock_status, $price_minor_units );

			if ( is_wp_error( $result ) ) {
				if ( $attempt < self::ASYNC_MAX_ATTEMPTS && self::should_retry_async_error( $result ) ) {
					self::schedule_async_retry( $product_id, $product_identifier, $stock_status, $price_minor_units, $attempt + 1, $sync_version );
					/* translators: 1: Retry attempt number, 2: Maximum attempts, 3: Error message. */
					self::record_availability_sync_result( $product_id, 'info', sprintf( __( 'Background sync retry %1$d/%2$d scheduled: %3$s', 'agent-zappy' ), $attempt + 1, self::ASYNC_MAX_ATTEMPTS, $result->get_error_message() ) );
					return;
				}
				self::record_availability_sync_result( $product_id, 'error', $result->get_error_message() );
				return;
			}

			self::record_availability_sync_result(
				$product_id,
				'success',
				sprintf(
					/* translators: 1: WooCommerce product ID, 2: WooCommerce stock status. */
					__( 'Background sync sent WooCommerce product ID %1$s to Agent Zappy with stock status %2$s.', 'agent-zappy' ),
					$product_identifier,
					$stock_status
				)
			);
		}


		/**
		 * Schedule a retry for async updates with basic backoff.
		 */
		private static function schedule_async_retry( int $product_id, string $product_identifier, string $stock_status, ?int $price_minor_units, int $attempt, int $sync_version ): void {
			$delays = array( 60, 300, 900 );
			$delay  = $delays[ min( max( 0, $attempt - 2 ), count( $delays ) - 1 ) ];
			$args   = array( $product_id, $product_identifier, $stock_status, $price_minor_units, $attempt, $sync_version );

			if ( function_exists( 'as_schedule_single_action' ) ) {
				as_schedule_single_action( time() + $delay, self::ASYNC_HOOK, $args, self::ASYNC_GROUP );
				return;
			}

			wp_schedule_single_event( time() + $delay, self::ASYNC_HOOK, $args );
		}

		/**
		 * Determine whether async errors should be retried.
		 */
		private static function should_retry_async_error( WP_Error $error ): bool {
			if ( self::is_timeout_error( $error ) ) {
				return true;
			}

			if ( 'agent_zappy_request_failed' === $error->get_error_code() ) {
				return true;
			}

			$data        = $error->get_error_data();
			$status_code = is_array( $data ) && isset( $data['status_code'] ) ? (int) $data['status_code'] : 0;
			return 429 === $status_code || $status_code >= 500;
		}

		/**
		 * Get queued async update count for health display.
		 */
		private static function get_async_queue_count(): int {
			if ( function_exists( 'as_get_scheduled_actions' ) ) {
				$ids = as_get_scheduled_actions( array( 'hook' => self::ASYNC_HOOK, 'group' => self::ASYNC_GROUP, 'status' => 'pending', 'per_page' => 100 ) );
				return is_array( $ids ) ? count( $ids ) : 0;
			}

			$cron = _get_cron_array();
			if ( ! is_array( $cron ) ) {
				return 0;
			}
			$count = 0;
			foreach ( $cron as $events ) {
				if ( isset( $events[ self::ASYNC_HOOK ] ) ) {
					$count += count( $events[ self::ASYNC_HOOK ] );
				}
			}
			return $count;
		}

		/**
		 * Get the WooCommerce product ID to send to Agent Zappy.
		 *
		 * @param WC_Product $product WooCommerce product.
		 * @return string
		 */
		private static function get_product_id_for_api( $product ): string {
			return (string) $product->get_id();
		}

		/**
		 * Convert a decimal WooCommerce price to the store currency's minor units.
		 *
		 * @param float $price Price value.
		 * @return int
		 */
		private static function to_price_minor_units( float $price ): int {
			$decimals = function_exists( 'wc_get_price_decimals' ) ? (int) wc_get_price_decimals() : 2;
			return (int) round( $price * pow( 10, max( 0, $decimals ) ) );
		}

		/**
		 * Store the latest Agent Zappy sync result on the WooCommerce product.
		 *
		 * @param int    $product_id Product ID.
		 * @param string $status Sync status.
		 * @param string $message Sync message.
		 */
		private static function record_availability_sync_result( int $product_id, string $status, string $message ): void {
			update_post_meta(
				$product_id,
				self::SYNC_META_KEY,
				array(
					'status'  => $status,
					'message' => $message,
					'time'    => current_time( 'mysql' ),
				)
			);
		}

		/**
		 * Add an admin message for the Agent Zappy settings screen.
		 *
		 * @param string $message Message text.
		 * @param string $type Message type.
		 */
		private static function add_admin_message( string $message, string $type ): void {
			add_settings_error(
				'agent_zappy_messages',
				'agent_zappy_message',
				$message,
				$type
			);
		}

		/**
		 * Add a settings link on the Plugins screen.
		 *
		 * @param array<int, string> $links Existing plugin links.
		 * @return array<int, string>
		 */
		public static function add_settings_link( array $links ): array {
			$settings_url = admin_url( 'admin.php?page=' . self::MENU_SLUG );

			array_unshift(
				$links,
				sprintf(
					'<a href="%1$s">%2$s</a>',
					esc_url( $settings_url ),
					esc_html__( 'Settings', 'agent-zappy' )
				)
			);

			return $links;
		}

		/**
		 * Enqueue front-end styles only when the widget can render.
		 */
		public static function enqueue_assets(): void {
			$options = self::get_options();
			if ( empty( $options['phone'] ) || is_admin() ) {
				return;
			}

			wp_enqueue_style(
				'agent-zappy',
				self::get_asset_url( 'css/widget.css' ),
				array(),
				self::VERSION
			);
		}


		/**
		 * Enqueue Agent Zappy admin styles on plugin screens.
		 *
		 * @param string $hook_suffix Current admin page hook suffix.
		 */
		public static function enqueue_admin_assets( string $hook_suffix ): void {
			$screen = function_exists( 'get_current_screen' ) ? get_current_screen() : null;
			$is_agent_zappy_screen = 'toplevel_page_' . self::MENU_SLUG === $hook_suffix;
			$is_product_screen     = $screen && 'product' === $screen->post_type;

			if ( ! $is_agent_zappy_screen && ! $is_product_screen ) {
				return;
			}

			wp_enqueue_style(
				'agent-zappy-admin',
				self::get_asset_url( 'css/admin.css' ),
				array(),
				self::VERSION
			);

			if ( $is_agent_zappy_screen ) {
				wp_enqueue_script(
					'agent-zappy-admin',
					self::get_asset_url( 'js/admin.js' ),
					array(),
					self::VERSION,
					true
				);
			}
		}

		/**
		 * Render the floating WhatsApp widget in the site footer.
		 */
		public static function render_widget(): void {
			$options = self::get_options();
			$phone   = $options['phone'];

			if ( empty( $phone ) || is_admin() ) {
				return;
			}

			$position = array_key_exists( $options['position'], self::get_positions() ) ? $options['position'] : 'bottom-right';
			$wa_url   = 'https://wa.me/' . rawurlencode( $phone );
			$message  = $options['message'];

			if ( function_exists( 'is_product' ) && is_product() && function_exists( 'wc_get_product' ) ) {
				$product = wc_get_product( get_queried_object_id() );
				if ( $product ) {
					$product_name = sanitize_text_field( wp_strip_all_tags( $product->get_name() ) );
					if ( '' !== $product_name ) {
						$message = sprintf(
							/* translators: %s: WooCommerce product name. */
							__( 'Hi, I need some info on %s', 'agent-zappy' ),
							$product_name
						);
					}
				}
			}

			if ( '' !== $message ) {
				$wa_url = add_query_arg( 'text', $message, $wa_url );
			}
			?>
			<a class="agent-zappy-whatsapp-widget agent-zappy-whatsapp-widget--<?php echo esc_attr( $position ); ?>" href="<?php echo esc_url( $wa_url ); ?>" target="_blank" rel="noopener noreferrer" aria-label="<?php esc_attr_e( 'Chat with us on WhatsApp', 'agent-zappy' ); ?>">
				<span class="agent-zappy-whatsapp-widget__icon" aria-hidden="true">
					<svg viewBox="0 0 32 32" focusable="false" role="img">
						<path d="M16.02 3.2c-7.02 0-12.72 5.66-12.72 12.63 0 2.23.59 4.41 1.7 6.33l-1.8 6.64 6.82-1.78a12.83 12.83 0 0 0 6 1.52c7.02 0 12.72-5.66 12.72-12.63S23.04 3.2 16.02 3.2Zm0 23.19c-1.86 0-3.68-.5-5.27-1.44l-.38-.23-4.05 1.06 1.08-3.93-.25-.4a10.42 10.42 0 0 1-1.62-5.62c0-5.78 4.71-10.48 10.49-10.48s10.49 4.7 10.49 10.48-4.71 10.56-10.49 10.56Zm5.75-7.86c-.31-.16-1.86-.91-2.15-1.02-.29-.1-.5-.16-.71.16-.21.31-.81 1.02-.99 1.23-.18.21-.36.24-.68.08-.31-.16-1.32-.48-2.52-1.54-.93-.82-1.56-1.84-1.74-2.15-.18-.31-.02-.48.14-.64.14-.14.31-.36.47-.55.16-.18.21-.31.31-.52.1-.21.05-.39-.03-.55-.08-.16-.71-1.7-.97-2.33-.26-.62-.52-.53-.71-.54l-.6-.01c-.21 0-.55.08-.84.39-.29.31-1.1 1.07-1.1 2.61s1.13 3.03 1.29 3.24c.16.21 2.23 3.38 5.39 4.74.75.32 1.34.51 1.8.65.76.24 1.45.21 1.99.13.61-.09 1.86-.76 2.12-1.49.26-.73.26-1.36.18-1.49-.08-.13-.29-.21-.6-.37Z" />
					</svg>
				</span>
				<span class="screen-reader-text"><?php esc_html_e( 'Open WhatsApp chat', 'agent-zappy' ); ?></span>
			</a>
			<?php
		}

		/**
		 * Render the plugin settings page.
		 */
		public static function render_settings_page(): void {
			if ( ! current_user_can( 'manage_options' ) ) {
				return;
			}

			$options        = self::get_options();
			$positions      = self::get_positions();
			$queue_count    = self::get_async_queue_count();
			$update_history = self::get_update_history_entries();
			$debug_entries  = self::get_webhook_debug_entries();
			$has_api_key    = '' !== self::get_saved_api_key();
			?>
			<div class="wrap agent-zappy-admin-wrap">
				<div class="agent-zappy-hero">
					<div>
						<p class="agent-zappy-eyebrow"><?php esc_html_e( 'WooCommerce sales automation', 'agent-zappy' ); ?></p>
					<h1><?php esc_html_e( 'Agent Zappy — Your WooCommerce Sales Assistant', 'agent-zappy' ); ?></h1>
						<p class="agent-zappy-hero__text"><?php esc_html_e( 'Turn product interest into conversations and keep Agent Zappy in sync with your WooCommerce store.', 'agent-zappy' ); ?></p>
					</div>
					<div class="agent-zappy-status-card" aria-label="<?php esc_attr_e( 'Setup status', 'agent-zappy' ); ?>">
						<span class="agent-zappy-status-card__label"><?php esc_html_e( 'Your setup at a glance', 'agent-zappy' ); ?></span>
						<ul>
						<li class="<?php echo esc_attr( empty( $options['phone'] ) ? 'is-missing' : 'is-complete' ); ?>"><?php esc_html_e( 'WhatsApp number', 'agent-zappy' ); ?></li>
						<li class="<?php echo esc_attr( $has_api_key ? 'is-complete' : 'is-missing' ); ?>"><?php echo esc_html( $has_api_key ? __( 'Agent Zappy connected', 'agent-zappy' ) : __( 'API key required', 'agent-zappy' ) ); ?></li>
						<li class="<?php echo esc_attr( empty( $options['api_url'] ) ? 'is-missing' : 'is-complete' ); ?>"><?php esc_html_e( 'Product connection ready', 'agent-zappy' ); ?></li>
						<li class="<?php echo esc_attr( 'yes' === $options['auto_sync_price'] ? 'is-complete' : 'is-missing' ); ?>"><?php esc_html_e( 'Automatic price updates', 'agent-zappy' ); ?></li>
							<li class="is-complete"><?php esc_html_e( 'WhatsApp chat location selected', 'agent-zappy' ); ?></li>
						<li class="<?php echo esc_attr( $queue_count > 20 ? 'is-missing' : 'is-complete' ); ?>"><?php 
/* translators: %d: Number of queued product updates. */
echo esc_html( sprintf( __( 'Product updates waiting: %d', 'agent-zappy' ), $queue_count ) ); ?></li>
						</ul>
					</div>
				</div>

				<?php settings_errors( 'agent_zappy_messages' ); ?>

				<div class="agent-zappy-layout">
					<div class="agent-zappy-main-column">
						<details class="agent-zappy-settings-panel">
							<summary class="agent-zappy-section-intro">
								<span class="agent-zappy-section-number">1</span>
								<span class="agent-zappy-section-copy">
									<strong><?php esc_html_e( 'WhatsApp customer chat', 'agent-zappy' ); ?></strong>
									<small><?php esc_html_e( 'Let customers message your business directly from your store.', 'agent-zappy' ); ?></small>
								</span>
								<span class="agent-zappy-section-action">
									<?php echo esc_html( empty( $options['phone'] ) ? __( 'Set up', 'agent-zappy' ) : __( 'Edit', 'agent-zappy' ) ); ?>
									<span class="dashicons dashicons-arrow-down-alt2" aria-hidden="true"></span>
								</span>
							</summary>

							<form method="post" action="options.php" class="agent-zappy-card agent-zappy-card--primary">
							<?php settings_fields( self::MENU_SLUG ); ?>
							<input type="hidden" name="<?php echo esc_attr( self::OPTION_KEY ); ?>[auto_sync]" value="<?php echo esc_attr( $options['auto_sync'] ); ?>" />
							<div class="agent-zappy-card__header">
								<div>
									<p class="agent-zappy-card__eyebrow"><?php esc_html_e( 'What customers will see', 'agent-zappy' ); ?></p>
									<h2><?php esc_html_e( 'A WhatsApp button on your store', 'agent-zappy' ); ?></h2>
									<p><?php esc_html_e( 'Customers can tap it to start a conversation with your business.', 'agent-zappy' ); ?></p>
								</div>
								<span class="agent-zappy-feature-icon dashicons dashicons-whatsapp" aria-hidden="true"></span>
							</div>

							<div class="agent-zappy-field-grid">
								<div class="agent-zappy-field">
									<label for="agent-zappy-whatsapp-phone"><?php esc_html_e( 'WhatsApp number', 'agent-zappy' ); ?></label>
									<input type="tel" id="agent-zappy-whatsapp-phone" name="<?php echo esc_attr( self::OPTION_KEY ); ?>[phone]" value="<?php echo esc_attr( $options['phone'] ); ?>" placeholder="15551234567" />
									<p><?php esc_html_e( 'Include the country code and use numbers only. Example: 15551234567.', 'agent-zappy' ); ?></p>
								</div>

								<div class="agent-zappy-field">
									<label for="agent-zappy-whatsapp-position"><?php esc_html_e( 'Button location', 'agent-zappy' ); ?></label>
									<select id="agent-zappy-whatsapp-position" name="<?php echo esc_attr( self::OPTION_KEY ); ?>[position]">
										<?php foreach ( $positions as $value => $label ) : ?>
											<option value="<?php echo esc_attr( $value ); ?>" <?php selected( $options['position'], $value ); ?>><?php echo esc_html( $label ); ?></option>
										<?php endforeach; ?>
									</select>
									<p><?php esc_html_e( 'Choose where the WhatsApp button appears on your store.', 'agent-zappy' ); ?></p>
								</div>
							</div>

							<div class="agent-zappy-field">
								<label for="agent-zappy-whatsapp-message"><?php esc_html_e( 'Message customers see', 'agent-zappy' ); ?></label>
								<textarea rows="4" id="agent-zappy-whatsapp-message" name="<?php echo esc_attr( self::OPTION_KEY ); ?>[message]" placeholder="<?php esc_attr_e( 'Hi, I need help with an order.', 'agent-zappy' ); ?>"><?php echo esc_textarea( $options['message'] ); ?></textarea>
								<p><?php esc_html_e( 'This message appears when WhatsApp opens. On a product page, Agent Zappy automatically mentions that product.', 'agent-zappy' ); ?></p>
							</div>

							<div class="agent-zappy-card__footer">
								<?php submit_button( __( 'Save WhatsApp settings', 'agent-zappy' ), 'primary', 'submit', false ); ?>
							</div>
							</form>
						</details>

						<div class="agent-zappy-section-intro agent-zappy-section-intro--sync">
							<span class="agent-zappy-section-number">2</span>
							<div>
								<h2><?php esc_html_e( 'Product auto-sync', 'agent-zappy' ); ?></h2>
								<p><?php esc_html_e( 'Keep product and variation prices and stock status updated automatically.', 'agent-zappy' ); ?></p>
							</div>
						</div>

						<form method="post" action="options.php" class="agent-zappy-card agent-zappy-card--primary">
							<?php settings_fields( self::MENU_SLUG ); ?>
							<input type="hidden" name="<?php echo esc_attr( self::OPTION_KEY ); ?>[phone]" value="<?php echo esc_attr( $options['phone'] ); ?>" />
							<input type="hidden" name="<?php echo esc_attr( self::OPTION_KEY ); ?>[position]" value="<?php echo esc_attr( $options['position'] ); ?>" />
							<input type="hidden" name="<?php echo esc_attr( self::OPTION_KEY ); ?>[message]" value="<?php echo esc_attr( $options['message'] ); ?>" />
							<div class="agent-zappy-card__header">
								<div>
									<p class="agent-zappy-card__eyebrow"><?php esc_html_e( 'Secure connection', 'agent-zappy' ); ?></p>
									<h2><?php echo esc_html( $has_api_key ? __( 'Agent Zappy is connected', 'agent-zappy' ) : __( 'Connect your WooCommerce products', 'agent-zappy' ) ); ?></h2>
									<p><?php echo esc_html( $has_api_key ? __( 'Your saved API key will securely authenticate product updates.', 'agent-zappy' ) : __( 'Enter the API key supplied by Agent Zappy to enable product updates.', 'agent-zappy' ) ); ?></p>
								</div>
								<span class="agent-zappy-feature-icon agent-zappy-feature-icon--sync dashicons dashicons-update" aria-hidden="true"></span>
							</div>
					<div class="agent-zappy-connection-state <?php echo esc_attr( $has_api_key ? 'is-connected' : 'is-required' ); ?>">
						<span class="dashicons <?php echo esc_attr( $has_api_key ? 'dashicons-yes-alt' : 'dashicons-lock' ); ?>" aria-hidden="true"></span>
								<div>
									<strong><?php echo esc_html( $has_api_key ? __( 'Connection ready', 'agent-zappy' ) : __( 'API key required', 'agent-zappy' ) ); ?></strong>
									<p><?php echo esc_html( $has_api_key ? __( 'Automatic product and variation updates can now be sent to Agent Zappy.', 'agent-zappy' ) : __( 'No product or variation details will be sent until an API key is saved.', 'agent-zappy' ) ); ?></p>
								</div>
							</div>
							<h3 class="agent-zappy-subsection-title"><?php esc_html_e( 'Connection details', 'agent-zappy' ); ?></h3>
							<div class="agent-zappy-field">
								<label for="agent-zappy-api-key">
									<?php esc_html_e( 'Agent Zappy API key', 'agent-zappy' ); ?>
							<span class="agent-zappy-key-badge <?php echo esc_attr( $has_api_key ? 'is-saved' : 'is-required' ); ?>"><?php echo esc_html( $has_api_key ? __( 'Saved', 'agent-zappy' ) : __( 'Required', 'agent-zappy' ) ); ?></span>
								</label>
								<div class="agent-zappy-api-key-control">
							<input type="password" id="agent-zappy-api-key" name="<?php echo esc_attr( self::OPTION_KEY ); ?>[api_key]" value="<?php echo $has_api_key ? esc_attr( self::API_KEY_MASK ) : ''; ?>" autocomplete="new-password" placeholder="<?php esc_attr_e( 'Paste your API key', 'agent-zappy' ); ?>"<?php if ( $has_api_key ) : ?> data-agent-zappy-masked="true"<?php endif; ?> />
									<?php submit_button( __( 'Save API key', 'agent-zappy' ), 'primary', 'agent_zappy_save_api_key', false ); ?>
								</div>
								<p><?php echo esc_html( $has_api_key ? __( 'Your key is saved and hidden for security. Click the masked field only when you need to replace it.', 'agent-zappy' ) : __( 'Paste the API key supplied by Agent Zappy, then save it to enable product updates.', 'agent-zappy' ) ); ?></p>
							</div>

							<details class="agent-zappy-advanced-settings">
								<summary><?php esc_html_e( 'Advanced: Change webhook URL', 'agent-zappy' ); ?></summary>
								<div class="agent-zappy-advanced-settings__content">
									<div class="agent-zappy-field">
										<label for="agent-zappy-api-url"><?php esc_html_e( 'Product webhook URL', 'agent-zappy' ); ?></label>
										<input type="url" id="agent-zappy-api-url" name="<?php echo esc_attr( self::OPTION_KEY ); ?>[api_url]" value="<?php echo esc_attr( $options['api_url'] ); ?>" placeholder="<?php echo esc_attr( self::API_URL ); ?>" />
										<p><?php esc_html_e( 'The production webhook is selected automatically. Change this only when instructed by Agent Zappy support.', 'agent-zappy' ); ?></p>
									</div>
								</div>
							</details>

							<h3 class="agent-zappy-subsection-title agent-zappy-subsection-title--automation"><?php esc_html_e( 'Automatic updates', 'agent-zappy' ); ?></h3>

							<div class="agent-zappy-field agent-zappy-toggle-field">
								<input type="hidden" name="<?php echo esc_attr( self::OPTION_KEY ); ?>[auto_sync]" value="no" />
								<label for="agent-zappy-auto-sync">
									<input type="checkbox" id="agent-zappy-auto-sync" name="<?php echo esc_attr( self::OPTION_KEY ); ?>[auto_sync]" value="yes" <?php checked( $options['auto_sync'], 'yes' ); ?> />
									<?php esc_html_e( 'Automatically sync WooCommerce stock changes in real time', 'agent-zappy' ); ?>
								</label>
								<p><?php esc_html_e( 'When a WooCommerce product stock status changes, Agent Zappy receives the native stock status such as instock, outofstock, or onbackorder.', 'agent-zappy' ); ?></p>
							</div>

							<div class="agent-zappy-field agent-zappy-toggle-field">
								<input type="hidden" name="<?php echo esc_attr( self::OPTION_KEY ); ?>[auto_sync_price]" value="no" />
								<label for="agent-zappy-auto-sync-price">
									<input type="checkbox" id="agent-zappy-auto-sync-price" name="<?php echo esc_attr( self::OPTION_KEY ); ?>[auto_sync_price]" value="yes" <?php checked( $options['auto_sync_price'], 'yes' ); ?> />
									<?php esc_html_e( 'Automatically sync WooCommerce price changes', 'agent-zappy' ); ?>
								</label>
								<p><?php esc_html_e( 'When a product price changes, Agent Zappy receives id, stock_status, and price in the smallest unit configured for this WooCommerce store.', 'agent-zappy' ); ?></p>
							</div>

							<div class="agent-zappy-field agent-zappy-toggle-field">
								<input type="hidden" name="<?php echo esc_attr( self::OPTION_KEY ); ?>[debug_enabled]" value="no" />
								<label for="agent-zappy-debug-enabled">
									<input type="checkbox" id="agent-zappy-debug-enabled" name="<?php echo esc_attr( self::OPTION_KEY ); ?>[debug_enabled]" value="yes" <?php checked( $options['debug_enabled'], 'yes' ); ?> />
									<?php esc_html_e( 'Enable webhook debug history', 'agent-zappy' ); ?>
								</label>
								<p><?php esc_html_e( 'Enable temporarily while troubleshooting. Disable it on production sites after testing.', 'agent-zappy' ); ?></p>
							</div>
							<div class="agent-zappy-card__footer">
								<?php submit_button( $has_api_key ? __( 'Save auto-sync settings', 'agent-zappy' ) : __( 'Connect Agent Zappy', 'agent-zappy' ), $has_api_key ? 'secondary' : 'primary', 'submit', false ); ?>
							</div>
						</form>
					</div>

					<aside class="agent-zappy-side-column">
						<div class="agent-zappy-card agent-zappy-card--guide">
							<p class="agent-zappy-card__eyebrow"><?php esc_html_e( 'Quick start', 'agent-zappy' ); ?></p>
							<h2><?php esc_html_e( 'Ready in three steps', 'agent-zappy' ); ?></h2>
							<ol class="agent-zappy-steps">
								<li><?php esc_html_e( 'Add your WhatsApp number for customer conversations.', 'agent-zappy' ); ?></li>
								<li><?php esc_html_e( 'Connect Agent Zappy using the API key you received.', 'agent-zappy' ); ?></li>
								<li><?php esc_html_e( 'Review recent product updates while auto-sync takes care of the rest.', 'agent-zappy' ); ?></li>
							</ol>
						</div>

						<div class="agent-zappy-card agent-zappy-card--updates">
							<div class="agent-zappy-card__header agent-zappy-card__header--compact">
								<div>
									<h2><?php esc_html_e( 'Recent product updates', 'agent-zappy' ); ?></h2>
									<p><?php esc_html_e( 'The latest 20 product and variation updates sent to Agent Zappy.', 'agent-zappy' ); ?></p>
								</div>
							</div>
							<?php if ( empty( $update_history ) ) : ?>
								<div class="agent-zappy-update-empty">
									<span class="dashicons dashicons-update" aria-hidden="true"></span>
									<p><?php esc_html_e( 'No updates yet. New product and variation updates will appear here automatically.', 'agent-zappy' ); ?></p>
								</div>
							<?php else : ?>
								<div class="agent-zappy-update-history">
									<?php foreach ( $update_history as $entry ) : ?>
										<?php
										$product_id   = sanitize_text_field( (string) ( $entry['product_id'] ?? '' ) );
										$stock_status = sanitize_key( (string) ( $entry['stock_status'] ?? '' ) );
										$successful   = ! empty( $entry['successful'] );
										$sent_time    = ! empty( $entry['time'] ) ? mysql2date( get_option( 'date_format' ) . ' ' . get_option( 'time_format' ), (string) $entry['time'] ) : '';
										?>
										<div class="agent-zappy-update-item">
											<div class="agent-zappy-update-item__header">
												<strong><?php 
/* translators: %s: WooCommerce product or variation ID. */
echo esc_html( sprintf( __( 'Product #%s', 'agent-zappy' ), $product_id ) ); ?></strong>
								<span class="agent-zappy-update-status <?php echo esc_attr( $successful ? 'is-success' : 'is-failed' ); ?>">
													<?php echo esc_html( $successful ? __( 'Sent', 'agent-zappy' ) : __( 'Failed', 'agent-zappy' ) ); ?>
												</span>
											</div>
											<p class="agent-zappy-update-time"><?php echo esc_html( $sent_time ); ?></p>
											<p class="agent-zappy-update-details">
												<span><?php 
/* translators: %s: Translated stock-status label. */
echo esc_html( sprintf( __( 'Stock: %s', 'agent-zappy' ), self::get_stock_status_label( $stock_status ) ) ); ?></span>
												<span><?php echo isset( $entry['price'] ) ? esc_html( self::get_sent_price_label( (int) $entry['price'] ) ) : esc_html__( 'Price: Not sent', 'agent-zappy' ); ?></span>
											</p>
										</div>
									<?php endforeach; ?>
								</div>
							<?php endif; ?>
							<form method="post" action="<?php echo esc_url( admin_url( 'admin.php?page=' . self::MENU_SLUG ) ); ?>" class="agent-zappy-update-clear">
								<?php wp_nonce_field( 'agent_zappy_clear_update_history', 'agent_zappy_clear_update_history_nonce' ); ?>
								<?php submit_button( __( 'Clear update history', 'agent-zappy' ), 'secondary', 'agent_zappy_clear_update_history', false ); ?>
							</form>
						</div>

						<div class="agent-zappy-card agent-zappy-card--technical">
							<div class="agent-zappy-card__header agent-zappy-card__header--compact">
								<div>
									<p class="agent-zappy-card__eyebrow"><?php esc_html_e( 'Advanced', 'agent-zappy' ); ?></p>
									<h2><?php esc_html_e( 'Webhook diagnostics', 'agent-zappy' ); ?></h2>
									<p><?php esc_html_e( 'Technical request and response details for troubleshooting. Your API key is never shown or stored here.', 'agent-zappy' ); ?></p>
								</div>
							</div>
							<?php if ( 'yes' !== $options['debug_enabled'] ) : ?>
								<p><strong><?php esc_html_e( 'Debug history is disabled.', 'agent-zappy' ); ?></strong> <?php esc_html_e( 'Enable it in webhook settings before reproducing an issue.', 'agent-zappy' ); ?></p>
							<?php endif; ?>
							<?php if ( empty( $debug_entries ) ) : ?>
								<p><?php esc_html_e( 'No requests have been recorded yet. Update a product or variation to begin.', 'agent-zappy' ); ?></p>
							<?php else : ?>
								<?php foreach ( $debug_entries as $entry ) : ?>
									<?php
									$status_code = isset( $entry['status_code'] ) ? (int) $entry['status_code'] : 0;
									/* translators: %d: HTTP response status code. */
									$status_label = $status_code ? sprintf( __( 'HTTP %d', 'agent-zappy' ), $status_code ) : __( 'Transport error', 'agent-zappy' );
									$payload = isset( $entry['payload'] ) && is_array( $entry['payload'] ) ? wp_json_encode( $entry['payload'], JSON_PRETTY_PRINT ) : '{}';
									?>
									<details class="agent-zappy-debug-entry">
										<summary><?php echo esc_html( sprintf( '%1$s — %2$s', $entry['time'] ?? '', $status_label ) ); ?></summary>
										<p><strong><?php esc_html_e( 'URL:', 'agent-zappy' ); ?></strong> <?php echo esc_html( $entry['url'] ?? '' ); ?></p>
										<p><strong><?php esc_html_e( 'Request body:', 'agent-zappy' ); ?></strong></p>
										<pre><?php echo esc_html( $payload ); ?></pre>
										<?php if ( ! empty( $entry['error'] ) ) : ?>
											<p><strong><?php esc_html_e( 'Error:', 'agent-zappy' ); ?></strong> <?php echo esc_html( $entry['error'] ); ?></p>
										<?php endif; ?>
										<p><strong><?php esc_html_e( 'Response body:', 'agent-zappy' ); ?></strong></p>
										<pre><?php echo esc_html( $entry['response_body'] ?? '' ); ?></pre>
									</details>
								<?php endforeach; ?>
							<?php endif; ?>
							<form method="post" action="<?php echo esc_url( admin_url( 'admin.php?page=' . self::MENU_SLUG ) ); ?>">
								<?php wp_nonce_field( 'agent_zappy_clear_webhook_debug', 'agent_zappy_clear_webhook_debug_nonce' ); ?>
								<?php submit_button( __( 'Clear debug history', 'agent-zappy' ), 'secondary', 'agent_zappy_clear_webhook_debug', false ); ?>
							</form>
						</div>
					</aside>
				</div>
			</div>
			<?php
		}

		/**
		 * Get the root plugin file used by WordPress for activation.
		 */
		private static function get_plugin_file(): string {
			if ( defined( 'AGENT_ZAPPY_PLUGIN_FILE' ) ) {
				return AGENT_ZAPPY_PLUGIN_FILE;
			}

			return __FILE__;
		}

		/**
		 * Resolve an asset URL in both the installable package and repository layout.
		 *
		 * @param string $relative_path Path inside the assets directory.
		 */
		private static function get_asset_url( string $relative_path ): string {
			$plugin_file = self::get_plugin_file();
			$asset_path  = trailingslashit( dirname( $plugin_file ) ) . 'assets/' . ltrim( $relative_path, '/' );

			if ( file_exists( $asset_path ) ) {
				return plugins_url( 'assets/' . ltrim( $relative_path, '/' ), $plugin_file );
			}

			return plugins_url( 'agent-zappy/assets/' . ltrim( $relative_path, '/' ), $plugin_file );
		}

		/**
		 * Get saved options merged with defaults.
		 *
		 * @return array<string, string>
		 */
		private static function get_options(): array {
			$options = get_option( self::OPTION_KEY, array() );
			if ( ! is_array( $options ) ) {
				$options = array();
			}

			return wp_parse_args( $options, self::get_default_options() );
		}

		/**
		 * Return only the API key explicitly stored by the current settings UI.
		 * Display masks and legacy credential fields are never accepted.
		 */
		private static function get_saved_api_key(): string {
			$options = get_option( self::OPTION_KEY, array() );
			if ( ! is_array( $options ) || ! isset( $options['api_key'] ) ) {
				return '';
			}

			$api_key = trim( (string) $options['api_key'] );
			return self::API_KEY_MASK === $api_key ? '' : $api_key;
		}

		/**
		 * Default plugin options.
		 *
		 * @return array<string, string>
		 */
		private static function get_default_options(): array {
			return array(
				'phone'    => '',
				'position' => 'bottom-right',
				'message'  => '',
				'api_key' => '',
				'api_url'   => self::API_URL,
				'auto_sync' => 'yes',
				'auto_sync_price' => 'yes',
				'debug_enabled' => 'no',
			);
		}

		/**
		 * Available widget positions.
		 *
		 * @return array<string, string>
		 */
		private static function get_positions(): array {
			return array(
				'bottom-right' => __( 'Bottom right', 'agent-zappy' ),
				'bottom-left'  => __( 'Bottom left', 'agent-zappy' ),
				'top-right'    => __( 'Top right', 'agent-zappy' ),
				'top-left'     => __( 'Top left', 'agent-zappy' ),
			);
		}
	}

	if ( ! class_exists( 'ZA_WooCommerce_WhatsApp_Widget', false ) ) {
		class_alias( 'Agent_Zappy_Plugin', 'ZA_WooCommerce_WhatsApp_Widget' );
	}

	Agent_Zappy_Plugin::init();
	register_deactivation_hook( AGENT_ZAPPY_PLUGIN_FILE, array( 'Agent_Zappy_Plugin', 'deactivate' ) );
}