refactor: define interfaces for Google API clients (#58)

Add interface definitions for Gmail, Calendar, and Contacts clients
to enable unit testing through mock implementations.

- GmailClientInterface: GetMessage, SearchMessages, GetThread, FetchLabels,
  GetLabelName, GetLabels, GetAttachments, DownloadAttachment, DownloadInlineAttachment
- CalendarClientInterface: ListCalendars, ListEvents, GetEvent
- ContactsClientInterface: ListContacts, SearchContacts, GetContact, ListContactGroups

Each interface includes compile-time verification that the concrete Client
type implements it.

Closes #35

Author: rianjs

internal/calendar/interfaces.go

@@ -0,0 +1,21 @@
+package calendar
+
+import (
+	"google.golang.org/api/calendar/v3"
+)
+
+// CalendarClientInterface defines the interface for Calendar client operations.
+// This enables unit testing through mock implementations.
+type CalendarClientInterface interface {
+	// ListCalendars returns all calendars the user has access to
+	ListCalendars() ([]*calendar.CalendarListEntry, error)
+
+	// ListEvents returns events from the specified calendar within the given time range
+	ListEvents(calendarID string, timeMin, timeMax string, maxResults int64) ([]*calendar.Event, error)
+
+	// GetEvent retrieves a single event by ID
+	GetEvent(calendarID, eventID string) (*calendar.Event, error)
+}
+
+// Verify that Client implements CalendarClientInterface
+var _ CalendarClientInterface = (*Client)(nil)

internal/contacts/interfaces.go

@@ -0,0 +1,24 @@
+package contacts
+
+import (
+	"google.golang.org/api/people/v1"
+)
+
+// ContactsClientInterface defines the interface for Contacts client operations.
+// This enables unit testing through mock implementations.
+type ContactsClientInterface interface {
+	// ListContacts retrieves contacts from the user's account
+	ListContacts(pageToken string, pageSize int64) (*people.ListConnectionsResponse, error)
+
+	// SearchContacts searches for contacts matching a query
+	SearchContacts(query string, pageSize int64) (*people.SearchResponse, error)
+
+	// GetContact retrieves a specific contact by resource name
+	GetContact(resourceName string) (*people.Person, error)
+
+	// ListContactGroups retrieves all contact groups
+	ListContactGroups(pageToken string, pageSize int64) (*people.ListContactGroupsResponse, error)
+}
+
+// Verify that Client implements ContactsClientInterface
+var _ ContactsClientInterface = (*Client)(nil)

internal/gmail/interfaces.go

@@ -0,0 +1,39 @@
+package gmail
+
+import (
+	"google.golang.org/api/gmail/v1"
+)
+
+// GmailClientInterface defines the interface for Gmail client operations.
+// This enables unit testing through mock implementations.
+type GmailClientInterface interface {
+	// GetMessage retrieves a single message by ID
+	GetMessage(messageID string, includeBody bool) (*Message, error)
+
+	// SearchMessages searches for messages matching the query
+	SearchMessages(query string, maxResults int64) ([]*Message, int, error)
+
+	// GetThread retrieves all messages in a thread
+	GetThread(id string) ([]*Message, error)
+
+	// FetchLabels retrieves and caches all labels from the Gmail account
+	FetchLabels() error
+
+	// GetLabelName resolves a label ID to its display name
+	GetLabelName(labelID string) string
+
+	// GetLabels returns all cached labels
+	GetLabels() []*gmail.Label
+
+	// GetAttachments retrieves attachment metadata for a message
+	GetAttachments(messageID string) ([]*Attachment, error)
+
+	// DownloadAttachment downloads a single attachment by message ID and attachment ID
+	DownloadAttachment(messageID string, attachmentID string) ([]byte, error)
+
+	// DownloadInlineAttachment downloads an attachment that has inline data
+	DownloadInlineAttachment(messageID string, partID string) ([]byte, error)
+}
+
+// Verify that Client implements GmailClientInterface
+var _ GmailClientInterface = (*Client)(nil)