devrev-Python-SDK 2.14.1__tar.gz → 3.0.0__tar.gz

{devrev_python_sdk-2.14.1 → devrev_python_sdk-3.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devrev-Python-SDK
-Version: 2.14.1
+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-3.0.0/docs/api/services/conversations.md

@@ -0,0 +1,84 @@
+# Conversations Service
+
+Manage customer conversations in DevRev.
+
+## ConversationsService
+
+::: devrev.services.conversations.ConversationsService
+    options:
+      show_source: true
+
+## AsyncConversationsService
+
+::: devrev.services.conversations.AsyncConversationsService
+    options:
+      show_source: true
+
+## Usage Examples
+
+### List Conversations
+
+```python
+from devrev import DevRevClient
+
+client = DevRevClient()
+
+response = client.conversations.list(limit=20)
+for conv in response.conversations:
+    print(f"{conv.id}: {conv.title}")
+```
+
+### Get Conversation
+
+```python
+response = client.conversations.get(id="don:core:dvrv-us-1:devo/1:conversation/123")
+print(f"Title: {response.conversation.title}")
+```
+
+### Sort Order
+
+`list` accepts a `sort_by` parameter. Both forms are accepted and normalized
+to the server form before the request is sent:
+
+- Canonical: `"modified_date:desc"`, `"created_date:asc"`
+- Legacy shortcut: `"-modified_date"` (descending), `"created_date"` (ascending)
+
+!!! note "Server requires `field:direction`"
+    The DevRev server rejects bare `"-field"` entries. The SDK normalizes
+    legacy shortcuts to the `field:direction` form on your behalf.
+
+### List Conversations Modified Since
+
+Use `list_modified_since` to stream conversations that changed within a recent
+window. It pages server-side sorted `modified_date:desc` and stops as soon as
+a record older than the cutoff is seen.
+
+```python
+from datetime import datetime, timedelta, timezone
+from devrev import DevRevClient
+
+client = DevRevClient()
+
+cutoff = datetime.now(timezone.utc) - timedelta(days=7)
+recent = client.conversations.list_modified_since(cutoff, limit=200)
+for conv in recent:
+    print(f"{conv.id}: {conv.title}")
+```
+
+### Async Usage
+
+```python
+import asyncio
+from datetime import datetime, timedelta, timezone
+from devrev import AsyncDevRevClient
+
+async def main():
+    async with AsyncDevRevClient() as client:
+        cutoff = datetime.now(timezone.utc) - timedelta(days=1)
+        recent = await client.conversations.list_modified_since(cutoff)
+        for conv in recent:
+            print(f"{conv.id}: {conv.title}")
+
+asyncio.run(main())
+```
+

{devrev_python_sdk-2.14.1 → devrev_python_sdk-3.0.0}/docs/api/services/works.md

@@ -2,6 +2,9 @@
 
 Manage work items (issues, tickets, tasks, opportunities) in DevRev.
 
+In DevRev, **works** is the umbrella type covering tickets (customer support),
+issues (engineering), and tasks.
+
 ## WorksService
 
 ::: devrev.services.works.WorksService
@@ -15,6 +18,8 @@ Manage work items (issues, tickets, tasks, opportunities) in DevRev.
         - delete
         - export
         - count
+        - list_modified_since
+        - list_created_since
 
 ## AsyncWorksService
 
@@ -121,6 +126,65 @@ response = client.works.export(
 print(f"Exported {len(response.works)} issues")
 ```
 
+### Sort Order
+
+`list` and `export` accept a `sort_by` parameter. Both forms are accepted and
+normalized to the server form before the request is sent:
+
+- Canonical: `"modified_date:desc"`, `"created_date:asc"`
+- Legacy shortcut: `"-modified_date"` (descending), `"created_date"` (ascending)
+
+```python
+# Canonical form
+response = client.works.list(
+    type=[WorkType.TICKET],
+    sort_by=["modified_date:desc"],
+)
+
+# Legacy shortcut — normalized internally to "modified_date:desc"
+response = client.works.list(
+    type=[WorkType.TICKET],
+    sort_by=["-modified_date"],
+)
+```
+
+!!! note "Server requires `field:direction`"
+    The DevRev server rejects bare `"-field"` entries. The SDK normalizes
+    legacy shortcuts to the `field:direction` form on your behalf — you do not
+    need to change existing call sites, but new code should prefer the
+    canonical form.
+
+### List Work Items Modified or Created Since
+
+Use `list_modified_since` / `list_created_since` to stream work items that
+changed within a recent window. Both helpers page server-side sorted
+`{timestamp_field}:desc` and early-exit as soon as a record older than the
+cutoff is seen.
+
+```python
+from datetime import datetime, timedelta, timezone
+from devrev import DevRevClient
+from devrev.models import WorkType
+
+client = DevRevClient()
+
+cutoff = datetime.now(timezone.utc) - timedelta(days=7)
+
+# All works modified in the last 7 days
+recent = client.works.list_modified_since(
+    cutoff,
+    type=[WorkType.TICKET, WorkType.ISSUE],
+)
+
+# Cap total items; page_size tunes per-request page size
+recent_capped = client.works.list_created_since(
+    cutoff,
+    type=[WorkType.TICKET],
+    limit=500,
+    page_size=100,
+)
+```
+
 ### Async Usage
 
 ```python
@@ -133,6 +197,10 @@ async def main():
         for work in response.works:
             print(f"[{work.type}] {work.title}")
 
+        # Async variants of the time-based helpers
+        cutoff = datetime.now(timezone.utc) - timedelta(days=1)
+        recent = await client.works.list_modified_since(cutoff)
+
 asyncio.run(main())
 ```
 

{devrev_python_sdk-2.14.1 → devrev_python_sdk-3.0.0}/docs/changelog.md

@@ -7,6 +7,94 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+### Changed
+
+### Fixed
+
+## [3.0.0] - 2026-04-22
+
+### Added
+
+- **`WorksService.list_modified_since` and `list_created_since`** (CUSS-451) —
+  New sync and async helpers on `WorksService` / `AsyncWorksService` that
+  stream work items with `modified_date >= after` or `created_date >= after`.
+  Both page server-side sorted `{timestamp_field}:desc` and early-exit when a
+  record older than the cutoff is seen. Accept `type`, `owned_by`,
+  `applies_to_part`, `limit` (hard cap on total items), and `page_size`
+  (per-request page size).
+- **`ConversationsService.list_modified_since`** (CUSS-451) — New sync and
+  async helper that streams conversations modified after a given datetime,
+  newest first. Pages via cursor until the server returns no further cursor,
+  `limit` is reached, or a conversation older than `after` is seen. Accepts
+  `limit` and `page_size`.
+- **MCP tools for time-windowed queries** (CUSS-451) —
+  `devrev_works_list_modified_since`, `devrev_works_list_created_since`, and
+  `devrev_conversations_list_modified_since`. Each accepts an ISO-8601
+  `after` timestamp and optional `limit`.
+- **`sort_by` and `modified_date_after` / `modified_date_before` on
+  `devrev_conversations_list` MCP tool** (CUSS-451) — Expose the same sort
+  and date-range filters already available in the SDK `list` request.
+- **`sort_by` on `devrev_works_list` and `devrev_works_export` MCP tools**
+  (CUSS-451) — Forward the sort order down to the SDK.
+
+### Changed / Breaking
+
+- **BREAKING: `WorksListRequest` and `WorksExportRequest` no longer accept
+  date filter fields** (CUSS-451) — `WorksListRequest` previously exposed
+  `created_date` and `modified_date` fields, and `WorksExportRequest`
+  previously exposed a `created_date` field. These were aspirational: the
+  DevRev PUBLIC API rejects both filters on `/works.list` and
+  `/works.export` with `400 bad-request.bad-request-field`. The fields have
+  been removed from both request models. Existing callers that populate
+  `WorksListRequest(created_date=...)`,
+  `WorksListRequest(modified_date=...)`, or
+  `WorksExportRequest(created_date=...)` will now raise
+  `pydantic.ValidationError` at construction time.
+
+    **Migration**: use the new `WorksService.list_modified_since` /
+    `WorksService.list_created_since` helpers (sync and async), which page
+    server-side sorted `{timestamp_field}:desc` and early-exit on records
+    older than the cutoff. See `docs/api/services/works.md` for examples.
+- **`sort_by` syntax normalization** (CUSS-451) — The DevRev server rejects
+  bare `"-field"` entries on `/works.list` and `/conversations.list` and
+  requires the canonical `"field:asc"` / `"field:desc"` form. `WorksService`
+  and `ConversationsService` now normalize both legacy `"-field"` /
+  `"field"` shortcuts and canonical `"field:direction"` entries to the
+  server form before sending the request. Existing call sites using the
+  `"-field"` shortcut continue to work unchanged; new code should prefer the
+  canonical form. Callers that previously sent `"-field"` directly to a
+  request model and bypassed the service layer will now see their input
+  normalized when they route through `WorksService.list` /
+  `ConversationsService.list`.
+
+### Fixed
+
+- **`/works.list` rejected bare `"-field"` sort entries** (CUSS-451) —
+  Integration tests observed the DevRev PUBLIC API returning an error for
+  bare `"-modified_date"` / `"-created_date"` sort values, requiring the
+  canonical `field:direction` form. `WorksService.list` /
+  `WorksService.export` (and their async variants) now normalize
+  `sort_by` before sending.
+- **`/conversations.list` rejected bare `"-field"` sort entries** (CUSS-451)
+  — Same server behavior observed for conversations. `ConversationsService.list`
+  (and its async variant) now normalize `sort_by` before sending.
+- **`list_modified_since` / `list_created_since` helpers paginate until the
+  cutoff is crossed** (CUSS-451) — Server-side `modified_date` / `created_date`
+  filters may not be honored uniformly across older accounts. The new
+  helpers apply client-side early-exit on the sorted stream so results are
+  bounded by the cutoff even when the server does not filter.
+- **`BaseService._post` serialized non-JSON-native types incorrectly**
+  (CUSS-451) — `BaseService._post` and `AsyncBaseService._post` dumped
+  request models with `model_dump(exclude_none=True, by_alias=True)`, which
+  returns Python-native types (e.g., `datetime` as `datetime` objects
+  rather than ISO 8601 strings). Request bodies containing timestamps — as
+  used by the new `list_modified_since` / `list_created_since` filter
+  payloads — failed to round-trip through the HTTP layer. Both methods now
+  pass `mode="json"` so Pydantic produces JSON-serializable primitives
+  before the request is sent.
+
 ## [2.14.1] - 2026-04-14
 
 ### Security
@@ -636,6 +724,7 @@ This release marks the completion of all four development phases, providing a pr
 
 | Version | Date | Highlights |
 |---------|------|------------|
+| 3.0.0 | 2026-04-22 | 🚨 BREAKING: Remove unsupported date filter fields from Works requests; add time-windowed list helpers |
 | 2.7.0 | 2026-02-28 | 🔍 Server version discoverability for AI agents |
 | 2.6.0 | 2026-02-28 | 🔐 Compliance-grade audit logging, MCP documentation |
 | 2.4.1 | 2026-02-27 | 🐛 CI: mypy strict-mode type errors, test collection |

{devrev_python_sdk-2.14.1 → devrev_python_sdk-3.0.0}/docs/mcp/tools-reference.md

@@ -10,15 +10,32 @@ Complete reference of all MCP capabilities provided by the DevRev MCP Server.
 
 Tools are the primary way AI assistants interact with DevRev. Each tool maps to one or more DevRev API endpoints.
 
-### Works (Tickets & Issues)
+### Works (Tickets, Issues & Tasks)
+
+In DevRev, **works** is the umbrella type covering tickets (customer support),
+issues (engineering), and tasks.
 
 | Tool | Description |
 |------|-------------|
-| `devrev_works_list` | List work items (tickets, issues) with filters |
+| `devrev_works_list` | List work items with filters and `sort_by` (e.g., `["modified_date:desc"]`) |
 | `devrev_works_get` | Get a specific work item by ID |
-| `devrev_works_create` | Create a new ticket or issue |
+| `devrev_works_create` | Create a new ticket, issue, or task |
 | `devrev_works_update` | Update a work item's fields |
 | `devrev_works_delete` | Delete a work item (requires destructive tools enabled) |
+| `devrev_works_export` | Bulk-export work items (accepts `sort_by`) |
+| `devrev_works_list_modified_since` | List work items with `modified_date >= after` (ISO-8601), paged newest-first |
+| `devrev_works_list_created_since` | List work items with `created_date >= after` (ISO-8601), paged newest-first |
+
+**Key parameters:**
+
+- `sort_by` (on `devrev_works_list` / `devrev_works_export`): List of
+  `"field:asc"` / `"field:desc"` entries. The legacy `"-field"` shortcut is
+  also accepted and normalized by the SDK before the request is sent.
+- `after` (on `*_list_modified_since` / `*_list_created_since`): ISO-8601
+  timestamp (e.g., `"2025-01-15T00:00:00Z"`). Items at or after this
+  timestamp are returned.
+- `limit` (on `*_list_modified_since` / `*_list_created_since`): Hard cap on
+  total items returned across all pages.
 
 ### Accounts
 
@@ -64,11 +81,22 @@ Tools are the primary way AI assistants interact with DevRev. Each tool maps to
 
 | Tool | Description |
 |------|-------------|
-| `devrev_conversations_list` | List conversations |
+| `devrev_conversations_list` | List conversations; supports `modified_date_after` / `modified_date_before` (ISO-8601) and `sort_by` |
+| `devrev_conversations_list_modified_since` | List conversations with `modified_date >= after` (ISO-8601), paged newest-first |
 | `devrev_conversations_get` | Get conversation details |
 | `devrev_conversations_create` | Create a conversation |
 | `devrev_conversations_update` | Update a conversation |
 
+**Key parameters:**
+
+- `modified_date_after` / `modified_date_before` (on `devrev_conversations_list`):
+  ISO-8601 timestamps bounding the `modified_date` filter.
+- `sort_by` (on `devrev_conversations_list`): Same syntax as on
+  `devrev_works_list` — `"field:asc"` / `"field:desc"` entries, with the
+  legacy `"-field"` shortcut accepted and normalized by the SDK.
+- `after` (on `devrev_conversations_list_modified_since`): ISO-8601
+  timestamp. Items at or after this timestamp are returned.
+
 ### Parts (Products & Features)
 
 | Tool | Description |

{devrev_python_sdk-2.14.1 → devrev_python_sdk-3.0.0}/openapi-spec-corrections.yaml

@@ -220,3 +220,115 @@ components:
           nullable: true
           description: User state
 
+    # ============================================================================
+    # CORRECTION #3: /works.list sort_by syntax (CUSS-451)
+    # ============================================================================
+    #
+    # Issue: OpenAPI spec documents `sort_by` as an array of strings without
+    #   specifying the accepted entry format. The live PUBLIC API rejects
+    #   bare "-field" shortcuts and requires the canonical
+    #   "field:asc" / "field:desc" form.
+    #
+    # Affected Endpoint: POST /works.list (and POST /works.export)
+    # Severity: HIGH - Causes 4xx validation errors for any client that
+    #   relies on the common "-field" descending shortcut.
+    # Ticket: CUSS-451
+    #
+    # Observed server response for `sort_by: ["-modified_date"]`:
+    #   400 Bad Request — "sort_by entries must be of the form
+    #   'field:asc' or 'field:desc'"
+    #
+    # SDK Mitigation: `WorksService.list` / `WorksService.export` normalize
+    #   `sort_by` entries before sending. Callers MAY continue to pass
+    #   "-field" / "field" shortcuts; they are rewritten to
+    #   "field:desc" / "field:asc" on the wire.
+    #
+    # Spec Correction (documentation-only — no schema change needed):
+    WorksListSortByCorrection:
+      type: array
+      description: |
+        Sort order for /works.list results.
+
+        **Required format**: Each entry MUST be `"field:asc"` or
+        `"field:desc"`. The server rejects bare `"-field"` and `"field"`
+        shortcuts.
+
+        **SDK behavior**: The Python SDK normalizes legacy shortcuts to the
+        canonical form before sending, so callers may pass either format to
+        `WorksService.list` / `WorksService.export`.
+      items:
+        type: string
+        pattern: "^[a-zA-Z_][a-zA-Z0-9_.]*:(asc|desc)$"
+        example: "modified_date:desc"
+      example:
+        - "modified_date:desc"
+        - "created_date:asc"
+
+    # ============================================================================
+    # CORRECTION #4: /conversations.list sort_by syntax (CUSS-451)
+    # ============================================================================
+    #
+    # Issue: Same as Correction #3 but on the conversations endpoint. The
+    #   live PUBLIC API rejects bare "-field" entries on
+    #   POST /conversations.list and requires "field:asc" / "field:desc".
+    #
+    # Affected Endpoint: POST /conversations.list
+    # Severity: HIGH - Causes 4xx validation errors.
+    # Ticket: CUSS-451
+    #
+    # SDK Mitigation: `ConversationsService.list` normalizes `sort_by`
+    #   entries before sending.
+    ConversationsListSortByCorrection:
+      type: array
+      description: |
+        Sort order for /conversations.list results.
+
+        **Required format**: Each entry MUST be `"field:asc"` or
+        `"field:desc"`. Matches the corrected syntax documented for
+        /works.list.
+      items:
+        type: string
+        pattern: "^[a-zA-Z_][a-zA-Z0-9_.]*:(asc|desc)$"
+        example: "modified_date:desc"
+      example:
+        - "modified_date:desc"
+
+    # ============================================================================
+    # CORRECTION #5: Time-windowed listing on /works.list and /conversations.list (CUSS-451)
+    # ============================================================================
+    #
+    # Issue: The spec documents `modified_date` / `created_date` filters on
+    #   /works.list and /conversations.list, but server-side filtering is
+    #   not uniformly honored across all accounts. Observed behavior:
+    #     - Some accounts return records older than the declared `after`
+    #       cutoff when paginating results.
+    #     - Sort order is honored reliably when `sort_by` uses the
+    #       `field:direction` form (see Corrections #3 and #4).
+    #
+    # Affected Endpoints: POST /works.list, POST /conversations.list
+    # Severity: MEDIUM - Does not break validation, but causes over-broad
+    #   result sets for clients that rely on the server-side date filter.
+    # Ticket: CUSS-451
+    #
+    # SDK Mitigation: `WorksService.list_modified_since`,
+    #   `WorksService.list_created_since`, and
+    #   `ConversationsService.list_modified_since` page server-side sorted
+    #   `{timestamp_field}:desc` and apply a client-side early-exit as soon
+    #   as a record older than the cutoff is seen. This guarantees the
+    #   returned set is bounded by the cutoff regardless of server-side
+    #   filter behavior.
+    #
+    # Documentation-only correction (no schema change):
+    TimeWindowedListingCorrection:
+      type: object
+      description: |
+        /works.list and /conversations.list support `modified_date` and
+        (for works) `created_date` filters, but server-side honoring of
+        these filters is inconsistent across accounts. Clients that need a
+        strict time-window guarantee should sort by the timestamp field in
+        descending order and early-exit on the first record older than the
+        cutoff.
+      properties:
+        note:
+          type: string
+          example: "See SDK helpers list_modified_since / list_created_since."

{devrev_python_sdk-2.14.1 → devrev_python_sdk-3.0.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "devrev-Python-SDK"
-version = "2.14.1"
+version = "3.0.0"
 description = "A modern, type-safe Python SDK for the DevRev API"
 readme = "README.md"
 requires-python = ">=3.11"

{devrev_python_sdk-2.14.1 → devrev_python_sdk-3.0.0}/src/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_python_sdk-2.14.1 → devrev_python_sdk-3.0.0}/src/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_python_sdk-2.14.1 → devrev_python_sdk-3.0.0}/src/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)