<?php
/**
 * Settings → OSSEngine admin screen.
 *
 * Shows connection status, connected website, tracking state, WooCommerce
 * status, connect/reconnect/disconnect actions, and an analytics link.
 * All actions require manage_options + nonces.
 *
 * @package OSSEngine
 */

defined( 'ABSPATH' ) || exit;

class OSSEngine_Settings {

	const PAGE_SLUG         = 'ossengine-analytics-connector';
	const ACTION_DISCONNECT = 'ossengine_disconnect';
	const ACTION_REFRESH    = 'ossengine_refresh';
	const ACTION_SAVE       = 'ossengine_save';

	/**
	 * @var OSSEngine_Options
	 */
	private $options;

	/**
	 * @var OSSEngine_Api
	 */
	private $api;

	/**
	 * @var OSSEngine_Auth
	 */
	private $auth;

	/**
	 * @var OSSEngine_BYO
	 */
	private $byo;

	/**
	 * @param OSSEngine_Options $options Options.
	 * @param OSSEngine_Api     $api     API client.
	 * @param OSSEngine_Auth    $auth    Auth flow.
	 * @param OSSEngine_BYO     $byo     BYO mode.
	 */
	public function __construct( OSSEngine_Options $options, OSSEngine_Api $api, OSSEngine_Auth $auth, OSSEngine_BYO $byo ) {
		$this->options = $options;
		$this->api     = $api;
		$this->auth    = $auth;
		$this->byo     = $byo;
	}

	/**
	 * Register menu, actions, notices, and cron refresh.
	 */
	public function register() {
		add_action( 'admin_menu', array( $this, 'add_menu' ) );
		add_action( 'admin_enqueue_scripts', array( $this, 'enqueue_admin_assets' ) );
		add_action( 'admin_post_' . self::ACTION_DISCONNECT, array( $this, 'handle_disconnect' ) );
		add_action( 'admin_post_' . self::ACTION_REFRESH, array( $this, 'handle_refresh' ) );
		add_action( 'admin_post_' . self::ACTION_SAVE, array( $this, 'handle_save' ) );
		add_action( 'admin_notices', array( $this, 'render_notice' ) );
		add_action( OSSEngine_Options::CRON_HOOK, array( $this, 'cron_refresh' ) );
	}

	/**
	 * Add Settings → OSSEngine.
	 */
	public function add_menu() {
		add_options_page(
			__( 'OSSEngine Analytics Connector', 'ossengine-analytics-connector' ),
			__( 'OSSEngine Analytics', 'ossengine-analytics-connector' ),
			'manage_options',
			self::PAGE_SLUG,
			array( $this, 'render' )
		);
	}

	/**
	 * Enqueue the settings-screen script + scoped styles (plugin screen only).
	 *
	 * @param string $hook_suffix Current admin page hook suffix.
	 */
	public function enqueue_admin_assets( $hook_suffix ) {
		if ( 'settings_page_' . self::PAGE_SLUG !== $hook_suffix ) {
			return;
		}
		wp_register_script(
			'ossengine-analytics-connector-admin',
			plugins_url( 'assets/js/ossengine-admin.js', OSSENGINE_PLUGIN_FILE ),
			array(),
			OSSENGINE_VERSION,
			true
		);
		wp_enqueue_script( 'ossengine-analytics-connector-admin' );
		wp_register_style(
			'ossengine-analytics-connector-admin',
			false,
			array(),
			OSSENGINE_VERSION
		);
		wp_enqueue_style( 'ossengine-analytics-connector-admin' );
		wp_add_inline_style(
			'ossengine-analytics-connector-admin',
			'.ossengine-analytics-connector-lead{max-width:720px}.ossengine-analytics-connector-info{margin:12px 0;padding:12px 16px}.ossengine-analytics-connector-list{list-style:disc;margin:8px 0 8px 20px}.ossengine-analytics-connector-ordered{margin:8px 0 8px 20px}.ossengine-analytics-connector-errorbox{margin:12px 0}'
		);
	}

