Synchronize unread message status with Webex server

[sgrimee]

Summary

Implement true server-synchronized unread message tracking instead of the current session-based approach. Messages should be marked as unread based on server state, not just since program launch.

Current Problem

• Unread messages currently mean "received after program launch"
• No synchronization with actual read status on Webex servers
• Messages read in other clients still show as unread in webex-tui

Research Required

• Investigate Webex API for read status events and endpoints
• Determine if webex-rust crate supports read status tracking
• Research how to mark messages/spaces as read on server
• Understand initial state retrieval for message read status
• Test read status synchronization with other Webex clients

Implementation Requirements

Server Read Status Events

• Receive events when spaces/messages are marked as read
• Send events when user reads messages in webex-tui
• Handle read status for individual messages vs entire conversations

Initialization Behavior

• Query server for current read status of all messages/rooms
• Distinguish between read and unread messages on startup
• Handle large message histories efficiently

Synchronization

• Real-time updates when messages are read in other clients
• Mark messages as read on server when viewed in webex-tui
• Handle offline/online synchronization scenarios

Dependencies

• May require extending webex-rust crate with read status APIs
• Related to issues Highlight unread messages in room view #79 and Display number of unread messages in room list #91 (message highlighting and unread counts)

Acceptance Criteria

• Unread status matches server state on program startup
• Reading messages in webex-tui marks them as read on server
• Messages read in other clients update status in webex-tui
• Read status events are properly handled and processed
• Performance acceptable with large message histories

🤖 Generated with Claude Code

[sgrimee]

Investigation Complete: Unread Detection Blocked by Webex API Limitation

Summary

After extensive investigation and implementation attempts, the unread room filter feature cannot be implemented reliably due to a fundamental Webex API limitation.

Bugs Fixed During Investigation

1. Infinite recursion in cb_message_received() causing stack overflow ✅ FIXED
2. Incomplete data loading - only fetching first 100 rooms instead of up to 1000 ✅ FIXED
3. Iterator chain overflow - visible_rooms() returning Box<dyn Iterator> ✅ FIXED
4. Unread status overwrite during room updates ✅ FIXED

Critical API Limitation Discovered

Root Cause: The last_seen_id field in membership data is only populated when using the REST API's mark-as-read endpoint. It is NOT populated when reading messages in the official Webex client.

Evidence from Testing:

• Fetched 999 memberships, 523 rooms marked as unread
• All "read" rooms had last_seen_id = None, even recently opened ones
• Rooms clearly read in official client showed as unread in our implementation

Community Confirmation:

• Cisco Community Forum: "There is no official supported method to get unread messages via the API"
• Multiple developers report same issue: last_seen_id remains null even after reading in official client

Impact

• Cannot distinguish read vs unread rooms using REST API alone
• Any implementation shows false positives (read rooms appear unread)
• No synchronization with official client possible

Files Modified

• webex-tui/src/teams/app_handler.rs - Room loading and unread detection logic
• webex-tui/src/app/cache/rooms.rs - Added update_with_room_and_unread()
• webex-tui/src/app/callbacks.rs - Fixed infinite recursion, restored message handling
• webex-tui/src/app/state.rs - Changed visible_rooms() to return Vec
• webex-rust/src/types.rs - Added ReadStatus::from_room_and_membership()

Documentation Updated

• webex-tui/spec/unread-detection.md - Added CRITICAL LIMITATION section

Recommendation

Close this issue as "Blocked by Webex API Limitation"

The feature cannot be implemented without API changes from Cisco. Possible workarounds exist but would not synchronize with the official client:

1. Local persistence using WebSocket events (would drift from official client)
2. Heuristic approach based on activity timestamps (unreliable)

The implementation code is preserved in the spec and codebase for future reference if the API is enhanced.

[sgrimee]

API Testing Complete: Mark-as-Read Endpoint Is Non-Functional

Test Results

Created a test script to verify if the Webex REST API's mark-as-read functionality works. The test:

1. Fetches a room's membership (initial last_seen_id)
2. Calls PUT /memberships/{id} with lastSeenId set to latest message
3. Fetches the membership again to verify the update

Results:

Found room: "Jacob Tate" (direct room)
Initial last_seen_id: None
Latest message ID: Y2lzY29zcGFyazovL3VzL01FU1NBR0UvN2FjMGMzMDAtYzNkYy0xMWYwLWJjYWEtY2Y0MTEzYjhhOTY1
✓ mark_message_as_read() succeeded (200 OK)
After mark read, last_seen_id: None  ❌

Found room: "Koree-Ullie-Sam" (group room)
Initial last_seen_id: None
Latest message ID: Y2lzY29zcGFyazovL3VzL01FU1NBR0UvMWJkNmMyZTAtYzBhZC0xMWYwLWFlZTYtZGRlY2UxNmJjNmYx
✓ mark_message_as_read() succeeded (200 OK)
After mark read, last_seen_id: None  ❌

Critical Finding

The Webex REST API's mark-as-read endpoint is non-functional:

• ✅ The PUT /memberships/{id} request succeeds (200 OK)
• ❌ The server does NOT update the lastSeenId field
• ❌ Affects both direct (1:1) and group rooms
• ❌ Field remains None even after waiting for server processing

API Limitation Confirmed

This is a confirmed Webex API bug/limitation:

1. Official client doesn't populate last_seen_id when reading messages
2. REST API accepts mark-as-read requests but doesn't update the field
3. No way to reliably determine read status via REST API

Alternative: Local Persistence

webex-tui already has local read status tracking:

• File: ~/Library/Caches/webex-tui/read_status.json (macOS)
• File: ~/.cache/webex-tui/read_status.json (Linux)
• Tracks read/unread state independently of Webex API

This local tracking works but:

• Does NOT sync with official Webex client
• Resets if cache is cleared
• Only tracks status within webex-tui

Recommendation

Closing this issue as "Cannot Fix - Blocked by Webex API Bug"

The unread detection feature cannot be implemented because:

1. The Webex REST API's lastSeenId field is non-functional
2. No alternative API exists to determine read status
3. Local tracking exists but doesn't sync with official client

This is a Webex platform limitation that cannot be worked around.

Test Code

Test script created at: webex-tui/src/bin/test_mark_read.rs
Unit test added at: webex-rust/src/lib.rs::test_mark_message_as_read

Run with: WEBEX_TOKEN=xxx ROOM_NAME="Room Name" cargo run --bin test_mark_read

[sgrimee]

Closing as Cannot Fix - Blocked by Webex API Bug. The REST API's lastSeenId field is non-functional and cannot be used for unread detection.