Add ability to create, update project invitations

docs/projects.rst

@@ -8,6 +8,7 @@ Where:
 - ``pk`` - is the project id
 - ``formid`` - is the form id
 - ``owner`` - is the username for the user or organization of the project
+- ``invitation_pk`` - is the project invitation id
 
 Register a new Project
 -----------------------
@@ -515,3 +516,239 @@ Get user profiles that have starred a project
 
 	<pre class="prettyprint">
 	<b>GET</b> /api/v1/projects/<code>{pk}</code>/star</pre>
+
+Get Project Invitation List
+---------------------------
+
+.. raw:: html
+
+	<pre class="prettyprint"><b>GET</b> /api/v1/projects/{pk}/invitations</pre>
+
+Example
+^^^^^^^
+
+::
+
+        curl -X GET https://api.ona.io/api/v1/projects/1/invitations
+
+Response
+^^^^^^^^
+
+::
+
+        [
+            {
+                "id": 1,
+                "email":"[email protected]",
+                "role":"readonly",
+                "status": 1
+
+            },
+            {
+                "id": 2,
+                "email":"[email protected]",
+                "role":"editor",
+                "status": 2,
+            }
+        ]
+
+Get a list of project invitations with a specific status
+--------------------------------------------------------
+
+The available choices are:
+
+- ``1`` - Pending. Invitations which have not been accepted by recipients.
+- ``2`` - Accepted. Invitations which have been accepted by recipients.
+- ``3`` - Revoked. Invitations which were cancelled.
+
+
+.. raw:: html
+
+	<pre class="prettyprint"><b>GET</b> /api/v1/projects/{pk}/invitations?status=2</pre>
+
+
+Example
+^^^^^^^
+
+::
+
+        curl -X GET https://api.ona.io/api/v1/projects/1/invitations?status=2
+
+Response
+^^^^^^^^
+
+::
+
+        [
+
+            {
+                "id": 2,
+                "email":"[email protected]",
+                "role":"editor",
+                "status": 2,
+            }
+        ]
+
+
+Create a new project invitation
+-------------------------------
+
+Invite an **unregistered** user to a project. An email will be sent to the user which has a link for them to
+create an account.
+
+.. raw:: html
+
+	<pre class="prettyprint"><b>POST</b> /api/v1/projects/{pk}/invitations</pre>
+
+Example
+^^^^^^^
+
+::
+
+        curl -X POST -d "[email protected]" -d "role=readonly" https://api.ona.io/api/v1/projects/1/invitations
+
+
+``email``: The email address of the unregistered user.
+
+- Should be a valid email. If the ``PROJECT_INVITATION_EMAIL_DOMAIN_WHITELIST`` setting has been enabled, then the email domain has to be in the whitelist for it to be also valid
+
+**Example**
+
+::
+
+    PROJECT_INVITATION_EMAIL_DOMAIN_WHITELIST=["foo.com", "bar.com"]
+
+- Email should not be that of a registered user
+
+``role``: The user's role for the project.
+
+- Must be a valid role
+
+
+Response
+^^^^^^^^
+
+::
+
+        {
+            "id": 1,
+            "email": "[email protected]",
+            "role": "readonly",
+            "status": 1,
+        }
+
+
+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'
+
+
+Update a project invitation
+---------------------------
+
+.. raw:: html
+
+	<pre class="prettyprint">
+    <b>PUT</b> /api/v1/projects/{pk}/invitations
+    </pre>
+
+
+Example
+^^^^^^^
+
+::
+
+        curl -X PUT -d "[email protected]" -d "role=editor" -d "invitation_id=1"  https://api.ona.io/api/v1/projects/1/invitations/1
+
+Response
+^^^^^^^^
+
+::
+
+        {
+            "id": 1,
+            "email": "[email protected]",
+            "role": "editor",
+            "status": 1,
+        }
+
+
+Resend a project invitation
+---------------------------
+
+Resend a project invitation email
+
+.. raw:: html
+
+	<pre class="prettyprint"><b>POST</b> /api/v1/projects/{pk}/resend-invitation</pre>
+
+Example
+^^^^^^^
+
+::
+
+        curl -X POST -d "invitation_id=6" https://api.ona.io/api/v1/projects/1/resend-invitation
+
+
+``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
+---------------------------
+
+Cancel a project invitation. A revoked invitation means that project will **not** be shared with the new user
+even if they accept the invitation.
+
+.. raw:: html
+
+	<pre class="prettyprint"><b>POST</b> /api/v1/projects/{pk}/revoke-invitation</pre>
+
+Example
+^^^^^^^
+
+::
+
+        curl -X POST -d "invitation_id=6" https://api.ona.io/api/v1/projects/1/revoke-invitation
+
+``invitation_id``: The primary key of the ``ProjectInvitation`` to resend. 
+
+- Must be a ``ProjectInvitation`` whose status is **Pending**
+
+Response
+^^^^^^^^
+
+::
+
+        {
+            "message": "Success"
+        }
+
+
+Accept a project invitation
+---------------------------
+
+Since a project invitation is sent to an unregistered user, acceptance of the invitation is handled
+when `creating a new user <https://github.com/onaio/onadata/blob/main/docs/profiles.rst#register-a-new-user>`_.
+
+All pending invitations whose email match the new user's email will be accepted and projects shared with the
+user