	/**
	 * Disconnect: permanently delete the Umami website and its analytics data,
	 * revoke server-side, and clear the local token.
	 *
	 * Requires the admin to have typed exactly "DELETE" in the confirmation
	 * form; anything else aborts before any request is sent.
	 */
	public function handle_disconnect() {
		$this->require_capability();
		check_admin_referer( self::ACTION_DISCONNECT );

		$confirmation = isset( $_POST['confirmation'] ) ? sanitize_text_field( wp_unslash( $_POST['confirmation'] ) ) : ''; // phpcs:ignore WordPress.Security.NonceVerification.Missing -- verified by check_admin_referer() above.
		if ( 'DELETE' !== $confirmation ) {
			$this->options->set_notice( 'error', __( 'Type DELETE to confirm permanent deletion. Nothing was disconnected.', 'ossengine-analytics-connector' ) );
			$this->redirect();
		}

		$connection = $this->options->get_connection();
		$token      = $this->options->get_site_token();
		if ( '' !== $token && '' !== $connection['integration_id'] ) {
			$result = $this->api->disconnect( $token, $connection['integration_id'], 'DELETE' );
			if ( is_wp_error( $result )
				&& 'ossengine_expired' !== $result->get_error_code()
				&& 'ossengine_not_found' !== $result->get_error_code() ) {
				$this->options->set_notice( 'error', $result->get_error_message() );
				$this->redirect();
			}
		}
		$this->options->reset_connection();
		$this->options->set_notice( 'updated', __( 'Disconnected. The Umami website and its analytics data have been permanently deleted.', 'ossengine-analytics-connector' ) );
		$this->redirect();
	}

	/**
	 * Manual status/config refresh (no per-page-view API calls otherwise).
	 */
	public function handle_refresh() {
		$this->require_capability();
		check_admin_referer( self::ACTION_REFRESH );

		$connection = $this->options->get_connection();
		$token      = $this->options->get_site_token();
		if ( 'managed' !== $connection['mode'] || '' === $token || '' === $connection['integration_id'] ) {
			$this->options->set_notice( 'error', __( 'Nothing to refresh. Connect OSSEngine Analytics first.', 'ossengine-analytics-connector' ) );
			$this->redirect();
		}
		$status = $this->api->get_status( $token, $connection['integration_id'] );
		if ( is_wp_error( $status ) ) {
			$this->options->set_notice( 'error', $status->get_error_message() );
			$this->redirect();
		}
		$this->auth->refresh_config( $token, $connection['integration_id'] );
		$this->options->set_notice( 'updated', __( 'Connection status refreshed.', 'ossengine-analytics-connector' ) );
		$this->redirect();
	}

	/**
	 * Save tracking toggles and BYO settings.
	 */
	public function handle_save() {
		$this->require_capability();
		check_admin_referer( self::ACTION_SAVE );

		$this->options->update_connection(
			array(
				'tracking_enabled' => ! empty( $_POST['tracking_enabled'] ), // phpcs:ignore WordPress.Security.NonceVerification.Missing
				'exclude_admin'    => ! empty( $_POST['exclude_admin'] ), // phpcs:ignore WordPress.Security.NonceVerification.Missing
			)
		);

		$byo_enabled = ! empty( $_POST['byo_enabled'] ); // phpcs:ignore WordPress.Security.NonceVerification.Missing
		$byo_url     = isset( $_POST['byo_url'] ) ? esc_url_raw( sanitize_text_field( wp_unslash( $_POST['byo_url'] ) ) ) : ''; // phpcs:ignore WordPress.Security.NonceVerification.Missing -- verified by check_admin_referer() above.
		$byo_site    = isset( $_POST['byo_website_id'] ) ? sanitize_text_field( wp_unslash( $_POST['byo_website_id'] ) ) : ''; // phpcs:ignore WordPress.Security.NonceVerification.Missing
		update_option(
			OSSEngine_WooCommerce::OPTION_ENABLED,
			OSSEngine_WooCommerce::is_available() && ! empty( $_POST['woo_enabled'] ) // phpcs:ignore WordPress.Security.NonceVerification.Missing
		);
		$result      = $this->byo->save( $byo_enabled, $byo_url, $byo_site );
		if ( is_wp_error( $result ) ) {
			$this->options->set_notice( 'error', $result->get_error_message() );
		} else {
			$this->options->set_notice( 'updated', __( 'Settings saved.', 'ossengine-analytics-connector' ) );
		}
		$this->redirect();
	}

