2. Make Offline-Safe Requests

Instead of calling Dio or Http directly, use the SyncVault client:

// POST request
final response = await SyncVault.instance.post(
  '/jobs/complete',
  data: {'jobId': 123, 'status': 'DONE'},
  idempotencyKey: 'job_123_complete', // Prevents duplicate execution
);

if (response.isQueued) {
  print("Saved offline! Will sync later.");
} else if (response.isSent) {
  print("Sent immediately! Status: ${response.response?.statusCode}");
}

// GET, PUT, DELETE, PATCH are also available
await SyncVault.instance.get('/users');
await SyncVault.instance.put('/users/123', data: {...});
await SyncVault.instance.delete('/users/123');
await SyncVault.instance.patch('/users/123', data: {...});

3. Listen to Sync Status

Perfect for showing a "Syncing..." indicator in your UI:

SyncVault.instance.statusStream.listen((status) {
  switch (status) {
    case SyncStatus.syncing:
      showToast("Uploading offline data...");
    case SyncStatus.synced:
      showToast("All caught up!");
    case SyncStatus.pending:
      showToast("${await SyncVault.instance.pendingCount} items waiting");
    case SyncStatus.error:
      showToast("Sync error occurred");
  }
});

4. Track Individual Actions (Event Bus)

Listen to specific job completions — perfect for updating UI when background sync finishes:

// Listen to all events
SyncVault.instance.onEvent.listen((event) {
  print('Action ${event.id}: ${event.status}');

  if (event.isSuccess) {
    // Action completed successfully
    print('Response: ${event.response}');
  } else if (event.isPermanentFailure) {
    // Action failed permanently (dead letter)
    print('Error: ${event.error}');
  }
});

// Filter events for a specific action
SyncVault.instance.eventsFor('action-id').listen((event) {
  // Only events for this action
});

// Filter by idempotency key
SyncVault.instance.eventsForKey('my-idempotency-key').listen((event) {
  // Only events with this key
});

Event Statuses:

5. Manual Sync

Trigger sync manually if needed:

final successCount = await SyncVault.instance.processQueue();
print('Synced $successCount items');

6. Check Pending Actions

// Get count
final count = await SyncVault.instance.pendingCount;

// Get all pending actions
final actions = await SyncVault.instance.getPendingActions();

// Clear all pending (use with caution)
await SyncVault.instance.clearQueue();

🎨 Flutter Widgets

SyncVault provides ready-to-use widgets for common UI patterns:

SyncVaultListener

Listens to sync events and calls callbacks — wrap your screen to react to background sync:

SyncVaultListener(
  // Called when any action completes successfully
  onSuccess: (event) {
    if (event.id == myActionId) {
      ScaffoldMessenger.of(context).showSnackBar(
        SnackBar(content: Text('Synced!')),
      );
    }
  },
  // Called when an action permanently fails
  onDeadLetter: (event) {
    showError('Sync failed: ${event.error}');
  },
  // Optional: filter by action ID or idempotency key
  actionId: 'specific-action-id',
  idempotencyKey: 'specific-key',
  child: YourScreen(),
)

SyncStatusBuilder

Rebuilds automatically when sync status changes:

SyncStatusBuilder(
  builder: (context, status) {
    return Icon(
      status == SyncStatus.syncing
          ? Icons.sync
          : Icons.cloud_done,
      color: status == SyncStatus.error
          ? Colors.red
          : Colors.green,
    );
  },
)

SyncEventBuilder

Rebuilds when events occur for a specific action — great for per-item sync indicators:

SyncEventBuilder(
  actionId: myActionId,
  builder: (context, lastEvent) {
    if (lastEvent == null) {
      return Icon(Icons.cloud_upload); // Queued
    }
    if (lastEvent.status == SyncEventStatus.started) {
      return CircularProgressIndicator(); // Syncing
    }
    if (lastEvent.isSuccess) {
      return Icon(Icons.check, color: Colors.green);
    }
    return Icon(Icons.error, color: Colors.red);
  },
)

🏗️ Architecture

SyncVault follows a Store-and-Forward architecture:

