feat: Added support for select query parameter to optimize API response size (#407)

* feat: add support for select query parameter to optimize API response size

* fix: update events.py

Author: AaronDDM

.coveragerc

@@ -1,3 +1,5 @@
 [run]
 source = nylas
-omit = tests/*
+omit = 
+    tests/*
+    examples/*

CHANGELOG.md

@@ -1,6 +1,10 @@
 nylas-python Changelog
 ======================
 
+Unreleased
+----------------
+* Added support for `select` query parameter in list calendars, list events, and list messages.
+
 v6.6.0
 ----------------
 * Added response headers to all responses from the Nylas API
@@ -27,7 +31,6 @@ v6.3.1
 * Added Folder Webhooks
 * Removed use of TestCommand
 
-
 v6.3.0
 ----------------
 * Added Folder query param support

examples/select_param_demo/README.md

@@ -0,0 +1,58 @@
+# Select Parameter Demo
+
+This example demonstrates the usage of the `select` query parameter across different Nylas resources. The `select` parameter allows you to specify which fields you want to receive in the API response, helping to optimize your API calls by reducing the amount of data transferred.
+
+## Features Demonstrated
+
+1. **Backwards Compatibility**: Shows that existing code that doesn't use the `select` parameter continues to work as expected, receiving all fields.
+2. **Field Selection**: Demonstrates how to use the `select` parameter to request only specific fields for better performance.
+3. **Multiple Resources**: Shows the `select` parameter working across different resources:
+   - Messages
+   - Calendars
+   - Events
+   - Drafts
+   - Contacts
+
+## Setup
+
+1. Create a `.env` file in the root directory with your Nylas API credentials:
+   ```
+   NYLAS_API_KEY=your_api_key_here
+   ```
+
+2. Install the required dependencies:
+   ```bash
+   pip install nylas python-dotenv
+   ```
+
+## Running the Example
+
+Run the example script:
+```bash
+python select_param_example.py
+```
+
+The script will demonstrate both the traditional way of fetching all fields and the new selective field fetching for each resource type.
+
+## Example Output
+
+The script will show output similar to this for each resource:
+```
+=== Messages Resource ===
+
+Fetching messages (all fields):
+Full message - Subject: Example Subject, ID: abc123...
+
+Fetching messages with select (only id and subject):
+Minimal message - Subject: Example Subject, ID: abc123...
+```
+
+## Benefits of Using Select
+
+1. **Reduced Data Transfer**: By selecting only the fields you need, you reduce the amount of data transferred over the network.
+2. **Improved Performance**: Smaller payloads mean faster API responses and less processing time.
+3. **Bandwidth Optimization**: Especially useful in mobile applications or when dealing with limited bandwidth.
+
+## Available Fields
+
+The fields available for selection vary by resource type. Refer to the [Nylas API documentation](https://developer.nylas.com/) for a complete list of available fields for each resource type. 

examples/select_param_demo/select_param_example.py

@@ -0,0 +1,180 @@
+#!/usr/bin/env python3
+"""
+Nylas SDK Example: Using Select Parameters
+
+This example demonstrates how to use the 'select' query parameter across different Nylas resources
+to optimize API response size and performance by requesting only specific fields.
+
+Required Environment Variables:
+    NYLAS_API_KEY: Your Nylas API key
+    NYLAS_GRANT_ID: Your Nylas grant ID
+
+Usage:
+    First, install the SDK in development mode:
+    cd /path/to/nylas-python
+    pip install -e .
+
+    Then set environment variables and run:
+    export NYLAS_API_KEY="your_api_key"
+    export NYLAS_GRANT_ID="your_grant_id"
+    python examples/select_param_demo/select_param_example.py
+"""
+
+import os
+import sys
+import json
+from nylas import Client
+
+
+def get_env_or_exit(var_name: str) -> str:
+    """Get an environment variable or exit if not found."""
+    value = os.getenv(var_name)
+    if not value:
+        print(f"Error: {var_name} environment variable is required")
+        sys.exit(1)
+    return value
+
+
+def print_data(data: list, title: str) -> None:
+    """Pretty print the data with a title."""
+    print(f"\n{title}:")
+    for item in data:
+        # Convert to dict and pretty print
+        item_dict = item.to_dict()
+        print(json.dumps(item_dict, indent=2))
+
+
+def demonstrate_messages(client: Client, grant_id: str) -> None:
+    """Demonstrate select parameter usage with Messages resource."""
+    print("\n=== Messages Resource ===")
+    
+    # Backwards compatibility - fetch all fields
+    print("\nFetching messages (all fields):")
+    messages = client.messages.list(identifier=grant_id, query_params={"limit": 2})
+    print_data(messages.data, "Full message data (all fields)")
+    
+    # Using select parameter - fetch only specific fields
+    print("\nFetching messages with select (only id and subject):")
+    messages = client.messages.list(
+        identifier=grant_id,
+        query_params={"limit": 2, "select": "id,subject"}
+    )
+    print_data(messages.data, "Minimal message data (only selected fields)")
+
+
+def demonstrate_calendars(client: Client, grant_id: str) -> None:
+    """Demonstrate select parameter usage with Calendars resource."""
+    print("\n=== Calendars Resource ===")
+    
+    # Backwards compatibility - fetch all fields
+    print("\nFetching calendars (all fields):")
+    calendars = client.calendars.list(identifier=grant_id, query_params={"limit": 2})
+    print_data(calendars.data, "Full calendar data (all fields)")
+    
+    # Using select parameter - fetch only specific fields
+    print("\nFetching calendars with select (only id and name):")
+    calendars = client.calendars.list(
+        identifier=grant_id,
+        query_params={"limit": 2, "select": "id,name"}
+    )
+    print_data(calendars.data, "Minimal calendar data (only selected fields)")
+
+
+def demonstrate_events(client: Client, grant_id: str) -> None:
+    """Demonstrate select parameter usage with Events resource."""
+    print("\n=== Events Resource ===")
+    
+    # First, get a calendar ID
+    print("\nFetching first calendar to use for events...")
+    calendars = client.calendars.list(identifier=grant_id, query_params={"limit": 1})
+    if not calendars.data:
+        print("No calendars found. Skipping events demonstration.")
+        return
+    
+    calendar_id = calendars.data[0].id
+    print(f"Using calendar: {calendars.data[0].name} (ID: {calendar_id})")
+    
+    # Backwards compatibility - fetch all fields
+    print("\nFetching events (all fields):")
+    events = client.events.list(
+        identifier=grant_id,
+        query_params={"limit": 2, "calendar_id": calendar_id}
+    )
+    print_data(events.data, "Full event data (all fields)")
+    
+    # Using select parameter - fetch only specific fields
+    print("\nFetching events with select (only id and title):")
+    events = client.events.list(
+        identifier=grant_id,
+        query_params={
+            "limit": 2,
+            "calendar_id": calendar_id,
+            "select": "id,title"
+        }
+    )
+    print_data(events.data, "Minimal event data (only selected fields)")
+
+
+def demonstrate_drafts(client: Client, grant_id: str) -> None:
+    """Demonstrate select parameter usage with Drafts resource."""
+    print("\n=== Drafts Resource ===")
+    
+    # Backwards compatibility - fetch all fields
+    print("\nFetching drafts (all fields):")
+    drafts = client.drafts.list(identifier=grant_id, query_params={"limit": 2})
+    print_data(drafts.data, "Full draft data (all fields)")
+    
+    # Using select parameter - fetch only specific fields
+    print("\nFetching drafts with select (only id and subject):")
+    drafts = client.drafts.list(
+        identifier=grant_id,
+        query_params={"limit": 2, "select": "id,subject"}
+    )
+    print_data(drafts.data, "Minimal draft data (only selected fields)")
+
+
+def demonstrate_contacts(client: Client, grant_id: str) -> None:
+    """Demonstrate select parameter usage with Contacts resource."""
+    print("\n=== Contacts Resource ===")
+    
+    # Backwards compatibility - fetch all fields
+    print("\nFetching contacts (all fields):")
+    contacts = client.contacts.list(identifier=grant_id, query_params={"limit": 2})
+    print_data(contacts.data, "Full contact data (all fields)")
+    
+    # Using select parameter - fetch only specific fields
+    print("\nFetching contacts with select (only id, grant_id, and given_name):")
+    contacts = client.contacts.list(
+        identifier=grant_id,
+        query_params={"limit": 2, "select": "id,grant_id,given_name"}
+    )
+    print_data(contacts.data, "Minimal contact data (only selected fields)")
+
+
+def main():
+    """Main function demonstrating select parameter usage across resources."""
+    # Get required environment variables
+    api_key = get_env_or_exit("NYLAS_API_KEY")
+    grant_id = get_env_or_exit("NYLAS_GRANT_ID")
+
+    # Initialize Nylas client
+    client = Client(
+        api_key=api_key,
+    )
+
+    print("\nDemonstrating Select Parameter Usage")
+    print("===================================")
+    print("This shows both backwards compatibility and selective field fetching")
+
+    # Demonstrate select parameter across different resources
+    demonstrate_messages(client, grant_id)
+    demonstrate_calendars(client, grant_id)
+    demonstrate_events(client, grant_id)
+    demonstrate_drafts(client, grant_id)
+    demonstrate_contacts(client, grant_id)
+
+    print("\nExample completed!")
+
+
+if __name__ == "__main__":
+    main() 

nylas/models/calendars.py

@@ -57,11 +57,25 @@ class ListCalendarsQueryParams(ListQueryParams):
         page_token (NotRequired[str]): An identifier that specifies which page of data to return.
             This value should be taken from a ListResponse object's next_cursor parameter.
         metadata_pair: Pass in your metadata key-value pair to search for metadata.
+        select (NotRequired[str]): Comma-separated list of fields to return in the response.
+            This allows you to receive only the portion of object data that you're interested in.
     """
 
     metadata_pair: NotRequired[Dict[str, str]]
 
 
+class FindCalendarQueryParams(TypedDict):
+    """
+    Interface of the query parameters for finding a calendar.
+
+    Attributes:
+        select: Comma-separated list of fields to return in the response.
+            This allows you to receive only the portion of object data that you're interested in.
+    """
+
+    select: NotRequired[str]
+
+
 class CreateCalendarRequest(TypedDict):
     """
     Interface of a Nylas create calendar request

nylas/models/contacts.py

@@ -173,6 +173,20 @@ class Contact:
     groups: Optional[List[ContactGroupId]] = None
 
 
+class FindContactQueryParams(TypedDict):
+    """
+    The available query parameters for finding a contact.
+    Attributes:
+        profile_picture: If true and picture_url is present, the response includes a Base64 binary data blob that
+            you can use to view information as an image file.
+        select: Comma-separated list of fields to return in the response.
+            This allows you to receive only the portion of object data that you're interested in.
+    """
+
+    profile_picture: NotRequired[bool]
+    select: NotRequired[str]
+
+
 class WriteablePhoneNumber(TypedDict):
     """
     A phone number for a contact.
@@ -316,21 +330,20 @@ class CreateContactRequest(TypedDict):
 
 class ListContactsQueryParams(ListQueryParams):
     """
-    Interface of the query parameters for listing calendars.
+    Interface representing the query parameters for listing contacts.
 
     Attributes:
+        email: Return contacts with matching email address.
+        phone_number: Return contacts with matching phone number.
+        source: Return contacts from a specific source.
+        group: Return contacts from a specific group.
+        recurse: Return contacts from all sub-groups of the specified group.
+        select (NotRequired[str]): Comma-separated list of fields to return in the response.
+            This allows you to receive only the portion of object data that you're interested in.
         limit (NotRequired[int]): The maximum number of objects to return.
             This field defaults to 50. The maximum allowed value is 200.
         page_token (NotRequired[str]): An identifier that specifies which page of data to return.
             This value should be taken from a ListResponse object's next_cursor parameter.
-        email: Returns the contacts matching the exact contact's email.
-        phone_number: Returns the contacts matching the contact's exact phone number
-        source: Returns the contacts matching from the address book or auto-generated contacts from emails.
-            For example of contacts only from the address book: /contacts?source=address_bookor
-            for only autogenerated contacts:/contacts?source=inbox`
-        group: Returns the contacts belonging to the Contact Group matching this ID
-        recurse: When set to true, returns the contacts also within the specified Contact Group subgroups,
-            if the group parameter is set.
     """
 
     email: NotRequired[str]
@@ -340,18 +353,6 @@ class ListContactsQueryParams(ListQueryParams):
     recurse: NotRequired[bool]
 
 
-class FindContactQueryParams(TypedDict):
-    """
-    The available query parameters for finding a contact.
-
-    Attributes:
-        profile_picture: If true and picture_url is present, the response includes a Base64 binary data blob that
-            you can use to view information as an image file.
-    """
-
-    profile_picture: NotRequired[bool]
-
-
 class GroupType(str, Enum):
     """Enum representing the different types of contact groups."""
 

nylas/models/drafts.py

@@ -149,6 +149,18 @@ class CreateDraftRequest(TypedDict):
 """
 
 
+class FindDraftQueryParams(TypedDict):
+    """
+    Query parameters for finding a draft.
+
+    Attributes:
+        select: Comma-separated list of fields to return in the response.
+            This allows you to receive only the portion of object data that you're interested in.
+    """
+
+    select: NotRequired[str]
+
+
 class SendMessageRequest(CreateDraftRequest):
     """
     A request to send a message.