Dart & Flutter quick start

Two packages on pub.dev:

• vaultbase: the client, in pure Dart. Runs in Flutter apps, Dart servers, CLIs and tests.
• vaultbase_flutter: what an app adds on top: sessions that survive restarts, OAuth in the system browser, and app lifecycle handling. It re-exports vaultbase, so a Flutter app imports only this one.

Both need Dart 3.6 (Flutter 3.27) and a Vaultbase server 0.27 or later.

Install

# Flutter app
flutter pub add vaultbase_flutter

# Dart server, CLI or package
dart pub add vaultbase

Hello, Vaultbase

import 'package:vaultbase/vaultbase.dart';

Future<void> main() async {
  final vb = Vaultbase('https://api.example.com');

  // Records
  final post = await vb.collection('posts').create({'title': 'Hi'});
  final page = await vb.collection('posts').list(
      filter: vb.filter('author = {:id}', {'id': post['author']}),
      sort: '-created');

  // Auth
  await vb.auth.collection('users').login('[email protected]', 'a-long-password');

  // Realtime
  final sub = vb.collection('posts').subscribe((e) => print('${e.action} ${e.id}'));
  // sub.cancel() when done

  vb.close();
}

In a Flutter app

Create one client when the app starts, with a store that keeps the session, and wait for the saved session before the first frame:

import 'package:flutter/foundation.dart';
import 'package:flutter/material.dart';
import 'package:vaultbase_flutter/vaultbase_flutter.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  final vb = Vaultbase('https://api.example.com',
      authStore: kIsWeb ? PrefsAuthStore() : SecureAuthStore());
  await vb.authStore.ready;
  VaultbaseLifecycle(vb);
  runApp(MyApp(vb: vb));
}

Rebuild on sign-in and sign-out with vb.authStore.onChange:

StreamBuilder<StoredAuth?>(
  stream: vb.authStore.onChange,
  initialData: vb.authStore.current,
  builder: (context, snap) =>
      snap.data == null ? SignInPage(vb: vb) : HomePage(vb: vb),
)

See Flutter for the stores, lifecycle and OAuth set-up per platform. The example app puts it together: sign-in, GitHub sign-in, and a list that updates live.

The client

Vaultbase(
  'https://api.example.com',
  authStore: MemoryAuthStore(),   // the default; SecureAuthStore / PrefsAuthStore in apps
  httpClient: http.Client(),      // your own, for proxies, certificate pinning or tests
  timeout: Duration(seconds: 30), // per request; none by default
  autoCancel: false,              // see Cancelling requests
  headers: {'x-app': 'notes'},    // sent with every request
);

The session’s token is refreshed 60 seconds before it expires, and once after a 401, shared by every request in flight. A refresh that fails because the device is offline keeps the session; only one the server refuses signs the user out.

What’s on the client

vb.collection(name)	Records: list, iterate, get, create, update, delete, aggregate
vb.singleton(name)	The record of a singleton collection
vb.batch()	Up to 100 operations in one transaction
vb.auth	Sign-in flows and the session
vb.files	Uploads, URLs, access tokens
vb.realtime	The realtime connection
vb.flags	Feature flags
vb.custom	Your custom routes under /api/v1/custom/
vb.send(path)	Any endpoint, with the session and error mapping

Errors are typed: see Errors. Generated record classes: see Typed records.