feat: Add spec-based mocking for API client interface

[timothyfroehlich]

Summary

Complete the mock framework by adding proper spec validation for API client interfaces.

Background

The current mock factory framework (PR #53) provides excellent spec-based mocking for most components, but API client mocking still uses basic AsyncMock() without interface validation.

Current State

File: tests/utils/mock_factories.py:96

def create_api_client_mock() -> AsyncMock:
    # For now, use basic AsyncMock since we don't have a specific API client interface
    # TODO: Add specific spec when API client interface is formalized

Proposed Solution

1. Formalize API Client Interface

• Define formal interface class for API clients (e.g., APIClient protocol)
• Standardize method signatures across pinballmap and geocoding clients
• Document expected return types and error handling

2. Update Mock Factory

• Replace basic AsyncMock() with AsyncMock(spec=APIClient)
• Add interface validation to prevent method signature violations
• Include usage examples in docstring

3. Validation

• Ensure all existing API client usage conforms to new interface
• Add tests to verify spec enforcement catches violations
• Update any non-conforming client implementations

Benefits

• Early Error Detection: Catch API interface changes at test time
• Consistent Interface: Standardized API client behavior across codebase
• Complete Coverage: Finish the spec-based mock framework implementation
• Maintainability: Clear contracts for future API client implementations

Acceptance Criteria

• Define APIClient protocol with standardized methods
• Update create_api_client_mock() to use proper spec
• Verify all existing API client code conforms to interface
• Add validation tests for spec enforcement
• Update documentation with usage examples

Related

• Part of spec-based mock framework from PR feat: Complete test framework refactor with authentic fixtures and spec-based mocks #53
• Completes TODO comment identified in code review