Add full Lists API support with list-item operations

Author: pengfeiye

CHANGELOG.md

@@ -2,6 +2,7 @@ nylas-python Changelog
 ======================
 Unreleased
 ----------
+* Added Lists support (`Client.lists`, `/v3/lists`): list, create, find, update, and delete lists, plus `list_items`, `add_items`, and `remove_items` for `/v3/lists/{list_id}/items`, with typed request/response models in `nylas.models.lists`
 * Added Manage Domains (`Client.domains`, `/v3/admin/domains`): list, create, find, update, delete, `get_info`, and `verify` with models in `nylas.models.domains`; optional `ServiceAccountSigner` (`nylas.handler.service_account`) for service-account headers (`X-Nylas-Kid`, `X-Nylas-Nonce`, `X-Nylas-Timestamp`, `X-Nylas-Signature`) on each `Domains` method; new `cryptography` dependency, RSA signing, and `HttpClient` `serialized_json_body` so signed payloads match the wire body
 * Added Transactional Send: `Client.transactional_send.send()` for `POST /v3/domains/{domain_name}/messages/send`, with `TransactionalSendMessageRequest` and `TransactionalTemplate` models (JSON and multipart send behavior aligned with grant `messages.send`)
 * Added Policies support (`Client.policies`, `/v3/policies`): list, create, find, update, and delete, with typed request/response models in `nylas.models.policies`

nylas/client.py

@@ -8,6 +8,7 @@
 from nylas.resources.events import Events
 from nylas.resources.folders import Folders
 from nylas.resources.messages import Messages
+from nylas.resources.lists import Lists
 from nylas.resources.threads import Threads
 from nylas.resources.transactional_send import TransactionalSend
 from nylas.resources.webhooks import Webhooks
@@ -186,6 +187,16 @@ def messages(self) -> Messages:
         """
         return Messages(self.http_client)
 
+    @property
+    def lists(self) -> Lists:
+        """
+        Access the Lists API.
+
+        Returns:
+            The Lists API.
+        """
+        return Lists(self.http_client)
+
     @property
     def threads(self) -> Threads:
         """

nylas/models/lists.py

@@ -0,0 +1,69 @@
+from dataclasses import dataclass
+from typing import List as TypingList, Literal, Optional
+
+from dataclasses_json import dataclass_json
+from typing_extensions import NotRequired, TypedDict
+
+from nylas.models.list_query_params import ListQueryParams
+
+ListType = Literal["domain", "tld", "address"]
+
+
+class ListListsQueryParams(ListQueryParams):
+    """Query parameters for listing lists."""
+
+    pass
+
+
+class ListListItemsQueryParams(ListQueryParams):
+    """Query parameters for listing items in a list."""
+
+    pass
+
+
+class CreateListRequest(TypedDict):
+    """Request body for creating a list."""
+
+    name: str
+    type: ListType
+    description: NotRequired[str]
+
+
+class UpdateListRequest(TypedDict, total=False):
+    """Request body for updating a list."""
+
+    name: NotRequired[str]
+    description: NotRequired[str]
+
+
+class UpdateListItemsRequest(TypedDict):
+    """Request body for adding/removing list items."""
+
+    items: TypingList[str]
+
+
+@dataclass_json
+@dataclass
+class NylasList:
+    """A typed collection used in `in_list` rule conditions."""
+
+    id: Optional[str] = None
+    name: Optional[str] = None
+    description: Optional[str] = None
+    type: Optional[str] = None
+    items_count: Optional[int] = None
+    application_id: Optional[str] = None
+    organization_id: Optional[str] = None
+    created_at: Optional[int] = None
+    updated_at: Optional[int] = None
+
+
+@dataclass_json
+@dataclass
+class ListItem:
+    """A single value belonging to a Nylas list."""
+
+    id: Optional[str] = None
+    list_id: Optional[str] = None
+    value: Optional[str] = None
+    created_at: Optional[int] = None

nylas/resources/lists.py

@@ -0,0 +1,126 @@
+from nylas.config import RequestOverrides
+from nylas.handler.api_resources import (
+    CreatableApiResource,
+    DestroyableApiResource,
+    FindableApiResource,
+    ListableApiResource,
+    UpdatableApiResource,
+)
+from nylas.models.lists import (
+    CreateListRequest,
+    ListItem,
+    ListListItemsQueryParams,
+    ListListsQueryParams,
+    NylasList,
+    UpdateListItemsRequest,
+    UpdateListRequest,
+)
+from nylas.models.response import DeleteResponse, ListResponse, Response
+
+
+class Lists(
+    ListableApiResource,
+    FindableApiResource,
+    CreatableApiResource,
+    UpdatableApiResource,
+    DestroyableApiResource,
+):
+    """Nylas Lists API."""
+
+    def list(
+        self,
+        query_params: ListListsQueryParams = None,
+        overrides: RequestOverrides = None,
+    ) -> ListResponse[NylasList]:
+        """Return all lists for the application."""
+        return super().list(
+            path="/v3/lists",
+            response_type=NylasList,
+            query_params=query_params,
+            overrides=overrides,
+        )
+
+    def create(
+        self,
+        request_body: CreateListRequest,
+        overrides: RequestOverrides = None,
+    ) -> Response[NylasList]:
+        """Create a new list."""
+        return super().create(
+            path="/v3/lists",
+            request_body=request_body,
+            response_type=NylasList,
+            overrides=overrides,
+        )
+
+    def find(self, list_id: str, overrides: RequestOverrides = None) -> Response[NylasList]:
+        """Return a specific list by ID."""
+        return super().find(
+            path=f"/v3/lists/{list_id}",
+            response_type=NylasList,
+            overrides=overrides,
+        )
+
+    def update(
+        self,
+        list_id: str,
+        request_body: UpdateListRequest,
+        overrides: RequestOverrides = None,
+    ) -> Response[NylasList]:
+        """Update a list by ID."""
+        return super().update(
+            path=f"/v3/lists/{list_id}",
+            response_type=NylasList,
+            request_body=request_body,
+            method="PUT",
+            overrides=overrides,
+        )
+
+    def destroy(self, list_id: str, overrides: RequestOverrides = None) -> DeleteResponse:
+        """Delete a list by ID."""
+        return super().destroy(path=f"/v3/lists/{list_id}", overrides=overrides)
+
+    def list_items(
+        self,
+        list_id: str,
+        query_params: ListListItemsQueryParams = None,
+        overrides: RequestOverrides = None,
+    ) -> ListResponse[ListItem]:
+        """Return all items in a list."""
+        return super().list(
+            path=f"/v3/lists/{list_id}/items",
+            response_type=ListItem,
+            query_params=query_params,
+            overrides=overrides,
+        )
+
+    def add_items(
+        self,
+        list_id: str,
+        request_body: UpdateListItemsRequest,
+        overrides: RequestOverrides = None,
+    ) -> Response[NylasList]:
+        """Add items to a list."""
+        return super().create(
+            path=f"/v3/lists/{list_id}/items",
+            request_body=request_body,
+            response_type=NylasList,
+            overrides=overrides,
+        )
+
+    def remove_items(
+        self,
+        list_id: str,
+        request_body: UpdateListItemsRequest,
+        overrides: RequestOverrides = None,
+    ) -> Response[NylasList]:
+        """Remove items from a list."""
+        json_response, headers = self._http_client._execute(
+            "DELETE",
+            f"/v3/lists/{list_id}/items",
+            None,
+            None,
+            request_body,
+            overrides=overrides,
+        )
+        return Response.from_dict(json_response, NylasList, headers)