arcade-gmail 2.0.0__py3-none-any.whl

arcade_gmail/constants.py

@@ -0,0 +1,18 @@
+import os
+
+from arcade_gmail.enums import GmailReplyToWhom
+
+# The default reply in Gmail is to only the sender. Since Gmail also offers the possibility of
+# changing the default to 'reply to all', we support both options through an env variable.
+# https://support.google.com/mail/answer/6585?hl=en&sjid=15399867888091633568-SA#null
+try:
+    GMAIL_DEFAULT_REPLY_TO = GmailReplyToWhom(
+        # Values accepted are defined in the arcade_google.tools.models.GmailReplyToWhom Enum
+        os.getenv("ARCADE_GMAIL_DEFAULT_REPLY_TO", GmailReplyToWhom.ONLY_THE_SENDER.value).lower()
+    )
+except ValueError as e:
+    raise ValueError(
+        "Invalid value for ARCADE_GMAIL_DEFAULT_REPLY_TO: "
+        f"'{os.getenv('ARCADE_GMAIL_DEFAULT_REPLY_TO')}'. Expected one of "
+        f"{list(GmailReplyToWhom.__members__.keys())}"
+    ) from e

arcade_gmail/enums.py

@@ -0,0 +1,11 @@
+from enum import Enum
+
+
+class GmailReplyToWhom(str, Enum):
+    EVERY_RECIPIENT = "every_recipient"
+    ONLY_THE_SENDER = "only_the_sender"
+
+
+class GmailAction(str, Enum):
+    SEND = "send"
+    DRAFT = "draft"

arcade_gmail/exceptions.py

@@ -0,0 +1,19 @@
+class GmailToolError(Exception):
+    """Base exception for Google tool errors."""
+
+    def __init__(self, message: str, developer_message: str | None = None):
+        self.message = message
+        self.developer_message = developer_message
+        super().__init__(self.message)
+
+    def __str__(self) -> str:
+        base_message = self.message
+        if self.developer_message:
+            return f"{base_message} (Developer: {self.developer_message})"
+        return base_message
+
+
+class GmailServiceError(GmailToolError):
+    """Raised when there's an error building or using the Google service."""
+
+    pass

arcade_gmail/tools/__init__.py

@@ -0,0 +1,39 @@
+from arcade_gmail.tools.gmail import (
+    change_email_labels,
+    create_label,
+    delete_draft_email,
+    get_thread,
+    list_draft_emails,
+    list_emails,
+    list_emails_by_header,
+    list_labels,
+    list_threads,
+    reply_to_email,
+    search_threads,
+    send_draft_email,
+    send_email,
+    trash_email,
+    update_draft_email,
+    write_draft_email,
+    write_draft_reply_email,
+)
+
+__all__ = [
+    "change_email_labels",
+    "create_label",
+    "delete_draft_email",
+    "get_thread",
+    "list_draft_emails",
+    "list_emails",
+    "list_emails_by_header",
+    "list_labels",
+    "list_threads",
+    "reply_to_email",
+    "search_threads",
+    "send_draft_email",
+    "send_email",
+    "trash_email",
+    "update_draft_email",
+    "write_draft_email",
+    "write_draft_reply_email",
+]

arcade_gmail/tools/gmail.py

