feat: Add the possibility to create invitation links to circles

appinfo/routes.php

@@ -38,6 +38,10 @@
 		['name' => 'Local#editName', 'url' => '/circles/{circleId}/name', 'verb' => 'PUT'],
 		['name' => 'Local#editDescription', 'url' => '/circles/{circleId}/description', 'verb' => 'PUT'],
 		['name' => 'Local#editSetting', 'url' => '/circles/{circleId}/setting', 'verb' => 'PUT'],
+		['name' => 'Local#createInvitation', 'url' => '/circles/{circleId}/invitation', 'verb' => 'PUT'],
+		['name' => 'Local#revokeInvitation', 'url' => '/circles/{circleId}/invitation', 'verb' => 'DELETE'],
+		['name' => 'Local#getInvitation', 'url' => '/invitations/{invitationCode}', 'verb' => 'GET'],
+		['name' => 'Local#joinInvitation', 'url' => '/invitations/{invitationCode}', 'verb' => 'POST'],
 		['name' => 'Local#editConfig', 'url' => '/circles/{circleId}/config', 'verb' => 'PUT'],
 		['name' => 'Local#link', 'url' => '/link/{circleId}/{singleId}', 'verb' => 'GET'],
 

lib/Controller/LocalController.php

@@ -32,6 +32,9 @@
 use OCA\Circles\Service\SearchService;
 use OCA\Circles\Tools\Traits\TDeserialize;
 use OCA\Circles\Tools\Traits\TNCLogger;
+use OCP\AppFramework\Http;
+use OCP\AppFramework\Http\Attribute\NoAdminRequired;
+use OCP\AppFramework\Http\Attribute\UserRateLimit;
 use OCP\AppFramework\Http\DataResponse;
 use OCP\AppFramework\OCS\OCSException;
 use OCP\AppFramework\OCSController;
@@ -590,6 +593,120 @@ public function link(string $circleId, string $singleId): DataResponse {
 		}
 	}
 
+	/**
+	 * @param string $circleId
+	 *
+	 * @return DataResponse
+	 * @throws OCSException
+	 */
+	#[NoAdminRequired]
+	public function createInvitation(string $circleId): DataResponse {
+		try {
+			$this->setCurrentFederatedUser();
+
+			$outcome = $this->circleService->createInvitation($circleId);
+
+			return new DataResponse($this->serializeArray($outcome));
+		} catch (\Exception $e) {
+			$this->e($e, ['circleId' => $circleId]);
+			throw new OCSException($e->getMessage(), (int)$e->getCode(), $e);
+		}
+	}
+
+	/**
+	 * @param string $circleId
+	 *
+	 * @return DataResponse
+	 * @throws OCSException
+	 */
+	#[NoAdminRequired]
+	public function revokeInvitation(string $circleId): DataResponse {
+		try {
+			$this->setCurrentFederatedUser();
+
+			$outcome = $this->circleService->revokeInvitation($circleId);
+
+			return new DataResponse($this->serializeArray($outcome));
+		} catch (\Exception $e) {
+			$this->e($e, ['circleId' => $circleId]);
+			throw new OCSException($e->getMessage(), (int)$e->getCode(), $e);
+		}
+	}
+
+	/**
+	 * @param string $invitationCode
+	 *
+	 * @return DataResponse
+	 * @throws OCSException
+	 */
+	#[NoAdminRequired]
+	#[UserRateLimit(limit: 10, period: 3600)]
+	public function getInvitation(string $invitationCode): DataResponse {
+		try {
+			$this->setCurrentFederatedUser();
+
+			$circleProbe = (new CircleProbe())
+				->includeSystemCircles()
+				->includeHiddenCircles()
+				->filterByInvitationCode($invitationCode);
+
+			$circles = $this->circleService->getCircles($circleProbe);
+			if (empty($circles)) {
+				return new DataResponse([], Http::STATUS_NOT_FOUND);
+			}
+			$circle = reset($circles);
+
+			$membershipStatus = 'NOT_A_MEMBER';
+			if ($circle->hasInitiator()) {
+				if ($circle->getInitiator()->getLevel() > Member::LEVEL_NONE) {
+					$membershipStatus = 'MEMBER';
+				} elseif ($circle->getInitiator()->getStatus() === Member::STATUS_REQUEST) {
+					$membershipStatus = 'REQUESTED_MEMBERSHIP';
+				}
+			}
+
+			return new DataResponse([
+				'circleId' => $circle->getSingleId(),
+				'circleName' => $circle->getName(),
+				'membershipStatus' => $membershipStatus,
+			]);
+		} catch (\Exception $e) {
+			$this->e($e, ['circleId' => $invitationCode]);
+			throw new OCSException($e->getMessage(), (int)$e->getCode(), $e);
+		}
+	}
+
+	/**
+	 * @param string $invitationCode
+	 *
+	 * @return DataResponse
+	 * @throws OCSException
+	 */
+	#[NoAdminRequired]
+	#[UserRateLimit(limit: 10, period: 3600)]
+	public function joinInvitation(string $invitationCode): DataResponse {
+		try {
+			$this->setCurrentFederatedUser();
+
+			$circleProbe = (new CircleProbe())
+				->includeSystemCircles()
+				->includeHiddenCircles()
+				->filterByInvitationCode($invitationCode);
+
+			$circles = $this->circleService->getCircles($circleProbe);
+			if (empty($circles)) {
+				return new DataResponse([], Http::STATUS_NOT_FOUND);
+			}
+			$circle = reset($circles);
+
+			$result = $this->circleService->circleJoin($circle->getSingleId(), $invitationCode);
+
+			return new DataResponse($this->serializeArray($result));
+		} catch (\Exception $e) {
+			$this->e($e, ['circleId' => $invitationCode]);
+			throw new OCSException($e->getMessage(), (int)$e->getCode(), $e);
+		}
+	}
 
 	/**
 	 * @return void

lib/Db/CircleInvitationRequest.php

@@ -0,0 +1,55 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2021 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCA\Circles\Db;
+
+use OCA\Circles\Exceptions\InvalidIdException;
+use OCA\Circles\Model\CircleInvitation;
+
+/**
+ * Class CircleInvitationRequest
+ *
+ * @package OCA\Circles\Db
+ */
+class CircleInvitationRequest extends CircleRequestBuilder {
+	/**
+	 * @param CircleInvitation $circleInvitation
+	 *
+	 * @throws InvalidIdException
+	 */
+	public function save(CircleInvitation $circleInvitation): void {
+		$this->confirmValidId($circleInvitation->getCircleId());
+
+		$qb = $this->getCircleInvitationInsertSql();
+		$qb->setValue('circle_id', $qb->createNamedParameter($circleInvitation->getCircleId()))
+			->setValue('invitation_code', $qb->createNamedParameter($circleInvitation->getInvitationCode()))
+			->setValue('created_by', $qb->createNamedParameter($circleInvitation->getCreatedBy()));
+		$qb->executeStatement();
+	}
+
+	/**
+	 * @param CircleInvitation $circleInvitation
+	 *
+	 * @throws InvalidIdException
+	 */
+	public function replace(CircleInvitation $circleInvitation): void {
+		$this->delete($circleInvitation->getCircleId());
+		$this->save($circleInvitation);
+	}
+
+	/**
+	 * @param string $circleId
+	 */
+	public function delete(string $circleId): void {
+		$qb = $this->getCircleInvitationDeleteSql();
+		$qb->limitToCircleId($circleId);
+
+		$qb->executeStatement();
+	}
+}

