feat: Add PATCH endpoint to defer a task (#78)

* feat(tasks): Add PATCH endpoint to defer tasks

 introduces a new feature allowing users to defer a task to a future date. A task can be deferred by making a PATCH request to the task detail endpoint with the action=defer query parameter.

- A new route in TaskDetailView that handles PATCH requests with ?action=defer.
- DeferTaskSerializer to validate the incoming deferredTill timestamp, ensuring it is a future date.
- A new defer_task method in TaskService containing the core business logic. This includes a validation rule that prevents deferring a task too close to its due date.
- The TaskModel has been updated with a deferredDetails field to store information about the deferral.
- A custom UnprocessableEntityException has been added to handle business rule violations, which the global exception handler now processes into a 422 HTTP response.

* refactor: refactor the codes according to the bot suggestions

* refactor: refactor the codes according to the bot suggestions

* Update todo/constants/messages.py

Co-authored-by: Anuj Chhikara <[email protected]>

* refactor:  robust task deferral endpoint

refactor the PATCH /tasks/{id}?action=defer API with extensive error handling and improved business logic based on code reviews.

- Adds a  error when deferring a  task.
- Enforces a configurable notice period for deferrals close to the due date.
- Hardens the API by validating the  parameter strictly.
- Refactors exception handling to be more specific and robust.
- Improves test coverage for new service logic, views, and exceptions.

* fix(task-service): normalise datetimes in defer_task to avoid naive/aware clash

- Force deferred_till to be UTC-aware if it arrives naive.
- Convert stored dueAt to UTC-aware before applying the minimum-notice rule.
- Prevents TypeError: can't compare offset-naive and offset-aware datetimes, eliminating 500 responses on PATCH /v1/tasks?action=defer.
- All integration tests now pass.

* fix: missing imports

* fix: added source path for task id to get the more appropiate error details

* refactor: align defer task serializer with Python conventions

* refactor: align defer task serializer with Python conventions

* fix(db): Resolve timezone inconsistency in API datetime fields

Previously, API responses for updated tasks returned naive datetime strings (e.g., 2025-10-21T02:35:25.433000), while responses for newly created tasks correctly returned timezone-aware strings (e.g., 2025-06-21T10:10:32.337301Z).

This was caused by the PyMongo  defaulting to . As a result, when a task was read from the database during an update operation, its timezone-aware BSON date was converted to a naive Python  object, which was then serialized into the API response without timezone information.

This commit configures the  with . This ensures that all datetime objects retrieved from the database remain timezone-aware, guaranteeing consistent ISO 8601 formatting with the UTC 'Z' suffix across all API responses.

* feat: added unit and integration tests for defer task endpoint (#79)

* feat: added unit test for defer task endpoint

* feat: added remaining unit tests for the defer task PATCH endpoint

* fix: failing tests

* fix: added deferredDetails on create task unit test

* feat: added integration tests for the defer task endpoint and also added missing integration tests for update task endpoint

* chore: remove comments from the integration tests code as it was unnecesseey

* chore: remove comments from the integration tests code as it was unnecesseey

* fix: imports

* fix: enhance defer task tests and fix auth issues

- corrected authentication failures in integration tests for task updates and deferrals. Introduced an AuthenticatedMongoTestCase to standardize JWT cookie setup, resolving multiple 401 Unauthorized errors.

- updated the global exception handler for TaskStateConflictException to include the source field in the error response, ensuring consistency and fixing a KeyError in the corresponding unit test.

-  added new integration tests for the defer task endpoint to validate API behavior with invalid and missing deferredTill dates, improving the feature's robustness.

- refactored the task update and deferral integration tests to follow the established authentication pattern from other tests, making them cleaner and more consistent.

* fix: failing test

---------

Co-authored-by: Anuj Chhikara <[email protected]>

Author: Achintya-Chatterjee

todo/constants/messages.py

@@ -40,18 +40,23 @@ class ApiErrors:
     INVALID_STATE_PARAMETER = "Invalid state parameter"
     TOKEN_REFRESH_FAILED = "Token refresh failed: {0}"
     LOGOUT_FAILED = "Logout failed: {0}"
+    STATE_CONFLICT_TITLE = "State Conflict"
 
 
 # Validation error messages
 class ValidationErrors:
     BLANK_TITLE = "Title must not be blank."
     INVALID_OBJECT_ID = "{0} is not a valid ObjectId."
     PAST_DUE_DATE = "Due date must be in the future."
+    PAST_DEFERRED_TILL_DATE = "deferredTill cannot be in the past."
+    CANNOT_DEFER_TOO_CLOSE_TO_DUE_DATE = "Cannot defer task too close to the due date."
+    CANNOT_DEFER_A_DONE_TASK = "Cannot defer a task that is already marked as done."
     PAGE_POSITIVE = "Page must be a positive integer"
     LIMIT_POSITIVE = "Limit must be a positive integer"
     MAX_LIMIT_EXCEEDED = "Maximum limit of {0} exceeded"
     MISSING_LABEL_IDS = "The following label ID(s) do not exist: {0}."
     INVALID_TASK_ID_FORMAT = "Please enter a valid Task ID format."
+    UNSUPPORTED_ACTION = "Unsupported action '{0}'."
     FUTURE_STARTED_AT = "The start date cannot be set in the future."
     INVALID_LABELS_STRUCTURE = "Labels must be provided as a list or tuple of ObjectId strings."
     MISSING_GOOGLE_ID = "Google ID is required"

todo/constants/task.py

@@ -13,3 +13,6 @@ class TaskPriority(Enum):
     HIGH = 1
     MEDIUM = 2
     LOW = 3
+
+
+MINIMUM_DEFERRAL_NOTICE_DAYS = 20

todo/dto/deferred_details_dto.py

@@ -0,0 +1,9 @@
+from pydantic import BaseModel
+from datetime import datetime
+from todo.dto.user_dto import UserDTO
+
+
+class DeferredDetailsDTO(BaseModel):
+    deferredAt: datetime
+    deferredTill: datetime
+    deferredBy: UserDTO

todo/dto/task_dto.py

@@ -3,6 +3,7 @@
 from pydantic import BaseModel, field_validator
 
 from todo.constants.task import TaskPriority, TaskStatus
+from todo.dto.deferred_details_dto import DeferredDetailsDTO
 from todo.dto.label_dto import LabelDTO
 from todo.dto.user_dto import UserDTO
 
@@ -19,6 +20,7 @@ class TaskDTO(BaseModel):
     labels: List[LabelDTO] = []
     startedAt: datetime | None = None
     dueAt: datetime | None = None
+    deferredDetails: DeferredDetailsDTO | None = None
     createdAt: datetime
     updatedAt: datetime | None = None
     createdBy: UserDTO

todo/exceptions/exception_handler.py

@@ -9,7 +9,11 @@
 
 from todo.dto.responses.error_response import ApiErrorDetail, ApiErrorResponse, ApiErrorSource
 from todo.constants.messages import ApiErrors, ValidationErrors, AuthErrorMessages
-from todo.exceptions.task_exceptions import TaskNotFoundException
+from todo.exceptions.task_exceptions import (
+    TaskNotFoundException,
+    UnprocessableEntityException,
+    TaskStateConflictException,
+)
 from .auth_exceptions import TokenExpiredError, TokenMissingError, TokenInvalidError
 from .google_auth_exceptions import (
     GoogleAuthException,
@@ -183,6 +187,21 @@ def handle_exception(exc, context):
                 detail=str(exc),
             )
         )
+    elif isinstance(exc, UnprocessableEntityException):
+        status_code = status.HTTP_422_UNPROCESSABLE_ENTITY
+        determined_message = str(exc)
+        error_list.append(
+            ApiErrorDetail(source=exc.source, title=ApiErrors.VALIDATION_ERROR, detail=determined_message)
+        )
+    elif isinstance(exc, TaskStateConflictException):
+        status_code = status.HTTP_409_CONFLICT
+        error_list.append(
+            ApiErrorDetail(
+                source={"path": "task_id"},
+                title=ApiErrors.STATE_CONFLICT_TITLE,
+                detail=str(exc),
+            )
+        )
     elif isinstance(exc, BsonInvalidId):
         status_code = status.HTTP_400_BAD_REQUEST
         error_list.append(

todo/exceptions/task_exceptions.py

@@ -8,3 +8,16 @@ def __init__(self, task_id: str | None = None, message_template: str = ApiErrors
         else:
             self.message = ApiErrors.TASK_NOT_FOUND_GENERIC
         super().__init__(self.message)
+
+
+class UnprocessableEntityException(Exception):
+    def __init__(self, message: str, source: dict | None = None):
+        self.message = message
+        self.source = source
+        super().__init__(self.message)
+
+
+class TaskStateConflictException(Exception):
+    def __init__(self, message: str):
+        self.message = message
+        super().__init__(self.message)

todo/serializers/defer_task_serializer.py

@@ -0,0 +1,12 @@
+from rest_framework import serializers
+from datetime import datetime, timezone
+from todo.constants.messages import ValidationErrors
+
+
+class DeferTaskSerializer(serializers.Serializer):
+    deferredTill = serializers.DateTimeField()
+
+    def validate_deferredTill(self, value):
+        if value < datetime.now(timezone.utc):
+            raise serializers.ValidationError(ValidationErrors.PAST_DEFERRED_TILL_DATE)
+        return value

todo/services/task_service.py

@@ -4,23 +4,28 @@
 from django.core.exceptions import ValidationError
 from django.urls import reverse_lazy
 from urllib.parse import urlencode
-from datetime import datetime, timezone
+from datetime import datetime, timezone, timedelta
 from rest_framework.exceptions import ValidationError as DRFValidationError
+from todo.dto.deferred_details_dto import DeferredDetailsDTO
 from todo.dto.label_dto import LabelDTO
 from todo.dto.task_dto import TaskDTO, CreateTaskDTO
 from todo.dto.user_dto import UserDTO
 from todo.dto.responses.get_tasks_response import GetTasksResponse
 from todo.dto.responses.create_task_response import CreateTaskResponse
 from todo.dto.responses.error_response import ApiErrorResponse, ApiErrorDetail, ApiErrorSource
 from todo.dto.responses.paginated_response import LinksData
-from todo.models.task import TaskModel
+from todo.models.task import TaskModel, DeferredDetailsModel
 from todo.models.common.pyobjectid import PyObjectId
 from todo.repositories.task_repository import TaskRepository
 from todo.repositories.label_repository import LabelRepository
-from todo.constants.task import TaskStatus, TaskPriority
+from todo.constants.task import TaskStatus, TaskPriority, MINIMUM_DEFERRAL_NOTICE_DAYS
 from todo.constants.messages import ApiErrors, ValidationErrors
 from django.conf import settings
-from todo.exceptions.task_exceptions import TaskNotFoundException
+from todo.exceptions.task_exceptions import (
+    TaskNotFoundException,
+    UnprocessableEntityException,
+    TaskStateConflictException,
+)
 from bson.errors import InvalidId as BsonInvalidId
 
 
@@ -111,6 +116,9 @@ def prepare_task_dto(cls, task_model: TaskModel) -> TaskDTO:
         assignee = cls.prepare_user_dto(task_model.assignee) if task_model.assignee else None
         created_by = cls.prepare_user_dto(task_model.createdBy)
         updated_by = cls.prepare_user_dto(task_model.updatedBy) if task_model.updatedBy else None
+        deferred_details = (
+            cls.prepare_deferred_details_dto(task_model.deferredDetails) if task_model.deferredDetails else None
+        )
 
         return TaskDTO(
             id=str(task_model.id),
@@ -124,6 +132,7 @@ def prepare_task_dto(cls, task_model: TaskModel) -> TaskDTO:
             dueAt=task_model.dueAt,
             status=task_model.status,
             priority=task_model.priority,
+            deferredDetails=deferred_details,
             createdAt=task_model.createdAt,
             updatedAt=task_model.updatedAt,
             createdBy=created_by,
@@ -148,6 +157,19 @@ def _prepare_label_dtos(cls, label_ids: List[str]) -> List[LabelDTO]:
             for label_model in label_models
         ]
 
+    @classmethod
+    def prepare_deferred_details_dto(cls, deferred_details_model: DeferredDetailsModel) -> DeferredDetailsDTO | None:
+        if not deferred_details_model:
+            return None
+
+        deferred_by_user = cls.prepare_user_dto(deferred_details_model.deferredBy)
+
+        return DeferredDetailsDTO(
+            deferredAt=deferred_details_model.deferredAt,
+            deferredTill=deferred_details_model.deferredTill,
+            deferredBy=deferred_by_user,
+        )
+
     @classmethod
     def prepare_user_dto(cls, user_id: str) -> UserDTO:
         return UserDTO(id=user_id, name="SYSTEM")
@@ -213,6 +235,50 @@ def update_task(cls, task_id: str, validated_data: dict, user_id: str = "system"
 
         return cls.prepare_task_dto(updated_task)
 
+    @classmethod
+    def defer_task(cls, task_id: str, deferred_till: datetime, user_id: str) -> TaskDTO:
+        current_task = TaskRepository.get_by_id(task_id)
+        if not current_task:
+            raise TaskNotFoundException(task_id)
+
+        if current_task.status == TaskStatus.DONE:
+            raise TaskStateConflictException(ValidationErrors.CANNOT_DEFER_A_DONE_TASK)
+
+        if deferred_till.tzinfo is None:
+            deferred_till = deferred_till.replace(tzinfo=timezone.utc)
+
+        if current_task.dueAt:
+            due_at = (
+                current_task.dueAt.replace(tzinfo=timezone.utc)
+                if current_task.dueAt.tzinfo is None
+                else current_task.dueAt.astimezone(timezone.utc)
+            )
+
+            defer_limit = due_at - timedelta(days=MINIMUM_DEFERRAL_NOTICE_DAYS)
+
+            if deferred_till > defer_limit:
+                raise UnprocessableEntityException(
+                    ValidationErrors.CANNOT_DEFER_TOO_CLOSE_TO_DUE_DATE,
+                    source={ApiErrorSource.PARAMETER: "deferredTill"},
+                )
+
+        deferred_details = DeferredDetailsModel(
+            deferredAt=datetime.now(timezone.utc),
+            deferredTill=deferred_till,
+            deferredBy=user_id,
+        )
+
+        update_payload = {
+            "deferredDetails": deferred_details.model_dump(),
+            "updatedBy": user_id,
+        }
+
+        updated_task = TaskRepository.update(task_id, update_payload)
+        if not updated_task:
+            raise TaskNotFoundException(task_id)
+
+        return cls.prepare_task_dto(updated_task)
+
     @classmethod
     def create_task(cls, dto: CreateTaskDTO) -> CreateTaskResponse:
         now = datetime.now(timezone.utc)

todo/tests/integration/test_task_defer_api.py

@@ -0,0 +1,129 @@
+from datetime import datetime, timedelta, timezone
+from http import HTTPStatus
+from bson import ObjectId
+from django.urls import reverse
+from rest_framework.test import APIClient
+from todo.constants.messages import ApiErrors, ValidationErrors
+from todo.constants.task import MINIMUM_DEFERRAL_NOTICE_DAYS, TaskPriority, TaskStatus
+from todo.tests.integration.base_mongo_test import BaseMongoTestCase
+from todo.tests.fixtures.task import tasks_db_data
+from todo.utils.google_jwt_utils import generate_google_token_pair
+
+
+class AuthenticatedMongoTestCase(BaseMongoTestCase):
+    def setUp(self):
+        super().setUp()
+        self.client = APIClient()
+        self._setup_auth_cookies()
+
+    def _setup_auth_cookies(self):
+        user_data = {
+            "user_id": str(ObjectId()),
+            "google_id": "test_google_id",
+            "email": "[email protected]",
+            "name": "Test User",
+        }
+        tokens = generate_google_token_pair(user_data)
+        self.client.cookies["ext-access"] = tokens["access_token"]
+        self.client.cookies["ext-refresh"] = tokens["refresh_token"]
+
+
+class TaskDeferAPIIntegrationTest(AuthenticatedMongoTestCase):
+    def setUp(self):
+        super().setUp()
+        self.db.tasks.delete_many({})
+
+    def _insert_task(self, *, status: str = TaskStatus.TODO.value, due_at: datetime | None = None) -> str:
+        task_fixture = tasks_db_data[0].copy()
+        new_id = ObjectId()
+        task_fixture["_id"] = new_id
+        task_fixture.pop("id", None)
+        task_fixture["displayId"] = "#IT-DEF"
+        task_fixture["status"] = status
+        task_fixture["priority"] = TaskPriority.MEDIUM.value
+        task_fixture["createdAt"] = datetime.now(timezone.utc)
+        if due_at:
+            task_fixture["dueAt"] = due_at
+        else:
+            task_fixture.pop("dueAt", None)
+
+        self.db.tasks.insert_one(task_fixture)
+        return str(new_id)
+
+    def test_defer_task_success(self):
+        now = datetime.now(timezone.utc)
+        due_at = now + timedelta(days=MINIMUM_DEFERRAL_NOTICE_DAYS + 30)
+        task_id = self._insert_task(due_at=due_at)
+        deferred_till = now + timedelta(days=10)
+
+        url = reverse("task_detail", args=[task_id]) + "?action=defer"
+        response = self.client.patch(url, data={"deferredTill": deferred_till.isoformat()}, format="json")
+
+        self.assertEqual(response.status_code, HTTPStatus.OK)
+        response_data = response.json()
+        self.assertIn("deferredDetails", response_data)
+        self.assertIsNotNone(response_data["deferredDetails"])
+        raw_dt_str = response_data["deferredDetails"]["deferredTill"]
+
+        if raw_dt_str.endswith("Z"):
+            raw_dt_str = raw_dt_str.replace("Z", "+00:00")
+
+        response_deferred_till = datetime.fromisoformat(raw_dt_str)
+
+        if response_deferred_till.tzinfo is None:
+            response_deferred_till = response_deferred_till.replace(tzinfo=timezone.utc)
+
+        self.assertTrue(abs(response_deferred_till - deferred_till) < timedelta(seconds=1))
+
+    def test_defer_task_too_close_to_due_date_returns_422(self):
+        now = datetime.now(timezone.utc)
+        due_at = now + timedelta(days=MINIMUM_DEFERRAL_NOTICE_DAYS + 5)
+        task_id = self._insert_task(due_at=due_at)
+
+        defer_limit = due_at - timedelta(days=MINIMUM_DEFERRAL_NOTICE_DAYS)
+        deferred_till = defer_limit + timedelta(days=1)
+
+        url = reverse("task_detail", args=[task_id]) + "?action=defer"
+        response = self.client.patch(url, data={"deferredTill": deferred_till.isoformat()}, format="json")
+
+        self.assertEqual(response.status_code, HTTPStatus.UNPROCESSABLE_ENTITY)
+        response_json = response.json()
+        self.assertEqual(response_json["statusCode"], HTTPStatus.UNPROCESSABLE_ENTITY)
+        self.assertEqual(response_json["message"], ValidationErrors.CANNOT_DEFER_TOO_CLOSE_TO_DUE_DATE)
+        error = response_json["errors"][0]
+        self.assertEqual(error["title"], ApiErrors.VALIDATION_ERROR)
+        self.assertEqual(error["detail"], ValidationErrors.CANNOT_DEFER_TOO_CLOSE_TO_DUE_DATE)
+        self.assertEqual(error["source"]["parameter"], "deferredTill")
+
+    def test_defer_done_task_returns_409(self):
+        task_id = self._insert_task(status=TaskStatus.DONE.value)
+        deferred_till = datetime.now(timezone.utc) + timedelta(days=5)
+
+        url = reverse("task_detail", args=[task_id]) + "?action=defer"
+        response = self.client.patch(url, data={"deferredTill": deferred_till.isoformat()}, format="json")
+
+        self.assertEqual(response.status_code, HTTPStatus.CONFLICT)
+        response_data = response.json()
+        self.assertEqual(response_data["statusCode"], HTTPStatus.CONFLICT)
+        self.assertEqual(response_data["message"], ValidationErrors.CANNOT_DEFER_A_DONE_TASK)
+        error = response_data["errors"][0]
+        self.assertEqual(error["title"], ApiErrors.STATE_CONFLICT_TITLE)
+        self.assertEqual(error["detail"], ValidationErrors.CANNOT_DEFER_A_DONE_TASK)
+        self.assertEqual(error["source"]["path"], "task_id")
+
+    def test_defer_task_with_invalid_date_format_returns_400(self):
+        task_id = self._insert_task()
+        url = reverse("task_detail", args=[task_id]) + "?action=defer"
+        response = self.client.patch(url, data={"deferredTill": "invalid-date-format"}, format="json")
+        self.assertEqual(response.status_code, HTTPStatus.BAD_REQUEST)
+        response_data = response.json()
+        self.assertEqual(response_data["errors"][0]["source"]["parameter"], "deferredTill")
+
+    def test_defer_task_with_missing_date_returns_400(self):
+        task_id = self._insert_task()
+        url = reverse("task_detail", args=[task_id]) + "?action=defer"
+        response = self.client.patch(url, data={}, format="json")
+        self.assertEqual(response.status_code, HTTPStatus.BAD_REQUEST)
+        response_data = response.json()
+        self.assertEqual(response_data["errors"][0]["source"]["parameter"], "deferredTill")
+        self.assertIn("required", response_data["errors"][0]["detail"])