Add ability to create, update project invitiations

[kelvin-muchiri]

Suggested Feature / Enhancement

Add endpoints that will add ability to create, update a project invitation. The project invitation will allow a non-existing user to be invited to a project.

The project admin will enter the email address of the unregistered user to invite and their role for each project. An email will be sent to the recipient with an invite link that will allow them to create an account. After creating the account, the recipient will automatically have access to all projects they have been invited to as long as they register using the same email which the invitation was sent to

Benefits of implementing the feature/enhancement

Currently, you can only invite a registered user to a project. To invite an unregistered user, you'd have to inform them to create an account first then invite them to a project. This feature squashes the two processes into one process eliminating the extra overhead.

Suggested implementation plan(Steps to be taken to implement feature)

Project Invitation Model

The model will contain the following fields:

• pk: auto-generated int/uuid
• email: The email address of a non-registered user being invited
• project: A foreign key to the the project a user has been invited to
• role: The role of the invited user for the project
• status: An enum for the status of the invitation. Possible values are Pending = 1, Accepted = 2, Revoked = 3. Default value will be Pending
• invited_by: The user who created the invitation.
• accepted_by: The user who accepted the invitation.
• created_at: The date and time the invitation was created
• accepted_at: The date and time the invitation was accepted
• resent_at: The date and time the invitation was last resent
• revoked_at: The date and time the invitation was revoked

List of Project Invitations

GET /api/v1/projects/{pk}/invitations

Response

[
   {
      "id": 1,
      "email":"[email protected]",
      "status": 1,
      "role":"readonly"
   },
   {
      "id": 2,
      "email":"[email protected]",
      "status": 1,
      "role":"editor"
   }
]

Create a Project Invitation

POST /api/v1/projects/{pk}/invitations

Payload

{
   "email": "[email protected]",
   "role": "editor"
}

email: The email address of the unregistered user.

• Should be a valid email. If the project invitation email domain whitelist has been enabled, then the email domain has to be in the whitelist for it to be also valid
• Email should not be that of a registered user

role: The user's role for the project.

• Must be a valid role

Response

{
    "id": 6,
    "email": "[email protected]",
    "role": "editor",
    "status": 1
}

Updating a project invitation

PUT /api/v1/projects/{project_pk}/invitations

Payload

{
   "email": "[email protected]",
   "role": "readonly",
   "invitation_id": 6
}

Response

{
    "id": 6,
    "email": "[email protected]",
    "role": "readonly",
    "status": 1
}

Resend a Project Invitation

Endpoint POST /api/v1/projects/{pk}/resend-invitation

Payload

{
  "invitation_id": "6"
}

invitation_id: The primary key of the ProjectInvitation to resend. Must be a ProjectInvitation whose status is Pending

Response

{
    "message": "Success"
}

Revoke a Project Invitation

Endpoint POST /api/v1/projects/{pk}/revoke-invitation

Payload

{
  "invitation_id": "6"
}

invitation_id: The primary key of the ProjectInvitation to resend. Must be a ProjectInvitation whose status is Pending

Response

{
    "message": "Success"
}

Sending the invite

The invitation should be sent asynchronously upon successful creation of an invitation or resend request.

The link embedded in the email will be of the format http://{url}
where:

• url - is the URL the recipient will be redirected to on clicking the link. The default is {domain}/api/v1/profiles where domain is domain where the API is hosted.

Normally, you would want the email recipient to be redirected to a web app. This can be achieved by
adding the setting PROJECT_INVITATION_URL

Example

    PROJECT_INVITATION_URL = 'https://example.com/register'

Accepting the invite

Since a project invitation is sent to an unregistered user, acceptance of the invitation is handled
when creating a new user.

All pending invitations whose email match the new user's email will be accepted and projects shared with the
user