api: Use batch-based narrow updates for marking messages as read (#820)

[abdallah-9a]

Summary

This PR addresses the server-side timeout issue when marking a large number of messages as read (Issue #820).

Changes

• Implemented update_message_flags_for_narrow to support the modern batch-based endpoint (Feature Level 155+).
• Refactored mark_all_as_read, mark_stream_as_read, and mark_topic_as_read to use a batching logic with last_processed_id as the anchor.
• Added DeprecationWarning to legacy methods to encourage switching to the more reliable narrow-based API.
• Maintained backward compatibility for servers with feature levels below 155.

Testing

• Verified the batching loop logic (1000 messages per batch).
• Checked that the found_newest flag correctly terminates the loop.
• Confirmed that errors in any batch are returned immediately to the caller.

Fixes #820

[abdallah-9a]

I've implemented the batching logic to resolve the timeout issue (#820). However, I'm encountering a conflict in the CI's OpenAPI schema validation:

Some tests expect the legacy response (only result and msg).

Other tests (likely for newer server versions) fail because 'complete' is a required property.

I've tried to provide a compatible response, but the validator still flags 'additional properties' in some environments. I'd appreciate guidance on how to satisfy both schemas in the SDK while maintaining the batching logic. My implementation correctly handles the feature_level >= 155 check.

[abdallah-9a]

Here is the error from the CI that required the 'complete' property:

Traceback (most recent call last):
  ...
  File "/__w/python-zulip-api/python-zulip-api/server/zerver/openapi/openapi.py", line 484, in validate_test_response
    raise SchemaError(message) from None
zerver.openapi.openapi.SchemaError: Response validation error at post /api/v1/mark_all_as_read (200):

InvalidData: InvalidData: Value {'result': 'success', 'msg': ''} not valid for schema of type any: (<ValidationError: "'complete' is a required property">,) ```