noma_chat 0.9.1

Plug & play Flutter chat: SDK with REST + real-time client, offline Hive cache, UI adapter and a ready-to-use UI Kit for the Noma chat backend.

noma_chat

Full-featured Flutter chat in one dependency. Drop it in, wire five lines, ship.

[Two users chatting in real time with reactions]

---

What you get

Layer	What's included
SDK	REST client · WebSocket / SSE / polling with auto-failover · auth · retry · circuit breaker · offline queue
Cache	Persistent Hive CE storage — messages, rooms and receipts survive cold restarts
UI Kit	30+ production-ready widgets: bubbles, voice messages, reactions, mentions, threads, group flows, search

---

Quick start

# pubspec.yaml
dependencies:
  noma_chat: ^0.9.0

import 'package:noma_chat/noma_chat.dart';

final chat = await NomaChat.create(
  baseUrl: 'https://chat.myapp.com/v1',
  realtimeUrl: 'https://chat.myapp.com',
  tokenProvider: () => authService.getToken(),
  currentUser: ChatUser(id: userId, displayName: name),
);
await chat.connect();

Drop the UI into your widget tree:

// Full chat screen
ChatView(controller: ChatController(chat: chat, roomId: roomId))

// Room list
RoomListView(controller: RoomListController(chat: chat))

---

Screenshots

[Room list with unread badges]    [Chat with reactions and mentions]    [Voice recorder with lock gesture]    [Group info and member management]

---

Features at a glance

SDK

• Real-time: WebSocket → SSE → polling, automatic failover between transports
• Circuit breaker + exponential backoff + offline message queue
• Token rotation without reconnecting
• 8 sub-APIs: auth, users, rooms, members, messages, contacts, presence, attachments

UI Kit — messages

• Text, image, audio, video, file and link-preview bubbles
• Voice recording with lock-to-record gesture
• Emoji reactions + reaction picker
• @mentions with autocomplete overlay
• Threaded replies
• Per-user read receipts (DM any-read → blue; group all-read → blue)
• Typing indicators
• Forward to multiple rooms
• Pinned messages banner
• Message search

UI Kit — rooms & people

• Room list with unread badges, mute, pin and hide
• WhatsApp-style DM flow (lazy room creation before first message)
• Block / unblock (blocker syncs list; blocked user is never notified)
• Group creation, name + avatar edit, member add / remove / promote
• Profile and avatar management with built-in crop flow
• Media gallery page
• Quick replies bar
• Invitation accept / reject callbacks

Theme & l10n

• ChatTheme with 155+ fields
• ChatTheme.branded(accent:) — derives ~12 accent slots from one colour
• Light / dark presets, high-contrast WCAG-AAA mode
• 7 locales out of the box: en, es, fr, de, it, pt, ca

---

Theming

One line to match your brand:

theme: ChatTheme.branded(
  accent: Colors.indigo,
  contrastingOnAccent: Colors.white,
)

Or full control:

theme: ChatTheme(
  bubble: ChatBubbleTheme(outgoingColor: Color(0xFF4F46E5)),
  input: ChatInputTheme(backgroundColor: Colors.white),
  roomList: ChatRoomListTheme(unreadBadgeColor: Color(0xFF4F46E5)),
)

See Developer Guide — Theming for all 155+ fields.

---

Platform support

Platform	Status	Notes
Android	Production	Primary target. Chat, attachments, voice, presence, offline cache exercised end-to-end.
iOS	Production	Primary target. Same as Android.
macOS / Linux / Windows	Best effort	SDK and UI Kit work; voice uses platform audio backends. Not exercised in production.
Web	Limited	SDK, cache (IndexedDB) and audio playback work. Voice recording is disabled (filesystem staging).

---

Documentation

Document	Contents
Developer Guide	Architecture · all APIs · configuration · theming · customization · events · testing
ARCHITECTURE.md	Internal layers and data-flow diagrams
INTEGRATING.md	CHT backend contract (endpoints, auth, WS frames, S2S)
MIGRATING.md	Step-by-step upgrade guide for every breaking release
CHANGELOG.md	Version history

---

When NOT to use

• Custom backend with incompatible wire protocol — the SDK speaks the CHT contract (REST + WS/SSE, JWT, specific error codes). You can plug a custom ChatClient via NomaChat.fromClient(), but adapting the full contract is non-trivial. Consider whether it fits before adopting.
• End-to-end encryption — TLS only. If E2EE is a hard requirement, use a different SDK.
• Hard latency SLO under ~100 ms — the SDK is push-based but does not advertise a real-time SLO. For voice / video signalling, use a dedicated SDK.

---

Troubleshooting

Common issues and fixes are documented in the Developer Guide — Troubleshooting section.

---

Links

• Source: github.com/nomasystems/noma_chat_flutter
• Issues: github.com/nomasystems/noma_chat_flutter/issues
• License: Apache-2.0