Hostaway MCP Server

# Feature Specification: Guest Communication & Enhanced Error Handling (v1.1) **Feature Branch**: `002-enhance-the-hostaway` **Created**: 2025-10-13 **Status**: Draft **Input**: User description: "Enhance the Hostaway MCP Server with guest communication capabilities and improved error handling. The system should allow AI agents to search messages from multiple channels and retrieve conversation history. Implement partial failure handling for batch operations, allowing graceful degradation when some operations succeed while others fail. Increase test coverage from 72.80% to 80% by adding edge case and error path tests." ## User Scenarios & Testing *(mandatory)* ### User Story 1 - Guest Message Search & History (Priority: P1) AI agents need to access guest communication history to provide context-aware support and respond to inquiries with full knowledge of previous interactions across all communication channels. **Why this priority**: Guest communication is the primary deferred feature from v1.0 (User Story 4). Property managers rely on message history to understand guest context, resolve issues, and provide personalized service. Without this capability, AI agents cannot effectively support guest communication workflows. **Independent Test**: AI agent can search messages by guest name, booking ID, or date range across all channels (email, SMS, in-app) and retrieve complete conversation history with proper chronological ordering and channel identification. **Acceptance Scenarios**: 1. **Given** an AI agent is authenticated, **When** it searches for messages by booking ID 12345, **Then** the system returns all messages associated with that booking across all channels in chronological order 2. **Given** an AI agent is authenticated, **When** it requests conversation history for a specific guest, **Then** the system returns complete message thread with timestamps, channel types, and message content 3. **Given** an AI agent is authenticated, **When** it searches messages from the last 7 days, **Then** the system returns all recent communications filtered by date range 4. **Given** a guest has communicated via email and SMS, **When** AI agent retrieves the conversation, **Then** messages from both channels are consolidated into a unified timeline 5. **Given** multiple guests exist with similar names, **When** AI agent searches by partial name match, **Then** the system returns distinct results with disambiguation (booking IDs, dates, property names) --- ### User Story 2 - Partial Failure Resilience (Priority: P2) When AI agents perform batch operations (e.g., updating multiple bookings, processing multiple properties), the system should gracefully handle mixed success/failure scenarios rather than failing entirely, allowing successful operations to complete while clearly reporting failures. **Why this priority**: Production systems encounter partial failures regularly (network timeouts, rate limits, data validation errors). Current implementation lacks graceful degradation, causing entire batch operations to fail when a single item has an issue. This impacts user experience and operational efficiency. **Independent Test**: AI agent performs a batch operation to retrieve details for 10 properties where 2 properties have invalid IDs. System returns successful results for 8 valid properties while clearly reporting the 2 failures with specific error details, without rolling back successful operations. **Acceptance Scenarios**: 1. **Given** an AI agent requests data for 10 booking IDs where 2 IDs are invalid, **When** the batch operation executes, **Then** the system returns 8 successful results and 2 failure records with specific error messages 2. **Given** an AI agent performs multiple API calls where 1 call hits a rate limit, **When** the operation proceeds, **Then** successful calls complete normally while the rate-limited call is retried or reported as a failure 3. **Given** a batch operation includes items with different failure types (not found, unauthorized, validation error), **When** the operation completes, **Then** the response categorizes failures by type with actionable error messages 4. **Given** a partial failure occurs during message retrieval, **When** the system responds, **Then** successfully retrieved messages are returned alongside clear failure indicators for unavailable messages 5. **Given** a network timeout occurs during batch processing, **When** the timeout affects 3 of 10 items, **Then** the system returns results for completed items and indicates timeout status for affected items --- ### User Story 3 - Enhanced Test Coverage (Priority: P3) Development team needs comprehensive test coverage for edge cases and error paths to ensure system reliability, reduce production bugs, and maintain code quality standards set in the project constitution (80% minimum coverage). **Why this priority**: Current test coverage is 72.80%, below the constitutional requirement of 80%. Core logic is well-tested (>90%), but edge cases and error paths lack coverage. Increasing coverage reduces regression risk and improves confidence in future changes. **Independent Test**: Test suite achieves ≥80% overall coverage with specific focus on edge cases (boundary conditions, empty results, malformed data) and error paths (authentication failures, API errors, network issues). Coverage report shows improvement from 72.80% to ≥80% across all modules. **Acceptance Scenarios**: 1. **Given** the test suite runs, **When** coverage is measured, **Then** overall coverage is ≥80% across all source modules 2. **Given** edge case tests are added, **When** boundary conditions are tested (empty lists, null values, maximum limits), **Then** all edge cases have explicit test coverage 3. **Given** error path tests are implemented, **When** authentication failures, API errors, and network timeouts are simulated, **Then** error handling code paths achieve ≥80% coverage 4. **Given** the v1.1 feature set is complete, **When** integration tests run, **Then** new guest communication and partial failure features have ≥90% test coverage 5. **Given** tests are executed in CI/CD pipeline, **When** coverage thresholds are checked, **Then** build fails if coverage drops below 80% --- ### Edge Cases - What happens when a guest has no message history (new booking, no prior communication)? - How does the system handle messages with special characters, emojis, or non-UTF8 encoding? - What occurs when searching for messages during an active Hostaway API outage? - How does partial failure handling behave when ALL items in a batch fail (edge case of complete failure)? - What happens when message search returns more results than system memory can handle (pagination limits)? - How does the system respond to concurrent batch operations that may partially overlap? - What occurs when a batch operation is interrupted mid-execution (server restart, network failure)? - How are orphaned messages handled (messages without associated booking IDs)? - What happens when message timestamps are out of order or missing? - How does the system handle rate limits during batch message retrieval across channels? ## Requirements *(mandatory)* ### Functional Requirements - **FR-001**: System MUST allow AI agents to search messages by booking ID, returning all associated communications across all channels - **FR-002**: System MUST allow AI agents to search messages by guest name with support for partial matching - **FR-003**: System MUST allow AI agents to filter messages by date range (start date, end date) - **FR-004**: System MUST retrieve complete conversation history for a booking, ordered chronologically - **FR-005**: System MUST identify and label the communication channel for each message (email, SMS, in-app, platform messaging) - **FR-006**: System MUST consolidate messages from multiple channels into a unified conversation timeline - **FR-007**: System MUST handle batch operations with partial failures, returning successful results alongside failure details - **FR-008**: System MUST provide structured error responses for failed batch items, including error type, message, and item identifier - **FR-009**: System MUST continue processing remaining batch items when individual items fail (no cascade failures) - **FR-010**: System MUST track and report partial success metrics (e.g., "8 of 10 succeeded, 2 failed") - **FR-011**: System MUST categorize batch failures by type (not found, validation error, rate limit, timeout, unauthorized) - **FR-012**: System MUST maintain test coverage ≥80% across all source modules - **FR-013**: System MUST include edge case tests for boundary conditions (empty results, null values, maximum limits) - **FR-014**: System MUST include error path tests for authentication failures, API errors, and network timeouts - **FR-015**: System MUST include integration tests for guest communication and partial failure handling features - **FR-016**: System MUST preserve message metadata (timestamp, sender/recipient, channel, delivery status) when retrieving conversation history - **FR-017**: System MUST handle pagination for large message result sets (>100 messages) - **FR-018**: System MUST distinguish between system-sent and guest-sent messages in conversation history ### Key Entities - **Message**: Represents a single communication between system/property manager and guest. Includes content, timestamp, channel type, sender/recipient identifiers, delivery status, and associated booking ID. - **ConversationThread**: Collection of messages associated with a specific booking, ordered chronologically. Aggregates messages from multiple channels into a unified timeline. - **PartialFailureResponse**: Structure for batch operation results. Contains successful results array, failed items array with error details, and summary metrics (total attempted, succeeded, failed). - **BatchItem**: Individual item within a batch operation. Includes item identifier, operation type, success/failure status, result data (if successful), or error details (if failed). - **MessageSearchCriteria**: Filter parameters for message queries. Includes booking ID, guest name, date range, channel types, and pagination settings. ## Success Criteria *(mandatory)* ### Measurable Outcomes - **SC-001**: AI agents can retrieve complete guest conversation history in under 2 seconds for bookings with up to 100 messages - **SC-002**: Message search returns accurate results with 100% precision for booking ID lookups and ≥95% accuracy for partial name matching - **SC-003**: Batch operations with partial failures complete successfully, returning results for successful items within 5 seconds for batches of up to 50 items - **SC-004**: System maintains 99.9% uptime for message retrieval operations (excluding upstream Hostaway API failures) - **SC-005**: Test coverage increases from 72.80% to ≥80% across all modules, with ≥90% coverage for new v1.1 features - **SC-006**: Partial failure handling reduces complete operation failures by 80% compared to v1.0 (measured by successful partial completions vs. total failures) - **SC-007**: Message consolidation correctly merges multi-channel conversations with 100% accuracy (all messages present, correct chronological order) - **SC-008**: Error reporting for batch failures provides actionable information in 100% of failure cases (error type, affected item, remediation guidance) - **SC-009**: Property managers using AI agents report ≥90% satisfaction with guest communication history accuracy and completeness - **SC-010**: System handles concurrent batch operations without data corruption or race conditions (verified through load testing with 50 concurrent batches) ## Assumptions *(optional but recommended)* ### Technical Assumptions - Hostaway API provides message retrieval endpoints for all communication channels (email, SMS, in-app, platform messaging) - Hostaway API supports pagination for message queries (limit/offset or cursor-based) - Message data from Hostaway includes consistent metadata structure across channels (timestamp, sender, recipient, content, status) - Existing authentication and rate limiting mechanisms from v1.0 are sufficient for message retrieval operations - Current connection pooling and retry logic can handle increased API call volume from batch operations ### Business Assumptions - Property managers need historical context from guest communications to provide quality service - Partial failure handling is more valuable than all-or-nothing batch operations for operational workflows - Test coverage improvement does not require additional development resources beyond current team capacity - Guest privacy regulations (GDPR, CCPA) allow retrieval and display of historical communications for service purposes - Message retention policies from Hostaway align with property management operational needs (minimum 90 days retention) ### Data Assumptions - Message content is stored in UTF-8 format with support for special characters and emojis - Conversation threads are logically associated with booking IDs (no orphaned messages) - Message timestamps are reliable and timezone-aware (UTC or property timezone) - Channel identification is consistently provided by Hostaway API (no ambiguous channel types) - Deleted or archived messages are either inaccessible or clearly marked as unavailable ## Dependencies *(optional but recommended)* ### External Dependencies - **Hostaway Messages API**: New endpoint integration required for message retrieval and search. Dependency on Hostaway API documentation and endpoint availability. - **Hostaway Multi-Channel Support**: Assumes Hostaway provides unified access to messages across email, SMS, in-app, and platform channels. If separate APIs exist per channel, integration complexity increases. ### Internal Dependencies - **v1.0 Authentication System**: Guest communication features depend on existing OAuth 2.0 token management and authentication flow - **v1.0 Rate Limiting**: Partial failure handling integrates with existing rate limiter to handle batch operation throttling - **v1.0 Error Handling**: Enhanced error responses build upon existing HTTP exception framework - **Test Infrastructure**: Coverage improvements require existing pytest, pytest-cov, and CI/CD pipeline configuration ### Blocking Dependencies - **Test Environment Access**: User Story 1 (Guest Communication) requires access to Hostaway test/sandbox environment with sample message data. If unavailable, development must use mocked data or production access with strict privacy controls. - **Hostaway API Documentation**: Complete and accurate documentation for message-related endpoints is critical for implementation. Incomplete docs will block development. ## Out of Scope *(optional but recommended)* ### Explicitly Excluded - **Message Sending**: v1.1 focuses on message retrieval and history. Sending messages to guests (email, SMS) is deferred to v1.2. Rationale: Retrieval is prerequisite for context-aware sending. - **Real-Time Message Notifications**: Push notifications or webhooks for new guest messages are out of scope. System provides on-demand retrieval only. Rationale: Polling or webhook infrastructure adds complexity beyond v1.1 scope. - **Message Translation**: Multi-language translation of guest messages is excluded. Messages are displayed in original language. Rationale: Translation requires third-party services and is a separate feature. - **Message Analytics**: Sentiment analysis, message categorization, or communication metrics are not included. Rationale: Analytics layer is a future enhancement beyond core messaging functionality. - **Advanced Search**: Full-text search, keyword matching, or semantic search within message content is excluded. Search limited to booking ID, guest name, and date filters. Rationale: Full-text search requires additional indexing infrastructure. ### Deferred to Future Releases - **Message Templates** (v1.2): Pre-defined message templates for common scenarios (check-in instructions, checkout reminders) to enable message sending - **Guest Preferences** (v1.2): Tracking guest communication preferences (preferred channel, do-not-disturb times) - **Conversation Insights** (v1.3): AI-powered insights from conversation history (common issues, satisfaction indicators) - **Multi-Property Search** (v1.3): Cross-property message search for property managers with multiple listings - **Message Archival** (v1.4): Long-term archival and retrieval of historical messages beyond Hostaway's retention period ## Risks & Mitigations *(optional but recommended)* ### Technical Risks | Risk | Likelihood | Impact | Mitigation | |------|------------|--------|------------| | Hostaway API lacks comprehensive message endpoints | Medium | High | Early API discovery phase: validate endpoint availability before implementation. If gaps exist, document limitations and implement workarounds (e.g., channel-specific endpoints). | | Message volume exceeds pagination limits | Medium | Medium | Implement cursor-based pagination if available, or chunked retrieval with progress tracking. Set maximum result limits (e.g., 1000 messages per query) with clear user messaging. | | Partial failure logic introduces complexity and bugs | Medium | Medium | Extensive unit and integration testing for all failure scenarios. Implement feature flag for gradual rollout with rollback capability. | | Test coverage target not achievable in v1.1 timeline | Low | Medium | Prioritize coverage for new features (90%+) and critical paths. Defer non-critical edge cases to v1.2 if necessary. Track coverage trend rather than absolute target. | | Multi-channel message consolidation has edge cases | Medium | Medium | Define clear rules for edge cases (missing timestamps → use retrieval order, duplicate messages → dedupe by message ID). Comprehensive integration testing with multi-channel data. | ### Operational Risks | Risk | Likelihood | Impact | Mitigation | |------|------------|--------|------------| | Increased API call volume triggers rate limits | High | Medium | Leverage existing rate limiter with enhanced retry logic. Implement request batching where possible. Monitor API usage metrics and alert on threshold approach. | | Guest privacy concerns with message history access | Low | High | Implement audit logging for all message retrievals. Ensure compliance with GDPR/CCPA data access policies. Provide property managers with privacy controls. | | Performance degradation with large conversation histories | Medium | Medium | Implement result caching for frequently accessed conversations. Set pagination defaults (50 messages per page). Optimize database queries for message retrieval. | | Incomplete error information in partial failures | Medium | Low | Standardize error response structure with required fields (error code, message, item ID, remediation). Test all failure scenarios for error completeness. | ## Notes *(optional)* ### v1.0 to v1.1 Migration This specification builds upon v1.0 production deployment. Key v1.0 features that v1.1 extends: - **Authentication (v1.0 US1)**: OAuth 2.0 flow reused for message retrieval authorization - **Property & Booking Data (v1.0 US2-US3)**: Booking IDs from v1.0 are primary keys for message association - **Error Handling (v1.0)**: Existing HTTP exception framework extended with partial failure responses - **Rate Limiting (v1.0)**: Dual rate limiting (IP + account) applies to message retrieval and batch operations ### Design Principles for v1.1 1. **Backward Compatibility**: All v1.0 functionality remains unchanged. v1.1 is purely additive. 2. **Graceful Degradation**: Partial failure handling applies to new and existing batch operations (property lists, booking searches). 3. **Privacy-First**: Message retrieval includes audit trails. No message content stored locally; all fetched on-demand from Hostaway. 4. **Test-Driven**: 80% coverage target enforced by CI/CD. New features require tests before implementation (TDD). 5. **Performance-Aware**: Message retrieval optimized for <2s response times. Pagination required for >100 messages. ### Success Metrics Tracking - **Coverage Baseline**: v1.0 = 72.80%. Target: v1.1 ≥80%. Measured by pytest-cov in CI/CD pipeline. - **Partial Failure Reduction**: v1.0 = 0% partial success (all-or-nothing). Target: v1.1 = 80% reduction in complete failures. - **Message Retrieval Performance**: Target <2s for 100 messages. Monitored via application performance monitoring (APM). - **User Satisfaction**: Property manager feedback collected via post-deployment survey. Target ≥90% satisfaction with message history.