arcade-google 0.0.13__py3-none-any.whl

arcade_google/tools/gmail.py

@@ -0,0 +1,333 @@
+import base64
+import json
+from email.message import EmailMessage
+from email.mime.text import MIMEText
+from typing import Annotated, Optional
+
+from google.oauth2.credentials import Credentials
+from googleapiclient.discovery import build
+from googleapiclient.errors import HttpError
+
+from arcade.core.schema import ToolContext
+from arcade.sdk import tool
+from arcade.sdk.auth import Google
+from arcade.sdk.error import RetryableToolError
+from arcade_google.tools.utils import (
+    DateRange,
+    build_query_string,
+    fetch_messages,
+    get_draft_url,
+    get_email_in_trash_url,
+    get_sent_email_url,
+    parse_draft_email,
+    parse_email,
+)
+
+
+# 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[Optional[list[str]], "CC recipients of the email"] = None,
+    bcc: Annotated[Optional[list[str]], "BCC recipients of the email"] = None,
+) -> Annotated[str, "A confirmation message with the sent email ID and URL"]:
+    """
+    Send an email using the Gmail API.
+    """
+
+    # Set up the Gmail API client
+    service = build("gmail", "v1", credentials=Credentials(context.authorization.token))
+
+    message = EmailMessage()
+    message.set_content(body)
+    message["To"] = recipient
+    message["Subject"] = subject
+    if cc:
+        message["Cc"] = ", ".join(cc)
+    if bcc:
+        message["Bcc"] = ", ".join(bcc)
+
+    # Encode the message in base64
+    encoded_message = base64.urlsafe_b64encode(message.as_bytes()).decode()
+
+    # Create the email
+    email = {"raw": encoded_message}
+
+    # Send the email
+    sent_message = service.users().messages().send(userId="me", body=email).execute()
+    return f"Email with ID {sent_message['id']} sent: {get_sent_email_url(sent_message['id'])}"
+
+
+@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[str, "A confirmation message with the sent email ID and URL"]:
+    """
+    Send a draft email using the Gmail API.
+    """
+
+    # Set up the Gmail API client
+    service = build("gmail", "v1", credentials=Credentials(context.authorization.token))
+
+    # Send the draft email
+    sent_message = service.users().drafts().send(userId="me", body={"id": email_id}).execute()
+
+    # Construct the URL to the sent email
+    return (
+        f"Draft email with ID {sent_message['id']} sent: {get_sent_email_url(sent_message['id'])}"
+    )
+
+
+# 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[Optional[list[str]], "CC recipients of the draft email"] = None,
+    bcc: Annotated[Optional[list[str]], "BCC recipients of the draft email"] = None,
+) -> Annotated[str, "A confirmation message with the draft email ID and URL"]:
+    """
+    Compose a new email draft using the Gmail API.
+    """
+    # Set up the Gmail API client
+    service = build("gmail", "v1", credentials=Credentials(context.authorization.token))
+
+    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()
+
+    # Create the draft
+    draft = {"message": {"raw": raw_message}}
+
+    draft_message = service.users().drafts().create(userId="me", body=draft).execute()
+    return (
+        f"Draft email with ID {draft_message['id']} created: {get_draft_url(draft_message['id'])}"
+    )
+
+
+@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[Optional[list[str]], "CC recipients of the draft email"] = None,
+    bcc: Annotated[Optional[list[str]], "BCC recipients of the draft email"] = None,
+) -> Annotated[str, "A confirmation message with the updated draft email ID and URL"]:
+    """
+    Update an existing email draft using the Gmail API.
+    """
+
+    # Set up the Gmail API client
+    service = build("gmail", "v1", credentials=Credentials(context.authorization.token))
+
+    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()
+    )
+    return f"Draft email with ID {updated_draft_message['id']} updated: {get_draft_url(updated_draft_message['id'])}"
+
+
+@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.
+    """
+
+    # Set up the Gmail API client
+    service = build("gmail", "v1", credentials=Credentials(context.authorization.token))
+
+    # 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[str, "A confirmation message with the trashed email ID and URL"]:
+    """
+    Move an email to the trash folder using the Gmail API.
+    """
+
+    # Set up the Gmail API client
+    service = build("gmail", "v1", credentials=Credentials(context.authorization.token))
+
+    # Trash the email
+    service.users().messages().trash(userId="me", id=email_id).execute()
+
+    return f"Email with ID {email_id} trashed successfully: {get_email_in_trash_url(email_id)}"
+
+
+# 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[str, "A JSON string containing a list of draft email details and their IDs"]:
+    """
+    Lists draft emails in the user's draft mailbox using the Gmail API.
+    """
+    # Set up the Gmail API client
+    service = build("gmail", "v1", credentials=Credentials(context.authorization.token))
+
+    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:
+            print(f"Error reading draft email {draft_id}: {e}")
+
+    return json.dumps({"emails": emails})
+
+
+# Email Search Tools
+@tool(
+    requires_auth=Google(
+        scopes=["https://www.googleapis.com/auth/gmail.readonly"],
+    )
+)
+async def list_emails_by_header(
+    context: ToolContext,
+    sender: Annotated[Optional[str], "The name or email address of the sender of the email"] = None,
+    recipient: Annotated[Optional[str], "The name or email address of the recipient"] = None,
+    subject: Annotated[Optional[str], "Words to find in the subject of the email"] = None,
+    body: Annotated[Optional[str], "Words to find in the body of the email"] = None,
+    date_range: Annotated[Optional[DateRange], "The date range of the email"] = None,
+    limit: Annotated[Optional[int], "The maximum number of emails to return"] = 25,
+) -> Annotated[
+    str, "A JSON string 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 parametersMUST be provided: sender, recipient, subject, body.
+    """
+    if not any([sender, recipient, subject, body]):
+        raise RetryableToolError(
+            message="At least one of sender, recipient, subject, or body must be provided.",
+            developer_message="At least one of sender, recipient, subject, or body must be provided.",
+        )
+
+    query = build_query_string(sender, recipient, subject, body, date_range)
+
+    service = build("gmail", "v1", credentials=Credentials(context.authorization.token))
+    messages = fetch_messages(service, query, limit)
+
+    if not messages:
+        return json.dumps({"emails": []})
+
+    emails = process_messages(service, messages)
+    return json.dumps({"emails": emails})
+
+
+def process_messages(service, messages):
+    emails = []
+    for msg in messages:
+        try:
+            email_data = service.users().messages().get(userId="me", id=msg["id"]).execute()
+            email_details = parse_email(email_data)
+            emails += [email_details] if email_details else []
+        except HttpError as e:
+            print(f"Error reading email {msg['id']}: {e}")
+    return 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[str, "A JSON string containing a list of email details"]:
+    """
+    Read emails from a Gmail account and extract plain text content.
+    """
+    # Set up the Gmail API client
+    service = build("gmail", "v1", credentials=Credentials(context.authorization.token))
+
+    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_email(email_data)
+            if email_details:
+                emails.append(email_details)
+        except Exception as e:
+            print(f"Error reading email {msg['id']}: {e}")
+
+    return json.dumps({"emails": emails})

