externallib.php

<?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 <https://www.gnu.org/licenses/>.

/**
 * External API for enumerating LTI tools.
 *
 * @package    local_lti_tools_api
 * @copyright  2025 Daniel Landau
 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 */

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

require_once($CFG->libdir . '/externallib.php');
require_once($CFG->dirroot . '/mod/lti/locallib.php');

/**
 * External API class for LTI tools enumeration
 */
class local_lti_tools_api_external extends external_api {
    /**
     * Returns description of method parameters
     * @return external_function_parameters
     */
    public static function get_lti_tools_parameters() {
        return new external_function_parameters([
            'courseid' => new external_value(PARAM_INT, 'Course ID (optional, 0 for site-wide tools)', VALUE_DEFAULT, 0),
            'includesite' => new external_value(PARAM_BOOL, 'Include site-wide tools', VALUE_DEFAULT, true),
            'includecourse' => new external_value(PARAM_BOOL, 'Include course-specific tools', VALUE_DEFAULT, true),
        ]);
    }

    /**
     * Get available LTI tools
     * @param int $courseid Course ID
     * @param bool $includesite Include site-wide tools
     * @param bool $includecourse Include course-specific tools
     * @return array List of LTI tools
     */
    public static function get_lti_tools(
        $courseid = 0,
        $includesite = true,
        $includecourse = true
    ) {
        global $DB, $USER;

        // Validate parameters.
        $params = self::validate_parameters(self::get_lti_tools_parameters(), [
            'courseid' => $courseid,
            'includesite' => $includesite,
            'includecourse' => $includecourse,
        ]);

        $courseid = $params['courseid'];
        $includesite = $params['includesite'];
        $includecourse = $params['includecourse'];

        // Check capabilities.
        if ($courseid > 0) {
            $context = context_course::instance($courseid);

            // Check if user has the capability to add LTI instances.
            if (!has_capability('mod/lti:addinstance', $context)) {
                throw new required_capability_exception($context, 'mod/lti:addinstance', 'nopermissions', '');
            }
        } else {
            // For site-wide tools, we still need course context for permission check
            // since we're likely being called from a course context.
            $context = context_system::instance();
            // Check if user has capability to add LTI instances anywhere.
            $hascapability = false;

            // If user has system-level capability, allow access.
            if (has_capability('moodle/site:config', $context)) {
                $hascapability = true;
            } else {
                // Otherwise, check if they have mod/lti:addinstance in any course they're enrolled in.
                global $USER;
                $courses = enrol_get_my_courses();
                foreach ($courses as $course) {
                    $coursecontext = context_course::instance($course->id);
                    if (has_capability('mod/lti:addinstance', $coursecontext)) {
                        $hascapability = true;
                        break;
                    }
                }
            }

            if (!$hascapability) {
                throw new required_capability_exception($context, 'mod/lti:addinstance', 'nopermissions', '');
            }
        }

        $tools = [];

        // Get site-wide LTI tools.
        if ($includesite) {
            $sitetools = $DB->get_records('lti_types', ['course' => SITEID], 'name ASC');
            foreach ($sitetools as $tool) {
                $tools[] = [
                    'id' => $tool->id,
                    'name' => $tool->name,
                    'description' => $tool->description ?? '',
                    'baseurl' => $tool->baseurl,
                    'toolurl' => $tool->toolurl ?? '',
                    'state' => self::get_tool_state($tool->state),
                    'course' => $tool->course,
                    'scope' => 'site',
                    'icon' => $tool->icon ?? '',
                    'secureicon' => $tool->secureicon ?? '',
                    'createdby' => $tool->createdby,
                    'timecreated' => $tool->timecreated,
                    'timemodified' => $tool->timemodified,
                ];
            }
        }

        // Get course-specific LTI tools.
        if ($includecourse && $courseid > 0) {
            $coursetools = $DB->get_records('lti_types', ['course' => $courseid], 'name ASC');
            foreach ($coursetools as $tool) {
                $tools[] = [
                    'id' => $tool->id,
                    'name' => $tool->name,
                    'description' => $tool->description ?? '',
                    'baseurl' => $tool->baseurl,
                    'toolurl' => $tool->toolurl ?? '',
                    'state' => self::get_tool_state($tool->state),
                    'course' => $tool->course,
                    'scope' => 'course',
                    'icon' => $tool->icon ?? '',
                    'secureicon' => $tool->secureicon ?? '',
                    'createdby' => $tool->createdby,
                    'timecreated' => $tool->timecreated,
                    'timemodified' => $tool->timemodified,
                ];
            }
        }

        return $tools;
    }

