feat: OCS Calendar Export + Import

[SebastianKrupinski]

Summary

Extracted from #49995

This adds the ability to export and import calendars via the OCS

OCS Export

Endpoint: /ocs/v2.php/calendar/export
Request: POST

{
    "id": "personal",
    "format": "xcal", (optional "ical, jcal, xcal", defaults to "ical")
	"options": {
		"rangeStart": '' or 'UID of previous last event',
		"rangeCount": 100
	},
	"user": "user1" (optional admin permissions required)
}

OCS Import

Endpoint: /ocs/v2.php/calendar/import
Request: POST

{
	"id": "personal",
	"options": {
		"format": "xcal", (optional "ical, jcal, xcal", defaults to "ical")
		"validation": 0, (0 - no validate, 1 - validate and skip, 2 - validate and error)
		"errors": 0, (0 - continue, 1 - fail)
		"supersede": true,
		"showCreated": true,
		"showUpdated": true,
		"showSkipped": true,
		"showErrors": true
	},
	"user": "user1", (optional admin permissions required)
	"data": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><calendar><event><title>Meeting</title><date>2025-02-18</date></event></calendar>"
}

Checklist

• Code is properly formatted
• Sign-off message is added to all commits
• Tests (unit, integration, api and/or acceptance) are included
• Screenshots before/after for front-end changes
• Documentation (manuals or wiki) has been updated or is not required
• Backports requested where applicable (ex: critical bugfixes)

[provokateurin]

The code comments in the controller are a bit useless, you might want to remove them to avoid confusion if the code is refactored later.

[provokateurin]

I think you could limit the Content-Type type to the possible values, so it's clear in the OpenAPI spec what might be returned.

[provokateurin]

Suggested change

	public function index(string $id, ?string $type = null, ?array $options = null, ?string $user = null) {
	public function export(string $id, ?string $type = null, ?array $options = null, ?string $user = null) {

[provokateurin]

Suggested change

	public function index(string $id, array $options, string $data, ?string $user = null): DataResponse {
	public function import(string $id, array $options, string $data, ?string $user = null): DataResponse {

[provokateurin]

Suggested change

	* @param array{rangeStart:string,rangeCount:int<1,max>} $options configuration options
	* @param array{rangeStart:string,rangeCount:positive-int} $options configuration options

[provokateurin]

Suggested change

	* @param array{format?:string, validation?:int<0,2>, errors?:int<0,1>, supersede?:bool, showCreated?:bool, showUpdated?:bool, showSkipped?:bool, showErrors?:bool} $options configuration options
	* @param array{format?:string, validation?:0|1|2, errors?:0|1, supersede?:bool, showCreated?:bool, showUpdated?:bool, showSkipped?:bool, showErrors?:bool} $options configuration options

[provokateurin]

Why have this options parameter instead of putting all of them into the parameters right away?

[provokateurin]

Suggested change

#[OpenAPI(scope: OpenAPI::SCOPE_DEFAULT)]

Not necessary

[provokateurin]

Suggested change

#[OpenAPI(scope: OpenAPI::SCOPE_DEFAULT)]

[provokateurin]

Suggested change

	* @since 32.0.0
	* @since 33.0.0

All @SInCE are wrong here

[provokateurin]

Suggested change

	* SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors
	* SPDX-License-Identifier: AGPL-3.0-only
	* SPDX-FileCopyrightText: 2025 Nextcloud GmbH and Nextcloud contributors
	* SPDX-License-Identifier: AGPL-3.0-or-later