	/**
	 * Weekly cron: revalidate managed connection without blocking pages.
	 */
	public function cron_refresh() {
		$connection = $this->options->get_connection();
		$token      = $this->options->get_site_token();
		if ( 'managed' !== $connection['mode'] || '' === $token || '' === $connection['integration_id'] ) {
			return;
		}
		$this->auth->refresh_config( $token, $connection['integration_id'] );
	}

	/**
	 * Render the queued admin notice, if any.
	 */
	public function render_notice() {
		$screen = function_exists( 'get_current_screen' ) ? get_current_screen() : null;
		if ( ! $screen || 'settings_page_' . self::PAGE_SLUG !== $screen->id ) {
			return;
		}
		$notice = $this->options->take_notice();
		if ( null === $notice ) {
			return;
		}
		printf(
			'<div class="notice notice-%s is-dismissible"><p>%s</p></div>',
			'error' === $notice['type'] ? 'error' : 'success',
			esc_html( $notice['message'] )
		);
	}

	/**
	 * Render the settings page.
	 */
	public function render() {
		if ( ! current_user_can( 'manage_options' ) ) {
			wp_die( esc_html__( 'You are not allowed to manage analytics settings.', 'ossengine-analytics-connector' ), 403 );
		}
		$this->maybe_detect_remote_disconnect();
		$connection = $this->options->get_connection();
		$byo        = $this->options->get_byo();
		$woo_status = OSSEngine_WooCommerce::get_status();
		?>
		<div class="wrap">
			<h1><?php esc_html_e( 'OSSEngine Analytics Connector', 'ossengine-analytics-connector' ); ?></h1>
			<p class="description ossengine-analytics-connector-lead">
				<?php esc_html_e( 'Privacy-friendly, cookie-free analytics for WordPress, fully managed — no servers, no maintenance. Connect your site in one click and see who visits, where they come from, and what they do.', 'ossengine-analytics-connector' ); ?>
			</p>

			<div class="notice notice-info inline ossengine-analytics-connector-info">
				<p><strong><?php esc_html_e( 'Why OSSEngine?', 'ossengine-analytics-connector' ); ?></strong></p>
				<ul class="ossengine-analytics-connector-list">
					<li><?php esc_html_e( 'Privacy-friendly and cookie-free — GDPR-friendly analytics without cookie banners in most setups. You own 100% of your data.', 'ossengine-analytics-connector' ); ?></li>
					<li><?php esc_html_e( 'Lightweight script that loads asynchronously and never slows down your site. Logged-in administrators are excluded by default.', 'ossengine-analytics-connector' ); ?></li>
					<li><?php esc_html_e( 'Real-time dashboard: pageviews, visitors, referrers, devices, and campaigns. Optional WooCommerce tracking for product views, carts, checkouts, and purchases (no customer personal data is sent).', 'ossengine-analytics-connector' ); ?></li>
					<li><?php esc_html_e( 'Fully managed: unlimited sites, automatic updates and backups, no DevOps. Starts with a 14-day free trial, no credit card required.', 'ossengine-analytics-connector' ); ?></li>
				</ul>
				<?php if ( 'managed' !== $connection['mode'] || 'connected' !== $connection['status'] ) : ?>
				<p>
					<strong><?php esc_html_e( 'New to OSSEngine Analytics?', 'ossengine-analytics-connector' ); ?></strong>
					<?php esc_html_e( 'Create your free account first, then come back and click “Connect OSSEngine Analytics.', 'ossengine-analytics-connector' ); ?>
				</p>
				<ol class="ossengine-analytics-connector-ordered">
					<li><?php esc_html_e( 'Step 1: Start your 14-day free trial (Continue with Google or GitHub, no credit card).', 'ossengine-analytics-connector' ); ?></li>
					<li><?php esc_html_e( 'Step 2: Come back here and click “Connect OSSEngine to approve access — tracking configures itself.', 'ossengine-analytics-connector' ); ?></li>
					<li><?php esc_html_e( 'Step 3: Open your stats in the Umami app. Tracking starts automatically.', 'ossengine-analytics-connector' ); ?></li>
				</ol>
				<?php endif; ?>
			</div>

			<h2><?php esc_html_e( 'Connection', 'ossengine-analytics-connector' ); ?></h2>
			<table class="form-table" role="presentation">
				<tr>
					<th scope="row"><?php esc_html_e( 'Status', 'ossengine-analytics-connector' ); ?></th>
					<td><strong><?php echo esc_html( $this->status_label( $connection ) ); ?></strong></td>
				</tr>
				<?php if ( '' !== $connection['site_url'] ) : ?>
				<tr>
					<th scope="row"><?php esc_html_e( 'Website', 'ossengine-analytics-connector' ); ?></th>
					<td><?php echo esc_html( $connection['site_url'] ); ?></td>
				</tr>
				<?php endif; ?>
				<tr>
					<th scope="row"><?php esc_html_e( 'Tracking', 'ossengine-analytics-connector' ); ?></th>
					<td><?php echo esc_html( $this->tracking_label( $connection, $byo ) ); ?>
					<?php if ( 'connected' === $connection['status'] && $connection['exclude_admin'] ) : ?>
						<br /><span class="description"><?php esc_html_e( 'You are logged in as an administrator, so the script is hidden for you. Open the site in a private window (logged out) to verify it.', 'ossengine-analytics-connector' ); ?></span>
					<?php endif; ?>
					</td>
				</tr>
				<?php if ( 'connected' === $connection['status'] && '' !== $connection['script_url'] && '' !== $connection['ossengine_website_id'] ) : ?>
				<tr>
					<th scope="row"><?php esc_html_e( 'Snippet', 'ossengine-analytics-connector' ); ?></th>
					<td><code><?php echo esc_html( $this->snippet_preview( $connection ) ); ?></code>
						<br /><span class="description"><?php esc_html_e( 'View your post while logged out and search the page source for this tag. If it is missing, check the options above (tracking enabled, admin exclusion).', 'ossengine-analytics-connector' ); ?></span>
					</td>
				</tr>
				<?php endif; ?>
				<tr>
					<th scope="row"><?php esc_html_e( 'WooCommerce', 'ossengine-analytics-connector' ); ?></th>
					<td><?php echo esc_html( $this->woo_label( $woo_status ) ); ?></td>
				</tr>
			</table>

			<p>
				<?php if ( 'managed' !== $connection['mode'] || 'connected' !== $connection['status'] ) : ?>
					<a class="button button-primary" href="<?php echo esc_url( $this->action_url( OSSEngine_Auth::ACTION_CONNECT ) ); ?>">
						<?php esc_html_e( 'Connect OSSEngine Analytics', 'ossengine-analytics-connector' ); ?>
					</a>
					<a class="button" target="_blank" rel="noopener" href="<?php echo esc_url( $this->signup_url() ); ?>">
						<?php esc_html_e( 'New to OSSEngine? Sign up now', 'ossengine-analytics-connector' ); ?>
					</a>
					<br /><span class="description"><?php esc_html_e( 'Already have an account? Click “Connect OSSEngine Analytics and approve access. No account yet? Start your free trial first, then connect.', 'ossengine-analytics-connector' ); ?></span>
				<?php else : ?>
					<a class="button" href="<?php echo esc_url( $this->action_url( self::ACTION_REFRESH ) ); ?>">
						<?php esc_html_e( 'Refresh status', 'ossengine-analytics-connector' ); ?>
					</a>
					<a class="button" href="<?php echo esc_url( $this->action_url( OSSEngine_Auth::ACTION_CONNECT ) ); ?>">
						<?php esc_html_e( 'Reconnect', 'ossengine-analytics-connector' ); ?>
					</a>
					<a class="button button-primary" target="_blank" rel="noopener" href="<?php echo esc_url( $this->analytics_url() ); ?>">
						<?php esc_html_e( 'Open analytics', 'ossengine-analytics-connector' ); ?>
					</a>
					<br /><span class="description"><?php esc_html_e( 'Opens your stats directly in the Umami app (app.umamiengine.com).', 'ossengine-analytics-connector' ); ?></span>
				<?php endif; ?>
			</p>
			<?php if ( 'managed' === $connection['mode'] && 'connected' === $connection['status'] ) : ?>
			<details class="ossengine-analytics-connector-disconnect">
				<summary class="button button-link-delete"><?php esc_html_e( 'Disconnect…', 'ossengine-analytics-connector' ); ?></summary>
				<div class="notice notice-error inline ossengine-analytics-connector-errorbox">
					<p><strong><?php esc_html_e( 'Permanently delete the Umami website and all its analytics data?', 'ossengine-analytics-connector' ); ?></strong></p>
					<p>
						<?php
						printf(
							/* translators: %s: site URL */
							esc_html__( 'Disconnecting %s will permanently delete its Umami website and all analytics data. This cannot be undone.', 'ossengine-analytics-connector' ),
							'' !== $connection['site_url'] ? esc_html( $connection['site_url'] ) : esc_html__( 'this site', 'ossengine-analytics-connector' )
						);
						?>
					</p>
				</div>
				<form method="post" action="<?php echo esc_url( admin_url( 'admin-post.php' ) ); ?>">
					<input type="hidden" name="action" value="<?php echo esc_attr( self::ACTION_DISCONNECT ); ?>" />
					<?php wp_nonce_field( self::ACTION_DISCONNECT ); ?>
					<p>
						<label for="ossengine-analytics-connector-disconnect-confirm">
							<?php esc_html_e( 'Type DELETE to confirm:', 'ossengine-analytics-connector' ); ?>
						</label>
						<input type="text" id="ossengine-analytics-connector-disconnect-confirm" name="confirmation" value="" autocomplete="off" />
					</p>
					<p>
						<button type="submit" id="ossengine-analytics-connector-disconnect-submit" class="button button-link-delete" disabled>
							<?php esc_html_e( 'Disconnect and delete data', 'ossengine-analytics-connector' ); ?>
						</button>
					</p>
				</form>
			</details>
			<?php endif; ?>
			<?php if ( '' !== $connection['status_message'] ) : ?>
				<p class="description"><?php echo esc_html( $connection['status_message'] ); ?></p>
			<?php endif; ?>
			<?php if ( '' !== $connection['account_url'] ) : ?>
				<p><a href="<?php echo esc_url( $connection['account_url'] ); ?>" target="_blank" rel="noopener">
					<?php esc_html_e( 'Open your OSSEngine Analytics account', 'ossengine-analytics-connector' ); ?>
				</a></p>
			<?php endif; ?>

			<form method="post" action="<?php echo esc_url( admin_url( 'admin-post.php' ) ); ?>">
				<input type="hidden" name="action" value="<?php echo esc_attr( self::ACTION_SAVE ); ?>" />
				<?php wp_nonce_field( self::ACTION_SAVE ); ?>

				<h2><?php esc_html_e( 'Tracking', 'ossengine-analytics-connector' ); ?></h2>
				<p class="description"><?php esc_html_e( 'Activation makes no external requests. Tracking loads only on public pages when connected, and stays off when the ossengine_tracking_enabled filter returns false so consent plugins can suppress it.', 'ossengine-analytics-connector' ); ?></p>
				<table class="form-table" role="presentation">
					<tr>
						<th scope="row"><?php esc_html_e( 'Enable tracking', 'ossengine-analytics-connector' ); ?></th>
						<td><label><input type="checkbox" name="tracking_enabled" value="1" <?php checked( $connection['tracking_enabled'] ); ?> />
							<?php esc_html_e( 'Add the Umami tracking script to public pages.', 'ossengine-analytics-connector' ); ?></label></td>
					</tr>
					<tr>
						<th scope="row"><?php esc_html_e( 'Exclude administrators', 'ossengine-analytics-connector' ); ?></th>
						<td><label><input type="checkbox" name="exclude_admin" value="1" <?php checked( $connection['exclude_admin'] ); ?> />
							<?php esc_html_e( 'Do not track logged-in administrators (recommended).', 'ossengine-analytics-connector' ); ?></label></td>
					</tr>
					<?php if ( OSSEngine_WooCommerce::is_available() ) : ?>
					<tr>
						<th scope="row"><?php esc_html_e( 'WooCommerce events', 'ossengine-analytics-connector' ); ?></th>
						<td><label><input type="checkbox" name="woo_enabled" value="1" <?php checked( get_option( OSSEngine_WooCommerce::OPTION_ENABLED, false ) ); ?> />
							<?php esc_html_e( 'Track product views, add to cart, checkout, and purchases. No customer data is sent.', 'ossengine-analytics-connector' ); ?></label></td>
					</tr>
					<?php endif; ?>
				</table>

				<h2><?php esc_html_e( 'Existing Umami', 'ossengine-analytics-connector' ); ?></h2>
				<p class="description"><?php esc_html_e( 'Already run your own Umami Analytics instance? Enter its details instead of connecting OSSEngine Analytics. The two modes are mutually exclusive.', 'ossengine-analytics-connector' ); ?></p>
				<table class="form-table" role="presentation">
					<tr>
						<th scope="row"><?php esc_html_e( 'Use existing Umami', 'ossengine-analytics-connector' ); ?></th>
						<td><label><input type="checkbox" name="byo_enabled" value="1" <?php checked( $byo['enabled'] ); ?> />
							<?php esc_html_e( 'Track with my own Umami installation.', 'ossengine-analytics-connector' ); ?></label></td>
					</tr>
					<tr>
						<th scope="row"><label for="byo_url"><?php esc_html_e( 'Umami URL', 'ossengine-analytics-connector' ); ?></label></th>
						<td><input type="url" id="byo_url" name="byo_url" class="regular-text" placeholder="https://umami.example.com" value="<?php echo esc_attr( $byo['url'] ); ?>" /></td>
					</tr>
					<tr>
						<th scope="row"><label for="byo_website_id"><?php esc_html_e( 'Website ID', 'ossengine-analytics-connector' ); ?></label></th>
						<td><input type="text" id="byo_website_id" name="byo_website_id" class="regular-text" value="<?php echo esc_attr( $byo['website_id'] ); ?>" /></td>
					</tr>
				</table>

				<?php submit_button( __( 'Save settings', 'ossengine-analytics-connector' ) ); ?>
			</form>
		</div>
		<?php
	}

