[CHA-5933] feat: add scheduled messages

[nijeesh-stream]

Submit a pull request

CLA

• I have signed the Stream CLA (required).
• The code changes follow best practices
• Code changes are tested (add some information if not applicable)

Description of the pull request

TLDR

Lets a backend schedule a chat message to be sent later on behalf of a user, and then edit, cancel, send now or list those scheduled messages. Adds SDK methods only (sync and async). Existing behavior is unchanged unless scheduled_at is passed.

Risk: if scheduled_at is sent to a backend that does not know it yet, the backend ignores the field and sends the message immediately. The response then has no scheduled_message, which is how callers (and the integration tests) can tell.

Backend endpoints are behind a per-app flag and not yet released; merge after backend CHA-5924 ships.

Ticket

• https://linear.app/stream/issue/CHA-5933

What's added

• Channel.send_message(..., scheduled_at=datetime | str): a datetime is converted to UTC ISO 8601 (naive datetimes are taken as UTC). The response then carries scheduled_message.
• update_scheduled_message(scheduled_message_id, message=None, scheduled_at=None) → PATCH /scheduled_messages/{id} (at least one of the two is required).
• delete_scheduled_message(scheduled_message_id) → DELETE /scheduled_messages/{id} (cancel, or remove a failed one).
• send_scheduled_message_now(scheduled_message_id) → POST /scheduled_messages/{id}/send_now.
• query_scheduled_messages(user_id, filter=None, sort=None, options=None) → POST /scheduled_messages/query, mirroring query_drafts (filter by cid and status; sort scheduled_at ascending only; limit 1-100; next cursor).
• Types in stream_chat/types/scheduled_messages.py: QueryScheduledMessagesFilter, QueryScheduledMessagesOptions, ScheduledMessageStatus.
• Docs: docs/messages/scheduled_messages.md (includes the scheduled_message.* events; this SDK does not model event types).

Not added: include_scheduled_messages on channel query. The backend ignores it on server-side requests, so it has no effect from this SDK. App settings for the feature are not exposed by the app settings API.

Tests

• test_scheduled_messages_unit.py: mock-based tests (like test_channel_delete.py) for the request each new call sends, sync and async, plus datetime formatting.
• test_scheduled_messages.py and async_chat/test_scheduled_messages.py: integration tests (schedule → query → update → delete, and send now). They skip when the app does not have scheduled messages enabled (scheduled_messages_disabled) or the API does not return scheduled_message. The flag is set per app by Stream and is not in the app settings API, so the CI app cannot be baselined into it. Against a local backend with the flag off, they skip as intended.
• black, flake8, mypy clean on the changed files. CHANGELOG is generated at release time, so it is not edited here.

🤖 Generated with Claude Code