lib/Db/CircleRequest.php

@@ -167,13 +167,17 @@ public function getCircles(?IFederatedUser $initiator, CircleProbe $probe): arra
 			$qb->limitToInitiator(CoreQueryBuilder::CIRCLE, $initiator);
 			$qb->orderBy($qb->generateAlias(CoreQueryBuilder::CIRCLE, CoreQueryBuilder::INITIATOR) . '.level', 'desc');
 			$qb->addOrderBy(CoreQueryBuilder::CIRCLE . '.display_name', 'asc');
+			$qb->leftJoinCircleInvitation(CoreQueryBuilder::CIRCLE);
 		}
 		if ($probe->hasFilterMember()) {
 			$qb->limitToDirectMembership(CoreQueryBuilder::CIRCLE, $probe->getFilterMember());
 		}
 		if ($probe->hasFilterCircle()) {
 			$qb->filterCircleDetails($probe->getFilterCircle());
 		}
+		if ($probe->hasInvitationCode()) {
+			$qb->filterInvitationCode(CoreQueryBuilder::CIRCLE, $probe->getInvitationCode());
+		}
 		if ($probe->hasFilterRemoteInstance()) {
 			$qb->limitToRemoteInstance(CoreQueryBuilder::CIRCLE, $probe->getFilterRemoteInstance(), false);
 		}
