nextcloud-shortcuts/lib/Controller/ApiController.php

<?php

declare(strict_types=1);

/**
 * SPDX-FileCopyrightText: 2026 Lukas Schaefer
 * SPDX-License-Identifier: AGPL-3.0-or-later
 */

namespace OCA\Shortcuts\Controller;

use OCA\Shortcuts\Exception\ConflictException;
use OCA\Shortcuts\Exception\ForbiddenException;
use OCA\Shortcuts\Exception\InvalidPathException;
use OCA\Shortcuts\Exception\NotFoundException;
use OCA\Shortcuts\Service\ShortcutService;
use OCP\AppFramework\Http;
use OCP\AppFramework\Http\Attribute\ApiRoute;
use OCP\AppFramework\Http\Attribute\NoAdminRequired;
use OCP\AppFramework\Http\DataResponse;
use OCP\AppFramework\OCS\OCSBadRequestException;
use OCP\AppFramework\OCS\OCSForbiddenException;
use OCP\AppFramework\OCS\OCSNotFoundException;
use OCP\AppFramework\OCSController;
use OCP\IRequest;
use OCP\IUserSession;

/**
 * @psalm-suppress UnusedClass
 */
class ApiController extends OCSController {
	public function __construct(
		string $appName,
		IRequest $request,
		private ShortcutService $shortcutService,
		private IUserSession $userSession,
	) {
		parent::__construct($appName, $request);
	}

	/**
	 * Create a personal shortcut file
	 *
	 * @param int $fileId Target file or folder id
	 * @param string $destinationPath Destination folder path relative to the user files root
	 * @param ?string $name Optional shortcut file name
	 * @return DataResponse<Http::STATUS_OK, array{fileId: int, name: string, path: string, targetFileId: int, targetType: string}, array{}>
	 * @throws OCSBadRequestException Invalid request or name conflict
	 * @throws OCSForbiddenException Forbidden
	 * @throws OCSNotFoundException Target or destination not found
	 *
	 * 200: Shortcut created
	 * 400: Invalid request or name conflict
	 * 403: Forbidden
	 * 404: Target or destination not found
	 */
	#[NoAdminRequired]
	#[ApiRoute(verb: 'POST', url: '/api/v1/shortcuts')]
	public function create(int $fileId, string $destinationPath, ?string $name = null): DataResponse {
		$user = $this->userSession->getUser();
		if ($user === null) {
			throw new OCSForbiddenException('Not logged in');
		}

		try {
			return new DataResponse($this->shortcutService->create($user, $fileId, $destinationPath, $name));
		} catch (ConflictException|InvalidPathException $e) {
			throw new OCSBadRequestException($e->getMessage());
		} catch (ForbiddenException $e) {
			throw new OCSForbiddenException($e->getMessage());
		} catch (NotFoundException $e) {
			throw new OCSNotFoundException($e->getMessage());
		}
	}

	/**
	 * Resolve a shortcut stub to its target
	 *
	 * @param int $fileId Shortcut stub file id
	 * @return DataResponse<Http::STATUS_OK, array{targetFileId: int, targetType: string, name: string, path: string, dirname: string}, array{}>
	 * @throws OCSBadRequestException Invalid shortcut
	 * @throws OCSForbiddenException Forbidden
	 * @throws OCSNotFoundException Not found
	 *
	 * 200: Target resolved
	 * 400: Invalid shortcut
	 * 403: Forbidden
	 * 404: Not found
	 */
	#[NoAdminRequired]
	#[ApiRoute(verb: 'GET', url: '/api/v1/shortcuts/resolve')]
	public function resolve(int $fileId): DataResponse {
		$user = $this->userSession->getUser();
		if ($user === null) {
			throw new OCSForbiddenException('Not logged in');
		}

		try {
			return new DataResponse($this->shortcutService->resolve($user, $fileId));
		} catch (ForbiddenException $e) {
			throw new OCSForbiddenException($e->getMessage());
		} catch (NotFoundException $e) {
			throw new OCSNotFoundException($e->getMessage());
		} catch (InvalidPathException $e) {
			throw new OCSBadRequestException($e->getMessage());
		}
	}
}