    /**
     * Convert numeric state to readable string
     * @param int $state Tool state
     * @return string Human readable state
     */
    private static function get_tool_state($state) {
        switch ($state) {
            case LTI_TOOL_STATE_CONFIGURED:
                return 'configured';
            case LTI_TOOL_STATE_PENDING:
                return 'pending';
            case LTI_TOOL_STATE_REJECTED:
                return 'rejected';
            default:
                return 'unknown';
        }
    }

    /**
     * Returns description of method result value
     * @return external_description
     */
    public static function get_lti_tools_returns() {
        return new external_multiple_structure(
            new external_single_structure([
                'id' => new external_value(PARAM_INT, 'Tool ID'),
                'name' => new external_value(PARAM_TEXT, 'Tool name'),
                'description' => new external_value(PARAM_RAW, 'Tool description'),
                'baseurl' => new external_value(PARAM_URL, 'Base URL'),
                'toolurl' => new external_value(PARAM_URL, 'Tool URL'),
                'state' => new external_value(PARAM_TEXT, 'Tool state (configured, pending, rejected)'),
                'course' => new external_value(PARAM_INT, 'Course ID (SITEID for site-wide tools)'),
                'scope' => new external_value(PARAM_TEXT, 'Tool scope (site or course)'),
                'icon' => new external_value(PARAM_URL, 'Tool icon URL'),
                'secureicon' => new external_value(PARAM_URL, 'Secure tool icon URL'),
                'createdby' => new external_value(PARAM_INT, 'User ID who created the tool'),
                'timecreated' => new external_value(PARAM_INT, 'Time created timestamp'),
                'timemodified' => new external_value(PARAM_INT, 'Time modified timestamp'),
            ])
        );
    }