@@ -369,6 +373,7 @@ public function getCircle(
 		$qb->limitToUniqueId($id);
 		$qb->filterCircles(CoreQueryBuilder::CIRCLE, $probe);
 		$qb->leftJoinOwner(CoreQueryBuilder::CIRCLE);
+		$qb->leftJoinCircleInvitation(CoreQueryBuilder::CIRCLE);
 		//		$qb->setOptions(
 		//			[CoreRequestBuilder::CIRCLE, CoreRequestBuilder::INITIATOR], [
 		//																		   'mustBeMember' => false,

lib/Db/CircleRequestBuilder.php

@@ -33,6 +33,16 @@ protected function getCircleInsertSql(): CoreQueryBuilder {
 		return $qb;
 	}
 
+	/**
+	 * @return CoreQueryBuilder&IQueryBuilder
+	 */
+	protected function getCircleInvitationInsertSql(): CoreQueryBuilder {
+		$qb = $this->getQueryBuilder();
+		$qb->insert(self::TABLE_INVITATIONS)
+			->setValue('created', $qb->createNamedParameter($this->timezoneService->getUTCDate()));
+
+		return $qb;
+	}
 
 	/**
 	 * @return CoreQueryBuilder&IQueryBuilder
@@ -44,7 +54,6 @@ protected function getCircleUpdateSql(): CoreQueryBuilder {
 		return $qb;
 	}
 
-
 	/**
 	 * @param string $alias
 	 * @param bool $single
@@ -65,7 +74,6 @@ protected function getCircleSelectSql(
 		return $qb;
 	}
 
-
 	/**
 	 * Base of the Sql Delete request
 	 *
@@ -78,6 +86,17 @@ protected function getCircleDeleteSql(): CoreQueryBuilder {
 		return $qb;
 	}
 
+	/**
+	 * Base of the Sql Delete request
+	 *
+	 * @return CoreQueryBuilder&IQueryBuilder
+	 */
+	protected function getCircleInvitationDeleteSql(): CoreQueryBuilder {
+		$qb = $this->getQueryBuilder();
+		$qb->delete(self::TABLE_INVITATIONS);
+
+		return $qb;
+	}
 
 	/**
 	 * @param CoreQueryBuilder&IQueryBuilder $qb

lib/Db/CoreQueryBuilder.php

@@ -59,7 +59,7 @@ class CoreQueryBuilder extends ExtendedQueryBuilder {
 	public const TOKEN = 'u';
 	public const OPTIONS = 'v';
 	public const HELPER = 'w';
-
+	public const INVITATION = 'x';
 
 	public static $SQL_PATH = [
 		self::SINGLE => [
@@ -69,6 +69,7 @@ class CoreQueryBuilder extends ExtendedQueryBuilder {
 			self::OPTIONS => [
 			],
 			self::MEMBER,
+			self::INVITATION,
 			self::OWNER => [
 				self::BASED_ON
 			],
@@ -839,6 +840,30 @@ public function leftJoinOwner(string $alias, string $field = 'unique_id'): void
 		$this->leftJoinBasedOn($aliasMember);
 	}
 
+	/**
+	 * @param string $alias
+	 * @param string $field
+	 *
+	 * @throws RequestBuilderException
+	 */
+	public function leftJoinCircleInvitation(string $alias, string $field = 'unique_id'): void {
+		if ($this->getType() !== QueryBuilder::SELECT) {
+			return;
+		}
+
+		try {
+			$aliasInvitation = $this->generateAlias($alias, self::INVITATION, $options);
+		} catch (RequestBuilderException $e) {
+			return;
+		}
+
+		$expr = $this->expr();
+		$this->generateCircleInvitationSelectAlias($aliasInvitation)
+			->leftJoin(
+				$alias, CoreRequestBuilder::TABLE_INVITATIONS, $aliasInvitation,
+				$expr->eq($aliasInvitation . '.circle_id', $alias . '.' . $field),
+			);
+	}
 
 	/**
 	 * @param CircleProbe $probe
@@ -1308,6 +1333,12 @@ protected function limitInitiatorVisibility(string $alias): ICompositeExpression
 		$aliasMembershipCircle = $this->generateAlias($aliasMembership, self::CONFIG, $options);
 		$levelCheck = [$aliasMembership];
 
+		// no need to check anything, we are filtering by invitation code
+		$invitationCode = $this->get('filterInvitationCode', $options, '');
+		if ($invitationCode) {
+			return $this->expr()->andX($this->expr()->eq('1', '1'));
+		}
+
 		$directMember = '';
 		if ($this->getBool('initiatorDirectMember', $options, false)) {
 			$directMember = $this->generateAlias($alias, self::DIRECT_INITIATOR, $options);
@@ -1522,6 +1553,27 @@ public function limitToShareOwner(
 		}
 	}
 
+	/**
+	 * filter circle by invitation code
+	 *
+	 * @param string $invitationCode
+	 */
+	public function filterInvitationCode(string $alias, string $invitationCode): void {
+		if ($this->getType() !== QueryBuilder::SELECT) {
+			return;
+		}
+
+		try {
+			$aliasInvitation = $this->generateAlias($alias, self::INVITATION, $options);
+		} catch (RequestBuilderException $e) {
+			return;
+		}
+
+		$expr = $this->expr();
+		$this->andWhere(
+			$expr->eq($aliasInvitation . '.invitation_code', $this->createNamedParameter($invitationCode))
+		);
+	}
 
 	/**
 	 * @param string $aliasMount
@@ -1584,6 +1636,23 @@ private function generateMemberSelectAlias(string $alias, array $default = []):
 		return $this;
 	}
 
+	/**
+	 * @param string $alias
+	 * @param array $default
+	 *
+	 * @return $this
+	 */
+	private function generateCircleInvitationSelectAlias(string $alias, array $default = []): self {
+		$this->generateSelectAlias(
+			CoreRequestBuilder::$tables[CoreRequestBuilder::TABLE_INVITATIONS],
+			$alias,
+			$alias,
+			$default
+		);
+
+		return $this;
+	}
+
 
 	/**
 	 * @param string $alias