arcade_google/tools/models.py

@@ -0,0 +1,294 @@
+from datetime import datetime, timedelta
+from enum import Enum
+from zoneinfo import ZoneInfo
+
+
+# ---------------------------------------------------------------------------- #
+# Google Calendar Models and Enums
+# ---------------------------------------------------------------------------- #
+class DateRange(Enum):
+    TODAY = "today"
+    TOMORROW = "tomorrow"
+    THIS_WEEK = "this_week"
+    NEXT_WEEK = "next_week"
+    THIS_MONTH = "this_month"
+    NEXT_MONTH = "next_month"
+
+    def to_date_range(self):
+        today = datetime.now().date()
+        if self == DateRange.TODAY:
+            return today, today + timedelta(days=1)
+        elif self == DateRange.TOMORROW:
+            return today + timedelta(days=1), today + timedelta(days=2)
+        elif self == DateRange.THIS_WEEK:
+            start = today - timedelta(days=today.weekday())
+            return start, start + timedelta(days=7)
+        elif self == DateRange.NEXT_WEEK:
+            start = today + timedelta(days=7 - today.weekday())
+            return start, start + timedelta(days=7)
+        elif self == DateRange.THIS_MONTH:
+            start = today.replace(day=1)
+            next_month = start + timedelta(days=32)
+            end = next_month.replace(day=1)
+            return start, end
+        elif self == DateRange.NEXT_MONTH:
+            start = (today.replace(day=1) + timedelta(days=32)).replace(day=1)
+            next_month = start + timedelta(days=32)
+            end = next_month.replace(day=1)
+            return start, end
+
+    def to_datetime_range(self, time_zone_name: str | None = None) -> tuple[datetime, datetime]:
+        start_date, end_date = self.to_date_range()
+        # time_zone = ZoneInfo(time_zone_name)
+        start_datetime = datetime.combine(
+            start_date, datetime.min.time()
+        )  # .replace(tzinfo=time_zone)
+        end_datetime = datetime.combine(end_date, datetime.min.time())  # .replace(tzinfo=time_zone)
+        return start_datetime, end_datetime
+
+
+class Day(Enum):
+    # TODO: THere are obvious limitations here. We should do better and support any date.
+    YESTERDAY = "yesterday"
+    TODAY = "today"
+    TOMORROW = "tomorrow"
+    THIS_SUNDAY = "this_sunday"
+    THIS_MONDAY = "this_monday"
+    THIS_TUESDAY = "this_tuesday"
+    THIS_WEDNESDAY = "this_wednesday"
+    THIS_THURSDAY = "this_thursday"
+    THIS_FRIDAY = "this_friday"
+    THIS_SATURDAY = "this_saturday"
+    NEXT_SUNDAY = "next_sunday"
+    NEXT_MONDAY = "next_monday"
+    NEXT_TUESDAY = "next_tuesday"
+    NEXT_WEDNESDAY = "next_wednesday"
+    NEXT_THURSDAY = "next_thursday"
+    NEXT_FRIDAY = "next_friday"
+    NEXT_SATURDAY = "next_saturday"
+
+    def to_date(self, time_zone_name: str):
+        time_zone = ZoneInfo(time_zone_name)
+        today = datetime.now(time_zone).date()
+        weekday = today.weekday()
+
+        if self == Day.YESTERDAY:
+            return today - timedelta(days=1)
+        elif self == Day.TODAY:
+            return today
+        elif self == Day.TOMORROW:
+            return today + timedelta(days=1)
+
+        day_offsets = {
+            Day.THIS_SUNDAY: 6,
+            Day.THIS_MONDAY: 0,
+            Day.THIS_TUESDAY: 1,
+            Day.THIS_WEDNESDAY: 2,
+            Day.THIS_THURSDAY: 3,
+            Day.THIS_FRIDAY: 4,
+            Day.THIS_SATURDAY: 5,
+        }
+
+        if self in day_offsets:
+            return today + timedelta(days=(day_offsets[self] - weekday) % 7)
+
+        next_week_offsets = {
+            Day.NEXT_SUNDAY: 6,
+            Day.NEXT_MONDAY: 0,
+            Day.NEXT_TUESDAY: 1,
+            Day.NEXT_WEDNESDAY: 2,
+            Day.NEXT_THURSDAY: 3,
+            Day.NEXT_FRIDAY: 4,
+            Day.NEXT_SATURDAY: 5,
+        }
+
+        if self in next_week_offsets:
+            return today + timedelta(days=(next_week_offsets[self] - weekday + 7) % 7)
+
+        raise ValueError(f"Invalid Day enum value: {self}")
+
+
+class TimeSlot(Enum):
+    _0000 = "00:00"
+    _0015 = "00:15"
+    _0030 = "00:30"
+    _0045 = "00:45"
+    _0100 = "01:00"
+    _0115 = "01:15"
+    _0130 = "01:30"
+    _0145 = "01:45"
+    _0200 = "02:00"
+    _0215 = "02:15"
+    _0230 = "02:30"
+    _0245 = "02:45"
+    _0300 = "03:00"
+    _0315 = "03:15"
+    _0330 = "03:30"
+    _0345 = "03:45"
+    _0400 = "04:00"
+    _0415 = "04:15"
+    _0430 = "04:30"
+    _0445 = "04:45"
+    _0500 = "05:00"
+    _0515 = "05:15"
+    _0530 = "05:30"
+    _0545 = "05:45"
+    _0600 = "06:00"
+    _0615 = "06:15"
+    _0630 = "06:30"
+    _0645 = "06:45"
+    _0700 = "07:00"
+    _0715 = "07:15"
+    _0730 = "07:30"
+    _0745 = "07:45"
+    _0800 = "08:00"
+    _0815 = "08:15"
+    _0830 = "08:30"
+    _0845 = "08:45"
+    _0900 = "09:00"
+    _0915 = "09:15"
+    _0930 = "09:30"
+    _0945 = "09:45"
+    _1000 = "10:00"
+    _1015 = "10:15"
+    _1030 = "10:30"
+    _1045 = "10:45"
+    _1100 = "11:00"
+    _1115 = "11:15"
+    _1130 = "11:30"
+    _1145 = "11:45"
+    _1200 = "12:00"
+    _1215 = "12:15"
+    _1230 = "12:30"
+    _1245 = "12:45"
+    _1300 = "13:00"
+    _1315 = "13:15"
+    _1330 = "13:30"
+    _1345 = "13:45"
+    _1400 = "14:00"
+    _1415 = "14:15"
+    _1430 = "14:30"
+    _1445 = "14:45"
+    _1500 = "15:00"
+    _1515 = "15:15"
+    _1530 = "15:30"
+    _1545 = "15:45"
+    _1600 = "16:00"
+    _1615 = "16:15"
+    _1630 = "16:30"
+    _1645 = "16:45"
+    _1700 = "17:00"
+    _1715 = "17:15"
+    _1730 = "17:30"
+    _1745 = "17:45"
+    _1800 = "18:00"
+    _1815 = "18:15"
+    _1830 = "18:30"
+    _1845 = "18:45"
+    _1900 = "19:00"
+    _1915 = "19:15"
+    _1930 = "19:30"
+    _1945 = "19:45"
+    _2000 = "20:00"
+    _2015 = "20:15"
+    _2030 = "20:30"
+    _2045 = "20:45"
+    _2100 = "21:00"
+    _2115 = "21:15"
+    _2130 = "21:30"
+    _2145 = "21:45"
+    _2200 = "22:00"
+    _2215 = "22:15"
+    _2230 = "22:30"
+    _2245 = "22:45"
+    _2300 = "23:00"
+    _2315 = "23:15"
+    _2330 = "23:30"
+    _2345 = "23:45"
+
+    def to_time(self):
+        return datetime.strptime(self.value, "%H:%M").time()
+
+
+class EventVisibility(Enum):
+    DEFAULT = "default"
+    PUBLIC = "public"
+    PRIVATE = "private"
+    CONFIDENTIAL = "confidential"
+
+
+class EventType(Enum):
+    BIRTHDAY = "birthday"  # Special all-day events with an annual recurrence.
+    DEFAULT = "default"  # Regular events
+    FOCUS_TIME = "focusTime"  # Focus time events
+    FROM_GMAIL = "fromGmail"  # Events from Gmail
+    OUT_OF_OFFICE = "outOfOffice"  # Out of office events
+    WORKING_LOCATION = "workingLocation"  # Working location events
+
+
+class SendUpdatesOptions(Enum):
+    NONE = "none"  # No notifications are sent
+    ALL = "all"  # Notifications are sent to all guests
+    EXTERNAL_ONLY = "externalOnly"  # Notifications are sent to non-Google Calendar guests only.
+
+
+# Utils for Google Drive tools
+class Corpora(str, Enum):
+    """
+    Bodies of items (files/documents) to which the query applies.
+    Prefer 'user' or 'drive' to 'allDrives' for efficiency.
+    By default, corpora is set to 'user'.
+    """
+
+    USER = "user"
+    DOMAIN = "domain"
+    DRIVE = "drive"
+    ALL_DRIVES = "allDrives"
+
+
+class OrderBy(str, Enum):
+    """
+    Sort keys for ordering files in Google Drive.
+    Each key has both ascending and descending options.
+    """
+
+    CREATED_TIME = "createdTime"  # When the file was created (ascending)
+    CREATED_TIME_DESC = "createdTime desc"  # When the file was created (descending)
+    FOLDER = "folder"  # The folder ID, sorted using alphabetical ordering (ascending)
+    FOLDER_DESC = "folder desc"  # The folder ID, sorted using alphabetical ordering (descending)
+    MODIFIED_BY_ME_TIME = (
+        "modifiedByMeTime"  # The last time the file was modified by the user (ascending)
+    )
+    MODIFIED_BY_ME_TIME_DESC = (
+        "modifiedByMeTime desc"  # The last time the file was modified by the user (descending)
+    )
+    MODIFIED_TIME = "modifiedTime"  # The last time the file was modified by anyone (ascending)
+    MODIFIED_TIME_DESC = (
+        "modifiedTime desc"  # The last time the file was modified by anyone (descending)
+    )
+    NAME = "name"  # The name of the file, sorted using alphabetical ordering (e.g., 1, 12, 2, 22) (ascending)
+    NAME_DESC = "name desc"  # The name of the file, sorted using alphabetical ordering (e.g., 1, 12, 2, 22) (descending)
+    NAME_NATURAL = "name_natural"  # The name of the file, sorted using natural sort ordering (e.g., 1, 2, 12, 22) (ascending)
+    NAME_NATURAL_DESC = "name_natural desc"  # The name of the file, sorted using natural sort ordering (e.g., 1, 2, 12, 22) (descending)
+    QUOTA_BYTES_USED = (
+        "quotaBytesUsed"  # The number of storage quota bytes used by the file (ascending)
+    )
+    QUOTA_BYTES_USED_DESC = (
+        "quotaBytesUsed desc"  # The number of storage quota bytes used by the file (descending)
+    )
+    RECENCY = "recency"  # The most recent timestamp from the file's date-time fields (ascending)
+    RECENCY_DESC = (
+        "recency desc"  # The most recent timestamp from the file's date-time fields (descending)
+    )
+    SHARED_WITH_ME_TIME = (
+        "sharedWithMeTime"  # When the file was shared with the user, if applicable (ascending)
+    )
+    SHARED_WITH_ME_TIME_DESC = "sharedWithMeTime desc"  # When the file was shared with the user, if applicable (descending)
+    STARRED = "starred"  # Whether the user has starred the file (ascending)
+    STARRED_DESC = "starred desc"  # Whether the user has starred the file (descending)
+    VIEWED_BY_ME_TIME = (
+        "viewedByMeTime"  # The last time the file was viewed by the user (ascending)
+    )
+    VIEWED_BY_ME_TIME_DESC = (
+        "viewedByMeTime desc"  # The last time the file was viewed by the user (descending)
+    )