    /**
     * Returns description of method parameters for adding LTI instance to course
     * @return external_function_parameters
     */
    public static function add_lti_instance_parameters() {
        return new external_function_parameters([
            'courseid' => new external_value(PARAM_INT, 'Course ID where to add the LTI instance'),
            'toolid' => new external_value(PARAM_INT, 'LTI Tool type ID'),
            'name' => new external_value(PARAM_TEXT, 'Activity name'),
            'intro' => new external_value(PARAM_RAW, 'Activity description/intro', VALUE_DEFAULT, ''),
            'sectionnum' => new external_value(PARAM_INT, 'Section number (0-based)', VALUE_DEFAULT, 0),
            'visible' => new external_value(PARAM_INT, 'Visibility of the activity (0 or 1)', VALUE_DEFAULT, 1),
            'customparameters' => new external_multiple_structure(
                new external_single_structure([
                    'name' => new external_value(PARAM_TEXT, 'Parameter name'),
                    'value' => new external_value(PARAM_RAW, 'Parameter value'),
                ]),
                'Custom parameters for this instance',
                VALUE_DEFAULT,
                []
            ),
            'resourcekey' => new external_value(PARAM_TEXT, 'Resource key (if different from tool default)', VALUE_DEFAULT, ''),
            'password' => new external_value(
                PARAM_TEXT,
                'Shared secret (if different from tool default)',
                VALUE_DEFAULT,
                ''
            ),
            'instructorchoicesendname' => new external_value(
                PARAM_INT,
                'Send student names (0 or 1)',
                VALUE_DEFAULT,
                0
            ),
            'instructorchoicesendemailaddr' => new external_value(
                PARAM_INT,
                'Send student emails (0 or 1)',
                VALUE_DEFAULT,
                0
            ),
            'instructorchoiceacceptgrades' => new external_value(
                PARAM_INT,
                'Accept grades from tool (0 or 1)',
                VALUE_DEFAULT,
                0
            ),
            'grade' => new external_value(PARAM_INT, 'Maximum grade (0 for no grading)', VALUE_DEFAULT, 100),
            'launchcontainer' => new external_value(
                PARAM_INT,
                'Launch container (1=default, 2=embed, 3=embed no blocks, 4=new window, 5=existing)',
                VALUE_DEFAULT,
                1
            ),
            'availablefrom' => new external_value(
                PARAM_INT,
                'Unix timestamp for availability start (0 for no restriction)',
                VALUE_DEFAULT,
                0
            ),
            'availableuntil' => new external_value(
                PARAM_INT,
                'Unix timestamp for availability end (0 for no restriction)',
                VALUE_DEFAULT,
                0
            ),
            'showavailability' => new external_value(
                PARAM_INT,
                'Show availability info to students (0 or 1)',
                VALUE_DEFAULT,
                1
            ),
            'hidewhenrestricted' => new external_value(
                PARAM_INT,
                'Hide activity when restricted (1) or show greyed-out (0)',
                VALUE_DEFAULT,
                0
            ),
        ]);
    }

