Folders API support

CHANGELOG.md

@@ -4,6 +4,7 @@ nylas-python Changelog
 v6.0.0b6
 ----------------
 * Add support for Read, Update, and Delete for Messages API
+* Add support for folders API
 * Fix required fields for `Calendar` and `Grant` models
 
 v6.0.0b5

nylas/client.py

@@ -5,6 +5,7 @@
 from nylas.resources.calendars import Calendars
 from nylas.resources.connectors import Connectors
 from nylas.resources.events import Events
+from nylas.resources.folders import Folders
 from nylas.resources.messages import Messages
 from nylas.resources.threads import Threads
 from nylas.resources.webhooks import Webhooks
@@ -85,6 +86,16 @@ def events(self) -> Events:
         """
         return Events(self.http_client)
 
+    @property
+    def folders(self) -> Folders:
+        """
+        Access the Folders API.
+
+        Returns:
+            The Folders API.
+        """
+        return Folders(self.http_client)
+
     @property
     def messages(self) -> Messages:
         """

nylas/models/folders.py

@@ -0,0 +1,72 @@
+from dataclasses import dataclass
+from typing import Optional
+
+from dataclasses_json import dataclass_json
+from typing_extensions import TypedDict, NotRequired
+
+
+@dataclass_json
+@dataclass
+class Folder:
+    """
+    Class representing a Nylas folder.
+
+    Attributes:
+        id: A globally unique object identifier.
+        grant_id: A Grant ID of the Nylas account.
+        name: Folder name
+        object: The type of object.
+        parent_id: ID of the parent folder. (Microsoft only)
+        background_color: Folder background color. (Google only)
+        text_color: Folder text color. (Google only)
+        system_folder: Indicates if the folder is user created or system created. (Google Only)
+        child_count: The number of immediate child folders in the current folder. (Microsoft only)
+        unread_count: The number of unread items inside of a folder.
+        total_count: The number of items inside of a folder.
+    """
+
+    id: str
+    grant_id: str
+    name: str
+    object: str = "folder"
+    parent_id: Optional[str] = None
+    background_color: Optional[str] = None
+    text_color: Optional[str] = None
+    system_folder: Optional[bool] = None
+    child_count: Optional[int] = None
+    unread_count: Optional[int] = None
+    total_count: Optional[int] = None
+
+
+class CreateFolderRequest(TypedDict):
+    """
+    Class representation of the Nylas folder creation request.
+
+    Attributes:
+        name: The name of the folder.
+        parent_id: The parent ID of the folder. (Microsoft only)
+        background_color: The background color of the folder. (Google only)
+        tex_color: The text color of the folder. (Google only)
+    """
+
+    name: str
+    parent_id: NotRequired[str]
+    background_color: NotRequired[str]
+    tex_color: NotRequired[str]
+
+
+class UpdateFolderRequest(TypedDict):
+    """
+    Class representation of the Nylas folder update request.
+
+    Attributes:
+        name: The name of the folder.
+        parent_id: The parent ID of the folder. (Microsoft only)
+        background_color: The background color of the folder. (Google only)
+        tex_color: The text color of the folder. (Google only)
+    """
+
+    name: NotRequired[str]
+    parent_id: NotRequired[str]
+    background_color: NotRequired[str]
+    tex_color: NotRequired[str]

nylas/resources/folders.py

@@ -0,0 +1,107 @@
+from nylas.handler.api_resources import (
+    ListableApiResource,
+    FindableApiResource,
+    CreatableApiResource,
+    UpdatableApiResource,
+    DestroyableApiResource,
+)
+from nylas.models.folders import (
+    Folder,
+    CreateFolderRequest,
+    UpdateFolderRequest,
+)
+from nylas.models.response import Response, ListResponse, DeleteResponse
+
+
+class Folders(
+    ListableApiResource,
+    FindableApiResource,
+    CreatableApiResource,
+    UpdatableApiResource,
+    DestroyableApiResource,
+):
+    def list(self, identifier: str) -> ListResponse[Folder]:
+        """
+        Return all Folders.
+
+        Args:
+            identifier: The identifier of the Grant to act upon.
+
+        Returns:
+            The list of Folders.
+        """
+
+        return super(Folders, self).list(
+            path=f"/v3/grants/{identifier}/folders",
+            response_type=Folder,
+        )
+
+    def find(self, identifier: str, folder_id: str) -> Response[Folder]:
+        """
+        Return a Folder.
+
+        Args:
+            identifier: The identifier of the Grant to act upon.
+            folder_id: The ID of the Folder to retrieve.
+
+        Returns:
+            The Folder.
+        """
+        return super(Folders, self).find(
+            path=f"/v3/grants/{identifier}/folders/{folder_id}",
+            response_type=Folder,
+        )
+
+    def create(
+        self, identifier: str, request_body: CreateFolderRequest
+    ) -> Response[Folder]:
+        """
+        Create a Folder.
+
+        Args:
+            identifier: The identifier of the Grant to act upon.
+            request_body: The values to create the Folder with.
+
+        Returns:
+            The created Folder.
+        """
+        return super(Folders, self).create(
+            path=f"/v3/grants/{identifier}/folders",
+            response_type=Folder,
+            request_body=request_body,
+        )
+
+    def update(
+        self, identifier: str, folder_id: str, request_body: UpdateFolderRequest
+    ) -> Response[Folder]:
+        """
+        Update a Folder.
+
+        Args:
+            identifier: The identifier of the Grant to act upon.
+            folder_id: The ID of the Folder to update.
+            request_body: The values to update the Folder with.
+
+        Returns:
+            The updated Folder.
+        """
+        return super(Folders, self).update(
+            path=f"/v3/grants/{identifier}/folders/{folder_id}",
+            response_type=Folder,
+            request_body=request_body,
+        )
+
+    def destroy(self, identifier: str, folder_id: str) -> DeleteResponse:
+        """
+        Delete a Folder.
+
+        Args:
+            identifier: The identifier of the Grant to act upon.
+            folder_id: The ID of the Folder to delete.
+
+        Returns:
+            The deletion response.
+        """
+        return super(Folders, self).destroy(
+            path=f"/v3/grants/{identifier}/folders/{folder_id}"
+        )