MDL-57750 calendar: add api function to get action events by timesort

Part of MDL-55611 epic.

calendar/classes/api.php

@@ -2322,4 +2322,44 @@ class api {
         }
         return $context;
     }
+
+    /**
+     * Get a list of action events for the logged in user by the given
+     * timesort values.
+     *
+     * @param int|null $timesortfrom The start timesort value (inclusive)
+     * @param int|null $timesortto The end timesort value (inclusive)
+     * @param int|null $aftereventid Only return events after this one
+     * @param int $limitnum Limit results to this amount (between 1 and 50)
+     * @return array A list of action_event objects
+     */
+    public static function get_action_events_by_timesort(
+        $timesortfrom = null,
+        $timesortto = null,
+        $aftereventid = null,
+        $limitnum = 20
+    ) {
+        global $USER;
+
+        if (is_null($timesortfrom) && is_null($timesortto)) {
+            throw new \moodle_exception("Must provide a timesort to and/or from value");
+        }
+
+        if ($limitnum < 1 || $limitnum > 50) {
+            throw new \moodle_exception("Limit must be between 1 and 50 (inclusive)");
+        }
+
+        $vault = \core_calendar\local\event\core_container::get_event_vault();
+        $mapper = \core_calendar\local\event\core_container::get_event_mapper();
+
+        $afterevent = null;
+        if ($aftereventid && $event = $vault->get_event_by_id($aftereventid)) {
+            $afterevent = $event;
+        }
+
+        // Don't expose the new classes outside this module.
+        return array_map(function($event) use ($mapper) {
+           return $mapper->from_event_to_legacy_event($event);
+        }, $vault->get_action_events_by_timesort($USER, $timesortfrom, $timesortto, $afterevent, $limitnum));
+    }
 }