@@ -0,0 +1,664 @@
+import base64
+from email.mime.text import MIMEText
+from typing import Annotated, Any
+
+from arcade_tdk import ToolContext, tool
+from arcade_tdk.auth import Google
+from arcade_tdk.errors import RetryableToolError
+from googleapiclient.errors import HttpError
+
+from arcade_gmail.constants import GMAIL_DEFAULT_REPLY_TO
+from arcade_gmail.enums import GmailAction, GmailReplyToWhom
+from arcade_gmail.exceptions import GmailToolError
+from arcade_gmail.utils import (
+    DateRange,
+    _build_gmail_service,
+    build_email_message,
+    build_gmail_query_string,
+    build_reply_recipients,
+    fetch_messages,
+    get_draft_url,
+    get_email_details,
+    get_email_in_trash_url,
+    get_label_ids,
+    get_sent_email_url,
+    parse_draft_email,
+    parse_multipart_email,
+    parse_plain_text_email,
+    remove_none_values,
+)
+
+
+# Email sending tools
+@tool(
+    requires_auth=Google(
+        scopes=["https://www.googleapis.com/auth/gmail.send"],
+    )
+)
+async def send_email(
+    context: ToolContext,
+    subject: Annotated[str, "The subject of the email"],
+    body: Annotated[str, "The body of the email"],
+    recipient: Annotated[str, "The recipient of the email"],
+    cc: Annotated[list[str] | None, "CC recipients of the email"] = None,
+    bcc: Annotated[list[str] | None, "BCC recipients of the email"] = None,
+) -> Annotated[dict, "A dictionary containing the sent email details"]:
+    """
+    Send an email using the Gmail API.
+    """
+    service = _build_gmail_service(context)
+    email = build_email_message(recipient, subject, body, cc, bcc)
+
+    sent_message = service.users().messages().send(userId="me", body=email).execute()
+
+    email = parse_plain_text_email(sent_message)
+    email["url"] = get_sent_email_url(sent_message["id"])
+    return email
+
+
+@tool(
+    requires_auth=Google(
+        scopes=["https://www.googleapis.com/auth/gmail.send"],
+    )
+)
+async def send_draft_email(
+    context: ToolContext, email_id: Annotated[str, "The ID of the draft to send"]
+) -> Annotated[dict, "A dictionary containing the sent email details"]:
+    """
+    Send a draft email using the Gmail API.
+    """
+
+    service = _build_gmail_service(context)
+
+    # Send the draft email
+    sent_message = service.users().drafts().send(userId="me", body={"id": email_id}).execute()
+
+    email = parse_plain_text_email(sent_message)
+    email["url"] = get_sent_email_url(sent_message["id"])
+    return email
+
+
+# Note: in the Gmail UI, a user can customize the recipient and cc fields before replying.
+# We decided not to support this feature, since we'd need a way for LLMs to tell apart between
+# adding or removing recipients/cc, or replacing with an entirely new list of addresses,
+# which would make the tool more complex to call.
+@tool(
+    requires_auth=Google(
+        scopes=["https://www.googleapis.com/auth/gmail.send"],
+    )
+)
+async def reply_to_email(
+    context: ToolContext,
+    body: Annotated[str, "The body of the email"],
+    reply_to_message_id: Annotated[str, "The ID of the message to reply to"],
+    reply_to_whom: Annotated[
+        GmailReplyToWhom,
+        "Whether to reply to every recipient (including cc) or only to the original sender. "
+        f"Defaults to '{GMAIL_DEFAULT_REPLY_TO}'.",
+    ] = GMAIL_DEFAULT_REPLY_TO,
+    bcc: Annotated[list[str] | None, "BCC recipients of the email"] = None,
+) -> Annotated[dict, "A dictionary containing the sent email details"]:
+    """
+    Send a reply to an email message.
+    """
+    if isinstance(reply_to_whom, str):
+        reply_to_whom = GmailReplyToWhom(reply_to_whom)
+
+    service = _build_gmail_service(context)
+
+    current_user = service.users().getProfile(userId="me").execute()
+
+    try:
+        replying_to_email = (
+            service.users().messages().get(userId="me", id=reply_to_message_id).execute()
+        )
+    except HttpError as e:
+        raise RetryableToolError(
+            message=f"Could not retrieve the message with id {reply_to_message_id}.",
+            developer_message=(
+                f"Could not retrieve the message with id {reply_to_message_id}. "
+                f"Reason: '{e.reason}'. Error details: '{e.error_details}'"
+            ),
+        ) from e
+
+    replying_to_email = parse_multipart_email(replying_to_email)
+
+    recipients = build_reply_recipients(
+        replying_to_email, current_user["emailAddress"], reply_to_whom
+    )
+
+    email = build_email_message(
+        recipient=recipients,
+        subject=f"Re: {replying_to_email['subject']}",
+        body=body,
+        cc=None
+        if reply_to_whom == GmailReplyToWhom.ONLY_THE_SENDER
+        else replying_to_email["cc"].split(","),
+        bcc=bcc,
+        replying_to=replying_to_email,
+    )
+
+    sent_message = service.users().messages().send(userId="me", body=email).execute()
+
+    email = parse_plain_text_email(sent_message)
+    email["url"] = get_sent_email_url(sent_message["id"])
+    return email
+
+
+# Draft Management Tools
+@tool(
+    requires_auth=Google(
+        scopes=["https://www.googleapis.com/auth/gmail.compose"],
+    )
+)
+async def write_draft_email(
+    context: ToolContext,
+    subject: Annotated[str, "The subject of the draft email"],
+    body: Annotated[str, "The body of the draft email"],
+    recipient: Annotated[str, "The recipient of the draft email"],
+    cc: Annotated[list[str] | None, "CC recipients of the draft email"] = None,
+    bcc: Annotated[list[str] | None, "BCC recipients of the draft email"] = None,
+) -> Annotated[dict, "A dictionary containing the created draft email details"]:
+    """
+    Compose a new email draft using the Gmail API.
+    """
+    # Set up the Gmail API client
+    service = _build_gmail_service(context)
+
+    draft = {
+        "message": build_email_message(recipient, subject, body, cc, bcc, action=GmailAction.DRAFT)
+    }
+
+    draft_message = service.users().drafts().create(userId="me", body=draft).execute()
+    email = parse_draft_email(draft_message)
+    email["url"] = get_draft_url(draft_message["id"])
+    return email
+
+
+# Note: in the Gmail UI, a user can customize the recipient and cc fields before replying.
+# We decided not to support this feature, since we'd need a way for LLMs to tell apart between
+# adding or removing recipients/cc, or replacing with an entirely new list of addresses,
+# which would make the tool more complex to call.
+@tool(
+    requires_auth=Google(
+        scopes=["https://www.googleapis.com/auth/gmail.compose"],
+    )
+)
+async def write_draft_reply_email(
+    context: ToolContext,
+    body: Annotated[str, "The body of the draft reply email"],
+    reply_to_message_id: Annotated[str, "The Gmail message ID of the message to draft a reply to"],
+    reply_to_whom: Annotated[
+        GmailReplyToWhom,
+        "Whether to reply to every recipient (including cc) or only to the original sender. "
+        f"Defaults to '{GMAIL_DEFAULT_REPLY_TO}'.",
+    ] = GMAIL_DEFAULT_REPLY_TO,
+    bcc: Annotated[list[str] | None, "BCC recipients of the draft reply email"] = None,
+) -> Annotated[dict, "A dictionary containing the created draft reply email details"]:
+    """
+    Compose a draft reply to an email message.
+    """
+    if isinstance(reply_to_whom, str):
+        reply_to_whom = GmailReplyToWhom(reply_to_whom)
+
+    service = _build_gmail_service(context)
+
+    current_user = service.users().getProfile(userId="me").execute()
+
+    try:
+        replying_to_email = (
+            service.users().messages().get(userId="me", id=reply_to_message_id).execute()
+        )
+    except HttpError as e:
+        raise RetryableToolError(
+            message="Could not retrieve the message to respond to.",
+            developer_message=(
+                "Could not retrieve the message to respond to. "
+                f"Reason: '{e.reason}'. Error details: '{e.error_details}'"
+            ),
+        )
+
+    replying_to_email = parse_multipart_email(replying_to_email)
+
+    recipients = build_reply_recipients(
+        replying_to_email, current_user["emailAddress"], reply_to_whom
+    )
+
+    draft_message = {
+        "message": build_email_message(
+            recipient=recipients,
+            subject=f"Re: {replying_to_email['subject']}",
+            body=body,
+            cc=None
+            if reply_to_whom == GmailReplyToWhom.ONLY_THE_SENDER
+            else replying_to_email["cc"].split(","),
+            bcc=bcc,
+            replying_to=replying_to_email,
+            action=GmailAction.DRAFT,
+        ),
+    }
+
+    draft = service.users().drafts().create(userId="me", body=draft_message).execute()
+
+    email = parse_draft_email(draft)
+    email["url"] = get_draft_url(draft["id"])
+    return email
+
+
+@tool(
+    requires_auth=Google(
+        scopes=["https://www.googleapis.com/auth/gmail.compose"],
+    )
+)
+async def update_draft_email(
+    context: ToolContext,
+    draft_email_id: Annotated[str, "The ID of the draft email to update."],
+    subject: Annotated[str, "The subject of the draft email"],
+    body: Annotated[str, "The body of the draft email"],
+    recipient: Annotated[str, "The recipient of the draft email"],
+    cc: Annotated[list[str] | None, "CC recipients of the draft email"] = None,
+    bcc: Annotated[list[str] | None, "BCC recipients of the draft email"] = None,
+) -> Annotated[dict, "A dictionary containing the updated draft email details"]:
+    """
+    Update an existing email draft using the Gmail API.
+    """
+    service = _build_gmail_service(context)
+
+    message = MIMEText(body)
+    message["to"] = recipient
+    message["subject"] = subject
+    if cc:
+        message["Cc"] = ", ".join(cc)
+    if bcc:
+        message["Bcc"] = ", ".join(bcc)
+
+    # Encode the message in base64
+    raw_message = base64.urlsafe_b64encode(message.as_bytes()).decode()
+
+    # Update the draft
+    draft = {"id": draft_email_id, "message": {"raw": raw_message}}
+
+    updated_draft_message = (
+        service.users().drafts().update(userId="me", id=draft_email_id, body=draft).execute()
+    )
+
+    email = parse_draft_email(updated_draft_message)
+    email["url"] = get_draft_url(updated_draft_message["id"])
+
+    return email
+
+
+@tool(
+    requires_auth=Google(
+        scopes=["https://www.googleapis.com/auth/gmail.compose"],
+    )
+)
+async def delete_draft_email(
+    context: ToolContext,
+    draft_email_id: Annotated[str, "The ID of the draft email to delete"],
+) -> Annotated[str, "A confirmation message indicating successful deletion"]:
+    """
+    Delete a draft email using the Gmail API.
+    """
+    service = _build_gmail_service(context)
+
+    # Delete the draft
+    service.users().drafts().delete(userId="me", id=draft_email_id).execute()
+    return f"Draft email with ID {draft_email_id} deleted successfully."
+
+
+# Email Management Tools
+@tool(
+    requires_auth=Google(
+        scopes=["https://www.googleapis.com/auth/gmail.modify"],
+    )
+)
+async def trash_email(
+    context: ToolContext, email_id: Annotated[str, "The ID of the email to trash"]
+) -> Annotated[dict, "A dictionary containing the trashed email details"]:
+    """
+    Move an email to the trash folder using the Gmail API.
+    """
+
+    service = _build_gmail_service(context)
+
+    # Trash the email
+    trashed_email = service.users().messages().trash(userId="me", id=email_id).execute()
+
+    email = parse_plain_text_email(trashed_email)
+    email["url"] = get_email_in_trash_url(trashed_email["id"])
+    return email
+
+
+# Draft Search Tools
+@tool(
+    requires_auth=Google(
+        scopes=["https://www.googleapis.com/auth/gmail.readonly"],
+    )
+)
+async def list_draft_emails(
+    context: ToolContext,
+    n_drafts: Annotated[int, "Number of draft emails to read"] = 5,
+) -> Annotated[dict, "A dictionary containing a list of draft email details"]:
+    """
+    Lists draft emails in the user's draft mailbox using the Gmail API.
+    """
+    service = _build_gmail_service(context)
+
+    listed_drafts = service.users().drafts().list(userId="me").execute()
+
+    if not listed_drafts:
+        return {"emails": []}
+
+    draft_ids = [draft["id"] for draft in listed_drafts.get("drafts", [])][:n_drafts]
+
+    emails = []
+    for draft_id in draft_ids:
+        try:
+            draft_data = service.users().drafts().get(userId="me", id=draft_id).execute()
+            draft_details = parse_draft_email(draft_data)
+            if draft_details:
+                emails.append(draft_details)
+        except Exception as e:
+            raise GmailToolError(
+                message=f"Error reading draft email {draft_id}.", developer_message=str(e)
+            )
+
+    return {"emails": emails}
+
+
+@tool(
+    requires_auth=Google(
+        scopes=["https://www.googleapis.com/auth/gmail.readonly"],
+    )
+)
+async def list_emails_by_header(
+    context: ToolContext,
+    sender: Annotated[str | None, "The name or email address of the sender of the email"] = None,
+    recipient: Annotated[str | None, "The name or email address of the recipient"] = None,
+    subject: Annotated[str | None, "Words to find in the subject of the email"] = None,
+    body: Annotated[str | None, "Words to find in the body of the email"] = None,
+    date_range: Annotated[DateRange | None, "The date range of the email"] = None,
+    label: Annotated[str | None, "The label name to filter by"] = None,
+    max_results: Annotated[int, "The maximum number of emails to return"] = 25,
+) -> Annotated[
+    dict, "A dictionary containing a list of email details matching the search criteria"
+]:
+    """
+    Search for emails by header using the Gmail API.
+
+    At least one of the following parameters MUST be provided: sender, recipient,
+    subject, date_range, label, or body.
+    """
+    service = _build_gmail_service(context)
+    # Ensure at least one search parameter is provided
+    if not any([sender, recipient, subject, body, label, date_range]):
+        raise RetryableToolError(
+            message=(
+                "At least one of sender, recipient, subject, body, label, query, "
+                "or date_range must be provided."
+            ),
+            developer_message=(
+                "At least one of sender, recipient, subject, body, label, query, "
+                "or date_range must be provided."
+            ),
+        )
+
+    # Check if label is valid
+    if label:
+        label_ids = get_label_ids(service, [label])
+
+        if not label_ids:
+            labels = service.users().labels().list(userId="me").execute().get("labels", [])
+            label_names = [label["name"] for label in labels]
+            raise RetryableToolError(
+                message=f"Invalid label: {label}",
+                developer_message=f"Invalid label: {label}",
+                additional_prompt_content=f"List of valid labels: {label_names}",
+            )
+
+    # Build a Gmail-style query string based on the filters
+    query = build_gmail_query_string(sender, recipient, subject, body, date_range, label)
+
+    # Fetch matching messages. This fetches message metadata from Gmail
+    messages = fetch_messages(service, query, max_results)
+
+    # If no messages found, return an empty list
+    if not messages:
+        return {"emails": []}
+
+    # Process each message into a structured email object
+    emails = get_email_details(service, messages)
+
+    # Return the list of emails in a dictionary with key "emails"
+    return {"emails": emails}
+
+
+@tool(
+    requires_auth=Google(
+        scopes=["https://www.googleapis.com/auth/gmail.readonly"],
+    )
+)
+async def list_emails(
+    context: ToolContext,
+    n_emails: Annotated[int, "Number of emails to read"] = 5,
+) -> Annotated[dict, "A dictionary containing a list of email details"]:
+    """
+    Read emails from a Gmail account and extract plain text content.
+    """
+    service = _build_gmail_service(context)
+
+    messages = service.users().messages().list(userId="me").execute().get("messages", [])
+
+    if not messages:
+        return {"emails": []}
+
+    emails = []
+    for msg in messages[:n_emails]:
+        try:
+            email_data = service.users().messages().get(userId="me", id=msg["id"]).execute()
+            email_details = parse_plain_text_email(email_data)
+            if email_details:
+                emails.append(email_details)
+        except Exception as e:
+            raise GmailToolError(
+                message=f"Error reading email {msg['id']}.", developer_message=str(e)
+            )
+    return {"emails": emails}
+
+
+@tool(
+    requires_auth=Google(
+        scopes=["https://www.googleapis.com/auth/gmail.readonly"],
+    )
+)
+async def search_threads(
+    context: ToolContext,
+    page_token: Annotated[
+        str | None, "Page token to retrieve a specific page of results in the list"
+    ] = None,
+    max_results: Annotated[int, "The maximum number of threads to return"] = 10,
+    include_spam_trash: Annotated[bool, "Whether to include spam and trash in the results"] = False,
+    label_ids: Annotated[list[str] | None, "The IDs of labels to filter by"] = None,
+    sender: Annotated[str | None, "The name or email address of the sender of the email"] = None,
+    recipient: Annotated[str | None, "The name or email address of the recipient"] = None,
+    subject: Annotated[str | None, "Words to find in the subject of the email"] = None,
+    body: Annotated[str | None, "Words to find in the body of the email"] = None,
+    date_range: Annotated[DateRange | None, "The date range of the email"] = None,
+) -> Annotated[dict, "A dictionary containing a list of thread details"]:
+    """Search for threads in the user's mailbox"""
+    service = _build_gmail_service(context)
+
+    query = (
+        build_gmail_query_string(sender, recipient, subject, body, date_range)
+        if any([sender, recipient, subject, body, date_range])
+        else None
+    )
+
+    params = {
+        "userId": "me",
+        "maxResults": min(max_results, 500),
+        "pageToken": page_token,
+        "includeSpamTrash": include_spam_trash,
+        "labelIds": label_ids,
+        "q": query,
+    }
+    params = remove_none_values(params)
+
+    threads: list[dict[str, Any]] = []
+    next_page_token = None
+    # Paginate through thread pages until we have the desired number of threads
+    while len(threads) < max_results:
+        response = service.users().threads().list(**params).execute()
+
+        threads.extend(response.get("threads", []))
+        next_page_token = response.get("nextPageToken")
+
+        if not next_page_token:
+            break
+
+        params["pageToken"] = next_page_token
+        params["maxResults"] = min(max_results - len(threads), 500)
+
+    return {
+        "threads": threads,
+        "num_threads": len(threads),
+        "next_page_token": next_page_token,
+    }
+
+
+@tool(
+    requires_auth=Google(
+        scopes=["https://www.googleapis.com/auth/gmail.readonly"],
+    )
+)
+async def list_threads(
+    context: ToolContext,
+    page_token: Annotated[
+        str | None, "Page token to retrieve a specific page of results in the list"
+    ] = None,
+    max_results: Annotated[int, "The maximum number of threads to return"] = 10,
+    include_spam_trash: Annotated[bool, "Whether to include spam and trash in the results"] = False,
+) -> Annotated[dict, "A dictionary containing a list of thread details"]:
+    """List threads in the user's mailbox."""
+    threads: dict[str, Any] = await search_threads(
+        context, page_token, max_results, include_spam_trash
+    )
+    return threads
+
+
+@tool(
+    requires_auth=Google(
+        scopes=["https://www.googleapis.com/auth/gmail.readonly"],
+    )
+)
+async def get_thread(
+    context: ToolContext,
+    thread_id: Annotated[str, "The ID of the thread to retrieve"],
+) -> Annotated[dict, "A dictionary containing the thread details"]:
+    """Get the specified thread by ID."""
+    params = {
+        "userId": "me",
+        "id": thread_id,
+        "format": "full",
+    }
+    params = remove_none_values(params)
+
+    service = _build_gmail_service(context)
+
+    thread = service.users().threads().get(**params).execute()
+    thread["messages"] = [parse_plain_text_email(message) for message in thread.get("messages", [])]
+
+    return dict(thread)
+
+
+@tool(
+    requires_auth=Google(
+        scopes=["https://www.googleapis.com/auth/gmail.modify"],
+    )
+)
+async def change_email_labels(
+    context: ToolContext,
+    email_id: Annotated[str, "The ID of the email to modify labels for"],
+    labels_to_add: Annotated[list[str], "List of label names to add"],
+    labels_to_remove: Annotated[list[str], "List of label names to remove"],
+) -> Annotated[dict, "List of labels that were added, removed, and not found"]:
+    """
+    Add and remove labels from an email using the Gmail API.
+    """
+    service = _build_gmail_service(context)
+
+    add_labels = get_label_ids(service, labels_to_add)
+    remove_labels = get_label_ids(service, labels_to_remove)
+
+    invalid_labels = (
+        set(labels_to_add + labels_to_remove) - set(add_labels.keys()) - set(remove_labels.keys())
+    )
+
+    if invalid_labels:
+        # prepare the list of valid labels
+        labels = service.users().labels().list(userId="me").execute().get("labels", [])
+        label_names = [label["name"] for label in labels]
+
+        # raise a retryable error with the list of valid labels
+        raise RetryableToolError(
+            message=f"Invalid labels: {invalid_labels}",
+            developer_message=f"Invalid labels: {invalid_labels}",
+            additional_prompt_content=f"List of valid labels: {label_names}",
+        )
+
+    # Prepare the modification body with label IDs.
+    body = {
+        "addLabelIds": list(add_labels.values()),
+        "removeLabelIds": list(remove_labels.values()),
+    }
+
+    try:  # Modify the email labels.
+        service.users().messages().modify(userId="me", id=email_id, body=body).execute()
+
+    except Exception as e:
+        raise GmailToolError(
+            message=f"Error modifying labels for email {email_id}", developer_message=str(e)
+        )
+
+    # Confirmation JSON with lists for added and removed labels.
+    confirmation = {
+        "addedLabels": list(add_labels.keys()),
+        "removedLabels": list(remove_labels.keys()),
+    }
+
+    return {"confirmation": dict(confirmation)}
+
+
+@tool(
+    requires_auth=Google(
+        scopes=["https://www.googleapis.com/auth/gmail.readonly"],
+    )
+)
+async def list_labels(
+    context: ToolContext,
+) -> Annotated[dict, "A dictionary containing a list of label details"]:
+    """List all the labels in the user's mailbox."""
+
+    service = _build_gmail_service(context)
+
+    labels = service.users().labels().list(userId="me").execute().get("labels", [])
+
+    return {"labels": labels}
+
+
+@tool(
+    requires_auth=Google(
+        scopes=["https://www.googleapis.com/auth/gmail.labels"],
+    )
+)
+async def create_label(
+    context: ToolContext,
+    label_name: Annotated[str, "The name of the label to create"],
+) -> Annotated[dict, "The details of the created label"]:
+    """Create a new label in the user's mailbox."""
+
+    service = _build_gmail_service(context)
+    label = service.users().labels().create(userId="me", body={"name": label_name}).execute()
+
+    return {"label": label}