    /**
     * Add an LTI tool instance to a course
     * @param int $courseid Course ID
     * @param int $toolid LTI Tool type ID
     * @param string $name Activity name
     * @param string $intro Activity description
     * @param int $sectionnum Section number
     * @param int $visible Visibility (0 or 1)
     * @param array $customparameters Custom parameters
     * @param string $resourcekey Resource key
     * @param string $password Shared secret
     * @param int $instructorchoicesendname Send names (0 or 1)
     * @param int $instructorchoicesendemailaddr Send emails (0 or 1)
     * @param int $instructorchoiceacceptgrades Accept grades (0 or 1)
     * @param int $grade Maximum grade
     * @param int $launchcontainer Launch container
     * @param int $availablefrom Unix timestamp for availability start
     * @param int $availableuntil Unix timestamp for availability end
     * @param int $showavailability Show availability info to students (0 or 1)
     * @param int $hidewhenrestricted Completely hide activity when date restrictions apply (1) or show greyed-out (0)
     * @return array LTI instance details
     */
    public static function add_lti_instance(
        $courseid,
        $toolid,
        $name,
        $intro = '',
        $sectionnum = 0,
        $visible = 1,
        $customparameters = [],
        $resourcekey = '',
        $password = '',
        $instructorchoicesendname = 0,
        $instructorchoicesendemailaddr = 0,
        $instructorchoiceacceptgrades = 0,
        $grade = 100,
        $launchcontainer = 1,
        $availablefrom = 0,
        $availableuntil = 0,
        $showavailability = 1,
        $hidewhenrestricted = 0
    ) {
        global $DB, $CFG;

        require_once($CFG->dirroot . '/course/modlib.php');
        require_once($CFG->dirroot . '/mod/lti/lib.php');

        // Validate parameters.
        $params = self::validate_parameters(self::add_lti_instance_parameters(), [
            'courseid' => $courseid,
            'toolid' => $toolid,
            'name' => $name,
            'intro' => $intro,
            'sectionnum' => $sectionnum,
            'visible' => $visible,
            'customparameters' => $customparameters,
            'resourcekey' => $resourcekey,
            'password' => $password,
            'instructorchoicesendname' => $instructorchoicesendname,
            'instructorchoicesendemailaddr' => $instructorchoicesendemailaddr,
            'instructorchoiceacceptgrades' => $instructorchoiceacceptgrades,
            'grade' => $grade,
            'launchcontainer' => $launchcontainer,
            'availablefrom' => $availablefrom,
            'availableuntil' => $availableuntil,
            'showavailability' => $showavailability,
            'hidewhenrestricted' => $hidewhenrestricted,
        ]);

        // Check capabilities.
        $context = context_course::instance($params['courseid']);
        require_capability('mod/lti:addinstance', $context);

        // Verify course exists.
        $course = $DB->get_record('course', ['id' => $params['courseid']], '*', MUST_EXIST);

        // Verify tool exists and is accessible.
        $tool = $DB->get_record('lti_types', ['id' => $params['toolid']], '*', MUST_EXIST);
        if ($tool->course != SITEID && $tool->course != $params['courseid']) {
            throw new moodle_exception('invalidtoolid', 'mod_lti');
        }

        // Prepare module data.
        $moduleinfo = new stdClass();
        $moduleinfo->course = $params['courseid'];
        $moduleinfo->name = $params['name'];
        $moduleinfo->intro = $params['intro'];
        $moduleinfo->introformat = FORMAT_HTML;
        $moduleinfo->module = $DB->get_field('modules', 'id', ['name' => 'lti']);
        $moduleinfo->modulename = 'lti';
        $moduleinfo->section = $params['sectionnum'];
        $moduleinfo->visible = $params['visible'];
        $moduleinfo->visibleoncoursepage = $params['visible'];
        $moduleinfo->groupmode = 0;
        $moduleinfo->groupingid = 0;

        // LTI specific settings.
        $moduleinfo->typeid = $params['toolid'];
        $moduleinfo->toolurl = $tool->baseurl;
        // Get the tool configuration for resourcekey and password.
        $toolconfig = lti_get_type_config($tool->id);
        $moduleinfo->resourcekey = $params['resourcekey'] ?: ($toolconfig['resourcekey'] ?? '');
        $moduleinfo->password = $params['password'] ?: ($toolconfig['password'] ?? '');
        $moduleinfo->instructorchoicesendname = $params['instructorchoicesendname'];
        $moduleinfo->instructorchoicesendemailaddr = $params['instructorchoicesendemailaddr'];
        $moduleinfo->instructorchoiceacceptgrades = $params['instructorchoiceacceptgrades'];
        $moduleinfo->grade = $params['grade'];
        $moduleinfo->launchcontainer = $params['launchcontainer'];

        // Handle custom parameters.
        $customparams = '';
        if (!empty($params['customparameters'])) {
            $customparamstrings = [];
            foreach ($params['customparameters'] as $param) {
                $customparamstrings[] = $param['name'] . '=' . $param['value'];
            }
            $customparams = implode("\n", $customparamstrings);
        }
        $moduleinfo->instructorcustomparameters = $customparams;

        // Handle availability restrictions.
        if (!empty($params['availablefrom']) || !empty($params['availableuntil'])) {
            $conditions = [];

            // Add "available from" condition.
            if (!empty($params['availablefrom'])) {
                $conditions[] = (object)[
                    'type' => 'date',
                    'd' => '>=',
                    't' => $params['availablefrom'],
                ];
            }

            // Add "available until" condition.
            if (!empty($params['availableuntil'])) {
                $conditions[] = (object)[
                    'type' => 'date',
                    'd' => '<',
                    't' => $params['availableuntil'],
                ];
            }

            if (!empty($conditions)) {
                // For AND operations, showc array controls visibility of each condition.
                // Showc[i] = true: show activity greyed out with restriction info.
                // Showc[i] = false: completely hide the activity.
                //
                // Hidewhenrestricted: 1 = hide completely, 0 = show greyed out.
                // Therefore: showc = !hidewhenrestricted (invert the logic).
                $showwhenrestricted = !((bool)$params['hidewhenrestricted']);
                $showc = array_fill(0, count($conditions), $showwhenrestricted);

                $availability = (object)[
                    'op' => '&',
                    'c' => $conditions,
                    'showc' => $showc,
                ];
                $moduleinfo->availability = json_encode($availability);
            }
        }

        // Add the module.
        $moduleinfo = add_moduleinfo($moduleinfo, $course);

        $url = new moodle_url('/mod/lti/view.php', ['id' => $moduleinfo->coursemodule]);
        return [
            'instanceid' => $moduleinfo->instance,
            'coursemoduleid' => $moduleinfo->coursemodule,
            'name' => $moduleinfo->name,
            'url' => $url->out(false),
            'success' => true,
            'message' => 'LTI instance added successfully',
        ];
    }

