Initial Setup

[Juknum]

• I've read the code of conduct 🇫🇷.

Description

Implementation of most generics endpoints for the API.

Removed

• GraphQL has been removed in favor of REST endpoints. This is due to the lack of support for multipart/form-data requests in GraphQL.

Added

Permissions

Decorators

• @GuardPermissions: Decorator to check if the request user has the required permissions to access the endpoint.

   @UseGuards(PermissionGuard)
   @GuardPermissions('CAN_EDIT_USER')
   example() {
   	// ...
   }

• @GuardSelfParam: Decorator to check if the request user is the owner of the requested resource.

   @Get(':id')
   @UseGuards(SelfGuard)
   @GuardSelf('id')
   example(@Param('id') user_id: string) {
   	// ...
   }

• @GuardSelfOrPermissions: Decorator to check if the request user has the required permissions or if he is the owner of the requested resource.

   @Get(':id')
   @UseGuards(SelfOrPermissionGuard)
   @GuardSelfOrPermissions('id', ['ROOT'])
   example(@Param('id') user_id: string) {
   	// ...
   }

• @GuardSubscribed: Decorator to check if the request user is subscribed.

   @UseGuards(SubscribedGuard)
   example() {
   	// ...
   }

• @GuardSelfOrSubscribed: Decorator to check if the request user is the owner of the requested resource or if he is subscribed.

   @Get(':id')
   @UseGuards(SelfOrSubscribedGuard)
   @GuardSelfOrSubscribed('id')
   example(@Param('id') user_id: string) {
   	// ...
   }

• @GuardSelfOrSubscribed: Decorator to check if the request user is the owner of the requested resource or if he is subscribed or if he has the required permissions.

   @Get(':id')
   @UseGuards(SelfOrPermsOrSubGuard)
   @GuardSelfOrPermsOrSub('id', ['ROOT'])
   example(@Param('id') user_id: string) {
   	// ...
   }

Permissions

• Each user has a collection of permissions, empty by default.
• All available permissions are defined in the src/exported/api/constants/perms.ts file.
• Permissions expire after their expiration date. A CRON job runs every 10 minutes to revoke expired permissions. (see PermissionsService)

Roles

• Each user has a collection of roles, empty by default.
• A role is basically a collection of permissions. One role can be assigned to multiple users.
• When assigned to users, a RoleExpiration will be created for each user which contains the expiration date of the role for that user.
• Roles does not expires, but their assignation does. A CRON job runs every 10 minutes to revoke expired roles. (see RolesService)
• While a role does not expires, it can still be revoked globally (setting its revoked field to true). This will revoke the role for all users that have it assigned.

Authentification

• All endpoints are protected by default. To access them, you need to provide a valid JWT token in the Authorization header.
• To get a valid JWT token, you need to login with your email and password. A JWT token will be returned if the login is successful.
• When a user creates an account or update its email, a confirmation email is sent to the user. The user needs to click on the link in the email to confirm its email address. The link will redirect the user to the API with a token query parameter. This token is used to confirm the email address of the user.

Logs

• Each authenticated request is logged to the corresponding logged user (via the JWT token). Unauthenticated users are not concerned.
• A CRON job runs every day at 7:00 AM to delete logs older than 30 days.

Promotions

• A new promotion is created each year on July 15th.
• At the moment, promotions are limited to a collection of users and a logo.

Users

• Users can be created without a password by admins. The password is generated and sent to the user via email.
• Users can be updated by admins or by themselves.
• Users can only be deleted by themselves.
• Subscribed users are currently defined by a boolean (temporary solution).
• User picture should be 1:1 ratio.
• User banner should be 16:9 ratio.
• Both user picture and banner are in the SUBSCRIBER visibility group. This means that only subscribed users can access them (owner or admin can access them too, see Files section).

Files

• Each file can have a visibility group. This group defines who can access the file. For a user to access a file, he needs to be in the visibility group of the file, to be an admin or to own the file.
• If the file does not have a visibility group, it is considered as public and can be accessed by anyone (unless permissions guards are used on the endpoint).

Translations

• Translations are managed by the @nestjs/i18n module and the translate service TranslateService, the source files are in the src/i18n/en-US folder.

Example on how to add and use a translation

// src/i18n/en-US/responses.json
{
	"error": {
		"id": {
			"not_found": "The {type} with id {id} was not found",
			// ...
		}
		// ...
	}
}

// Implementation
class TranslateService {
	// ...

	public readonly Errors = {
		Id: {
			NotFound: <T>(type: Class<T> | string, id: string | number) => 
				this.generic('responses.errors.id.not_found', { type, id }),
			// ...
		},
		// ...
	}
}

// Usage
class FooService {
	constructor(private readonly t: TranslateService) {}

	bar(): string {
		return this.t.Errors.Id.NotFound(User, 1);
	}
}

Swagger

• Swagger documentation is available at http://localhost:3000/.

Linked PRs

• To be merged before: [API] Mise en place MikroORM core#1