google-api-client-wrapper 1.0.0__py3-none-any.whl

google_api_client_wrapper-1.0.0.dist-info/METADATA

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: google-api-client-wrapper
+Version: 1.0.0
+Summary: A comprehensive Python wrapper for Google APIs, providing clean and intuitive access to Gmail, Google Drive, Google Calendar, and Google Tasks services.
+Author-email: Dagmawi Molla <dagmawishewadeg@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2025 Dagmawi Molla
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/dsmolla/google-api-client-wrapper
+Project-URL: Documentation, https://github.com/dsmolla/google-api-wrapper/blob/main/README.md
+Project-URL: Repository, https://github.com/dsmolla/google-api-client-wrapper
+Keywords: google-api,gmail,google-drive,google-calendar,google-tasks,api-wrapper,python-wrapper
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: google-api-python-client>=2.163.0
+Requires-Dist: google-auth>=2.28.1
+Requires-Dist: google-auth-httplib2
+Requires-Dist: google-auth-oauthlib>=1.2.1
+Requires-Dist: tzlocal>=5.3.1
+Requires-Dist: html2text>=2025.4.15
+Dynamic: license-file
+
+# Google API Client
+
+A comprehensive Python wrapper for Google APIs, providing clean and intuitive access to Gmail, Google Drive, Google Calendar, and Google Tasks services.
+
+## Features
+
+- **Gmail Service**: Send, receive, search, and manage emails
+- **Google Drive Service**: Upload, download, and manage files and folders
+- **Google Calendar Service**: Create, update, and manage calendar events
+- **Google Tasks Service**: Manage tasks and task lists
+- **OAuth2 Authentication**: Secure authentication flow
+- **Query Builders**: Intuitive query building for each service
+- **Multi-User Authentication**: Supports multiple users to be authenticated
+- **Dataclass Models**: Uses Python dataclasses for clean, type-safe data structures (GmailMessage, EmailAddress, Task, Event, etc.)
+
+## Installation
+
+
+## Quick Start
+
+```python
+from google_client.user_client import UserClient
+from datetime import datetime, timedelta
+
+# Authenticate User
+user_1 = UserClient.from_file("< user_1_token_path >", "< app_credentials_path >")
+user_2, user_2_token = UserClient.from_credentials_info(
+    "< user_2_token_dict >": 1,
+"< app_credentials_dict >": 2,
+"< scopes_list >,
+)
+
+# List User 1's emails
+user_1_emails = user_1.gmail.list_emails()
+
+# Create a calendar event for User 2
+user_2_event = user_2.calendar.create_event(datetime.now(), datetime.now() + timedelta(hours=1))
+```
+
+## Package Documentation
+
+Each service has detailed documentation with examples and API reference:
+
+- **[Gmail Service](google_client/services/gmail/README.md)** - Email management and operations
+- **[Google Drive Service](google_client/services/drive/README.md)** - File and folder management
+- **[Google Calendar Service](google_client/services/calendar/README.md)** - Calendar and event management
+- **[Google Tasks Service](google_client/services/tasks/README.md)** - Task and task list management
+
+## Links
+- **[Google Auth & Tokens](https://developers.google.com/identity/protocols/oauth2/web-server#python)**
+
+--- 
+See individual package documentation for detailed usage examples and API references.
+
+For more information look at the official Google API Documentation for each service
+

google_api_client_wrapper-1.0.0.dist-info/RECORD

@@ -0,0 +1,39 @@
+google_api_client_wrapper-1.0.0.dist-info/licenses/LICENSE,sha256=Rctsw-Efg0OoOLOVl4vLNXopCB61er5H5aF1GXPqaR8,1091
+google_client/__init__.py,sha256=h6aGXG3HRmhov2wdymfrjMSvbjwXlpnjqf2rHBULT7c,59
+google_client/user_client.py,sha256=2ib-5MzX2Wp6Ant9FURxeEsLAqUQRSeAr8fmuhqMPIg,6939
+google_client/services/__init__.py,sha256=BTDc288hVabLRpdYLjzko-zV5efHMARC4SBfqFf6pcU,212
+google_client/services/calendar/__init__.py,sha256=VZl9TOXAKNvDTBJX_cdNGSj0dT044UjeP51eCcm5P08,373
+google_client/services/calendar/api_service.py,sha256=5EtDk4ZiGTPfuEnDLTuirqK4bZ9H1VPMHsq3BSB6CAw,17271
+google_client/services/calendar/constants.py,sha256=nb9onECh3NpMDjbaEZrY_rz57Nd8fQhzDKgB2FtAPNI,1235
+google_client/services/calendar/exceptions.py,sha256=WbWRf1dwICNnEQSblUU88i5IKfgGDBYJdE63MaqE_X4,824
+google_client/services/calendar/query_builder.py,sha256=qMUNzq1_RrlAyL3lZd_ms9b0Q6ZzjphoU8qitmHAhZU,10741
+google_client/services/calendar/types.py,sha256=lDodMsfsnkfB-QekYQXNZJSGA1BZhIQln92ZDIZM6Ts,14877
+google_client/services/calendar/utils.py,sha256=0X4_yGakkllak51FMJNAEyW1CEG4IGMe_B86inFrxN4,11741
+google_client/services/drive/__init__.py,sha256=vC2xPcj9LwDYrlJnkDDbVhV_lZrpTBBCSGZPXwb_7GA,323
+google_client/services/drive/api_service.py,sha256=ay5oPzfOfudH0utuLPJi2fwi670RqBH3pTbdpB15n-8,42362
+google_client/services/drive/constants.py,sha256=F1vw9xDM90KtRsEBnGdQfEczZvlQ4q8oy2sSYU2p5sE,1458
+google_client/services/drive/exceptions.py,sha256=sPWSIkN5ME__YLqP5zUUvHr0bN7JovYyNLWSdle-WZ4,1259
+google_client/services/drive/query_builder.py,sha256=YvMLGH8KrJdF9Syn0JkUSK1RDHdRZtGGTQCPrn0jH84,13293
+google_client/services/drive/types.py,sha256=uElqEP2s2XSoU1ST9SLw_4rNPvLVQ98JjcemqdWy0Pg,7655
+google_client/services/drive/utils.py,sha256=DlfZ2-0gIl8V4MvdJ9TZWNPWaPfFjtev9YvJsZUD5tA,11318
+google_client/services/gmail/__init__.py,sha256=2KmwgFFCICBNWqzRUIAHhw91ECert1EUcRxr1k8dSqs,398
+google_client/services/gmail/api_service.py,sha256=4Nx7ZKwOsi6SgsOybFUHymjTZ2ikRxP4lZyoamv0Ruw,23586
+google_client/services/gmail/constants.py,sha256=HlSelKC2LQ69qsGy8kDuE3oM9MY26QOj7fLnfKyK1bQ,157
+google_client/services/gmail/exceptions.py,sha256=Y6ryrLgE1rb29-DqigTRVNJpbN9bY7jeIY-1vDqDE6M,994
+google_client/services/gmail/query_builder.py,sha256=T2DgV9qEdyC_4bmLuSp01nVdBQIxCngrVSB4GHczTZs,13423
+google_client/services/gmail/types.py,sha256=mSYCKEYEX-yIcx0ZG6JBv890V-6xU2E68wWSeF-pAeA,9468
+google_client/services/gmail/utils.py,sha256=5fgIwAAt1X8Mj1Lkw-ySYs1ikw8jCV_Ok_MKQE-sZuk,15740
+google_client/services/tasks/__init__.py,sha256=-49orKlF1Dv8-StGLXypFvrdd212eEVGQEqlpr4_RhI,251
+google_client/services/tasks/api_service.py,sha256=yXiXjggdXbHjxNrzZW9vvWgv0JjVA4lSIiQnZ0QQMdg,20067
+google_client/services/tasks/constants.py,sha256=iG7Pgwan-xvCi7dvrOGnxhqJ9GGrGrUapM1x638HYXY,803
+google_client/services/tasks/exceptions.py,sha256=twOONDyslz0sl8T8QeqmC0pySf3vxLgsL1r7Y4gvBPk,790
+google_client/services/tasks/query_builder.py,sha256=X2SlPwZAqhi_FAs1JBVjAhzb1g3H4_uop7BjRTB9g5U,11544
+google_client/services/tasks/types.py,sha256=6G8-cIF2tiOqTQ9a9SDOHdL4PKHmoSj1ODqMTpZl8Jo,5184
+google_client/services/tasks/utils.py,sha256=jXHaN0P3-SeQGzgUmErloiz6hF5JO1tyfbvd0dVA4Fw,6952
+google_client/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+google_client/utils/datetime.py,sha256=tCnCPLRjkC2jgwBXAY0wcXnjOBNIJJpJLQVD_nFJijY,4860
+google_client/utils/validation.py,sha256=fBvxyrjGwrGWF0GFRNXkJChBmdkWZl51Ir7u4h2JfWc,2177
+google_api_client_wrapper-1.0.0.dist-info/METADATA,sha256=fGscJdLRVpclvKNhDkKltq_i52o-pUthmMkjinqKoRk,4746
+google_api_client_wrapper-1.0.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+google_api_client_wrapper-1.0.0.dist-info/top_level.txt,sha256=8R7Ea6TH-HnXwFDVa1U0t2zjTQxPO4mr8kNbBaslVnA,14
+google_api_client_wrapper-1.0.0.dist-info/RECORD,,

google_api_client_wrapper-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

google_api_client_wrapper-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Dagmawi Molla
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

google_api_client_wrapper-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+google_client

google_client/__init__.py

@@ -0,0 +1,6 @@
+
+from . import services
+
+__all__ = [
+    "services",
+]

google_client/services/__init__.py

@@ -0,0 +1,13 @@
+"""Google API services for various services."""
+
+from . import calendar
+from . import gmail
+from . import drive
+from . import tasks
+
+__all__ = [
+    "calendar",
+    "gmail",
+    "drive",
+    "tasks"
+]

google_client/services/calendar/__init__.py

@@ -0,0 +1,14 @@
+"""Calendar client module for Google API integration."""
+
+from .api_service import CalendarApiService
+from .types import CalendarEvent, Attendee, TimeSlot, FreeBusyResponse
+from .query_builder import EventQueryBuilder
+
+__all__ = [
+    "CalendarApiService",
+    "CalendarEvent",
+    "Attendee",
+    "TimeSlot",
+    "FreeBusyResponse",
+    "EventQueryBuilder",
+]

google_client/services/calendar/api_service.py

@@ -0,0 +1,454 @@
+from datetime import datetime, timedelta
+from typing import Optional, List, Any, Dict
+
+from googleapiclient.errors import HttpError
+
+from ...utils.datetime import convert_datetime_to_iso, today_start
+from .types import CalendarEvent, Attendee, FreeBusyResponse, TimeSlot
+from . import utils
+from .constants import DEFAULT_MAX_RESULTS, MAX_RESULTS_LIMIT, DEFAULT_CALENDAR_ID, DEFAULT_FREEBUSY_DURATION_MINUTES
+from .exceptions import (
+    CalendarError, CalendarPermissionError, EventNotFoundError,
+    CalendarNotFoundError, EventConflictError, InvalidEventDataError
+)
+
+
+class CalendarApiService:
+    """
+    Service layer for Calendar API operations.
+    Contains all Calendar API functionality that was removed from dataclasses.
+    """
+    
+    def __init__(self, service: Any):
+        """
+        Initialize Calendar service.
+        
+        Args:
+            service: The Calendar API service instance
+        """
+        self._service = service
+
+    def query(self):
+        """
+        Create a new EventQueryBuilder for building complex event queries with a fluent API.
+
+        Returns:
+            EventQueryBuilder instance for method chaining
+
+        Example:
+            events = (user.calendar.query()
+                .limit(50)
+                .today()
+                .search("meeting")
+                .with_location()
+                .execute())
+        """
+        from .query_builder import EventQueryBuilder
+        return EventQueryBuilder(self)
+
+    def list_events(
+            self,
+            max_results: Optional[int] = DEFAULT_MAX_RESULTS,
+            start: Optional[datetime] = today_start(),
+            end: Optional[datetime] = None,
+            query: Optional[str] = None,
+            calendar_id: str = DEFAULT_CALENDAR_ID,
+            single_events: bool = True,
+            order_by: str = 'startTime'
+    ) -> List[CalendarEvent]:
+        """
+        Fetches a list of events from Google Calendar with optional filtering.
+
+        Args:
+            max_results: Maximum number of events to retrieve. Defaults to 100.
+            start: Start time for events (inclusive). Defaults to today.
+            end: End time for events (exclusive). Defaults to 30 days from start date
+            query: Text search query string.
+            calendar_id: Calendar ID to query (default: 'primary').
+            single_events: Whether to expand recurring events into instances.
+            order_by: How to order the events ('startTime' or 'updated').
+
+        Returns:
+            A list of CalendarEvent objects representing the events found.
+            If no events are found, an empty list is returned.
+        """
+        # Input validation
+        if max_results and (max_results < 1 or max_results > MAX_RESULTS_LIMIT):
+            raise ValueError(f"max_results must be between 1 and {MAX_RESULTS_LIMIT}")
+
+        if not end:
+            end = start + timedelta(days=30)
+
+        try:
+            # Build request parameters
+            request_params = {
+                'calendarId': calendar_id,
+                'maxResults': max_results,
+                'singleEvents': single_events,
+            }
+            
+            if order_by and single_events:
+                request_params['orderBy'] = order_by
+
+            # Add time range filters
+            if start:
+                request_params['timeMin'] = convert_datetime_to_iso(start)
+            if end:
+                request_params['timeMax'] = convert_datetime_to_iso(end)
+            if query:
+                request_params['q'] = query
+
+            # Make API call
+            result = self._service.events().list(**request_params).execute()
+            events_data = result.get('items', [])
+
+
+            # Parse events
+            calendar_events = []
+            for event_data in events_data:
+                try:
+                    calendar_events.append(utils.from_google_event(event_data))
+                except Exception as e:
+                    pass
+
+            return calendar_events
+
+        except HttpError as e:
+            if e.resp.status == 403:
+                raise CalendarPermissionError(f"Permission denied")
+            elif e.resp.status == 404:
+                raise CalendarNotFoundError(f"Calendar not found")
+            else:
+                raise CalendarError(f"Calendar API error listing events")
+        except Exception as e:
+            raise CalendarError(f"Unexpected error listing events")
+
+    def get_event(self, event_id: str, calendar_id: str = DEFAULT_CALENDAR_ID) -> CalendarEvent:
+        """
+        Retrieves a specific event from Google Calendar using its unique identifier.
+
+        Args:
+            event_id: The unique identifier of the event to be retrieved.
+            calendar_id: Calendar ID containing the event (default: 'primary').
+
+        Returns:
+            A CalendarEvent object representing the event with the specified ID.
+        """
+
+        try:
+            event_data = self._service.events().get(
+                calendarId=calendar_id,
+                eventId=event_id
+            ).execute()
+            
+            return utils.from_google_event(event_data)
+            
+        except HttpError as e:
+            if e.resp.status == 404:
+                raise EventNotFoundError(f"Event not found")
+            elif e.resp.status == 403:
+                raise CalendarPermissionError(f"Permission denied accessing event")
+            else:
+                raise CalendarError(f"Calendar API error getting event")
+        except Exception as e:
+            raise CalendarError(f"Unexpected error getting event")
+
+    def create_event(
+            self,
+            start: datetime,
+            end: datetime,
+            summary: str = None,
+            description: str = None,
+            location: str = None,
+            attendees: List[Attendee] = None,
+            recurrence: List[str] = None,
+            calendar_id: str = DEFAULT_CALENDAR_ID
+    ) -> CalendarEvent:
+        """
+        Creates a new calendar event.
+
+        Args:
+            start: Event start datetime.
+            end: Event end datetime.
+            summary: Brief title or summary of the event.
+            description: Detailed description of the event.
+            location: Physical or virtual location of the event.
+            attendees: List of Attendee objects for invited people.
+            recurrence: List of recurrence rules in RFC 5545 format.
+            calendar_id: Calendar ID to create event in (default: 'primary').
+
+        Returns:
+            A CalendarEvent object representing the created event.
+        """
+        # Create event preparation
+
+        try:
+            # Create event body using utils
+            event_body = utils.create_event_body(
+                start=start,
+                end=end,
+                summary=summary,
+                description=description,
+                location=location,
+                attendees=attendees,
+                recurrence=recurrence
+            )
+
+            # Make API call
+            created_event = self._service.events().insert(
+                calendarId=calendar_id,
+                body=event_body
+            ).execute()
+            
+            calendar_event = utils.from_google_event(created_event)
+            return calendar_event
+            
+        except HttpError as e:
+            if e.resp.status == 403:
+                raise CalendarPermissionError(f"Permission denied creating event")
+            elif e.resp.status == 409:
+                raise EventConflictError(f"Event conflict")
+            else:
+                raise CalendarError(f"Calendar API error creating event")
+        except ValueError as e:
+            raise InvalidEventDataError(f"Invalid event data")
+        except Exception as e:
+            raise CalendarError(f"Unexpected error creating event")
+
+    def update_event(
+            self,
+            event: CalendarEvent,
+            calendar_id: str = DEFAULT_CALENDAR_ID
+    ) -> CalendarEvent:
+        """
+        Updates an existing calendar event.
+
+        Args:
+            event: CalendarEvent object with updated data.
+            calendar_id: Calendar ID containing the event (default: 'primary').
+
+        Returns:
+            A CalendarEvent object representing the updated event.
+        """
+
+        try:
+            # Convert event to API format
+            event_body = event.to_dict()
+            
+            # Remove fields that shouldn't be updated
+            fields_to_remove = ['id', 'htmlLink', 'recurringEventId']
+            for field in fields_to_remove:
+                event_body.pop(field, None)
+            
+            # Add datetime fields if they exist
+            if event.start and event.end:
+                event_body['start'] = {'dateTime': convert_datetime_to_iso(event.start)}
+                event_body['end'] = {'dateTime': convert_datetime_to_iso(event.end)}
+
+            # Make API call
+            updated_event = self._service.events().update(
+                calendarId=calendar_id,
+                eventId=event.event_id,
+                body=event_body
+            ).execute()
+            
+            updated_calendar_event = utils.from_google_event(updated_event)
+            return updated_calendar_event
+            
+        except HttpError as e:
+            if e.resp.status == 404:
+                raise EventNotFoundError(f"Event not found")
+            elif e.resp.status == 403:
+                raise CalendarPermissionError(f"Permission denied updating event")
+            elif e.resp.status == 409:
+                raise EventConflictError(f"Event conflict during update")
+            else:
+                raise CalendarError(f"Calendar API error updating event")
+        except ValueError as e:
+            raise InvalidEventDataError(f"Invalid event data")
+        except Exception as e:
+            raise CalendarError(f"Unexpected error updating event")
+
+    def delete_event(
+            self,
+            event: CalendarEvent,
+            calendar_id: str = DEFAULT_CALENDAR_ID
+    ) -> bool:
+        """
+        Deletes a calendar event.
+
+        Args:
+            event: The Calendar event to delete.
+            calendar_id: Calendar ID containing the event (default: 'primary').
+
+        Returns:
+            True if the operation was successful, False otherwise.
+        """
+
+        try:
+            self._service.events().delete(
+                calendarId=calendar_id,
+                eventId=event.event_id
+            ).execute()
+            
+            return True
+            
+        except HttpError as e:
+            if e.resp.status == 404:
+                raise EventNotFoundError(f"Event not found")
+            elif e.resp.status == 403:
+                raise CalendarPermissionError(f"Permission denied deleting event")
+            else:
+                raise CalendarError(f"Calendar API error deleting event")
+        except Exception as e:
+            raise CalendarError(f"Unexpected error deleting event")
+
+    def batch_get_events(self, event_ids: List[str], calendar_id: str = DEFAULT_CALENDAR_ID) -> List[CalendarEvent]:
+        """
+        Retrieves multiple events by their IDs.
+
+        Args:
+            event_ids: List of event IDs to retrieve.
+            calendar_id: Calendar ID containing the events (default: 'primary').
+
+        Returns:
+            List of CalendarEvent objects.
+        """
+
+        calendar_events = []
+        for event_id in event_ids:
+            try:
+                calendar_events.append(self.get_event(event_id, calendar_id))
+            except Exception as e:
+                pass
+
+        return calendar_events
+
+    def batch_create_events(self, events_data: List[Dict[str, Any]], calendar_id: str = DEFAULT_CALENDAR_ID) -> List[CalendarEvent]:
+        """
+        Creates multiple events.
+
+        Args:
+            events_data: List of dictionaries containing event parameters.
+            calendar_id: Calendar ID to create events in (default: 'primary').
+
+        Returns:
+            List of created CalendarEvent objects.
+        """
+
+        created_events = []
+        for event_data in events_data:
+            try:
+                created_events.append(self.create_event(calendar_id=calendar_id, **event_data))
+            except Exception as e:
+                pass
+
+        return created_events
+
+    def get_freebusy(
+        self,
+        start: datetime,
+        end: datetime,
+        calendar_ids: Optional[List[str]] = None,
+    ) -> FreeBusyResponse:
+        """
+        Query free/busy information for specified calendars and time range.
+        
+        Args:
+            start: Start datetime for the query
+            end: End datetime for the query  
+            calendar_ids: List of calendar IDs to query (defaults to primary calendar)
+
+        Returns:
+            FreeBusyResponse object containing availability information
+            
+        Raises:
+            CalendarError: If the API request fails
+            ValueError: If the parameters are invalid
+        """
+        if calendar_ids is None:
+            calendar_ids = [DEFAULT_CALENDAR_ID]
+        
+        # Validate the request parameters
+        utils.validate_freebusy_request(start, end, calendar_ids)
+        
+        try:
+            # Make the API call
+            request_body = {
+                "timeMin": convert_datetime_to_iso(start),
+                "timeMax": convert_datetime_to_iso(end),
+                "items": [{"id": cal_id} for cal_id in calendar_ids]
+            }
+
+            result = self._service.freebusy().query(body=request_body).execute()
+            
+            # Parse and return the response
+            return utils.parse_freebusy_response(result)
+            
+        except HttpError as e:
+            if e.resp.status == 403:
+                raise CalendarPermissionError("Permission denied for freebusy query")
+            elif e.resp.status == 404:
+                raise CalendarNotFoundError("One or more calendars not found")
+            else:
+                raise CalendarError(f"Calendar API error during freebusy query")
+        except ValueError as e:
+            raise ValueError(f"Invalid freebusy request")
+        except Exception as e:
+            raise CalendarError(f"Unexpected error during freebusy query")
+
+    def find_free_slots(
+        self,
+        start: datetime,
+        end: datetime,
+        duration_minutes: int = DEFAULT_FREEBUSY_DURATION_MINUTES,
+        calendar_ids: Optional[List[str]] = None
+    ) -> List[TimeSlot]:
+        """
+        Find all available time slots of a specified duration within a time range.
+        
+        Args:
+            start: Start datetime for the search
+            end: End datetime for the search
+            duration_minutes: Minimum duration for free slots in minutes
+            calendar_ids: List of calendar IDs to check (defaults to primary calendar)
+            
+        Returns:
+            List of TimeSlot objects representing available time slots
+            
+        Raises:
+            CalendarError: If the API request fails
+            ValueError: If the parameters are invalid
+        """
+        from .constants import MIN_TIME_SLOT_DURATION_MINUTES, MAX_TIME_SLOT_DURATION_MINUTES
+        
+        if duration_minutes < MIN_TIME_SLOT_DURATION_MINUTES:
+            raise ValueError(f"Duration must be at least {MIN_TIME_SLOT_DURATION_MINUTES} minutes")
+        if duration_minutes > MAX_TIME_SLOT_DURATION_MINUTES:
+            raise ValueError(f"Duration cannot exceed {MAX_TIME_SLOT_DURATION_MINUTES} minutes")
+        
+        # Get freebusy information
+        freebusy_response = self.get_freebusy(start, end, calendar_ids)
+        
+        # If multiple calendars, we need to find slots that are free in ALL calendars
+        if len(calendar_ids or [DEFAULT_CALENDAR_ID]) == 1:
+            calendar_id = calendar_ids[0] if calendar_ids else DEFAULT_CALENDAR_ID
+            return freebusy_response.get_free_slots(duration_minutes, calendar_id)
+        else:
+            # For multiple calendars, collect all busy periods from all calendars
+            all_busy_periods = []
+            for calendar_id in (calendar_ids or [DEFAULT_CALENDAR_ID]):
+                all_busy_periods.extend(freebusy_response.get_busy_periods(calendar_id))
+            
+            # Merge overlapping busy periods
+            merged_busy = utils.merge_overlapping_time_slots(all_busy_periods)
+            
+            # Create a temporary response with merged busy periods for the primary calendar
+            temp_response = FreeBusyResponse(
+                start=start,
+                end=end,
+                calendars={DEFAULT_CALENDAR_ID: merged_busy}
+            )
+            
+            return temp_response.get_free_slots(duration_minutes, DEFAULT_CALENDAR_ID)
+