ma_ng_outbox 0.0.8

Mariapps Internal Package to build Flutter apps faster

📦 Offline Outbox Sync for Flutter (ObjectBox + Isolate + Retry + Multipart Support)

A powerful and lightweight offline-first outbox queue system for Flutter apps. Designed for real-world enterprise use cases where network instability, large payloads, and token expiry must be handled automatically.

Supports:

✅ JSON API requests

✅ Multipart file uploads

✅ Multiple files per request

✅ Empty multipart field names

✅ Automatic retry with priority

✅ Automatic token refresh (401 handling)

✅ Runs in Isolate for non-blocking UI

✅ ObjectBox storage for fast persistence

✅ Fully background-safe

🚀 Features Feature Status JSON request outbox ✅ Multipart upload (files/images/docs) ✅ Multiple files with dynamic field names ✅ Empty file field name ("") support ✅ Priority-based queue (1 → 4) ✅ Automatic retry on failures ✅ Retry with new token on 401 ✅ Save status code + response ✅ RootIsolateToken support ✅ Zero UI freeze Isolate-based Production-ready 🔥 📦 Installation

Add to pubspec.yaml:

dependencies: ma_ng_outbox: git: url: https://github.com/

Make sure ObjectBox is installed:

dependencies: objectbox: any objectbox_flutter_libs: any

Run:

flutter pub get

🛠 Basic Setup 1️⃣ Initialize Outbox in main.dart void main() async { WidgetsFlutterBinding.ensureInitialized();

await OutboxBootstrap.setup();

runApp(MyApp()); }

🧱 How Outbox Works

Every API call is stored as an OutboxItem:

await objectBox.addToOutbox( operation: "POST", url: "https://api.server.com/save", payload: {"title": "Offline Save"}, priority: Priority.high, primaryKey: "local-123", );

Then Outbox will:

✔ Automatically sync when online ✔ Retry failed requests ✔ Retry 401 using refresh token ✔ Save response & status code ✔ Process highest priority first 🧵 Architecture Overview UI Layer ─────► addToOutbox() ──────► ObjectBox storage │ ▼ Background Sync Trigger │ ▼ Isolate Spawned │ ▼ outboxIsolateEntry() reads pending items │ ├──► JSON Request ├──► Multipart Request ├──► Multi-file Upload └──► Retry on 401 w/ Refresh Token │ ▼ Main Isolate receives result │ ▼ Update ObjectBox (status + response)

📡 Adding JSON Requests await objectBox.addToOutbox( operation: "POST", url: Api.saveData, payload: { "name": "Offline Entry", "timestamp": DateTime.now().toString(), }, priority: Priority.medium, );

📁 Adding File Upload Requests 1 file await objectBox.addToOutbox( operation: "POST", url: Api.uploadImage, payload: { "description": "Offline photo", "userId": 12, }, filePathsJson: jsonEncode([imageFile.path]), fileFieldsJson: jsonEncode(["file"]), // or "" );

Multiple files await objectBox.addToOutbox( operation: "POST", url: Api.uploadDocuments, payload: {"caseId": 55}, filePathsJson: jsonEncode([frontPath, backPath]), fileFieldsJson: jsonEncode(["front", "back"]), );

🔐 Token Refresh Flow (401 Handling)

If API returns 401 Unauthorized:

Call refresh token endpoint

Save new accessToken into OutboxItem

Retry original request

Continue syncing

This is built-in automatically.

📦 OutboxItem Fields class OutboxItem { int id; String operation; String url; int priority; // 1–4 String? payload; // JSON body String? response; // Server response String? filePathsJson; // ["path1","path2"] String? fileFieldsJson;// ["file",""] int isSynced; // 0 or 1 int retryCount; int lastTried; int createdAt; int? statusCode; // HTTP code String? newAccessToken; }

🔄 Manual Triggering of Sync

If internet becomes available:

SyncController.runIsolateSync( objectBox: objectBox, token: "

🌐 Network Listener Example ConnectivityService().onNetworkChange.listen((online) { if (online) SyncController.runIsolateSync(...); });

🧪 Debugging

Enable console logs:

kDebugMode ? print("...") : null;

View saved data using ObjectBox Admin:

if (Admin.isAvailable()) { Admin(objectBox.store); }

🚀 Performance & Scaling

25,000+ outbox items tested

Large file uploads supported

No UI freeze due to isolate-based processing

Suitable for enterprise offline apps