[nijeesh-stream]

CLA

• I have signed the Stream CLA (required).
• Code changes are tested

Description of the changes, What, Why and How?

Note

Stacked on #1951 (scheduled messages API layer): merge that first. The backend (CHA-5924) shipped in chat v239.72.0, behind the per-app flag chat_scheduled_messages_enabled (off by default).

TLDR

• Problem: feat: add scheduled messages API #1951 adds the scheduled message endpoints, types and events, but nothing keeps the current user's scheduled messages in memory. Every UI would have to query, track events and handle out-of-order responses itself.
• What/how: A new client.scheduledMessages (ScheduledMessageManager), built like client.reminders. It loads the user's scheduled messages with one query, stays in sync from scheduled_message.* events, is filled from channel responses, and updates itself after its own API calls. UIs read it through state and the selectors.
• Risks: Low. Everything is additive. Event handling only starts when the app calls registerSubscriptions(), and the store is only filled when the app calls load() or passes include_scheduled_messages. Server-side clients (_cacheEnabled() === false) never store anything.

Ticket

• https://linear.app/stream/issue/REACT-1384/llc-scheduled-messages-create-state-layer-scheduledmessagemanager
• Parent: https://linear.app/stream/issue/REACT-1347/add-scheduled-message-support-to-react-chat-sdk
• https://linear.app/stream/issue/CHA-5934

Store: client.scheduledMessages

State (StateStore<ScheduledMessageManagerState>)

Field	Meaning
scheduledMessages	Map<id, ScheduledMessageResponse> of the user's active messages (scheduled, sending, failed)
isLoaded	load() has succeeded at least once
isLoading	A query is running
isDisabled	The last query failed with 114 scheduled_messages_disabled; a later successful load clears it
lastQueryError	Error of the last failed query
next	Cursor for loadMore(); undefined when there is nothing more

Selectors

• getFromState(id)
• getForChannel(cid): messages outside threads, sorted by scheduled_at (ties by id)
• getForThread(parentId): the thread's replies, same order
• getCountForChannel(cid): count of getForChannel(cid) without building the list

Loading

• load(): queries up to 100 and replaces the store.
• Overlapping loads (for example a reload on connection.recovered and one started by the app) run through withCancellation: a newer load aborts the older one, the older result is not applied and resolves to undefined, and only the latest load clears isLoading.
• loadMore(): adds the next page in one store update; does nothing without next or while loading.
• A user can have 100 pending messages plus 7 days of failed ones, so failed messages can need loadMore(). Pending ones always fit in the first page.

Events (registerSubscriptions() / unregisterSubscriptions(), the same opt-in as ReminderManager)

• scheduled_message.created, .updated, .failed: upsert
• scheduled_message.sent, .deleted: remove
• connection.recovered: load() again if the store was loaded

Actions: updateScheduledMessage, deleteScheduledMessage and sendScheduledMessageNow call the client methods and then update the store. If one fails with a 404 (isScheduledMessageNotFoundError, from #1951), the message was already sent or deleted elsewhere and its event never reached this client: the item is removed from the store (and remembered, so a late event cannot bring it back) and the error is rethrown. Any other error leaves the store as it is.

Filled from elsewhere

• channel.sendMessage(message, { scheduled_at }): the response's scheduled_message is upserted. The message is not added to the channel; it arrives later through message.new.
• channel.query({ include_scheduled_messages: true }) and client.queryChannels(..., { include_scheduled_messages: true }): each channel's scheduled_messages replaces that channel's entries. [] empties them. If the field is absent (not requested, feature off, more than 100 across the page), the store is left as it is. queryChannels skips channels listed in stateOptions.skipInitialization, and a snapshot that changes nothing does not notify subscribers.
• disconnectUser() resets the store.

Ordering rules

Responses and events can arrive in any order. Two per-message rules keep the store correct:

1. Newest updated_at wins. An older response or event is ignored, so a send-now response arriving after scheduled_message.failed cannot turn the message back into scheduled. During load() and hydration, a stored version newer than the snapshot's is kept.

2. Sent and canceled are final. A message with status sent or canceled, or one removed by an event or deleteScheduledMessage, is remembered until disconnectUser(). A late response or a snapshot cannot bring it back. Scheduling again always uses a new message.id, so a remembered id never comes back legitimately.

3. Messages stored during a snapshot request are kept. The manager numbers every message it stores (version). load(), channel.query and queryChannels read the version before their request, and the snapshot only replaces messages stored before it, so a message scheduled or received from an event while the request was in flight stays. hydrateChannelState(cid, scheduledMessages, requestedAtVersion?) takes that version.

Known limitations:

• load() drops older failed pages that were fetched with loadMore(); its next cursor lets the UI fetch them again.
• A response that resolves after disconnectUser() is applied to the next session. This needs a request in flight at that exact moment.

Backend contract notes

• A message waiting for a send retry reports status: "sending"; 409 scheduled_message_sending happens exactly then, so UIs can disable actions from the status alone.
• scheduled_message.message.mentioned_users holds user IDs; the SendMessage response's message.mentioned_users holds user objects.
• In a scheduled SendMessage response, message.id is the scheduled message ID and the message is not in the channel. UIs must not insert an optimistic message for a scheduled send.
• A scheduled_at that is already past sends the message now: the response has message and no scheduled_message, and nothing is stored.

Public types

ScheduledMessageManager, ScheduledMessageManagerState, ScheduledMessageManagerOptions, ScheduledMessageEvent. The load limit and the map and query-handler types stay internal.

Tests

• Manager: upsert/remove, finished statuses, remembered removals, cache disabled, selectors (channel, thread, count, tie-break), hydration (present, [], absent, other channels kept), reset on disconnect.
• Events: each event type, retry sending, registration on and off, reload on connection.recovered.
• Loading: replace on load(), loadMore() paging in one update, finished messages skipped, error kept, isDisabled on 114 and cleared on success.
• Ordering: send-now response after .failed, stale .updated, equal updated_at, .sent and .failed while load() is in flight, a message stored while load() / channel.query / a hydration request is in flight is kept, and only the latest of two overlapping loads is applied.
• Hydration: channels in skipInitialization are left alone, and an unchanged snapshot does not notify subscribers.
• Not found: a 404 from each action removes the item, a later event does not bring it back, and other errors keep it.
• Integration: sendMessage with scheduled_at upserts, channel.query and queryChannels hydrate.

Changelog

• Add client.scheduledMessages (ScheduledMessageManager): a store of the current user's scheduled messages, kept in sync from scheduled_message.* events, with load() / loadMore(), getForChannel / getForThread / getCountForChannel, isDisabled, and updateScheduledMessage / deleteScheduledMessage / sendScheduledMessageNow (a 404 removes the item from the store).
• channel.sendMessage with scheduled_at, channel.query and client.queryChannels with include_scheduled_messages now fill client.scheduledMessages.

[NikolaGoranNaumovski]

Looks good with some minor changes.

One thing i would add is that i believe there are a lot of comments with large descriptions. I believe this is unnecessary as the code is self explanatory.