Flutter SDK

Installation

Add to pubspec.yaml:

dependencies:
  bunbase_flutter: ^0.13.0

Then run:

flutter pub get

Required Flutter permissions (Android — AndroidManifest.xml):

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

No extra configuration is needed for iOS or Web.

---

Setup

Create a single BunBaseClient instance — typically in a dependency provider or a top-level singleton:

import 'package:bunbase_flutter/bunbase_flutter.dart';

final bunbase = BunBaseClient('https://api.example.com');

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();

  // Restore a persisted session from Keychain / Android Keystore.
  await bunbase.auth.restoreSession();

  // Start listening for connectivity changes to auto-flush the offline queue.
  await bunbase.offlineQueue.startMonitoring();

  runApp(const MyApp());
}

---

Typed collections

class Post {
  final String id;
  final String title;
  Post({required this.id, required this.title});
  factory Post.fromJson(Map<String, dynamic> j) =>
      Post(id: j['id'], title: j['title']);
}

final posts = bunbase.collection('posts', Post.fromJson);

---

Auth state

auth.currentUser is a ValueNotifier<AuthUser?> — wire it directly to ValueListenableBuilder:

ValueListenableBuilder<AuthUser?>(
  valueListenable: bunbase.auth.currentUser,
  builder: (context, user, _) {
    if (user == null) return const LoginPage();
    return HomeScreen(user: user);
  },
)

---

Error handling

All methods throw a subclass of BunBaseError:

Type	When
ServerError	HTTP 4xx / 5xx — includes .status, .message, .code, .field
NetworkError	No connectivity or socket error
UnauthenticatedError	401 after token refresh failed
DecodingError	Malformed JSON response
TimeoutError	Ping / presence timeout

try {
  await bunbase.auth.login(email, password);
} on ServerError catch (e) {
  if (e.code == 'invalid_credentials') showSnack('Wrong email or password');
} on NetworkError catch (_) {
  showSnack('No internet connection');
}

---

Token persistence

Tokens are automatically persisted to the platform secure store:

Platform	Store
iOS / macOS	Keychain
Android	EncryptedSharedPreferences (AES-256-GCM)
Linux	libsecret
Windows	Credential Manager

Call auth.restoreSession() once on startup to load the persisted tokens without a network round-trip.

Pass enableTokenStore: false to BunBaseClient to disable persistence (useful for tests).