arcade_gmail/utils.py

@@ -0,0 +1,509 @@
+import logging
+import re
+from base64 import urlsafe_b64decode, urlsafe_b64encode
+from datetime import datetime, timedelta
+from email.message import EmailMessage
+from email.mime.text import MIMEText
+from enum import Enum
+from typing import Any
+
+from arcade_tdk import ToolContext
+from bs4 import BeautifulSoup
+from google.oauth2.credentials import Credentials
+from googleapiclient.discovery import build
+
+from arcade_gmail.enums import (
+    GmailAction,
+    GmailReplyToWhom,
+)
+from arcade_gmail.exceptions import GmailServiceError, GmailToolError
+
+logging.basicConfig(
+    level=logging.DEBUG,
+    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+)
+
+logger = logging.getLogger(__name__)
+
+
+class DateRange(Enum):
+    TODAY = "today"
+    YESTERDAY = "yesterday"
+    LAST_7_DAYS = "last_7_days"
+    LAST_30_DAYS = "last_30_days"
+    THIS_MONTH = "this_month"
+    LAST_MONTH = "last_month"
+    THIS_YEAR = "this_year"
+
+    def to_date_query(self) -> str:
+        today = datetime.now()
+        result = "after:"
+        comparison_date = today
+
+        if self == DateRange.YESTERDAY:
+            comparison_date = today - timedelta(days=1)
+        elif self == DateRange.LAST_7_DAYS:
+            comparison_date = today - timedelta(days=7)
+        elif self == DateRange.LAST_30_DAYS:
+            comparison_date = today - timedelta(days=30)
+        elif self == DateRange.THIS_MONTH:
+            comparison_date = today.replace(day=1)
+        elif self == DateRange.LAST_MONTH:
+            comparison_date = (today.replace(day=1) - timedelta(days=1)).replace(day=1)
+        elif self == DateRange.THIS_YEAR:
+            comparison_date = today.replace(month=1, day=1)
+        elif self == DateRange.LAST_MONTH:
+            comparison_date = (today.replace(month=1, day=1) - timedelta(days=1)).replace(
+                month=1, day=1
+            )
+
+        return result + comparison_date.strftime("%Y/%m/%d")
+
+
+def build_email_message(
+    recipient: str,
+    subject: str,
+    body: str,
+    cc: list[str] | None = None,
+    bcc: list[str] | None = None,
+    replying_to: dict[str, Any] | None = None,
+    action: GmailAction = GmailAction.SEND,
+) -> dict[str, Any]:
+    if replying_to:
+        body = build_reply_body(body, replying_to)
+
+    message: EmailMessage | MIMEText
+
+    if action == GmailAction.SEND:
+        message = EmailMessage()
+        message.set_content(body)
+    elif action == GmailAction.DRAFT:
+        message = MIMEText(body)
+
+    message["To"] = recipient
+    message["Subject"] = subject
+
+    if cc:
+        message["Cc"] = ",".join(cc)
+    if bcc:
+        message["Bcc"] = ",".join(bcc)
+    if replying_to:
+        message["In-Reply-To"] = replying_to["header_message_id"]
+        message["References"] = f"{replying_to['header_message_id']}, {replying_to['references']}"
+
+    encoded_message = urlsafe_b64encode(message.as_bytes()).decode()
+
+    data = {"raw": encoded_message}
+
+    if replying_to:
+        data["threadId"] = replying_to["thread_id"]
+
+    return data
+
+
+def _build_gmail_service(context: ToolContext) -> Any:
+    """
+    Private helper function to build and return the Gmail service client.
+
+    Args:
+        context (ToolContext): The context containing authorization details.
+
+    Returns:
+        googleapiclient.discovery.Resource: An authorized Gmail API service instance.
+    """
+    try:
+        credentials = Credentials(
+            context.authorization.token
+            if context.authorization and context.authorization.token
+            else ""
+        )
+    except Exception as e:
+        raise GmailServiceError(message="Failed to build Gmail service.", developer_message=str(e))
+
+    return build("gmail", "v1", credentials=credentials)
+
+
+def build_gmail_query_string(
+    sender: str | None = None,
+    recipient: str | None = None,
+    subject: str | None = None,
+    body: str | None = None,
+    date_range: DateRange | None = None,
+    label: str | None = None,
+) -> str:
+    """Helper function to build a query string
+    for Gmail list_emails_by_header and search_threads tools.
+    """
+    query = []
+    if sender:
+        query.append(f"from:{sender}")
+    if recipient:
+        query.append(f"to:{recipient}")
+    if subject:
+        query.append(f"subject:{subject}")
+    if body:
+        query.append(body)
+    if date_range:
+        query.append(date_range.to_date_query())
+    if label:
+        query.append(f"label:{label}")
+    return " ".join(query)
+
+
+def get_label_ids(service: Any, label_names: list[str]) -> dict[str, str]:
+    """
+    Retrieve label IDs for given label names.
+    Returns a dictionary mapping label names to their IDs.
+
+    Args:
+        service: Authenticated Gmail API service instance.
+        label_names: List of label names to retrieve IDs for.
+
+    Returns:
+        A dictionary mapping found label names to their corresponding IDs.
+    """
+    try:
+        # Fetch all existing labels from Gmail
+        labels = service.users().labels().list(userId="me").execute().get("labels", [])
+    except Exception as e:
+        raise GmailToolError(message="Failed to list labels.", developer_message=str(e)) from e
+
+    # Create a mapping from label names to their IDs
+    label_id_map = {label["name"]: label["id"] for label in labels}
+
+    found_labels = {}
+    for name in label_names:
+        label_id = label_id_map.get(name)
+        if label_id:
+            found_labels[name] = label_id
+        else:
+            logger.warning(f"Label '{name}' does not exist")
+
+    return found_labels
+
+
+def fetch_messages(service: Any, query_string: str, limit: int) -> list[dict[str, Any]]:
+    """
+    Helper function to fetch messages from Gmail API for the list_emails_by_header tool.
+    """
+    response = (
+        service.users()
+        .messages()
+        .list(userId="me", q=query_string, maxResults=limit or 100)
+        .execute()
+    )
+    return response.get("messages", [])  # type: ignore[no-any-return]
+
+
+def remove_none_values(params: dict) -> dict:
+    """
+    Remove None values from a dictionary.
+    :param params: The dictionary to clean
+    :return: A new dictionary with None values removed
+    """
+    return {k: v for k, v in params.items() if v is not None}
+
+
+def build_reply_recipients(
+    replying_to: dict[str, Any], current_user_email_address: str, reply_to_whom: GmailReplyToWhom
+) -> str:
+    if reply_to_whom == GmailReplyToWhom.ONLY_THE_SENDER:
+        recipients = [replying_to["from"]]
+    elif reply_to_whom == GmailReplyToWhom.EVERY_RECIPIENT:
+        recipients = [replying_to["from"], *replying_to["to"].split(",")]
+    else:
+        raise ValueError(f"Unsupported reply_to_whom value: {reply_to_whom}")
+
+    recipients = [
+        email_address.strip()
+        for email_address in recipients
+        if email_address.strip().lower() != current_user_email_address.lower().strip()
+    ]
+
+    return ", ".join(recipients)
+
+
+def get_draft_url(draft_id: str) -> str:
+    return f"https://mail.google.com/mail/u/0/#drafts/{draft_id}"
+
+
+def get_sent_email_url(sent_email_id: str) -> str:
+    return f"https://mail.google.com/mail/u/0/#sent/{sent_email_id}"
+
+
+def get_email_details(service: Any, messages: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    """
+    Retrieves full message data for each message ID in the given list and extracts email details.
+
+    :param service: Authenticated Gmail API service instance.
+    :param messages: A list of dictionaries, each representing a message with an 'id' key.
+    :return: A list of dictionaries, each containing parsed email details.
+    """
+
+    emails = []
+    for msg in messages:
+        try:
+            # Fetch the full message data from Gmail using the message ID
+            email_data = service.users().messages().get(userId="me", id=msg["id"]).execute()
+            # Parse the raw email data into a structured form
+            email_details = parse_plain_text_email(email_data)
+            # Only add the details if parsing was successful
+            if email_details:
+                emails.append(email_details)
+        except Exception as e:
+            # Log any errors encountered while trying to fetch or parse a message
+            raise GmailToolError(
+                message=f"Error reading email {msg['id']}.", developer_message=str(e)
+            )
+    return emails
+
+
+def get_email_in_trash_url(email_id: str) -> str:
+    return f"https://mail.google.com/mail/u/0/#trash/{email_id}"
+
+
+def parse_draft_email(draft_email_data: dict[str, Any]) -> dict[str, str]:
+    """
+    Parse draft email data and extract relevant information.
+
+    Args:
+        draft_email_data (Dict[str, Any]): Raw draft email data from Gmail API.
+
+    Returns:
+        dict[str, str]: Parsed draft email details
+    """
+    message = draft_email_data.get("message", {})
+    payload = message.get("payload", {})
+    headers = {d["name"].lower(): d["value"] for d in payload.get("headers", [])}
+
+    body_data = _get_email_plain_text_body(payload)
+
+    return {
+        "id": draft_email_data.get("id", ""),
+        "thread_id": draft_email_data.get("threadId", ""),
+        "from": headers.get("from", ""),
+        "date": headers.get("internaldate", ""),
+        "subject": headers.get("subject", ""),
+        "body": _clean_email_body(body_data) if body_data else "",
+    }
+
+
+def _clean_email_body(body: str | None) -> str:
+    """
+    Remove HTML tags and clean up email body text while preserving most content.
+
+    Args:
+        body (str): The raw email body text.
+
+    Returns:
+        str: Cleaned email body text.
+    """
+    if not body:
+        return ""
+
+    try:
+        # Remove HTML tags using BeautifulSoup
+        soup = BeautifulSoup(body, "html.parser")
+        text = soup.get_text(separator=" ")
+
+        # Clean up the text
+        cleaned_text = _clean_text(text)
+
+        return cleaned_text.strip()
+    except Exception:
+        logger.exception("Error cleaning email body")
+        return body
+
+
+def _get_email_plain_text_body(payload: dict[str, Any]) -> str | None:
+    """
+    Extract email body from payload, handling 'multipart/alternative' parts.
+
+    Args:
+        payload (Dict[str, Any]): Email payload data.
+
+    Returns:
+        str | None: Decoded email body or None if not found.
+    """
+    # Direct body extraction
+    if "body" in payload and payload["body"].get("data"):
+        return _clean_email_body(urlsafe_b64decode(payload["body"]["data"]).decode())
+
+    # Handle multipart and alternative parts
+    return _clean_email_body(_extract_plain_body(payload.get("parts", [])))
+
+
+def _extract_plain_body(parts: list) -> str | None:
+    """
+    Recursively extract the email body from parts, handling both plain text and HTML.
+
+    Args:
+        parts (List[Dict[str, Any]]): List of email parts.
+
+    Returns:
+        str | None: Decoded and cleaned email body or None if not found.
+    """
+    for part in parts:
+        mime_type = part.get("mimeType")
+
+        if mime_type == "text/plain" and "data" in part.get("body", {}):
+            return urlsafe_b64decode(part["body"]["data"]).decode()
+
+        elif mime_type.startswith("multipart/"):
+            subparts = part.get("parts", [])
+            body = _extract_plain_body(subparts)
+            if body:
+                return body
+
+    return _extract_html_body(parts)
+
+
+def _extract_html_body(parts: list) -> str | None:
+    """
+    Recursively extract the email body from parts, handling only HTML.
+
+    Args:
+        parts (List[Dict[str, Any]]): List of email parts.
+
+    Returns:
+        str | None: Decoded and cleaned email body or None if not found.
+    """
+    for part in parts:
+        mime_type = part.get("mimeType")
+
+        if mime_type == "text/html" and "data" in part.get("body", {}):
+            html_content = urlsafe_b64decode(part["body"]["data"]).decode()
+            return html_content
+
+        elif mime_type.startswith("multipart/"):
+            subparts = part.get("parts", [])
+            body = _extract_html_body(subparts)
+            if body:
+                return body
+
+    return None
+
+
+def _clean_text(text: str) -> str:
+    """
+    Clean up the text while preserving most content.
+
+    Args:
+        text (str): The input text.
+
+    Returns:
+        str: Cleaned text.
+    """
+    # Replace multiple newlines with a single newline
+    text = re.sub(r"\n+", "\n", text)
+
+    # Replace multiple spaces with a single space
+    text = re.sub(r"\s+", " ", text)
+
+    # Remove leading/trailing whitespace from each line
+    text = "\n".join(line.strip() for line in text.split("\n"))
+
+    return text
+
+
+def parse_plain_text_email(email_data: dict[str, Any]) -> dict[str, Any]:
+    """
+    Parse email data and extract relevant information.
+    Only returns the plain text body.
+
+    Args:
+        email_data (dict[str, Any]): Raw email data from Gmail API.
+
+    Returns:
+        dict[str, str]: Parsed email details
+    """
+    payload = email_data.get("payload", {})
+    headers = {d["name"].lower(): d["value"] for d in payload.get("headers", [])}
+
+    body_data = _get_email_plain_text_body(payload)
+
+    email_details = {
+        "id": email_data.get("id", ""),
+        "thread_id": email_data.get("threadId", ""),
+        "label_ids": email_data.get("labelIds", []),
+        "history_id": email_data.get("historyId", ""),
+        "snippet": email_data.get("snippet", ""),
+        "to": headers.get("to", ""),
+        "cc": headers.get("cc", ""),
+        "from": headers.get("from", ""),
+        "reply_to": headers.get("reply-to", ""),
+        "in_reply_to": headers.get("in-reply-to", ""),
+        "references": headers.get("references", ""),
+        "header_message_id": headers.get("message-id", ""),
+        "date": headers.get("date", ""),
+        "subject": headers.get("subject", ""),
+        "body": body_data or "",
+    }
+
+    return email_details
+
+
+def build_reply_body(body: str, replying_to: dict[str, Any]) -> str:
+    attribution = f"On {replying_to['date']}, {replying_to['from']} wrote:"
+    lines = replying_to["plain_text_body"].split("\n")
+    quoted_plain = "\n".join([f"> {line}" for line in lines])
+    return f"{body}\n\n{attribution}\n\n{quoted_plain}"
+
+
+def parse_multipart_email(email_data: dict[str, Any]) -> dict[str, Any]:
+    """
+    Parse email data and extract relevant information.
+    Returns the plain text and HTML body along with the images.
+
+    Args:
+        email_data (Dict[str, Any]): Raw email data from Gmail API.
+
+    Returns:
+        dict[str, Any]: Parsed email details
+    """
+
+    payload = email_data.get("payload", {})
+    headers = {d["name"].lower(): d["value"] for d in payload.get("headers", [])}
+
+    # Extract different parts of the email
+    plain_text_body = _get_email_plain_text_body(payload)
+    html_body = _get_email_html_body(payload)
+
+    email_details = {
+        "id": email_data.get("id", ""),
+        "thread_id": email_data.get("threadId", ""),
+        "label_ids": email_data.get("labelIds", []),
+        "history_id": email_data.get("historyId", ""),
+        "snippet": email_data.get("snippet", ""),
+        "to": headers.get("to", ""),
+        "cc": headers.get("cc", ""),
+        "from": headers.get("from", ""),
+        "reply_to": headers.get("reply-to", ""),
+        "in_reply_to": headers.get("in-reply-to", ""),
+        "references": headers.get("references", ""),
+        "header_message_id": headers.get("message-id", ""),
+        "date": headers.get("date", ""),
+        "subject": headers.get("subject", ""),
+        "plain_text_body": plain_text_body or _clean_email_body(html_body),
+        "html_body": html_body or "",
+    }
+
+    return email_details
+
+
+def _get_email_html_body(payload: dict[str, Any]) -> str | None:
+    """
+    Extract email html body from payload, handling 'multipart/alternative' parts.
+
+    Args:
+        payload (Dict[str, Any]): Email payload data.
+
+    Returns:
+        str | None: Decoded email body or None if not found.
+    """
+    # Direct body extraction
+    if "body" in payload and payload["body"].get("data"):
+        return urlsafe_b64decode(payload["body"]["data"]).decode()
+
+    # Handle multipart and alternative parts
+    return _extract_html_body(payload.get("parts", []))

arcade_gmail-2.0.0.dist-info/METADATA

@@ -0,0 +1,24 @@
+Metadata-Version: 2.4
+Name: arcade_gmail
+Version: 2.0.0
+Summary: Arcade.dev LLM tools for Gmail
+Author-email: Arcade <dev@arcade.dev>
+Requires-Python: >=3.10
+Requires-Dist: arcade-tdk<3.0.0,>=2.0.0
+Requires-Dist: beautifulsoup4<5.0.0,>=4.10.0
+Requires-Dist: google-api-core<3.0.0,>=2.19.1
+Requires-Dist: google-api-python-client<3.0.0,>=2.137.0
+Requires-Dist: google-auth-httplib2<1.0.0,>=0.2.0
+Requires-Dist: google-auth<3.0.0,>=2.32.0
+Requires-Dist: googleapis-common-protos<2.0.0,>=1.63.2
+Provides-Extra: dev
+Requires-Dist: arcade-ai[evals]<3.0.0,>=2.0.0; extra == 'dev'
+Requires-Dist: arcade-serve<3.0.0,>=2.0.0; extra == 'dev'
+Requires-Dist: mypy<1.6.0,>=1.5.1; extra == 'dev'
+Requires-Dist: pre-commit<3.5.0,>=3.4.0; extra == 'dev'
+Requires-Dist: pytest-asyncio<0.25.0,>=0.24.0; extra == 'dev'
+Requires-Dist: pytest-cov<4.1.0,>=4.0.0; extra == 'dev'
+Requires-Dist: pytest-mock<3.12.0,>=3.11.1; extra == 'dev'
+Requires-Dist: pytest<8.4.0,>=8.3.0; extra == 'dev'
+Requires-Dist: ruff<0.8.0,>=0.7.4; extra == 'dev'
+Requires-Dist: tox<4.12.0,>=4.11.1; extra == 'dev'

arcade_gmail-2.0.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+arcade_gmail/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+arcade_gmail/constants.py,sha256=PjhKJuWIPk5yUfYpXXVsZwpzEEHeoPjR978hF_uexzc,833
+arcade_gmail/enums.py,sha256=cBksG9CV5rpA2tnN7X1Sm40DgWrVf4QtmG1S24LuMPc,209
+arcade_gmail/exceptions.py,sha256=uVSnm_KcCdI8ZfRORi__bIyQYo_-ahi4hHj88BFJkmw,615
+arcade_gmail/utils.py,sha256=WHwemtgAlNO37YKCu0KDmDbflwlCdHoykHMGK1v78pE,16135
+arcade_gmail/tools/__init__.py,sha256=Pgl3P0ZCEuEuHuwJxWr_zAROefwo3bOeF4D3WXJGzNk,802
+arcade_gmail/tools/gmail.py,sha256=cXtO90IFQuqFic7PI-u-6xYB630SttLCoXGx9NBG2eU,23009
+arcade_gmail-2.0.0.dist-info/METADATA,sha256=KhJ23V3wiFHO54UZSBO5Rg4floRByA4aChOKh_UHMNo,1068
+arcade_gmail-2.0.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+arcade_gmail-2.0.0.dist-info/RECORD,,

arcade_gmail-2.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any