    /**
     * Returns description of method result value for add_lti_instance
     * @return external_description
     */
    public static function add_lti_instance_returns() {
        return new external_single_structure([
            'instanceid' => new external_value(PARAM_INT, 'LTI instance ID'),
            'coursemoduleid' => new external_value(PARAM_INT, 'Course module ID'),
            'name' => new external_value(PARAM_TEXT, 'Activity name'),
            'url' => new external_value(PARAM_URL, 'Activity URL'),
            'success' => new external_value(PARAM_BOOL, 'Success status'),
            'message' => new external_value(PARAM_TEXT, 'Status message'),
        ]);
    }

    /**
     * Returns description of method parameters for getting tool by name
     * @return external_function_parameters
     */
    public static function get_lti_tool_by_name_parameters() {
        return new external_function_parameters([
            'name' => new external_value(PARAM_TEXT, 'Tool name to search for'),
            'courseid' => new external_value(PARAM_INT, 'Course ID (optional, 0 for site-wide tools)', VALUE_DEFAULT, 0),
            'exactmatch' => new external_value(PARAM_BOOL, 'Exact name match (true) or partial match (false)', VALUE_DEFAULT, true),
        ]);
    }

    /**
     * Get LTI tool type ID by name
     * @param string $name Tool name to search for
     * @param int $courseid Course ID (0 for site-wide)
     * @param bool $exactmatch Whether to do exact or partial matching
     * @return array Tool information
     */
    public static function get_lti_tool_by_name($name, $courseid = 0, $exactmatch = true) {
        global $DB;

        // Validate parameters.
        $params = self::validate_parameters(self::get_lti_tool_by_name_parameters(), [
            'name' => $name,
            'courseid' => $courseid,
            'exactmatch' => $exactmatch,
        ]);

        $name = $params['name'];
        $courseid = $params['courseid'];
        $exactmatch = $params['exactmatch'];

        // Check capabilities.
        if ($courseid > 0) {
            $context = context_course::instance($courseid);
            require_capability('mod/lti:addinstance', $context);
        } else {
            // For site-wide searches, check if user has LTI capability in any course.
            $context = context_system::instance();
            $hascapability = false;

            if (has_capability('moodle/site:config', $context)) {
                $hascapability = true;
            } else {
                $courses = enrol_get_my_courses();
                foreach ($courses as $course) {
                    $coursecontext = context_course::instance($course->id);
                    if (has_capability('mod/lti:addinstance', $coursecontext)) {
                        $hascapability = true;
                        break;
                    }
                }
            }

            if (!$hascapability) {
                throw new required_capability_exception($context, 'mod/lti:addinstance', 'nopermissions', '');
            }
        }

        // Build the search conditions.
        $conditions = [];
        $paramsdb = [];

        if ($exactmatch) {
            $conditions[] = 'name = :name';
            $paramsdb['name'] = $name;
        } else {
            $conditions[] = $DB->sql_like('name', ':name', false);
            $paramsdb['name'] = '%' . $DB->sql_like_escape($name) . '%';
        }

        // Add course condition.
        if ($courseid > 0) {
            // Search in both site-wide and course-specific tools.
            $conditions[] = '(course = :siteid OR course = :courseid)';
            $paramsdb['siteid'] = SITEID;
            $paramsdb['courseid'] = $courseid;
        } else {
            // Only site-wide tools.
            $conditions[] = 'course = :siteid';
            $paramsdb['siteid'] = SITEID;
        }

        $sql = 'SELECT * FROM {lti_types} WHERE ' . implode(' AND ', $conditions) . ' ORDER BY name ASC';
        $tools = $DB->get_records_sql($sql, $paramsdb);

        $results = [];
        foreach ($tools as $tool) {
            $results[] = [
                'id' => $tool->id,
                'name' => $tool->name,
                'description' => $tool->description ?? '',
                'baseurl' => $tool->baseurl,
                'toolurl' => $tool->toolurl ?? '',
                'state' => self::get_tool_state($tool->state),
                'course' => $tool->course,
                'scope' => ($tool->course == SITEID) ? 'site' : 'course',
                'icon' => $tool->icon ?? '',
                'secureicon' => $tool->secureicon ?? '',
                'createdby' => $tool->createdby,
                'timecreated' => $tool->timecreated,
                'timemodified' => $tool->timemodified,
            ];
        }

        return $results;
    }