onadata/apps/api/permissions.py

@@ -191,7 +191,6 @@ def has_permission(self, request, view):
         is_authenticated = request and request.user.is_authenticated
 
         if is_authenticated and view.action == "create":
-
             # Handle bulk create
             # if doing a bulk create we will fail the entire process if the
             # user lacks permissions for even one instance
@@ -278,6 +277,12 @@ def has_object_permission(self, request, view, obj):
             if remove and request.user.username.lower() == username.lower():
                 return True
 
+        if view.action == "invitations" and not (
+            ManagerRole.user_has_role(request.user, obj)
+            or OwnerRole.user_has_role(request.user, obj)
+        ):
+            return False
+
         return super().has_object_permission(request, view, obj)
 
 
@@ -306,7 +311,6 @@ def has_permission(self, request, view):
             and (request.user.is_authenticated or not self.authenticated_users_only)
             and request.user.has_perms(perms)
         ):
-
             return True
 
         return False
@@ -387,7 +391,6 @@ class UserViewSetPermissions(DjangoModelPermissionsOrAnonReadOnly):
     """
 
     def has_permission(self, request, view):
-
         if request.user.is_anonymous and view.action == "list":
             if request.GET.get("search"):
                 raise exceptions.NotAuthenticated()

onadata/apps/api/tasks.py

@@ -4,6 +4,7 @@
 """
 import os
 import sys
+import logging
 from datetime import timedelta
 
 from celery.result import AsyncResult
@@ -17,7 +18,8 @@
 from onadata.apps.api import tools
 from onadata.libs.utils.email import send_generic_email
 from onadata.libs.utils.model_tools import queryset_iterator
-from onadata.apps.logger.models import Instance, XForm
+from onadata.apps.logger.models import Instance, ProjectInvitation, XForm
+from onadata.libs.utils.email import ProjectInvitationEmail
 from onadata.celeryapp import app
 
 User = get_user_model()
@@ -127,3 +129,19 @@ def delete_inactive_submissions():
         for instance in queryset_iterator(instances):
             # delete submission
             instance.delete()
+
+
+@app.task()
+def send_project_invitation_email_async(
+    invitation_id: str, url: str
+):  # pylint: disable=invalid-name
+    """Sends project invitation email asynchronously"""
+    try:
+        invitation = ProjectInvitation.objects.get(id=invitation_id)
+
+    except ProjectInvitation.DoesNotExist as err:
+        logging.exception(err)
+
+    else:
+        email = ProjectInvitationEmail(invitation, url)
+        email.send()

onadata/apps/api/tests/test_tasks.py

@@ -0,0 +1,32 @@
+"""Tests for module onadata.apps.api.tasks"""
+
+from unittest.mock import patch
+
+from onadata.apps.main.tests.test_base import TestBase
+from onadata.apps.api.tasks import (
+    send_project_invitation_email_async,
+)
+from onadata.apps.logger.models import ProjectInvitation
+from onadata.libs.utils.user_auth import get_user_default_project
+from onadata.libs.utils.email import ProjectInvitationEmail
+
+
+class SendProjectInivtationEmailAsyncTestCase(TestBase):
+    """Tests for send_project_invitation_email_async"""
+
+    def setUp(self) -> None:
+        super().setUp()
+
+        project = get_user_default_project(self.user)
+        self.invitation = ProjectInvitation.objects.create(
+            project=project,
+            email="[email protected]",
+            role="manager",
+        )
+
+    @patch.object(ProjectInvitationEmail, "send")
+    def test_sends_email(self, mock_send):
+        """Test email is sent"""
+        url = "https://example.com/register"
+        send_project_invitation_email_async(self.invitation.id, url)
+        mock_send.assert_called_once()