ReferenceApiController.php 5.1 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167
  1. <?php
  2. declare(strict_types=1);
  3. /**
  4. * @copyright Copyright (c) 2022 Julius Härtl <jus@bitgrid.net>
  5. *
  6. * @author Julius Härtl <jus@bitgrid.net>
  7. * @author Kate Döen <kate.doeen@nextcloud.com>
  8. *
  9. * @license GNU AGPL version 3 or any later version
  10. *
  11. * This program is free software: you can redistribute it and/or modify
  12. * it under the terms of the GNU Affero General Public License as
  13. * published by the Free Software Foundation, either version 3 of the
  14. * License, or (at your option) any later version.
  15. *
  16. * This program is distributed in the hope that it will be useful,
  17. * but WITHOUT ANY WARRANTY; without even the implied warranty of
  18. * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  19. * GNU Affero General Public License for more details.
  20. *
  21. * You should have received a copy of the GNU Affero General Public License
  22. * along with this program. If not, see <http://www.gnu.org/licenses/>.
  23. */
  24. namespace OC\Core\Controller;
  25. use OCA\Core\ResponseDefinitions;
  26. use OCP\AppFramework\Http;
  27. use OCP\AppFramework\Http\Attribute\ApiRoute;
  28. use OCP\AppFramework\Http\DataResponse;
  29. use OCP\Collaboration\Reference\IDiscoverableReferenceProvider;
  30. use OCP\Collaboration\Reference\IReferenceManager;
  31. use OCP\Collaboration\Reference\Reference;
  32. use OCP\IRequest;
  33. /**
  34. * @psalm-import-type CoreReference from ResponseDefinitions
  35. * @psalm-import-type CoreReferenceProvider from ResponseDefinitions
  36. */
  37. class ReferenceApiController extends \OCP\AppFramework\OCSController {
  38. public function __construct(
  39. string $appName,
  40. IRequest $request,
  41. private IReferenceManager $referenceManager,
  42. private ?string $userId,
  43. ) {
  44. parent::__construct($appName, $request);
  45. }
  46. /**
  47. * @NoAdminRequired
  48. *
  49. * Extract references from a text
  50. *
  51. * @param string $text Text to extract from
  52. * @param bool $resolve Resolve the references
  53. * @param int $limit Maximum amount of references to extract
  54. * @return DataResponse<Http::STATUS_OK, array{references: array<string, CoreReference|null>}, array{}>
  55. *
  56. * 200: References returned
  57. */
  58. #[ApiRoute(verb: 'POST', url: '/extract', root: '/references')]
  59. public function extract(string $text, bool $resolve = false, int $limit = 1): DataResponse {
  60. $references = $this->referenceManager->extractReferences($text);
  61. $result = [];
  62. $index = 0;
  63. foreach ($references as $reference) {
  64. if ($index++ >= $limit) {
  65. break;
  66. }
  67. $result[$reference] = $resolve ? $this->referenceManager->resolveReference($reference)->jsonSerialize() : null;
  68. }
  69. return new DataResponse([
  70. 'references' => $result
  71. ]);
  72. }
  73. /**
  74. * @NoAdminRequired
  75. *
  76. * Resolve a reference
  77. *
  78. * @param string $reference Reference to resolve
  79. * @return DataResponse<Http::STATUS_OK, array{references: array<string, ?CoreReference>}, array{}>
  80. *
  81. * 200: Reference returned
  82. */
  83. #[ApiRoute(verb: 'GET', url: '/resolve', root: '/references')]
  84. public function resolveOne(string $reference): DataResponse {
  85. /** @var ?CoreReference $resolvedReference */
  86. $resolvedReference = $this->referenceManager->resolveReference(trim($reference))?->jsonSerialize();
  87. $response = new DataResponse(['references' => [$reference => $resolvedReference]]);
  88. $response->cacheFor(3600, false, true);
  89. return $response;
  90. }
  91. /**
  92. * @NoAdminRequired
  93. *
  94. * Resolve multiple references
  95. *
  96. * @param string[] $references References to resolve
  97. * @param int $limit Maximum amount of references to resolve
  98. * @return DataResponse<Http::STATUS_OK, array{references: array<string, CoreReference|null>}, array{}>
  99. *
  100. * 200: References returned
  101. */
  102. #[ApiRoute(verb: 'POST', url: '/resolve', root: '/references')]
  103. public function resolve(array $references, int $limit = 1): DataResponse {
  104. $result = [];
  105. $index = 0;
  106. foreach ($references as $reference) {
  107. if ($index++ >= $limit) {
  108. break;
  109. }
  110. $result[$reference] = $this->referenceManager->resolveReference($reference)?->jsonSerialize();
  111. }
  112. return new DataResponse([
  113. 'references' => $result
  114. ]);
  115. }
  116. /**
  117. * @NoAdminRequired
  118. *
  119. * Get the providers
  120. *
  121. * @return DataResponse<Http::STATUS_OK, CoreReferenceProvider[], array{}>
  122. *
  123. * 200: Providers returned
  124. */
  125. #[ApiRoute(verb: 'GET', url: '/providers', root: '/references')]
  126. public function getProvidersInfo(): DataResponse {
  127. $providers = $this->referenceManager->getDiscoverableProviders();
  128. $jsonProviders = array_map(static function (IDiscoverableReferenceProvider $provider) {
  129. return $provider->jsonSerialize();
  130. }, $providers);
  131. return new DataResponse($jsonProviders);
  132. }
  133. /**
  134. * @NoAdminRequired
  135. *
  136. * Touch a provider
  137. *
  138. * @param string $providerId ID of the provider
  139. * @param int|null $timestamp Timestamp of the last usage
  140. * @return DataResponse<Http::STATUS_OK, array{success: bool}, array{}>
  141. *
  142. * 200: Provider touched
  143. */
  144. #[ApiRoute(verb: 'PUT', url: '/provider/{providerId}', root: '/references')]
  145. public function touchProvider(string $providerId, ?int $timestamp = null): DataResponse {
  146. if ($this->userId !== null) {
  147. $success = $this->referenceManager->touchProvider($this->userId, $providerId, $timestamp);
  148. return new DataResponse(['success' => $success]);
  149. }
  150. return new DataResponse(['success' => false]);
  151. }
  152. }