    /**
     * Returns description of method result value for get_lti_tool_by_name
     * @return external_description
     */
    public static function get_lti_tool_by_name_returns() {
        return new external_multiple_structure(
            new external_single_structure([
                'id' => new external_value(PARAM_INT, 'Tool ID'),
                'name' => new external_value(PARAM_TEXT, 'Tool name'),
                'description' => new external_value(PARAM_RAW, 'Tool description'),
                'baseurl' => new external_value(PARAM_URL, 'Base URL'),
                'toolurl' => new external_value(PARAM_URL, 'Tool URL'),
                'state' => new external_value(PARAM_TEXT, 'Tool state (configured, pending, rejected)'),
                'course' => new external_value(PARAM_INT, 'Course ID (SITEID for site-wide tools)'),
                'scope' => new external_value(PARAM_TEXT, 'Tool scope (site or course)'),
                'icon' => new external_value(PARAM_URL, 'Tool icon URL'),
                'secureicon' => new external_value(PARAM_URL, 'Secure tool icon URL'),
                'createdby' => new external_value(PARAM_INT, 'User ID who created the tool'),
                'timecreated' => new external_value(PARAM_INT, 'Time created timestamp'),
                'timemodified' => new external_value(PARAM_INT, 'Time modified timestamp'),
            ])
        );
    }

    /**
     * Returns description of method parameters for getting tool details
     * @return external_function_parameters
     */
    public static function get_lti_tool_details_parameters() {
        return new external_function_parameters([
            'toolid' => new external_value(PARAM_INT, 'LTI Tool ID'),
        ]);
    }

    /**
     * Get detailed information about a specific LTI tool
     * @param int $toolid Tool ID
     * @return array Tool details
     */
    public static function get_lti_tool_details($toolid) {
        global $DB;

        // Validate parameters.
        $params = self::validate_parameters(self::get_lti_tool_details_parameters(), [
            'toolid' => $toolid,
        ]);

        $toolid = $params['toolid'];

        // Check if tool exists.
        $tool = $DB->get_record('lti_types', ['id' => $toolid], '*', MUST_EXIST);

        // Check capabilities.
        if ($tool->course == SITEID) {
            // For site-level tools, check if user can manage LTI tools or has admin access.
            $context = context_system::instance();
            $hasaccess = false;

            if (has_capability('moodle/site:config', $context, null, false)) {
                $hasaccess = true;
            } else {
                // Also allow users who have LTI addinstance capability in any course.
                global $USER;
                $courses = enrol_get_my_courses();
                foreach ($courses as $course) {
                    $coursecontext = context_course::instance($course->id);
                    if (has_capability('mod/lti:addinstance', $coursecontext)) {
                        $hasaccess = true;
                        break;
                    }
                }
            }

            if (!$hasaccess) {
                throw new required_capability_exception($context, 'mod/lti:addinstance', 'nopermissions', '');
            }
        } else {
            $context = context_course::instance($tool->course);
            require_capability('mod/lti:addinstance', $context);
        }

        // Get tool configuration.
        $config = $DB->get_records_menu('lti_types_config', ['typeid' => $toolid], '', 'name, value');

        return [
            'id' => $tool->id,
            'name' => $tool->name,
            'description' => $tool->description ?? '',
            'baseurl' => $tool->baseurl,
            'toolurl' => $tool->toolurl ?? '',
            'state' => self::get_tool_state($tool->state),
            'course' => $tool->course,
            'scope' => ($tool->course == SITEID) ? 'site' : 'course',
            'icon' => $tool->icon ?? '',
            'secureicon' => $tool->secureicon ?? '',
            'createdby' => $tool->createdby,
            'timecreated' => $tool->timecreated,
            'timemodified' => $tool->timemodified,
            'configuration' => $config,
        ];
    }

