<?php

namespace WPForms\SetupWizard;

use WPForms\SetupWizard\Service\StripeConnectUrl;

/**
 * Setup Wizard Stripe Connect OAuth handler.
 *
 * Routes the user back into the wizard (resumed at the payments step) after
 * connecting Stripe, instead of the payments settings page. The OAuth
 * request-lifecycle — kickoff, redirect interception, pending-transient guard —
 * lives in {@see AbstractStripeConnect}; this class supplies the wizard-specific
 * kickoff argument, transient, Stripe mode, and destination, and additionally
 * forces the wizard to resume on the payments step via the bridge payload.
 *
 * @since 2.0.0
 */
class StripeConnect extends AbstractStripeConnect {

	/**
	 * Transient storing the pending Stripe OAuth state for wizard flows.
	 *
	 * @since 2.0.0
	 *
	 * @var string
	 */
	private const TRANSIENT_PENDING = 'wpforms_setup_wizard_stripe_pending';

	/**
	 * Transient storing the forced step to resume after OAuth.
	 *
	 * Public so the launch screen can consult it to distinguish a mid-wizard
	 * resume (Stripe OAuth return) from a first launch.
	 *
	 * @since 2.0.0
	 *
	 * @var string
	 */
	public const TRANSIENT_FORCE_STEP = 'wpforms_setup_wizard_force_step';

	/**
	 * Query argument used by the main wizard launcher.
	 *
	 * @since 2.0.0
	 *
	 * @var string
	 */
	private const WIZARD_ARG = 'wpforms_setup_wizard';

	/**
	 * Query argument that triggers the Stripe OAuth kickoff.
	 *
	 * @since 2.0.0
	 *
	 * @return string
	 */
	protected function kickoff_arg(): string {

		return StripeConnectUrl::KICKOFF_ARG;
	}

	/**
	 * Transient key storing the pending OAuth state.
	 *
	 * @since 2.0.0
	 *
	 * @return string
	 */
	protected function pending_transient(): string {

		return self::TRANSIENT_PENDING;
	}

	/**
	 * Get the Stripe mode for wizard connections.
	 *
	 * By default, the wizard connects in live mode. Define the constant
	 * `WPFORMS_SETUP_WIZARD_STRIPE_TEST_MODE` as true to use test mode
	 * for development/testing.
	 *
	 * @since 2.0.0
	 *
	 * @return string 'live' or 'test'.
	 */
	protected function get_stripe_mode(): string {

		$mode = 'live';

		if ( defined( 'WPFORMS_SETUP_WIZARD_STRIPE_TEST_MODE' ) && WPFORMS_SETUP_WIZARD_STRIPE_TEST_MODE ) {
			$mode = 'test';
		}

		/**
		 * Filter the Stripe mode used by the wizard.
		 *
		 * @since 2.0.0
		 *
		 * @param string $mode 'live' or 'test'.
		 */
		return apply_filters( 'wpforms_setup_wizard_stripe_connect_mode', $mode );
	}

	/**
	 * Register wizard-specific hooks beyond the shared OAuth lifecycle.
	 *
	 * @since 2.0.0
	 */
	protected function register_extra_hooks(): void { // phpcs:ignore WPForms.PHP.HooksMethod.InvalidPlaceForAddingHooks

		// Inject forced step into bridge payload.
		add_filter( 'wpforms_setup_wizard_bridge_payload', [ $this, 'inject_forced_step' ] );
	}

	/**
	 * Destination after a successful OAuth handshake: relaunch the wizard, resumed
	 * at the payments step.
	 *
	 * @since 2.0.0
	 *
	 * @return string
	 */
	protected function get_destination_url(): string {

		// Set forced step so the wizard resumes at payments.
		set_transient( self::TRANSIENT_FORCE_STEP, 'payments', HOUR_IN_SECONDS );

		return add_query_arg(
			self::WIZARD_ARG,
			1,
			admin_url( 'admin.php' )
		);
	}

	/**
	 * Inject the forced step into the bridge payload.
	 *
	 * After Stripe OAuth completes, the wizard should resume at the payments
	 * step instead of the welcome screen.
	 *
	 * @since 2.0.0
	 *
	 * @param mixed $payload Bridge payload.
	 *
	 * @return array
	 */
	public function inject_forced_step( $payload ): array {

		$payload = (array) $payload;

		$forced_step = get_transient( self::TRANSIENT_FORCE_STEP );

		if ( ! empty( $forced_step ) ) {
			$payload['current_step'] = $forced_step;

			delete_transient( self::TRANSIENT_FORCE_STEP );
		}

		return $payload;
	}
}