	/**
	 * Detect a dashboard-side disconnect while rendering the settings page.
	 *
	 * Disconnecting from the UmamiEngine dashboard revokes the site token
	 * server-side, but the plugin keeps its local copy and would keep showing
	 * "Connected" (and keep printing a dead tracking script) until the weekly
	 * cron or a manual refresh. A single lightweight status check per settings
	 * page view closes that gap: a dead token (expired/not_found) clears the
	 * local connection so the page shows the true state. Transient failures
	 * (5xx, rate limits, transport errors) never touch local state.
	 */
	private function maybe_detect_remote_disconnect() {
		$connection = $this->options->get_connection();
		$token      = $this->options->get_site_token();
		if ( 'managed' !== $connection['mode'] || 'connected' !== $connection['status'] ) {
			return;
		}
		if ( '' === $token || '' === $connection['integration_id'] ) {
			return;
		}
		$status = $this->api->get_status( $token, $connection['integration_id'] );
		if ( ! is_wp_error( $status ) ) {
			return;
		}
		$code = $status->get_error_code();
		if ( 'ossengine_expired' !== $code && 'ossengine_not_found' !== $code ) {
			return;
		}
		$this->options->reset_connection();
		$this->options->update_connection(
			array(
				'status_message' => __( 'This site was disconnected from your OSSEngine Analytics dashboard. Tracking has stopped. Reconnect to resume analytics.', 'ossengine-analytics-connector' ),
			)
		);
	}

