feat: Add FastAPI service and auto-generated client adapter for mail client operations

[gsiri-code]

Pull Request

Summary

This PR introduces two new components to the mail client workspace: a FastAPI service (mail_client_service) and an adapter (mail_client_adapter) that wraps an auto-generated service client. These components enable the mail client to operate as both a local library and a distributed service, maintaining the same interface regardless of deployment topology.

The FastAPI service provides a thin REST wrapper around the existing mail_client_api.Client interface, exposing four RESTful endpoints: GET /messages for listing messages, GET /messages/{message_id} for retrieving specific messages, POST /messages/{message_id}/mark-as-read for marking messages as read, and DELETE /messages/{message_id} for deleting messages. The service uses FastAPI's dependency injection to cleanly separate concerns and includes comprehensive error handling with appropriate HTTP status codes.

The auto-generated service client (mail_client_service_client) is created using the openapi-python-client package, providing type-safe HTTP communication with both sync and async support. The service adapter (mail_client_adapter) implements the mail_client_api.Client protocol, translating service responses to Message objects and providing seamless integration that works identically to the local gmail_client_impl. This architecture enables geographic flexibility - the same consumer code can work with either a local library or a remote service without modification. Swapping gmail_client_impl with mail_client_adapter works seamlessly in main.py, demonstrating the interface consistency across deployment models.

The implementation includes comprehensive testing infrastructure with unit tests for FastAPI endpoints using mocked dependencies, integration tests that verify end-to-end service calls through the adapter layer, and end-to-end tests that validate the complete system against the real Gmail API. The testing strategy uses FastAPI's TestClient for unit testing, mocks the Gmail client for integration testing, and runs against live infrastructure for E2E validation, ensuring robust coverage across all deployment scenarios.

Change Type

• 🐛 Bug fix
• ✨ Feature / enhancement
• 💥 Breaking change
• 📚 Documentation
• 🔧 Refactor / cleanup
• ⚡ Performance
• 🧪 Test improvement
• 🔨 Build / tooling

Impacted Areas

• mail_client_service
• mail_client_service_client
• mail_client_adapter
• Documentation
• Tests
• Tooling / CI
• mail_client_api
• gmail_client_impl
• Other (describe in summary)

Testing

Commands executed

# Install test dependencies
uv sync --extra test

# Run unit tests
uv run pytest src/mail_client_service
uv run pytest src/mail_client_adapter

# Run Integration and CI tests 
uv run pytest -m integration
uv run pytest -m e2e 
uv run pytest -m circleci 

Results

• Tests pass
• Type checks clean
• Linting clean
• Manual verification (if applicable)

Quality Checklist

• Contract boundaries respected; abstractions unchanged unless noted
• Backward compatibility confirmed or migration documented
• Security / secrets handled correctly
• Performance impact acceptable
• Docs updated for user-facing changes

Notes for Reviewers

We have verified that swapping the adapter for the original gmail client implementation in main.py works. Please give it a try!