┌─────────────────┐
│   Your App      │
│   (Request)     │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│   SyncVault     │
│   (Intercept)   │
└────────┬────────┘
         │
    ┌────┴────┐
    │ Online? │
    └────┬────┘
         │
    ┌────┴────┐
   Yes       No
    │         │
    ▼         ▼
┌───────┐ ┌───────┐
│  Dio  │ │ Queue │
│ (Send)│ │(Store)│
└───────┘ └───┬───┘
              │
              ▼
         ┌────────┐
         │  Hive  │
         │(Persist)│
         └────────┘
              │
    On Network Restore
              │
              ▼
         ┌────────┐
         │ Worker │
         │(Process)│
         └────────┘

1. Interceptor: Captures outgoing requests via SyncVault.instance.post(), etc.
2. Queue Manager: Serializes requests to local storage (FIFO order).
3. Network Watcher: Listens for connectivity changes via connectivity_plus.
4. Worker: Dequeues requests and retries with exponential backoff.

⚙️ Configuration

SyncVaultConfig(
  // Required
  baseUrl: 'https://api.example.com',

  // Optional: Custom storage path for Hive
  storagePath: '/path/to/storage',

  // Optional: Maximum retry attempts (default: 3)
  maxRetries: 5,

  // Optional: Custom Dio instance
  dio: myCustomDio,

  // Optional: Timeouts
  connectTimeout: Duration(seconds: 30),
  receiveTimeout: Duration(seconds: 30),

  // Optional: Custom storage adapter
  storage: MyCustomStorageAdapter(),
)

💾 Storage Adapters

SyncVault supports multiple storage backends out of the box:

Hive (Default)

Hive is the default storage adapter - fast, lightweight, and perfect for most use cases.

await SyncVault.init(
  config: SyncVaultConfig(
    baseUrl: 'https://api.example.com',
    storagePath: dir.path, // Required for Hive
  ),
);

SQLite

For apps that prefer relational databases or need more complex queries:

import 'package:sync_vault/sync_vault.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  // Create SQLite adapter
  final sqliteAdapter = SqfliteStorageAdapter();

  await SyncVault.init(
    config: SyncVaultConfig(
      baseUrl: 'https://api.example.com',
      storage: sqliteAdapter, // Use SQLite instead of Hive
    ),
  );

  runApp(MyApp());
}

You can also specify a custom database path:

final sqliteAdapter = SqfliteStorageAdapter(
  databasePath: '/custom/database/path',
);

🔌 Custom Storage Adapter

Implement StorageAdapter to use your own persistence layer:

class MyStorageAdapter implements StorageAdapter {
  @override
  Future<void> init() async { ... }

  @override
  Future<void> saveAction(SyncAction action) async { ... }

  @override
  Future<void> removeAction(String id) async { ... }

  @override
  Future<List<SyncAction>> getAllActions() async { ... }

  @override
  Future<void> clear() async { ... }

  @override
  Future<void> dispose() async { ... }

  @override
  Future<int> get count async { ... }
}

🧪 Testing

SyncVault is designed to be testable. Reset between tests:

tearDown(() async {
  await SyncVault.reset();
});

📱 Example

Check out the example directory for a complete Todo app demonstrating all features.

cd example
flutter run

🔒 Idempotency

Use idempotency keys to prevent duplicate operations when retrying:

await SyncVault.instance.post(
  '/payments',
  data: {'amount': 100},
  idempotencyKey: 'payment_${orderId}_${timestamp}',
);

If the same idempotency key is already in the queue, SyncVault will handle it appropriately.

📊 Retry Behavior

🤝 Contributing

PRs are welcome! Please read the contributing guidelines before submitting.

1. Fork the repo
2. Create your feature branch from dev (git checkout -b feature/amazing-feature dev)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request against dev

👤 Author

Nabhodipta Garai (@brownboycodes)

• 💼 LinkedIn
• 🐙 GitHub

📄 License

MIT © 2025 Nabhodipta Garai

Built with ❤️ for Flutter developers who work in the real world, where networks are unreliable.