Auth-Aware Kalam Client for Flutter

For a new Flutter app, prefer kalam_sync and KalamScope. That handles lifecycle pause/resume and an account-scoped cache without a custom controller.

Use this page when you stay on kalam_link and need the client to follow login, token refresh, and logout.

Lifecycle

Call KalamClient.init() once before runApp().
Connect after auth is ready — not before the first frame.
Start live queries only after you know which user/session to subscribe.
Dispose the client on logout.

Do not await KalamClient.connect() in main(). Even with lazy WebSocket connect, auth work can delay first render.

Riverpod example

DART

1import 'dart:async';2 3import 'package:flutter/widgets.dart';4import 'package:flutter_riverpod/flutter_riverpod.dart';5import 'package:kalam_link/kalam_link.dart';6 7Future<void> main() async {8  WidgetsFlutterBinding.ensureInitialized();9  await KalamClient.init();10  runApp(const ProviderScope(child: MyApp()));11}12 13class AppUser {14  const AppUser({required this.id});15  final String id;16}17 18final authTokenProvider = StreamProvider<String?>((ref) {19  return authRepository.idTokenChanges();20});21 22final appUserProvider = StreamProvider<AppUser?>((ref) {23  return userRepository.sessionChanges();24});25 26final kalamControllerProvider = Provider<KalamController>((ref) {27  final controller = KalamController(url: 'https://db.example.com');28  ref.onDispose(controller.dispose);29  return controller;30});31 32final kalamLifecycleProvider = Provider<void>((ref) {33  final controller = ref.watch(kalamControllerProvider);34 35  ref.listen<AsyncValue<String?>>(authTokenProvider, (_, next) {36    unawaited(controller.syncAuth(next.valueOrNull));37  });38 39  ref.listen<AsyncValue<AppUser?>>(appUserProvider, (_, next) {40    final user = next.valueOrNull;41    if (user == null) {42      unawaited(controller.stopRealtime());43      return;44    }45    unawaited(controller.ensureRealtimeReady(userId: user.id));46  });47});48 49class KalamController {50  KalamController({required this.url});51 52  final String url;53  KalamClient? _client;54  String? _currentToken;55  String? _subscribedUserId;56  StreamSubscription<List<Map<String, KalamCellValue>>>? _messagesSubscription;57 58  Future<void> syncAuth(String? token) async {59    if (token == _currentToken) return;60    _currentToken = token;61 62    if (token == null) {63      _subscribedUserId = null;64      await _messagesSubscription?.cancel();65      _messagesSubscription = null;66      await _client?.dispose();67      _client = null;68      return;69    }70 71    if (_client == null) {72      _client = await KalamClient.connect(73        url: url,74        authProvider: () async => Auth.jwt(_currentToken!),75      );76      return;77    }78 79    await _client!.refreshAuth();80  }81 82  Future<void> ensureRealtimeReady({required String userId}) async {83    final client = _client;84    if (client == null || _subscribedUserId == userId) return;85 86    await _messagesSubscription?.cancel();87    _subscribedUserId = userId;88    _messagesSubscription = client89        .liveTable<Map<String, KalamCellValue>>('messages')90        .listen((rows) => debugPrint('rows: ${rows.length}'));91  }92 93  Future<void> stopRealtime() async {94    _subscribedUserId = null;95    await _messagesSubscription?.cancel();96    _messagesSubscription = null;97  }98 99  Future<void> dispose() async {100    await _messagesSubscription?.cancel();101    await _client?.dispose();102  }103}

DART

1class MyApp extends ConsumerWidget {2  const MyApp({super.key});3 4  @override5  Widget build(BuildContext context, WidgetRef ref) {6    ref.watch(kalamLifecycleProvider);7    return const Directionality(8      textDirection: TextDirection.ltr,9      child: Placeholder(),10    );11  }12}

On logout, dispose the client. On token rotation, keep the same client and call refreshAuth().

See Authentication, Realtime Subscriptions, and Client Lifecycle.