feat: add support for include_hidden_folders query parameter in list folders endpoint (#426)

* feat: add support for include_hidden_folders query parameter in list folders endpoint

* Fix conflicts, synchronize tests

---------

Co-authored-by: Samuel Xavier <107475513+samuelpx@users.noreply.github.com>
Co-authored-by: Samuel Xavier <samuelxpp@gmail.com>

Author: AaronDDM

CHANGELOG.md

@@ -11,6 +11,7 @@ Unreleased
 * Added `raw_mime` field to Message model for Base64url-encoded message data
 * Added TrackingOptions model for message tracking configuration
 * Maintained backwards compatibility for existing message functionality
+* Added support for `include_hidden_folders` query parameter for listing folders (Microsoft only)
 
 v6.9.0
 ----------------

examples/include_hidden_folders_demo/README.md

@@ -0,0 +1,67 @@
+# Include Hidden Folders Example
+
+This example demonstrates how to use the `include_hidden_folders` query parameter when listing folders with the Nylas Python SDK.
+
+## Overview
+
+The `include_hidden_folders` parameter is Microsoft-specific and allows you to include hidden folders in the folder listing response. By default, this parameter is `False` and hidden folders are not included.
+
+## Prerequisites
+
+1. A Nylas application with Microsoft OAuth configured
+2. A valid Nylas API key
+3. A grant ID for a Microsoft account
+
+## Setup
+
+1. Set your environment variables:
+   ```bash
+   export NYLAS_API_KEY="your_api_key_here"
+   export NYLAS_GRANT_ID="your_grant_id_here"
+   export NYLAS_API_URI="https://api.us.nylas.com"  # Optional, defaults to US
+   ```
+
+2. Install the Nylas Python SDK:
+   ```bash
+   pip install nylas
+   ```
+
+## Running the Example
+
+```bash
+python include_hidden_folders_example.py
+```
+
+## Code Explanation
+
+The example demonstrates two scenarios:
+
+1. **Default behavior**: Lists folders without hidden folders
+   ```python
+   folders_response = nylas.folders.list(
+       identifier=grant_id,
+       query_params={"limit": 10}
+   )
+   ```
+
+2. **With hidden folders**: Lists folders including hidden folders (Microsoft only)
+   ```python
+   folders_with_hidden_response = nylas.folders.list(
+       identifier=grant_id,
+       query_params={
+           "include_hidden_folders": True,
+           "limit": 10
+       }
+   )
+   ```
+
+## Expected Output
+
+The example will show:
+- List of regular folders
+- List of folders including hidden ones (if any)
+- Comparison showing how many additional hidden folders were found
+
+## Note
+
+This feature is **Microsoft-specific only**. For other providers (Google, IMAP), the `include_hidden_folders` parameter will be ignored. 

examples/include_hidden_folders_demo/include_hidden_folders_example.py

@@ -0,0 +1,71 @@
+import os
+from nylas import Client
+
+
+def main():
+    """
+    This example demonstrates how to use the include_hidden_folders parameter
+    when listing folders with the Nylas SDK.
+
+    The include_hidden_folders parameter is Microsoft-specific and when set to True,
+    it includes hidden folders in the response.
+    """
+
+    # Initialize the client
+    nylas = Client(
+        api_key=os.environ.get("NYLAS_API_KEY"),
+        api_uri=os.environ.get("NYLAS_API_URI", "https://api.us.nylas.com"),
+    )
+
+    # Get the grant ID from environment variable
+    grant_id = os.environ.get("NYLAS_GRANT_ID")
+
+    if not grant_id:
+        print("Please set the NYLAS_GRANT_ID environment variable")
+        return
+
+    try:
+        print("Listing folders without hidden folders (default behavior):")
+        print("=" * 60)
+
+        # List folders without hidden folders (default)
+        folders_response = nylas.folders.list(
+            identifier=grant_id, query_params={"limit": 10}
+        )
+
+        for folder in folders_response.data:
+            print(f"- {folder.name} (ID: {folder.id})")
+
+        print(f"\nTotal folders found: {len(folders_response.data)}")
+
+        # Now list folders WITH hidden folders (Microsoft only)
+        print("\n\nListing folders with hidden folders included (Microsoft only):")
+        print("=" * 70)
+
+        folders_with_hidden_response = nylas.folders.list(
+            identifier=grant_id,
+            query_params={"include_hidden_folders": True, "limit": 10},
+        )
+
+        for folder in folders_with_hidden_response.data:
+            print(f"- {folder.name} (ID: {folder.id})")
+
+        print(
+            f"\nTotal folders found (including hidden): {len(folders_with_hidden_response.data)}"
+        )
+
+        # Compare the counts
+        hidden_count = len(folders_with_hidden_response.data) - len(
+            folders_response.data
+        )
+        if hidden_count > 0:
+            print(f"\nFound {hidden_count} additional hidden folder(s)")
+        else:
+            print("\nNo additional hidden folders found")
+
+    except Exception as e:
+        print(f"Error: {e}")
+
+
+if __name__ == "__main__":
+    main()

nylas/models/folders.py

@@ -85,6 +85,7 @@ class ListFolderQueryParams(ListQueryParams):
 
     Attributes:
         parent_id: (Microsoft and EWS only.) Use the ID of a folder to find all child folders it contains.
+        include_hidden_folders: (Microsoft only) When true, Nylas includes hidden folders in its response.
         single_level: (Microsoft only) If true, retrieves folders from a single-level hierarchy only.
             If false, retrieves folders across a multi-level hierarchy. Defaults to false.
         select (NotRequired[str]): Comma-separated list of fields to return in the response.
@@ -96,6 +97,7 @@ class ListFolderQueryParams(ListQueryParams):
     """
 
     parent_id: NotRequired[str]
+    include_hidden_folders: NotRequired[bool]
     single_level: NotRequired[bool]
 
 

tests/resources/test_folders.py

@@ -58,6 +58,15 @@ def test_list_folders_with_query_params(self, http_client_list_response):
             overrides=None,
         )
 
+    def test_list_folders_with_include_hidden_folders_param(
+        self, http_client_list_response
+    ):
+        folders = Folders(http_client_list_response)
+
+        folders.list(
+            identifier="abc-123", query_params={"include_hidden_folders": True}
+        )
+
     def test_list_folders_with_single_level_param(self, http_client_list_response):
         folders = Folders(http_client_list_response)
 
@@ -72,6 +81,24 @@ def test_list_folders_with_single_level_param(self, http_client_list_response):
             overrides=None,
         )
 
+    def test_list_folders_with_include_hidden_folders_false(
+        self, http_client_list_response
+    ):
+        folders = Folders(http_client_list_response)
+
+        folders.list(
+            identifier="abc-123", query_params={"include_hidden_folders": False}
+        )
+        
+        http_client_list_response._execute.assert_called_once_with(
+            "GET",
+            "/v3/grants/abc-123/folders",
+            None,
+            {"include_hidden_folders": False},
+            None,
+            overrides=None,
+        )
+
     def test_list_folders_with_single_level_false(self, http_client_list_response):
         folders = Folders(http_client_list_response)
 
@@ -86,19 +113,26 @@ def test_list_folders_with_single_level_false(self, http_client_list_response):
             overrides=None,
         )
 
-    def test_list_folders_with_combined_params(self, http_client_list_response):
+    def test_list_folders_with_multiple_params_including_hidden_folders(
+        self, http_client_list_response
+    ):
         folders = Folders(http_client_list_response)
 
         folders.list(
             identifier="abc-123",
-            query_params={"single_level": True, "parent_id": "parent-123", "limit": 10},
+            query_params={
+                "limit": 20,
+                "parent_id": "parent-123",
+                "include_hidden_folders": True,
+                "single_level": True,
+            },
         )
 
         http_client_list_response._execute.assert_called_once_with(
             "GET",
             "/v3/grants/abc-123/folders",
             None,
-            {"single_level": True, "parent_id": "parent-123", "limit": 10},
+            {"limit": 20, "parent_id": "parent-123", "include_hidden_folders": True, "single_level": True},
             None,
             overrides=None,
         )