flutter_supabase_chat_core 2.0.0
flutter_supabase_chat_core: ^2.0.0 copied to clipboard
Actively maintained, community-driven Supabase BaaS for chat applications with an optional chat UI.
2.0.0 - 2026-10-31 #
@rickypid
Stable release of 2.0.0. Same package code and database as 2.0.0-rc.3
(only the example, documentation and CI dependencies were updated): the
release candidates below list every change since 1.6.2.
⚠️⚠️ Breaking change: Dart API and database schema, see MIGRATION.md ⚠️⚠️
Highlights #
- Built on
flutter_chat_core/flutter_chat_ui2.x:ChatRoom,ChatUserandMessagereplace theflutter_chat_typesmodels. - Redesigned database: uuid ids,
timestamptzdates,chats.room_members, messages partitioned by week, message and room changes over private Realtime Broadcast channels. The same SQL scripts create a fresh database or migrate a 1.x one. SupabaseChatRoomsController(paginated, searchable rooms list with unread counters) and Telegram-like features: read receipts, replies, reactions, editing, pinned messages, forwarding, message search, pinned and muted rooms, group roles, optimistic sending with retry.- Stricter security: RLS and column privileges, database-owned message
metadata, private Realtime channels,
httpSupabaseHeadersFor(url). - Scoping hooks to keep the chats of different workspaces apart, injectable
client,
closeSession()/dispose().
Upgrading #
- From 1.x: follow MIGRATION.md (maintenance window required).
- From
2.0.0-rc.3: update the package, nothing else changes. - From
2.0.0-rc.1/rc.2: re-run the SQL scripts and update the package at the same time, see MIGRATION.md.
Dependencies #
- Example:
file_picker: ^13.1.0,file_saver: ^0.7.0(needs a Flutter stable shippingmeta1.19),open_filex: ^5.0.0,cupertino_icons: ^2.0.0.flutter_chat_uistays pinned to'>=2.11.1 <2.12.0'. - Documentation site: React 19; TypeScript stays on 5.x (the Docusaurus
tsconfigdoesn't support TypeScript 7). - GitHub Actions:
actions/checkout@v7,actions/setup-node@v7,actions/upload-pages-artifact@v5,actions/deploy-pages@v5,supabase/setup-cli@v3.
2.0.0-rc.3 - 2026-10-23 #
@rickypid
Third release candidate of 2.0.0: security fixes from an audit of the
package. Re-run the SQL scripts (01..05, 99, and 06 if you use it)
and update the package together: the Realtime protocol changed, see
MIGRATION.md.
Security #
- A message
sourcecould make thecleanup-mediaEdge Function delete any Storage object of the project (other rooms, avatars, other buckets) with the service role: the media queue only accepts achats_assetsobject in the deleted message's own room folder, not referenced by another message, and the function checks every row again. httpSupabaseHeaderssent the access token to any URL, and the example and the docs attached it to avatars and message sources other users choose:httpSupabaseHeadersFor(url)sends it only to this project's Storage;httpSupabaseHeadersis deprecated.- A member of a direct room could add third parties to it, or turn it into a
group, through unrestricted
UPDATEs ofchats.room_members/chats.rooms:UPDATEis granted per column (rooms: name, image, metadata; members: role; profiles: no globalrole) and role changes are for group admins. - Members could forge message events (fake, edited or hidden messages) on the
room's Realtime channel: only the database sends on
chats:room:<roomId>, the typing indicator moved tochats:room:<roomId>:typing. - Reusing another message's id let a member pin or rewrite reactions of
messages of other rooms, or get an admin deleting their copy to delete the
original too: message ids are unique (
chats.message_ids) and the RPCs update exactly the row they authorized. - Any member can no longer overwrite or delete another member's attachment:
chats_assetsobjects are updated by their uploader, deleted by their uploader or a group admin. - Online status could be faked or watched with the anon key: presence channels are private, any signed-in user may watch, only the owner publishes.
- Room and membership changes travel on a private per-user channel
(
chats:user:<uid>) instead of Postgres Changes, whoseDELETEevents told every subscriber who left which room; a member removed from a room is disconnected from its channels right away. - The forward origin (
forwardedFrom) is attested by the database from the forwarded message instead of being written by the client. - Message time is assigned by the database: a client
createdAtfar from its clock is rejected (a far-future date blocked the partition maintenance and stayed the room's last message), and it can't be changed afterwards. - Authors edit the content of their messages only: status, reactions and pin
change through the RPCs,
updatedAtis set by the database.
Fixed #
- The
partman-run-maintenancecron job always failed (its command shared a transaction block with aSELECT): the procedure runs alone, and a separatechats-messages-partitions-rlsjob plus an event trigger secure newchats.messagespartitions as soon as they are created. cleanup-mediaretries a failing object a few times and then leaves it aside (attempts,lastError) instead of blocking the queue.retryMessageof a message that did reach the server marks it sent.- The example app saves downloaded files under a sanitized name and asks before opening them (documents and media only).
Changed #
- Minimum SDKs raised to
Dart >=3.9.0andFlutter >=3.35.0: thesupabase_flutterversions the package depends on (>=2.16.0) already required Dart 3.9, so the previous minimum couldn't resolve. sendMessageandforwardMessageslet the database setcreatedAt.ChatForwardOrigin.claimbuilds the forward request; the stored origin is read withChatForwardOrigin.ofas before.SupabaseChatCoreConfig.realtimeUserChannelPrefix(chats:user:).chats.roomsandchats.room_membersare no longer in thesupabase_realtimepublication.- CI on GitHub Actions: analysis on the minimum and latest Flutter, pana, unit, database (pgTAP) and integration tests on a local Supabase stack, and the documentation build; publishing to pub.dev from a version tag after a manual approval; Dependabot.
2.0.0-rc.2 - 2026-10-22 #
@rickypid
Second release candidate of 2.0.0: message forwarding and a clean session teardown on sign out. No database changes since rc.1.
Added #
SupabaseChatCore.forwardMessages: forwards messages to another room as new messages of the logged-in user, oldest first. Each copy stores itsChatForwardOrigin(original author and date) in the metadata and drops reply, reactions, pin and edited mark; chat attachments are copied into the destination room's folder.ChatForwardOrigin: reads the origin of a forwarded message (ChatForwardOrigin.of(message)).SupabaseChatCore.closeSession(): closes the own presence, room channels, presence watches and theroomsChanges/room/userOnlineStatusstreams. Call it right before signing out, so private room channels leave cleanly instead of reporting subscription errors.
Changed #
- Signing out or switching user closes the session automatically: the
roomsChanges,roomanduserOnlineStatusstreams complete instead of outliving the user, andSupabaseChatRoomsControllerclears its rooms (the nextloadFirstPagelistens again for the new user). ChatRoomequality compares every field, not only theid: a refetched room is no longer dropped as unchanged by lists andValueNotifiers. Match rooms byidto find the same room.- The example app calls
closeSession()before signing out. - README and documentation site cover forwarding, signing out and the session lifecycle.
Fixed #
- Auth state changes arriving in bursts (initial session, signed in, token refreshed) could open the own presence channel twice.
- Late status callbacks of released room and presence channels changed the state of the current ones.
- Documentation site: "Edit this page" links, and links to the Flyer Chat 2.x documentation instead of 1.x.
2.0.0-rc.1 - 2026-10-21 #
@rickypid
Release candidate of 2.0.0: the API and the database schema are complete, feedback welcome before the stable release.
⚠️⚠️ Breaking change: Dart API and database schema, see MIGRATION.md ⚠️⚠️
Moves the package to flutter_chat_core/flutter_chat_ui 2.x and redesigns
the database. The same SQL scripts create a fresh database or migrate a 1.x
one (maintenance window required).
Breaking changes #
ChatRoom,ChatUserandflutter_chat_core'sMessagereplace theflutter_chat_typesmodels; dates areDateTime, ids are uuid strings.SupabaseChatControllerimplementsflutter_chat_core'sChatController;roomsUpdates()/updateRoomListbecomeroomsChanges()/applyRoomChange.SupabaseChatCoreConfigtakes named parameters;realtimeChatTypingUserPrefixChannelbecomesrealtimeRoomChannelPrefix.- Members are managed with
addMembers/removeMember/leaveRoom/setMemberRoleinstead ofupdateRoom;fetchUserandprocessRoomRow(s)are removed. - Errors are thrown as
SupabaseChatCoreExceptionsubtypes. - Database: uuid ids,
timestamptzdates,chats.room_members, messages partitioned by week (pg_partman+pg_cron), rooms created through thechats.create_roomRPC, message changes over private Realtime Broadcast channels (self-hosted Realtime >= v2.33).
Added #
SupabaseChatRoomsController: paginated, searchable rooms list kept in sync over Realtime, with unread counters.- Telegram-like features: read receipts and unread counts, replies, reactions, editing, pinned messages, message search, pinned and muted rooms, group roles, optimistic sending with retry.
- Scoping hooks on
SupabaseChatCoreConfigto keep the chats of different workspaces apart. - Injectable client (
SupabaseChatCore(client:, config:)) anddispose(). cleanup-mediaEdge Function to delete the files of deleted messages.migrate_storage_uuids.sh/.ps1: moves the 1.x attachments to the new room folders.- Redesigned Telegram-like example app, with voice messages on every platform.
Fixed #
- #38: the typing indicator hit the Realtime Presence rate limit; it now uses Broadcast.
- Web: the online status observer never removed its focus/blur listeners.
- Realtime channels leaked by the online status helpers.
Security #
- Stricter RLS: no self-granted membership, messages sent only as yourself, edits by the author, group management by admins only.
- Private room channels authorized by policies on
realtime.messages. - Policies limited to
authenticated, internal tables and trigger functions closed to clients (clean Supabase advisors).
Dependencies #
flutter_chat_typesreplaced byflutter_chat_core: ^2.9.0.supabase_flutter: ^2.17.2; Dart>=3.8.0, Flutter>=3.32.0.- The example pins
flutter_chat_ui: '>=2.11.1 <2.12.0'(2.12.0 crashes inside a standardScaffold).
1.6.1 - 2026-03-09 #
1.6.0 - 2025-06-17 #
1.4.3 - 2024-12-26 #
@rickypid
@lazy-geek
ℹ️ ℹ️ Recommended scheme migration ℹ️ ℹ️
Improvement documentations.
Fixed #
- Fixed #25 Update chats.update_last_messages trigger to make sure it is only called for actual last message in case of update
- Fixed #27 Error in room or message deletion query, a
limit(1)was incorrectly applied
1.4.1 - 2024-11-21 #
1.4.0 - 2024-11-21 #
1.3.2 - 2024-11-13 #
1.3.0 - 2024-11-04 #
1.2.0 - 2024-10-31 #
1.1.0 - 2024-08-30 #
1.0.0 - 2024-06-19 #
0.10.0 - 2024-04-04 #
@rickypid
Features #
- Added user online status support
- Added room messages pagination, now it's possible load messages on chat scrolling
- Added
SupabaseChatController
Widgets #
- Added
UserOnlineStateObserverwidget - Added
UserOnlineStatusWidgetwidget
Dependencies #
- Removed
diodependency - Upgraded
supabase_flutterto^2.4.0
