devrev-Python-SDK 2.14.0__py3-none-any.whl → 3.0.0__py3-none-any.whl

devrev/models/conversations.py

@@ -8,6 +8,7 @@ from typing import Any
 from pydantic import Field
 
 from devrev.models.base import (
+    DateFilter,
     DevRevBaseModel,
     DevRevResponseModel,
     PaginatedResponse,
@@ -63,6 +64,13 @@ class ConversationsListRequest(DevRevBaseModel):
 
     cursor: str | None = Field(default=None, description="Pagination cursor")
     limit: int | None = Field(default=None, ge=1, le=100, description="Max results")
+    modified_date: DateFilter | None = Field(
+        default=None, description="Filter by modification date"
+    )
+    sort_by: list[str] | None = Field(
+        default=None,
+        description='Sort order (e.g., ["modified_date:desc"])',
+    )
 
 
 class ConversationsUpdateRequest(DevRevBaseModel):

devrev/models/works.py

@@ -167,15 +167,18 @@ class WorksListRequest(DevRevBaseModel):
     type: list[WorkType] | None = Field(default=None, description="Filter by work types")
     applies_to_part: list[str] | None = Field(default=None, description="Filter by part IDs")
     created_by: list[str] | None = Field(default=None, description="Filter by creator user IDs")
-    created_date: DateFilter | None = Field(default=None, description="Filter by creation date")
     cursor: str | None = Field(default=None, description="Pagination cursor")
     external_ref: list[str] | None = Field(default=None, description="Filter by external refs")
     limit: int | None = Field(default=None, ge=1, le=100, description="Max results to return")
-    modified_date: DateFilter | None = Field(
-        default=None, description="Filter by modification date"
-    )
     owned_by: list[str] | None = Field(default=None, description="Filter by owner user IDs")
-    sort_by: list[str] | None = Field(default=None, description="Sort order")
+    sort_by: list[str] | None = Field(
+        default=None,
+        description=(
+            "Sort order. Each entry uses the server form 'field:asc' or 'field:desc' "
+            "(e.g. 'modified_date:desc'). The legacy '-field' form is accepted by the "
+            "service and normalized before being sent."
+        ),
+    )
     stage_name: list[str] | None = Field(default=None, description="Filter by stage names")
     target_close_date: DateFilter | None = Field(
         default=None, description="Filter by target close date"
@@ -226,8 +229,15 @@ class WorksExportRequest(DevRevBaseModel):
     type: list[WorkType] | None = Field(default=None, description="Filter by work types")
     applies_to_part: list[str] | None = Field(default=None, description="Filter by part IDs")
     created_by: list[str] | None = Field(default=None, description="Filter by creator user IDs")
-    created_date: DateFilter | None = Field(default=None, description="Filter by creation date")
     first: int | None = Field(default=None, ge=1, le=10000, description="Max results")
+    sort_by: list[str] | None = Field(
+        default=None,
+        description=(
+            "Sort order. Each entry uses the server form 'field:asc' or 'field:desc' "
+            "(e.g. 'modified_date:desc'). The legacy '-field' form is accepted by the "
+            "service and normalized before being sent."
+        ),
+    )
 
 
 class WorksCountRequest(DevRevBaseModel):

devrev/services/base.py

@@ -72,7 +72,9 @@ class BaseService:
         Returns:
             Parsed response model or raw dict if no response_type
         """
-        data = request.model_dump(exclude_none=True, by_alias=True) if request else None
+        data = (
+            request.model_dump(exclude_none=True, by_alias=True, mode="json") if request else None
+        )
         response = self._http.post(endpoint, data=data)
 
         # Handle empty responses (204 No Content or empty body)
@@ -185,7 +187,9 @@ class AsyncBaseService:
         Returns:
             Parsed response model or raw dict if no response_type
         """
-        data = request.model_dump(exclude_none=True, by_alias=True) if request else None
+        data = (
+            request.model_dump(exclude_none=True, by_alias=True, mode="json") if request else None
+        )
         response = await self._http.post(endpoint, data=data)
 
         # Handle empty responses (204 No Content or empty body)

devrev/services/conversations.py

@@ -3,8 +3,10 @@
 from __future__ import annotations
 
 from collections.abc import Sequence
+from datetime import datetime
 from typing import overload
 
+from devrev.models.base import DateFilter
 from devrev.models.conversations import (
     Conversation,
     ConversationExportItem,
@@ -24,6 +26,68 @@ from devrev.models.conversations import (
 from devrev.services.base import AsyncBaseService, BaseService
 
 
+def _normalize_sort_by(sort_by: Sequence[str] | None) -> list[str] | None:
+    """Normalize sort_by entries to the ``field:direction`` format.
+
+    Accepts entries already in ``field:direction`` form (e.g.
+    ``"modified_date:desc"``), the legacy ``"-field"`` shorthand for
+    descending order, and bare field names (e.g. ``"modified_date"``) which
+    default to ascending order.
+    """
+    if sort_by is None:
+        return None
+    normalized: list[str] = []
+    for entry in sort_by:
+        if ":" in entry:
+            normalized.append(entry)
+        elif entry.startswith("-"):
+            normalized.append(f"{entry[1:]}:desc")
+        else:
+            normalized.append(f"{entry}:asc")
+    return normalized
+
+
+# ``ConversationsListRequest.limit`` is pydantic-constrained to ``le=100``;
+# clamp any computed per-page limit so pagination loops do not construct a
+# request body that fails validation before it is ever sent.
+_CONVERSATIONS_MAX_PAGE = 100
+
+
+def _resolve_page_limit(
+    overall_limit: int | None,
+    collected: int,
+    page_size: int | None,
+) -> int | None:
+    """Compute the ``limit`` to send for the next page request.
+
+    The returned value is always clamped to ``_CONVERSATIONS_MAX_PAGE`` so
+    callers using an ``overall_limit`` greater than the server maximum (e.g.
+    ``limit=200, page_size=None``) still paginate correctly.
+    """
+    if overall_limit is None:
+        if page_size is None:
+            return None
+        return min(page_size, _CONVERSATIONS_MAX_PAGE)
+    remaining = overall_limit - collected
+    if page_size is None:
+        return min(remaining, _CONVERSATIONS_MAX_PAGE)
+    return min(page_size, remaining, _CONVERSATIONS_MAX_PAGE)
+
+
+def _is_before_cutoff(modified_date: datetime | None, cutoff: datetime) -> bool:
+    """Return True if ``modified_date`` is strictly older than ``cutoff``.
+
+    Returns False when the timestamp is unknown or when the two datetimes have
+    incompatible tz-awareness; the server-side filter remains authoritative.
+    """
+    if modified_date is None:
+        return False
+    try:
+        return modified_date < cutoff
+    except TypeError:
+        return False
+
+
 class ConversationsService(BaseService):
     """Service for managing DevRev Conversations."""
 
@@ -41,9 +105,55 @@ class ConversationsService(BaseService):
         """List conversations."""
         if request is None:
             request = ConversationsListRequest()
+        if request.sort_by is not None:
+            request.sort_by = _normalize_sort_by(request.sort_by)
         response = self._post("/conversations.list", request, ConversationsListResponse)
         return response.conversations
 
+    def list_modified_since(
+        self,
+        after: datetime,
+        *,
+        limit: int | None = None,
+        page_size: int | None = None,
+    ) -> Sequence[Conversation]:
+        """List conversations modified after a given datetime, newest first.
+
+        Streams pages via cursor until the server returns no further cursor,
+        ``limit`` is reached, or a conversation older than ``after`` is seen.
+
+        Args:
+            after: Only include conversations modified after this datetime.
+            limit: Maximum number of conversations to return overall.
+            page_size: Number of results per API request; ``None`` defers to server.
+
+        Returns:
+            List of Conversation objects modified after ``after``, newest first.
+        """
+        results: list[Conversation] = []
+        cursor: str | None = None
+        while True:
+            if limit is not None and len(results) >= limit:
+                break
+            request_limit = _resolve_page_limit(limit, len(results), page_size)
+            request = ConversationsListRequest(
+                cursor=cursor,
+                limit=request_limit,
+                modified_date=DateFilter(after=after),
+                sort_by=_normalize_sort_by(["modified_date:desc"]),
+            )
+            response = self._post("/conversations.list", request, ConversationsListResponse)
+            for conversation in response.conversations:
+                if _is_before_cutoff(conversation.modified_date, after):
+                    return results
+                results.append(conversation)
+                if limit is not None and len(results) >= limit:
+                    return results
+            if not response.next_cursor:
+                break
+            cursor = response.next_cursor
+        return results
+
     def update(self, request: ConversationsUpdateRequest) -> Conversation:
         """Update a conversation."""
         response = self._post("/conversations.update", request, ConversationsUpdateResponse)
@@ -127,9 +237,55 @@ class AsyncConversationsService(AsyncBaseService):
         """List conversations."""
         if request is None:
             request = ConversationsListRequest()
+        if request.sort_by is not None:
+            request.sort_by = _normalize_sort_by(request.sort_by)
         response = await self._post("/conversations.list", request, ConversationsListResponse)
         return response.conversations
 
+    async def list_modified_since(
+        self,
+        after: datetime,
+        *,
+        limit: int | None = None,
+        page_size: int | None = None,
+    ) -> Sequence[Conversation]:
+        """List conversations modified after a given datetime, newest first.
+
+        Streams pages via cursor until the server returns no further cursor,
+        ``limit`` is reached, or a conversation older than ``after`` is seen.
+
+        Args:
+            after: Only include conversations modified after this datetime.
+            limit: Maximum number of conversations to return overall.
+            page_size: Number of results per API request; ``None`` defers to server.
+
+        Returns:
+            List of Conversation objects modified after ``after``, newest first.
+        """
+        results: list[Conversation] = []
+        cursor: str | None = None
+        while True:
+            if limit is not None and len(results) >= limit:
+                break
+            request_limit = _resolve_page_limit(limit, len(results), page_size)
+            request = ConversationsListRequest(
+                cursor=cursor,
+                limit=request_limit,
+                modified_date=DateFilter(after=after),
+                sort_by=_normalize_sort_by(["modified_date:desc"]),
+            )
+            response = await self._post("/conversations.list", request, ConversationsListResponse)
+            for conversation in response.conversations:
+                if _is_before_cutoff(conversation.modified_date, after):
+                    return results
+                results.append(conversation)
+                if limit is not None and len(results) >= limit:
+                    return results
+            if not response.next_cursor:
+                break
+            cursor = response.next_cursor
+        return results
+
     async def update(self, request: ConversationsUpdateRequest) -> Conversation:
         """Update a conversation."""
         response = await self._post("/conversations.update", request, ConversationsUpdateResponse)

devrev/services/works.py

@@ -9,7 +9,7 @@ from collections.abc import Sequence
 from datetime import datetime
 from typing import TYPE_CHECKING, Any
 
-from devrev.models.base import DateFilter, StageUpdate
+from devrev.models.base import StageUpdate
 from devrev.models.works import (
     IssuePriority,
     TicketSeverity,
@@ -37,6 +37,74 @@ if TYPE_CHECKING:
     from devrev.utils.http import AsyncHTTPClient, HTTPClient
 
 
+# Module-level type aliases. Declared here so class-scoped annotations can
+# refer to ``list[...]`` without colliding with the ``list`` method defined on
+# :class:`WorksService` / :class:`AsyncWorksService`.
+_WorkList = list[Work]
+_StrList = list[str]
+
+
+def _is_before_cutoff(timestamp: datetime | None, cutoff: datetime) -> bool:
+    """Return True if ``timestamp`` is strictly older than ``cutoff``.
+
+    Returns False when the timestamp is unknown or when the two datetimes have
+    incompatible tz-awareness; the server-side filter remains authoritative.
+    """
+    if timestamp is None:
+        return False
+    try:
+        return timestamp < cutoff
+    except TypeError:
+        return False
+
+
+# ``WorksListRequest.limit`` is pydantic-constrained to ``le=100``; clamp any
+# computed per-page limit so pagination loops do not construct a request body
+# that fails validation before it is ever sent.
+_WORKS_MAX_PAGE = 100
+
+
+def _resolve_page_limit(
+    overall_limit: int | None,
+    collected: int,
+    page_size: int | None,
+) -> int | None:
+    """Compute the ``limit`` to send for the next page request.
+
+    The returned value is always clamped to ``_WORKS_MAX_PAGE`` so callers using
+    an ``overall_limit`` greater than the server maximum (e.g. ``limit=200,
+    page_size=None``) still paginate correctly.
+    """
+    if page_size is not None:
+        return min(page_size, _WORKS_MAX_PAGE)
+    if overall_limit is None:
+        return None
+    remaining = overall_limit - collected
+    return min(remaining, _WORKS_MAX_PAGE)
+
+
+def _normalize_sort_by(sort_by: Sequence[str] | None) -> _StrList | None:
+    """Normalize sort_by entries to the server-expected ``field:direction`` form.
+
+    Accepts both the legacy ``"-field"`` (descending) / ``"field"`` (ascending)
+    shorthand and the explicit ``"field:asc"`` / ``"field:desc"`` form. Returns
+    a new list with every entry in the ``"field:direction"`` form. Returns
+    ``None`` when the input is ``None`` so callers can pass the result straight
+    through to request models with no-op semantics.
+    """
+    if sort_by is None:
+        return None
+    normalized: list[str] = []
+    for entry in sort_by:
+        if ":" in entry:
+            normalized.append(entry)
+        elif entry.startswith("-"):
+            normalized.append(f"{entry[1:]}:desc")
+        else:
+            normalized.append(f"{entry}:asc")
+    return normalized
+
+
 class WorksService(BaseService):
     """Synchronous service for managing DevRev work items.
 
@@ -109,10 +177,10 @@ class WorksService(BaseService):
         type: Sequence[WorkType] | None = None,
         applies_to_part: Sequence[str] | None = None,
         created_by: Sequence[str] | None = None,
-        created_date: DateFilter | None = None,
         cursor: str | None = None,
         limit: int | None = None,
         owned_by: Sequence[str] | None = None,
+        sort_by: Sequence[str] | None = None,
         stage_name: Sequence[str] | None = None,
     ) -> WorksListResponse:
         """List work items.
@@ -121,10 +189,12 @@ class WorksService(BaseService):
             type: Filter by work types
             applies_to_part: Filter by part IDs
             created_by: Filter by creator user IDs
-            created_date: Filter by creation date
             cursor: Pagination cursor
             limit: Maximum number of results
             owned_by: Filter by owner user IDs
+            sort_by: Sort order. Accepts either the server form
+                ``"field:asc"`` / ``"field:desc"`` or the legacy
+                ``"-field"`` shorthand; the client normalizes before sending.
             stage_name: Filter by stage names
 
         Returns:
@@ -134,10 +204,10 @@ class WorksService(BaseService):
             type=type,
             applies_to_part=applies_to_part,
             created_by=created_by,
-            created_date=created_date,
             cursor=cursor,
             limit=limit,
             owned_by=owned_by,
+            sort_by=_normalize_sort_by(sort_by),
             stage_name=stage_name,
         )
         return self._post("/works.list", request, WorksListResponse)
@@ -198,8 +268,8 @@ class WorksService(BaseService):
         type: Sequence[WorkType] | None = None,
         applies_to_part: Sequence[str] | None = None,
         created_by: Sequence[str] | None = None,
-        created_date: DateFilter | None = None,
         first: int | None = None,
+        sort_by: Sequence[str] | None = None,
     ) -> Sequence[Work]:
         """Export work items.
 
@@ -207,8 +277,10 @@ class WorksService(BaseService):
             type: Filter by work types
             applies_to_part: Filter by part IDs
             created_by: Filter by creator user IDs
-            created_date: Filter by creation date
             first: Maximum number of results
+            sort_by: Sort order. Accepts either the server form
+                ``"field:asc"`` / ``"field:desc"`` or the legacy
+                ``"-field"`` shorthand; the client normalizes before sending.
 
         Returns:
             List of exported work items
@@ -217,8 +289,8 @@ class WorksService(BaseService):
             type=type,
             applies_to_part=applies_to_part,
             created_by=created_by,
-            created_date=created_date,
             first=first,
+            sort_by=_normalize_sort_by(sort_by),
         )
         response = self._post("/works.export", request, WorksExportResponse)
         return response.works
@@ -251,6 +323,104 @@ class WorksService(BaseService):
         response = self._post("/works.count", request, WorksCountResponse)
         return response.count
 
+    def _list_since(
+        self,
+        after: datetime,
+        timestamp_field: str,
+        *,
+        type: Sequence[WorkType] | None,
+        owned_by: Sequence[str] | None,
+        applies_to_part: Sequence[str] | None,
+        limit: int | None,
+        page_size: int | None,
+    ) -> _WorkList:
+        """Shared cursor-paginated fetcher for ``list_*_since`` helpers.
+
+        Streams pages sorted ``{timestamp_field}:desc`` and early-exits as soon
+        as a record's timestamp is strictly older than ``after``. Respects
+        ``limit`` as a hard cap on returned items.
+        """
+        sort_by = [f"{timestamp_field}:desc"]
+        collected: _WorkList = []
+        cursor: str | None = None
+        while True:
+            if limit is not None and len(collected) >= limit:
+                break
+            page = self.list(
+                type=type,
+                owned_by=owned_by,
+                applies_to_part=applies_to_part,
+                cursor=cursor,
+                limit=_resolve_page_limit(limit, len(collected), page_size),
+                sort_by=sort_by,
+            )
+            stop = False
+            for work in page.works:
+                timestamp = getattr(work, timestamp_field, None)
+                if _is_before_cutoff(timestamp, after):
+                    stop = True
+                    break
+                collected.append(work)
+                if limit is not None and len(collected) >= limit:
+                    stop = True
+                    break
+            if stop or not page.next_cursor:
+                break
+            cursor = page.next_cursor
+        return collected
+
+    def list_modified_since(
+        self,
+        after: datetime,
+        *,
+        type: Sequence[WorkType] | None = None,
+        owned_by: Sequence[str] | None = None,
+        applies_to_part: Sequence[str] | None = None,
+        limit: int | None = None,
+        page_size: int | None = None,
+    ) -> _WorkList:
+        """Return work items modified at or after ``after``.
+
+        Pages through ``works.list`` sorted by ``modified_date:desc`` and stops
+        as soon as it sees a record older than ``after``. Uses ``limit`` as a
+        hard cap when provided.
+        """
+        return self._list_since(
+            after,
+            "modified_date",
+            type=type,
+            owned_by=owned_by,
+            applies_to_part=applies_to_part,
+            limit=limit,
+            page_size=page_size,
+        )
+
+    def list_created_since(
+        self,
+        after: datetime,
+        *,
+        type: Sequence[WorkType] | None = None,
+        owned_by: Sequence[str] | None = None,
+        applies_to_part: Sequence[str] | None = None,
+        limit: int | None = None,
+        page_size: int | None = None,
+    ) -> _WorkList:
+        """Return work items created at or after ``after``.
+
+        Pages through ``works.list`` sorted by ``created_date:desc`` and stops
+        as soon as it sees a record older than ``after``. Uses ``limit`` as a
+        hard cap when provided.
+        """
+        return self._list_since(
+            after,
+            "created_date",
+            type=type,
+            owned_by=owned_by,
+            applies_to_part=applies_to_part,
+            limit=limit,
+            page_size=page_size,
+        )
+
 
 class AsyncWorksService(AsyncBaseService):
     """Asynchronous service for managing DevRev work items."""
@@ -301,14 +471,21 @@ class AsyncWorksService(AsyncBaseService):
         cursor: str | None = None,
         limit: int | None = None,
         owned_by: Sequence[str] | None = None,
+        sort_by: Sequence[str] | None = None,
     ) -> WorksListResponse:
-        """List work items."""
+        """List work items.
+
+        ``sort_by`` accepts either the server form ``"field:asc"`` /
+        ``"field:desc"`` or the legacy ``"-field"`` shorthand; the client
+        normalizes before sending.
+        """
         request = WorksListRequest(
             type=type,
             applies_to_part=applies_to_part,
             cursor=cursor,
             limit=limit,
             owned_by=owned_by,
+            sort_by=_normalize_sort_by(sort_by),
         )
         return await self._post("/works.list", request, WorksListResponse)
 
@@ -345,9 +522,19 @@ class AsyncWorksService(AsyncBaseService):
         *,
         type: Sequence[WorkType] | None = None,
         first: int | None = None,
+        sort_by: Sequence[str] | None = None,
     ) -> Sequence[Work]:
-        """Export work items."""
-        request = WorksExportRequest(type=type, first=first)
+        """Export work items.
+
+        ``sort_by`` accepts either the server form ``"field:asc"`` /
+        ``"field:desc"`` or the legacy ``"-field"`` shorthand; the client
+        normalizes before sending.
+        """
+        request = WorksExportRequest(
+            type=type,
+            first=first,
+            sort_by=_normalize_sort_by(sort_by),
+        )
         response = await self._post("/works.export", request, WorksExportResponse)
         return response.works
 
@@ -361,3 +548,101 @@ class AsyncWorksService(AsyncBaseService):
         request = WorksCountRequest(type=type, owned_by=owned_by)
         response = await self._post("/works.count", request, WorksCountResponse)
         return response.count
+
+    async def _list_since(
+        self,
+        after: datetime,
+        timestamp_field: str,
+        *,
+        type: Sequence[WorkType] | None,
+        owned_by: Sequence[str] | None,
+        applies_to_part: Sequence[str] | None,
+        limit: int | None,
+        page_size: int | None,
+    ) -> _WorkList:
+        """Shared cursor-paginated fetcher for async ``list_*_since`` helpers.
+
+        Streams pages sorted ``{timestamp_field}:desc`` and early-exits as soon
+        as a record's timestamp is strictly older than ``after``. Respects
+        ``limit`` as a hard cap on returned items.
+        """
+        sort_by = [f"{timestamp_field}:desc"]
+        collected: _WorkList = []
+        cursor: str | None = None
+        while True:
+            if limit is not None and len(collected) >= limit:
+                break
+            page = await self.list(
+                type=type,
+                owned_by=owned_by,
+                applies_to_part=applies_to_part,
+                cursor=cursor,
+                limit=_resolve_page_limit(limit, len(collected), page_size),
+                sort_by=sort_by,
+            )
+            stop = False
+            for work in page.works:
+                timestamp = getattr(work, timestamp_field, None)
+                if _is_before_cutoff(timestamp, after):
+                    stop = True
+                    break
+                collected.append(work)
+                if limit is not None and len(collected) >= limit:
+                    stop = True
+                    break
+            if stop or not page.next_cursor:
+                break
+            cursor = page.next_cursor
+        return collected
+
+    async def list_modified_since(
+        self,
+        after: datetime,
+        *,
+        type: Sequence[WorkType] | None = None,
+        owned_by: Sequence[str] | None = None,
+        applies_to_part: Sequence[str] | None = None,
+        limit: int | None = None,
+        page_size: int | None = None,
+    ) -> _WorkList:
+        """Return work items modified at or after ``after``.
+
+        Pages through ``works.list`` sorted by ``modified_date:desc`` and stops
+        as soon as it sees a record older than ``after``. Uses ``limit`` as a
+        hard cap when provided.
+        """
+        return await self._list_since(
+            after,
+            "modified_date",
+            type=type,
+            owned_by=owned_by,
+            applies_to_part=applies_to_part,
+            limit=limit,
+            page_size=page_size,
+        )
+
+    async def list_created_since(
+        self,
+        after: datetime,
+        *,
+        type: Sequence[WorkType] | None = None,
+        owned_by: Sequence[str] | None = None,
+        applies_to_part: Sequence[str] | None = None,
+        limit: int | None = None,
+        page_size: int | None = None,
+    ) -> _WorkList:
+        """Return work items created at or after ``after``.
+
+        Pages through ``works.list`` sorted by ``created_date:desc`` and stops
+        as soon as it sees a record older than ``after``. Uses ``limit`` as a
+        hard cap when provided.
+        """
+        return await self._list_since(
+            after,
+            "created_date",
+            type=type,
+            owned_by=owned_by,
+            applies_to_part=applies_to_part,
+            limit=limit,
+            page_size=page_size,
+        )

devrev_mcp/tools/conversations.py

@@ -3,11 +3,13 @@
 from __future__ import annotations
 
 import logging
+from datetime import datetime
 from typing import Any
 
 from mcp.server.fastmcp import Context
 
 from devrev.exceptions import DevRevError
+from devrev.models.base import DateFilter
 from devrev.models.conversations import (
     ConversationsCreateRequest,
     ConversationsDeleteRequest,
@@ -24,25 +26,71 @@ from devrev_mcp.utils.pagination import clamp_page_size, paginated_response
 logger = logging.getLogger(__name__)
 
 
+def _parse_iso_datetime(value: str, field_name: str) -> datetime:
+    """Parse an ISO-8601 datetime string, accepting a trailing ``Z`` for UTC.
+
+    Args:
+        value: The ISO-8601 datetime string.
+        field_name: Name of the parameter being parsed (for error messages).
+
+    Returns:
+        A parsed ``datetime`` instance.
+
+    Raises:
+        RuntimeError: If the string cannot be parsed.
+    """
+    try:
+        return datetime.fromisoformat(value.replace("Z", "+00:00"))
+    except ValueError as e:
+        raise RuntimeError(
+            f"Invalid {field_name} format: {value}. "
+            "Use ISO-8601 format (e.g., 2025-01-01T00:00:00Z)."
+        ) from e
+
+
 @mcp.tool()
 async def devrev_conversations_list(
     ctx: Context[Any, Any, Any],
     cursor: str | None = None,
     limit: int | None = None,
+    modified_date_after: str | None = None,
+    modified_date_before: str | None = None,
+    sort_by: list[str] | None = None,
 ) -> dict[str, Any]:
     """List DevRev conversations.
 
     Args:
         cursor: Pagination cursor from a previous response.
         limit: Maximum number of items to return (default: 25, max: 100).
+        modified_date_after: Only include conversations modified after this
+            ISO-8601 timestamp (e.g., "2025-01-01T00:00:00Z").
+        modified_date_before: Only include conversations modified before this
+            ISO-8601 timestamp.
+        sort_by: Sort order entries (e.g., ["modified_date:desc"] or
+            ["-modified_date"]).
     """
     app = ctx.request_context.lifespan_context
     try:
+        modified_date: DateFilter | None = None
+        if modified_date_after is not None or modified_date_before is not None:
+            after_dt = (
+                _parse_iso_datetime(modified_date_after, "modified_date_after")
+                if modified_date_after is not None
+                else None
+            )
+            before_dt = (
+                _parse_iso_datetime(modified_date_before, "modified_date_before")
+                if modified_date_before is not None
+                else None
+            )
+            modified_date = DateFilter(after=after_dt, before=before_dt)
         request = ConversationsListRequest(
             cursor=cursor,
             limit=clamp_page_size(
                 limit, default=app.config.default_page_size, maximum=app.config.max_page_size
             ),
+            modified_date=modified_date,
+            sort_by=sort_by,
         )
         conversations = await app.get_client().conversations.list(request)
         items = serialize_models(list(conversations))
@@ -51,6 +99,35 @@ async def devrev_conversations_list(
         raise RuntimeError(format_devrev_error(e)) from e
 
 
+@mcp.tool()
+async def devrev_conversations_list_modified_since(
+    ctx: Context[Any, Any, Any],
+    after: str,
+    limit: int | None = None,
+) -> dict[str, Any]:
+    """List DevRev conversations modified after a given ISO-8601 datetime.
+
+    Streams pages newest-first, stopping when the cutoff is crossed or the
+    ``limit`` is reached. The cutoff is supplied as an ISO-8601 string.
+
+    Args:
+        after: ISO-8601 datetime; only conversations modified after this are
+            returned (e.g., "2025-01-01T00:00:00Z").
+        limit: Maximum number of conversations to return overall.
+    """
+    app = ctx.request_context.lifespan_context
+    after_dt = _parse_iso_datetime(after, "after")
+    try:
+        conversations = await app.get_client().conversations.list_modified_since(
+            after=after_dt,
+            limit=limit,
+        )
+        items = serialize_models(list(conversations))
+        return {"count": len(items), "conversations": items}
+    except DevRevError as e:
+        raise RuntimeError(format_devrev_error(e)) from e
+
+
 @mcp.tool()
 async def devrev_conversations_get(
     ctx: Context[Any, Any, Any],

devrev_mcp/tools/works.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import logging
+from datetime import datetime
 from typing import Any
 
 from mcp.server.fastmcp import Context
@@ -18,6 +19,17 @@ from devrev_mcp.utils.pagination import clamp_page_size, paginated_response
 logger = logging.getLogger(__name__)
 
 
+def _parse_iso_after(value: str, param_name: str) -> datetime:
+    """Parse an ISO-8601 timestamp, accepting a trailing ``Z`` for UTC."""
+    try:
+        return datetime.fromisoformat(value.replace("Z", "+00:00"))
+    except ValueError as e:
+        raise RuntimeError(
+            f"Invalid {param_name} format: {value}. "
+            "Use ISO-8601 (e.g., 2024-01-15T00:00:00Z or 2024-01-15T00:00:00+00:00)."
+        ) from e
+
+
 @mcp.tool()
 async def devrev_works_list(
     ctx: Context[Any, Any, Any],
@@ -26,8 +38,12 @@ async def devrev_works_list(
     owned_by: list[str] | None = None,
     cursor: str | None = None,
     limit: int | None = None,
+    sort_by: list[str] | None = None,
 ) -> dict[str, Any]:
-    """List DevRev work items (tickets, issues, tasks).
+    """List DevRev work items (tickets, issues, and tasks).
+
+    Work items in DevRev include tickets (customer-facing), issues (internal
+    engineering), and tasks. Use the ``type`` filter to scope results.
 
     Args:
         type: Filter by work type(s): TICKET, ISSUE, TASK, OPPORTUNITY.
@@ -35,6 +51,8 @@ async def devrev_works_list(
         owned_by: Filter by owner user ID(s).
         cursor: Pagination cursor from a previous response.
         limit: Maximum number of items to return (default: 25, max: 100).
+        sort_by: Sort order as a list of ``"field:asc"`` / ``"field:desc"``
+            entries (or legacy ``"-field"`` shorthand), forwarded to the SDK.
     """
     app = ctx.request_context.lifespan_context
     try:
@@ -56,6 +74,7 @@ async def devrev_works_list(
             limit=clamp_page_size(
                 limit, default=app.config.default_page_size, maximum=app.config.max_page_size
             ),
+            sort_by=sort_by,
         )
         items = serialize_models(response.works)
         return paginated_response(items, next_cursor=response.next_cursor, total_label="works")
@@ -68,7 +87,7 @@ async def devrev_works_get(
     ctx: Context[Any, Any, Any],
     id: str,
 ) -> dict[str, Any]:
-    """Get a DevRev work item by ID.
+    """Get a DevRev work item (ticket, issue, or task) by ID.
 
     Args:
         id: The work item ID (e.g., don:core:dvrv-us-1:devo/1:issue/123).
@@ -161,7 +180,7 @@ if _config.enable_destructive_tools:
         priority: str | None = None,
         severity: str | None = None,
     ) -> dict[str, Any]:
-        """Update an existing DevRev work item.
+        """Update an existing DevRev work item (ticket, issue, or task).
 
         Only provided fields will be updated; others remain unchanged.
 
@@ -214,7 +233,7 @@ if _config.enable_destructive_tools:
         ctx: Context[Any, Any, Any],
         id: str,
     ) -> dict[str, Any]:
-        """Delete a DevRev work item.
+        """Delete a DevRev work item (ticket, issue, or task).
 
         Args:
             id: The work item ID to delete.
@@ -234,7 +253,7 @@ async def devrev_works_count(
     type: list[str] | None = None,
     owned_by: list[str] | None = None,
 ) -> dict[str, Any]:
-    """Count DevRev work items matching filters.
+    """Count DevRev work items (tickets, issues, and tasks) matching filters.
 
     Args:
         type: Filter by work type(s): TICKET, ISSUE, TASK, OPPORTUNITY.
@@ -263,14 +282,17 @@ async def devrev_works_export(
     ctx: Context[Any, Any, Any],
     type: list[str] | None = None,
     first: int | None = None,
+    sort_by: list[str] | None = None,
 ) -> dict[str, Any]:
-    """Export DevRev work items.
+    """Export DevRev work items (tickets, issues, and tasks).
 
     Returns a bulk export of work items. Use for large data retrieval.
 
     Args:
         type: Filter by work type(s): TICKET, ISSUE, TASK, OPPORTUNITY.
         first: Maximum number of items to export.
+        sort_by: Sort order as a list of ``"field:asc"`` / ``"field:desc"``
+            entries (or legacy ``"-field"`` shorthand), forwarded to the SDK.
     """
     app = ctx.request_context.lifespan_context
     try:
@@ -284,8 +306,102 @@ async def devrev_works_export(
                     f"Invalid work type: {e.args[0]}. "
                     f"Valid types: {', '.join(wt.name for wt in WorkType)}"
                 ) from e
-        works = await app.get_client().works.export(type=work_types, first=first)
+        works = await app.get_client().works.export(type=work_types, first=first, sort_by=sort_by)
         items = serialize_models(list(works))
         return {"count": len(items), "works": items}
     except DevRevError as e:
         raise RuntimeError(format_devrev_error(e)) from e
+
+
+@mcp.tool()
+async def devrev_works_list_modified_since(
+    ctx: Context[Any, Any, Any],
+    after: str,
+    type: list[str] | None = None,
+    owned_by: list[str] | None = None,
+    applies_to_part: list[str] | None = None,
+    limit: int | None = None,
+) -> dict[str, Any]:
+    """List DevRev work items (tickets, issues, and tasks) modified at or after a timestamp.
+
+    Pages through results server-side sorted by ``modified_date:desc`` and
+    returns all matches. Use ``limit`` as a hard cap on total items.
+
+    Args:
+        after: ISO-8601 timestamp (e.g., ``2024-01-15T00:00:00Z``). Items with
+            ``modified_date >= after`` are returned.
+        type: Filter by work type(s): TICKET, ISSUE, TASK, OPPORTUNITY.
+        owned_by: Filter by owner user ID(s).
+        applies_to_part: Filter by part ID(s) the work applies to.
+        limit: Maximum total items to return across all pages.
+    """
+    after_dt = _parse_iso_after(after, "after")
+    app = ctx.request_context.lifespan_context
+    try:
+        work_types = None
+        if type:
+            try:
+                work_types = [WorkType[t.upper()] for t in type]
+            except KeyError as e:
+                raise RuntimeError(
+                    f"Invalid work type: {e.args[0]}. "
+                    f"Valid types: {', '.join(wt.name for wt in WorkType)}"
+                ) from e
+        works = await app.get_client().works.list_modified_since(
+            after_dt,
+            type=work_types,
+            owned_by=owned_by,
+            applies_to_part=applies_to_part,
+            limit=limit,
+        )
+        items = serialize_models(list(works))
+        return paginated_response(items, next_cursor=None, total_label="works")
+    except DevRevError as e:
+        raise RuntimeError(format_devrev_error(e)) from e
+
+
+@mcp.tool()
+async def devrev_works_list_created_since(
+    ctx: Context[Any, Any, Any],
+    after: str,
+    type: list[str] | None = None,
+    owned_by: list[str] | None = None,
+    applies_to_part: list[str] | None = None,
+    limit: int | None = None,
+) -> dict[str, Any]:
+    """List DevRev work items (tickets, issues, and tasks) created at or after a timestamp.
+
+    Pages through results server-side sorted by ``created_date:desc`` and
+    returns all matches. Use ``limit`` as a hard cap on total items.
+
+    Args:
+        after: ISO-8601 timestamp (e.g., ``2024-01-15T00:00:00Z``). Items with
+            ``created_date >= after`` are returned.
+        type: Filter by work type(s): TICKET, ISSUE, TASK, OPPORTUNITY.
+        owned_by: Filter by owner user ID(s).
+        applies_to_part: Filter by part ID(s) the work applies to.
+        limit: Maximum total items to return across all pages.
+    """
+    after_dt = _parse_iso_after(after, "after")
+    app = ctx.request_context.lifespan_context
+    try:
+        work_types = None
+        if type:
+            try:
+                work_types = [WorkType[t.upper()] for t in type]
+            except KeyError as e:
+                raise RuntimeError(
+                    f"Invalid work type: {e.args[0]}. "
+                    f"Valid types: {', '.join(wt.name for wt in WorkType)}"
+                ) from e
+        works = await app.get_client().works.list_created_since(
+            after_dt,
+            type=work_types,
+            owned_by=owned_by,
+            applies_to_part=applies_to_part,
+            limit=limit,
+        )
+        items = serialize_models(list(works))
+        return paginated_response(items, next_cursor=None, total_label="works")
+    except DevRevError as e:
+        raise RuntimeError(format_devrev_error(e)) from e

{devrev_python_sdk-2.14.0.dist-info → devrev_python_sdk-3.0.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devrev-Python-SDK
-Version: 2.14.0
+Version: 3.0.0
 Summary: A modern, type-safe Python SDK for the DevRev API
 Project-URL: Homepage, https://github.com/mgmonteleone/py-dev-rev
 Project-URL: Documentation, https://github.com/mgmonteleone/py-dev-rev

{devrev_python_sdk-2.14.0.dist-info → devrev_python_sdk-3.0.0.dist-info}/RECORD

@@ -10,7 +10,7 @@ devrev/models/artifacts.py,sha256=3iA58RyVlX0S0U5iID3Cnoc096Y70QfGqYfKEhxfE9g,43
 devrev/models/base.py,sha256=qMxfptmsWimH-MMv84-qojy9Ip858ZYMe6GvTQkDAjo,4511
 devrev/models/brands.py,sha256=6nYVGoy7s8iDYLotfXefMTPIMIJoI8978TXm4RtIswY,3021
 devrev/models/code_changes.py,sha256=cJsv5aX6o859cmhbNwuQBLdhIi5XrN26lBvVF1IfiYs,3420
-devrev/models/conversations.py,sha256=55Hg4xlbZBXcAjqMQcK2mKbCF11y8b2U3gQ7nZqYiPo,4060
+devrev/models/conversations.py,sha256=SwyMFbqziaAo75daxdEl6DS-pEl9a-GFXE4Z-AKACMg,4324
 devrev/models/dev_users.py,sha256=0qQtd7pl2v2SF0pFjlzDWaVOUzI_U_uvNu4kXuXFfBs,9226
 devrev/models/engagements.py,sha256=8mz1KC_lCQIWHcSqX5q_ViQoV4Q9AtW3mcEEQECoAxc,5201
 devrev/models/groups.py,sha256=oB3eCuX14po5E8WhqkuuC-GlC1WXEPVfpqB5tn4NZ-o,4486
@@ -34,15 +34,15 @@ devrev/models/track_events.py,sha256=bb9belz1W3XvrUEgp9mGdOKELhRcWL-59wS9cIa1geY
 devrev/models/uoms.py,sha256=bxjk2YhJ3qrX6C52xuokgLCHD3K4-8DRDeu2QwjnK4E,5700
 devrev/models/webhooks.py,sha256=DzrLJiW1GYWvfaB-aVPcYCf4XkEGHz3dkyzbBKKdhFI,3655
 devrev/models/widgets.py,sha256=7WWN17_ySqnu1pjYSIS5B8J5dEaqkoB8X8GWzvI0ZYc,4577
-devrev/models/works.py,sha256=0PypJjDA5T3d-mmuvo5tl6_EUoz22YREmTWdFHx5jCc,10924
+devrev/models/works.py,sha256=sHZ_eJ6eCadWxPkM6HGcmbkiGRDYT2RnH3QZRO4T3tY,11198
 devrev/services/__init__.py,sha256=LWy_0xGNH692d6Wc4S4E9v6AoxjgfExFMzFmbrL2NTY,3975
 devrev/services/accounts.py,sha256=X7FgcODex0XKLiV_VvXKDl2Jm8XsNpn9qp40oRjZqME,9704
 devrev/services/articles.py,sha256=xOpJOG9f29a5W3IFROplL1a9eJdGucbUFkK-MAIIYlc,41637
 devrev/services/artifacts.py,sha256=SJzIi5M4np0ENoOTTGEAcoqoRFMVd8pe-BCo9vvhYzk,14124
-devrev/services/base.py,sha256=g55dfhd2-uAhgXuguiBacSP4yOAa03Q7hzKDG2vbZ8U,7100
+devrev/services/base.py,sha256=pzUOkOA0kc7yxQQS8AP65L-inpW1WxpsYwtZwA_LXk4,7174
 devrev/services/brands.py,sha256=W6FB9XXTtEzGOfm9IBI6dqY8WXrMeH6urwjiZKrDVgI,5679
 devrev/services/code_changes.py,sha256=ahDniXCz54GGmTFmNh88heUg0mHQcIAgaqwlqm1CP6E,3199
-devrev/services/conversations.py,sha256=yuQ8Sn0ZZ2gDQjG2C8Hjt_UcvD-fJ9R7yWwh7nCH4_o,7546
+devrev/services/conversations.py,sha256=Kx1pOyBc1Wkk32PmPhjXlM2KnLlLuN5Ydzrm9y5iJhM,13635
 devrev/services/dev_users.py,sha256=YDJUNk6Crz2TN_uwkWQIBmztIYrLd8EX3toNLdb_HEk,11870
 devrev/services/engagements.py,sha256=nT6AElHbFO40utp6R_QCGwTGunXjVci73I8YAtkqu8A,9094
 devrev/services/groups.py,sha256=0VpOKTwHiRjrKXrO1kdHo8V_z2I02GphYQhyDFnImxg,4960
@@ -62,7 +62,7 @@ devrev/services/timeline_entries.py,sha256=6nbVPcWlE3-ohLhvkM421eqYS5ztKtHmGsPek
 devrev/services/track_events.py,sha256=lI4wXkWu3uUuXtuRg1MGNkTZ7B0Lc1PjM8Kw-6sUnWc,1439
 devrev/services/uoms.py,sha256=AA3ymoHj24FIbsZpYC4tg2elSdQ3iINTVOz7MraZcj8,8163
 devrev/services/webhooks.py,sha256=-TSkcaya1y48WB24_vHd-bqO5xSqxRsCLiilncNzQZU,3917
-devrev/services/works.py,sha256=b-HWpPMLnda-1P6iB-_QzHu_MoB7z4g_OQGh26rqhtQ,11252
+devrev/services/works.py,sha256=EUlDaUOttiRhvFLa0tkZXtgF3PpLLZlyUqjf3Hp4zRo,21239
 devrev/utils/__init__.py,sha256=NOrbpkjDVLH8n9xf-xpZJiIIa_GVI_6vqTm3E8L3Udw,857
 devrev/utils/content_converter.py,sha256=emRBLiVoOfDGpPDzrMRnqQr4-QkqN13OdWlYOyU_LCg,28141
 devrev/utils/deprecation.py,sha256=7qB2Dx531oP7mNi7q2txOYsOKC9YwdHqlKPMFHOW9Ws,1275
@@ -95,7 +95,7 @@ devrev_mcp/resources/user.py,sha256=0Paq2w_nbj_dCQ8R0S81zlgjUhDAUzvn1_NmshadqM8,
 devrev_mcp/tools/__init__.py,sha256=wiou4HHy6HeOQY0El3KYqy_S7c2IC4hjsYHjMm7aH-w,54
 devrev_mcp/tools/accounts.py,sha256=CKD5bKxCNpm_60lakcrG9pBwNTrWOncH6MVQF4rT5wQ,6173
 devrev_mcp/tools/articles.py,sha256=tna2ZLcefAaYbvICbRicM-0gk1HEx5HJSLS5Sz9t0iI,14063
-devrev_mcp/tools/conversations.py,sha256=qpY12ZEOLv5IwVtokneZQpI3rmTWs3bFcWlxnRI97fU,5885
+devrev_mcp/tools/conversations.py,sha256=aEH8MOAQbdOEyIWbqGLYK2JjXcTaxAJqB5prBzmXvpY,8836
 devrev_mcp/tools/engagements.py,sha256=21zsMLlgY1FwKzSIxPf6XVdMY77p8NXrWZ7l8PRKI-0,8928
 devrev_mcp/tools/groups.py,sha256=E29eptwl_1rbmMPPElcSblWs71t1XdvSZIl1UR8TZr0,8456
 devrev_mcp/tools/incidents.py,sha256=XO9FaZlLHCXULCFpMpCOftYNfvajH5PeXOkW2uUZ_Z4,7984
@@ -110,13 +110,13 @@ devrev_mcp/tools/slas.py,sha256=q7eYC7nMxCGoHMDp1QbtCgSWiG4oHk78sydPtYwsh10,4902
 devrev_mcp/tools/tags.py,sha256=zj_my9CkPQu8_TTOqszfLULPNgxm83kHux-rWFxHvXQ,4711
 devrev_mcp/tools/timeline.py,sha256=p7P699Oq205jrzCVyYS6v4bXHEQizircHVyS5JE-GJ4,5326
 devrev_mcp/tools/users.py,sha256=7CtrxjgxniEb5-DaPh0rwL680a2fDFLJSIU5huuTjYE,4896
-devrev_mcp/tools/works.py,sha256=B1og_hy4gfCW9e38TzLVg8CGppKP6QKEMO2uCwZ5H5I,10446
+devrev_mcp/tools/works.py,sha256=IFaIXYR4j_2pZ39ykZgdHdo5nCk8OfgWU5bxBdHwp5E,15241
 devrev_mcp/utils/__init__.py,sha256=2_5b1KC5kjoUqFY1ZSdB2Tefd2ekjbZ-eHyFWBKI-0A,49
 devrev_mcp/utils/don_id.py,sha256=PAVzOSgaiqJQSdo1fwohFHq2x7PDNUZoBTN4LFGYM48,6294
 devrev_mcp/utils/errors.py,sha256=5mRAo76rJvvEVi6b1ZokPxDtX5JKkptaqmiYDLCkwBE,2110
 devrev_mcp/utils/formatting.py,sha256=6JssG5x1BxjdgSiQ8Ou3H-9Wo3wgWTWmejsrGez4wKc,2431
 devrev_mcp/utils/pagination.py,sha256=EOUgL-ZdSToM1Q-ydXmjhibsef5K1u1g3CaS9K8I2fY,1286
-devrev_python_sdk-2.14.0.dist-info/METADATA,sha256=0DK8rjdaH_pV5HiIfZ6-XGXdZOYiGA7NMoIss2dGo-M,40907
-devrev_python_sdk-2.14.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
-devrev_python_sdk-2.14.0.dist-info/entry_points.txt,sha256=XiV4J_yy0yzVZVxg7T66YERVIlqdPNp3O-NHTHkllqQ,63
-devrev_python_sdk-2.14.0.dist-info/RECORD,,
+devrev_python_sdk-3.0.0.dist-info/METADATA,sha256=X6qGjwru56IRRe8VAMJqh8AQTWKhjn0r4S_-GjGkbc4,40906
+devrev_python_sdk-3.0.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+devrev_python_sdk-3.0.0.dist-info/entry_points.txt,sha256=XiV4J_yy0yzVZVxg7T66YERVIlqdPNp3O-NHTHkllqQ,63
+devrev_python_sdk-3.0.0.dist-info/RECORD,,