    /**
     * Returns description of method result value for tool details
     * @return external_description
     */
    public static function get_lti_tool_details_returns() {
        return new external_single_structure([
            'id' => new external_value(PARAM_INT, 'Tool ID'),
            'name' => new external_value(PARAM_TEXT, 'Tool name'),
            'description' => new external_value(PARAM_RAW, 'Tool description'),
            'baseurl' => new external_value(PARAM_URL, 'Base URL'),
            'toolurl' => new external_value(PARAM_URL, 'Tool URL'),
            'state' => new external_value(PARAM_TEXT, 'Tool state'),
            'course' => new external_value(PARAM_INT, 'Course ID'),
            'scope' => new external_value(PARAM_TEXT, 'Tool scope'),
            'icon' => new external_value(PARAM_URL, 'Tool icon URL'),
            'secureicon' => new external_value(PARAM_URL, 'Secure tool icon URL'),
            'createdby' => new external_value(PARAM_INT, 'Created by user ID'),
            'timecreated' => new external_value(PARAM_INT, 'Time created'),
            'timemodified' => new external_value(PARAM_INT, 'Time modified'),
            'configuration' => new external_multiple_structure(
                new external_value(PARAM_RAW, 'Configuration value'),
                'Tool configuration parameters'
            ),
        ]);
    }

    /**
     * Returns description of method parameters for setting LTI availability
     * @return external_function_parameters
     */
    public static function set_lti_availability_parameters() {
        return new external_function_parameters([
            'coursemoduleid' => new external_value(PARAM_INT, 'Course module ID of the LTI instance'),
            'availablefrom' => new external_value(
                PARAM_INT,
                'Unix timestamp for availability start date (0 to remove)',
                VALUE_DEFAULT,
                0
            ),
            'availableuntil' => new external_value(
                PARAM_INT,
                'Unix timestamp for availability end date (0 to remove)',
                VALUE_DEFAULT,
                0
            ),
            'showavailability' => new external_value(
                PARAM_INT,
                'Show availability info to students (0 or 1)',
                VALUE_DEFAULT,
                1
            ),
            'hidewhenrestricted' => new external_value(
                PARAM_INT,
                'Completely hide activity when restricted (1) or show greyed-out (0)',
                VALUE_DEFAULT,
                0
            ),
        ]);
    }

