feat: offline support v2

[isekovanic]

🎯 Goal

🛠️ Summary of Changes

📦 SDK Architecture and Offline Persistence Refactor

🧠 Major Restructuring

• Moved all SDK logic and API handling into the LLC (Low-Level Client):
  • Centralizes logic and improves maintainability across platforms.
• Offline DB initialization moved to the LLC abstract class:
  • Can now be initialized before rendering the Chat component.
  • Prevents reinitialization on Chat unmount/remount.
  • Ensures openConnection() is only called once per app session.

💬 Reactions: Rewritten for Consistency and Performance

• Optimistic reaction updates fully reimplemented:
  • Properly respects enforce_unique.
  • Now handled entirely in LLC state (reaction.new, reaction.updated, reaction.removed).
  • Reactions are persisted to the DB (was previously memory-only).
• Fetching and displaying reactions fixed:
  • Fetched optimistically from DB, then updated via HTTP.
  • Removed limit of 10 reactions stored offline.
  • Reaction pagination now supported in offline mode.
  • Updates are batched rather than run synchronously.

🔄 Channel Handling and Sync Reliability

• Channel truncation fixes:
  • Read states are cleared correctly.
  • Messages are removed in efficient batches.
• Faster and more reliable channel guards:
  • Eliminates extra DB query.
  • Prefers event.channel for state updates when available.
• Visibility handling now updates DB rows instead of deleting them.
• Sync API behavior revised:
  • No longer reprocesses events already sent by SDK.
  • Sync errors no longer block the entire SDK.
• Callback scheduling added to sync manager:
  • Enables deferred state updates after sync completion.
  • Replaces unreliable listener-based sync logic.

📋 Channel List and Task Queue Improvements

• ChannelListManager now fully resides in the LLC:
  • Prevents duplicate queryChannels requests (esp. on slower devices).
  • Introduces a scheduling system to control re-queries.
• Pending task queue is now more stable and minimal:
  • Only queues failures — no more insert/remove jitter.
  • Tasks are dropped if retry is not viable (e.g., due to capability errors).
• Safe (detached) write queries introduced:
  • Enables state updates in sync event handlers and non-async contexts.

🚀 New Features

• Offline message sending support added:
  • Failed sends are queued and retried in order upon reconnect.
• Support for channel pinning and archiving.
• Soft and hard deletes now reflected in DB correctly.
• channel.truncated_at is respected and synced.
• Retry and error handling for queryChannels built into channelManager.

---

🧠 Performance and Stability Fixes

• Read query performance improved (getChannels, getChannelsForQuery).
• Member events now correctly update member_count.
• All event handling now routed through LLC’s internal state (not WS listeners).
• Only a single SQLite connection is used throughout:
  • Prevents issues from multi-writer scenarios in op-sqlite.
  • Previously, multiple Chat mounts could trigger multiple DB connections.

---

🛠 Implementation details

🎨 UI Changes

iOS

Before	After

Android

Before	After

🧪 Testing

☑️ Checklist

• I have signed the Stream CLA (required)
• PR targets the develop branch
• Documentation is updated
• New code is tested in main example apps, including all possible scenarios
  • SampleApp iOS and Android
  • Expo iOS and Android

[Stream-SDK-Bot]

SDK Size

title	develop	branch	diff	status
js_bundle_size	466 KB	459 KB	-6759 B	🚀

[khushal87]

Apart from the reviews above on some testing I found out a couple of bugs on my side. Not sure if you will be able to repro it but here are they:

• Even when I have loaded the channels in the channel list after the 1st page(2nd or subsequent pages) when my internet was active, it doesn’t load if I turn off my internet connection and open the app again. I am not able to load the 2nd page. Seems like a bug. Only able to load the first page.
• When your internet is off and you send some message they are in pending state for a long time(I think they should fail asap) after being sent, and when the connection recovers they are not resent instead you see them as a failed message. This is off, because if you are in the app and then you turn off your internet then it is sent as a failed message, but when you restart the app and send a message, it shows pending status for a long time.

[isekovanic]

Thanks for the detailed review @khushal87 !

As discussed offline:

1. This behaviour is by design, due to the fact that it is pointless to load more channels from the offline DB if we're going to overwrite them with the first query anyway. Once we move to indexed channelManagers in the future (and can reliably gather all of them) we can maybe revisit how we handle this, but if we do load more than the offset/limit combination we will either not be watching channels we are supposed to or the pagination will be broken (in terms of never covering those channels under queryChannels with watch: true.
2. Well spotted, both of these issues are fixed in the latest build.

[khushal87]

Overall, it looks fine after the testing. We will see if anything appears in the future and fix it subsequently. Great work @isekovanic 🚀