1
0

ReferenceApiController.php 4.4 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150
  1. <?php
  2. declare(strict_types=1);
  3. /**
  4. * SPDX-FileCopyrightText: 2022 Nextcloud GmbH and Nextcloud contributors
  5. * SPDX-License-Identifier: AGPL-3.0-or-later
  6. */
  7. namespace OC\Core\Controller;
  8. use OCA\Core\ResponseDefinitions;
  9. use OCP\AppFramework\Http;
  10. use OCP\AppFramework\Http\Attribute\ApiRoute;
  11. use OCP\AppFramework\Http\DataResponse;
  12. use OCP\Collaboration\Reference\IDiscoverableReferenceProvider;
  13. use OCP\Collaboration\Reference\IReferenceManager;
  14. use OCP\Collaboration\Reference\Reference;
  15. use OCP\IRequest;
  16. /**
  17. * @psalm-import-type CoreReference from ResponseDefinitions
  18. * @psalm-import-type CoreReferenceProvider from ResponseDefinitions
  19. */
  20. class ReferenceApiController extends \OCP\AppFramework\OCSController {
  21. public function __construct(
  22. string $appName,
  23. IRequest $request,
  24. private IReferenceManager $referenceManager,
  25. private ?string $userId,
  26. ) {
  27. parent::__construct($appName, $request);
  28. }
  29. /**
  30. * @NoAdminRequired
  31. *
  32. * Extract references from a text
  33. *
  34. * @param string $text Text to extract from
  35. * @param bool $resolve Resolve the references
  36. * @param int $limit Maximum amount of references to extract
  37. * @return DataResponse<Http::STATUS_OK, array{references: array<string, CoreReference|null>}, array{}>
  38. *
  39. * 200: References returned
  40. */
  41. #[ApiRoute(verb: 'POST', url: '/extract', root: '/references')]
  42. public function extract(string $text, bool $resolve = false, int $limit = 1): DataResponse {
  43. $references = $this->referenceManager->extractReferences($text);
  44. $result = [];
  45. $index = 0;
  46. foreach ($references as $reference) {
  47. if ($index++ >= $limit) {
  48. break;
  49. }
  50. $result[$reference] = $resolve ? $this->referenceManager->resolveReference($reference)->jsonSerialize() : null;
  51. }
  52. return new DataResponse([
  53. 'references' => $result
  54. ]);
  55. }
  56. /**
  57. * @NoAdminRequired
  58. *
  59. * Resolve a reference
  60. *
  61. * @param string $reference Reference to resolve
  62. * @return DataResponse<Http::STATUS_OK, array{references: array<string, ?CoreReference>}, array{}>
  63. *
  64. * 200: Reference returned
  65. */
  66. #[ApiRoute(verb: 'GET', url: '/resolve', root: '/references')]
  67. public function resolveOne(string $reference): DataResponse {
  68. /** @var ?CoreReference $resolvedReference */
  69. $resolvedReference = $this->referenceManager->resolveReference(trim($reference))?->jsonSerialize();
  70. $response = new DataResponse(['references' => [$reference => $resolvedReference]]);
  71. $response->cacheFor(3600, false, true);
  72. return $response;
  73. }
  74. /**
  75. * @NoAdminRequired
  76. *
  77. * Resolve multiple references
  78. *
  79. * @param string[] $references References to resolve
  80. * @param int $limit Maximum amount of references to resolve
  81. * @return DataResponse<Http::STATUS_OK, array{references: array<string, CoreReference|null>}, array{}>
  82. *
  83. * 200: References returned
  84. */
  85. #[ApiRoute(verb: 'POST', url: '/resolve', root: '/references')]
  86. public function resolve(array $references, int $limit = 1): DataResponse {
  87. $result = [];
  88. $index = 0;
  89. foreach ($references as $reference) {
  90. if ($index++ >= $limit) {
  91. break;
  92. }
  93. $result[$reference] = $this->referenceManager->resolveReference($reference)?->jsonSerialize();
  94. }
  95. return new DataResponse([
  96. 'references' => $result
  97. ]);
  98. }
  99. /**
  100. * @NoAdminRequired
  101. *
  102. * Get the providers
  103. *
  104. * @return DataResponse<Http::STATUS_OK, CoreReferenceProvider[], array{}>
  105. *
  106. * 200: Providers returned
  107. */
  108. #[ApiRoute(verb: 'GET', url: '/providers', root: '/references')]
  109. public function getProvidersInfo(): DataResponse {
  110. $providers = $this->referenceManager->getDiscoverableProviders();
  111. $jsonProviders = array_map(static function (IDiscoverableReferenceProvider $provider) {
  112. return $provider->jsonSerialize();
  113. }, $providers);
  114. return new DataResponse($jsonProviders);
  115. }
  116. /**
  117. * @NoAdminRequired
  118. *
  119. * Touch a provider
  120. *
  121. * @param string $providerId ID of the provider
  122. * @param int|null $timestamp Timestamp of the last usage
  123. * @return DataResponse<Http::STATUS_OK, array{success: bool}, array{}>
  124. *
  125. * 200: Provider touched
  126. */
  127. #[ApiRoute(verb: 'PUT', url: '/provider/{providerId}', root: '/references')]
  128. public function touchProvider(string $providerId, ?int $timestamp = null): DataResponse {
  129. if ($this->userId !== null) {
  130. $success = $this->referenceManager->touchProvider($this->userId, $providerId, $timestamp);
  131. return new DataResponse(['success' => $success]);
  132. }
  133. return new DataResponse(['success' => false]);
  134. }
  135. }