	/**
	 * Human-readable connection status.
	 *
	 * @param array $connection Connection array.
	 * @return string
	 */
	private function status_label( array $connection ) {
		if ( 'managed' === $connection['mode'] && 'connected' === $connection['status'] ) {
			return __( 'Connected', 'ossengine-analytics-connector' );
		}
		if ( 'byo' === $connection['mode'] && 'connected' === $connection['status'] ) {
			return __( 'Connected (existing Umami)', 'ossengine-analytics-connector' );
		}
		$labels = array(
			'pending'      => __( 'Connection pending', 'ossengine-analytics-connector' ),
			'expired'      => __( 'Connection expired', 'ossengine-analytics-connector' ),
			'revoked'      => __( 'Disconnected', 'ossengine-analytics-connector' ),
			'disconnected' => __( 'Not connected', 'ossengine-analytics-connector' ),
		);
		return isset( $labels[ $connection['status'] ] ) ? $labels[ $connection['status'] ] : __( 'Not connected', 'ossengine-analytics-connector' );
	}

	/**
	 * Human-readable tracking state.
	 *
	 * @param array $connection Connection array.
	 * @param array $byo        BYO array.
	 * @return string
	 */
	private function tracking_label( array $connection, array $byo ) {
		if ( ! $connection['tracking_enabled'] ) {
			return __( 'Disabled', 'ossengine-analytics-connector' );
		}
		if ( 'connected' === $connection['status'] ) {
			return __( 'Active', 'ossengine-analytics-connector' );
		}
		return __( 'Inactive — connect first', 'ossengine-analytics-connector' );
	}