    /**
     * Set or update availability restrictions for an existing LTI instance
     * @param int $coursemoduleid Course module ID
     * @param int $availablefrom Unix timestamp for availability start
     * @param int $availableuntil Unix timestamp for availability end
     * @param int $showavailability Show availability info to students (0 or 1)
     * @param int $hidewhenrestricted Completely hide activity when date restrictions apply (1) or show greyed-out (0)
     * @return array Update status
     */
    public static function set_lti_availability(
        $coursemoduleid,
        $availablefrom = 0,
        $availableuntil = 0,
        $showavailability = 1,
        $hidewhenrestricted = 0
    ) {
        global $DB, $CFG;

        require_once($CFG->dirroot . '/course/lib.php');
        require_once($CFG->dirroot . '/availability/classes/tree.php');

        // Validate parameters.
        $params = self::validate_parameters(self::set_lti_availability_parameters(), [
            'coursemoduleid' => $coursemoduleid,
            'availablefrom' => $availablefrom,
            'availableuntil' => $availableuntil,
            'showavailability' => $showavailability,
            'hidewhenrestricted' => $hidewhenrestricted,
        ]);

        // Get the course module.
        $cm = $DB->get_record('course_modules', ['id' => $params['coursemoduleid']], '*', MUST_EXIST);

        // Verify it's an LTI module.
        $module = $DB->get_record('modules', ['id' => $cm->module], '*', MUST_EXIST);
        if ($module->name !== 'lti') {
            throw new moodle_exception('invalidmodule', 'error', '', null, 'Module is not an LTI instance');
        }

        // Check capabilities.
        $context = context_module::instance($cm->id);
        require_capability('moodle/course:manageactivities', $context);

        // Get the course for later.
        $course = $DB->get_record('course', ['id' => $cm->course], '*', MUST_EXIST);

        // Build availability conditions.
        $availability = null;
        if (!empty($CFG->enableavailability) && ($params['availablefrom'] > 0 || $params['availableuntil'] > 0)) {
            $conditions = [];

            if ($params['availablefrom'] > 0) {
                $conditions[] = (object)[
                    'type' => 'date',
                    'd' => '>=',
                    't' => $params['availablefrom'],
                ];
            }

            if ($params['availableuntil'] > 0) {
                $conditions[] = (object)[
                    'type' => 'date',
                    'd' => '<',
                    't' => $params['availableuntil'],
                ];
            }

            // For AND operations, showc array controls visibility of each condition.
            // Showc[i] = true: show activity greyed out with restriction info.
            // Showc[i] = false: completely hide the activity.
            $showwhenrestricted = !((bool)$params['hidewhenrestricted']);
            $showc = array_fill(0, count($conditions), $showwhenrestricted);

            $availabilitydata = (object)[
                'op' => '&', // AND operator - both conditions must be met.
                'c' => $conditions,
                'showc' => $showc,
            ];

            $availability = json_encode($availabilitydata);
        }

        // Update the course module.
        $cm->availability = $availability;
        $DB->update_record('course_modules', $cm);

        // Rebuild course cache.
        rebuild_course_cache($course->id, true);

        // Prepare response.
        $response = [
            'success' => true,
            'coursemoduleid' => $cm->id,
            'message' => 'Availability updated successfully',
        ];

        // Add human-readable availability info.
        if ($params['availablefrom'] > 0) {
            $response['availablefrom'] = $params['availablefrom'];
            $response['availablefrom_readable'] = userdate($params['availablefrom']);
        }
        if ($params['availableuntil'] > 0) {
            $response['availableuntil'] = $params['availableuntil'];
            $response['availableuntil_readable'] = userdate($params['availableuntil']);
        }

        return $response;
    }

    /**
     * Returns description of method result value for set_lti_availability
     * @return external_description
     */
    public static function set_lti_availability_returns() {
        return new external_single_structure([
            'success' => new external_value(PARAM_BOOL, 'Success status'),
            'coursemoduleid' => new external_value(PARAM_INT, 'Course module ID'),
            'message' => new external_value(PARAM_TEXT, 'Status message'),
            'availablefrom' => new external_value(PARAM_INT, 'Unix timestamp for start date', VALUE_OPTIONAL),
            'availablefrom_readable' => new external_value(PARAM_TEXT, 'Human readable start date', VALUE_OPTIONAL),
            'availableuntil' => new external_value(PARAM_INT, 'Unix timestamp for end date', VALUE_OPTIONAL),
            'availableuntil_readable' => new external_value(PARAM_TEXT, 'Human readable end date', VALUE_OPTIONAL),
        ]);
    }
}