SDKs

Flutter SDK

Production-grade client for iOS, Android, Web, macOS, and Windows — with auth, realtime data, file uploads, and edge function calls.

orbitnest_studio_flutter is the official Flutter SDK. It wraps the REST API with typed models, caches sessions on device, and handles token refresh in the background.

Installation

yaml

# pubspec.yaml
dependencies:
  orbitnest_studio_flutter: ^1.0.0

bash

flutter pub get

Initialize

Create the client once in your app's startup flow — usually inside main() before runApp().

dart

import 'package:orbitnest_studio_flutter/orbitnest_studio_flutter.dart';

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

  await OrbitNestClient.initialize(
    projectUrl: 'https://studio.orbitnest.io/api/projects/my-app',
    anonKey:    const String.fromEnvironment('ORBITNEST_ANON_KEY'),
  );

  runApp(const MyApp());
}

Authentication

The auth namespace handles sign-up, sign-in, OTP verification, and session state. Sessions persist to SharedPreferences so users stay signed in across launches.

dart

final client = OrbitNestClient.instance;

// Sign up with OTP
await client.auth.signUpWithEmail(
  email: 'user@example.com',
  userMetadata: {'name': 'Jane'},
);

// User enters 4-digit code from email
final result = await client.auth.verifySignup(
  email: 'user@example.com',
  code:  '1234',
  password: 'optional',
);

// Sign in
final session = await client.auth.signIn(
  email: 'user@example.com',
  password: 'secret',
);

// Watch session state reactively
client.auth.onAuthStateChange.listen((state) {
  print('signed in: ${state.session != null}');
});

API user_metadata field

When calling signUpWithEmail, pass user_metadata — not data. The API rejects the latter. The SDK enforces this for you as of 1.0.0.

Database queries

dart

// Select
final posts = await client.from('posts')
  .select()
  .eq('published', true)
  .order('created_at', ascending: false)
  .limit(10);

// Insert
final created = await client.from('posts').insert({
  'title': 'Hello',
  'body':  'World',
}).select().single();

// Update
await client.from('posts')
  .update({'published': true})
  .eq('id', postId);

// Delete
await client.from('posts').delete().eq('id', postId);

File uploads

dart

import 'dart:io';

final file = File(imagePath);
final upload = await client.storage
  .from('avatars')
  .upload('${user.id}/avatar.png', file, contentType: 'image/png');

// Read back a public URL
final url = client.storage.from('avatars').getPublicUrl(upload.path);

Edge functions

dart

final result = await client.functions.invoke(
  'send-welcome-email',
  body: {'userId': user.id},
);

Avoid concurrent invocations

Always await each function call before starting the next. The FunctionsBloc uses a FIFO queue — concurrent calls can hang until the 3-minute Dio timeout.

Platform support

iOS 12+
Android API 21+
Web (Chromium, Safari, Firefox)
macOS 11+
Windows 10+