<?php
// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// Moodle is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.

/**
 * External: run one Adobe Connect connection-test step.
 *
 * @package    mod_meetletacbfree
 * @copyright  2026 MeetLet <info@meetlet.net>
 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 */

namespace mod_meetletacbfree\external;

use core_external\external_api;
use core_external\external_function_parameters;
use core_external\external_multiple_structure;
use core_external\external_single_structure;
use core_external\external_value;
use mod_meetletacbfree\local\conntest_runner;

defined('MOODLE_INTERNAL') || die();

/**
 * Ajax-capable connection test step runner for admin settings.
 */
class run_conntest_step extends external_api {
    public static function execute_parameters(): external_function_parameters {
        return new external_function_parameters([
            'step' => new external_value(PARAM_ALPHA, 'Connection test step name'),
        ]);
    }

    public static function execute(string $step): array {
        $params = self::validate_parameters(self::execute_parameters(), ['step' => $step]);
        $context = \context_system::instance();
        self::validate_context($context);
        require_capability('moodle/site:config', $context);

        \mod_meetletacbfree\registration\manager::require_registered();

        $result = conntest_runner::run_step($params['step']);
        $subresults = [];
        if (!empty($result['subresults']) && is_array($result['subresults'])) {
            foreach ($result['subresults'] as $sub) {
                $subresults[] = [
                    'label' => (string)($sub['label'] ?? ''),
                    'ok' => !empty($sub['ok']),
                    'detail' => (string)($sub['detail'] ?? ''),
                ];
            }
        }

        return [
            'step' => (string)($result['step'] ?? $params['step']),
            'label' => (string)($result['label'] ?? ''),
            'ok' => !empty($result['ok']),
            'detail' => (string)($result['detail'] ?? ''),
            'done' => !empty($result['done']),
            'abort' => !empty($result['abort']),
            'subresults' => $subresults,
        ];
    }

    public static function execute_returns(): external_single_structure {
        return new external_single_structure([
            'step' => new external_value(PARAM_ALPHANUMEXT, 'Step id'),
            'label' => new external_value(PARAM_TEXT, 'Step label'),
            'ok' => new external_value(PARAM_BOOL, 'Whether the step passed'),
            'detail' => new external_value(PARAM_RAW, 'Detail message'),
            'done' => new external_value(PARAM_BOOL, 'Whether the run is finished'),
            'abort' => new external_value(PARAM_BOOL, 'Whether remaining steps should abort'),
            'subresults' => new external_multiple_structure(
                new external_single_structure([
                    'label' => new external_value(PARAM_TEXT, 'Sub-step label'),
                    'ok' => new external_value(PARAM_BOOL, 'Sub-step ok'),
                    'detail' => new external_value(PARAM_RAW, 'Sub-step detail'),
                ]),
                'Optional nested results',
                VALUE_DEFAULT,
                []
            ),
        ]);
    }
}