	/**
	 * Human-readable WooCommerce status.
	 *
	 * @param string $status Status slug.
	 * @return string
	 */
	private function woo_label( $status ) {
		$labels = array(
			'not-installed' => __( 'WooCommerce not installed', 'ossengine-analytics-connector' ),
			'disabled'      => __( 'WooCommerce detected — event tracking off', 'ossengine-analytics-connector' ),
			'enabled'       => __( 'WooCommerce event tracking on', 'ossengine-analytics-connector' ),
		);
		return isset( $labels[ $status ] ) ? $labels[ $status ] : $status;
	}

	/**
	 * Exact script tag the plugin injects, for page-source verification.
	 *
	 * Mirrors the front-end tracker tag produced via the enqueue pipeline
	 * (OSSEngine_Tracking::enqueue_tracker() + script_loader_tag filter).
	 *
	 * @param array $connection Connection array.
	 * @return string
	 */
	private function snippet_preview( array $connection ) {
		return sprintf(
			'<script async defer src="%s" data-website-id="%s"></script>', // phpcs:ignore WordPress.WP.EnqueuedResources.NonEnqueuedScript -- escaped display text (echoed via esc_html() in a <code> block) showing admins what to look for in page source; not a printed script tag.
			$connection['script_url'],
			$connection['ossengine_website_id']
		);
	}

	/**
	 * Analytics app URL (the hosted Umami app itself).
	 *
	 * Previously this pointed at the account dashboard analytics page
	 * (dashboard.umamiengine.com/analytics). It now opens the Umami app
	 * directly (app.umamiengine.com) where stats are viewed.
	 *
	 * @return string
	 */
	private function analytics_url() {
		return $this->options->analytics_app_url();
	}

	/**
	 * Signup URL for new UmamiEngine customers.
	 *
	 * @return string
	 */
	private function signup_url() {
		return $this->options->signup_url();
	}

	/**
	 * Nonced admin-post URL for an action.
	 *
	 * @param string $action Action name.
	 * @return string
	 */
	private function action_url( $action ) {
		return wp_nonce_url(
			add_query_arg( array( 'action' => $action ), admin_url( 'admin-post.php' ) ),
			$action
		);
	}

	/**
	 * Enforce capability.
	 */
	private function require_capability() {
		if ( ! current_user_can( 'manage_options' ) ) {
			wp_die( esc_html__( 'You are not allowed to manage analytics settings.', 'ossengine-analytics-connector' ), 403 );
		}
	}

	/**
	 * Redirect back to the settings page.
	 */
	private function redirect() {
		wp_safe_redirect(
			add_query_arg( array( 'page' => self::PAGE_SLUG ), admin_url( 'options-general.php' ) )
		);
		exit;
	}
}