Strapi LDK (Lazy Development Kit) #

A comprehensive Flutter SDK that wraps Strapi's REST and GraphQL APIs into a simple, type-safe, and intuitive client-side library. Strapi LDK provides a Firebase-like experience while retaining Strapi's flexibility.

🚀 Phase 2 Now Available! #

Version 2.0 introduces powerful new features while maintaining full backward compatibility with Phase 1.

Features #

🌟 Phase 1 Features (Stable) #

• 🚀 Easy Setup: Initialize with just a few lines of code
• 🔐 Authentication: JWT-based auth with automatic token management
• 📊 CRUD Operations: Intuitive interface for Create, Read, Update, Delete
• 🔍 Advanced Querying: Fluent query builder with filters, sorting, and pagination
• 📁 File Upload: Simple file and media upload with progress tracking
• 🛡️ Type Safety: Full TypeScript-like type safety with Dart
• 🔄 Auto Retry: Built-in error handling and retry mechanisms
• 📱 Cross Platform: Works on Android, iOS, Web, and Desktop

✨ Phase 2 Features (Advanced) #

• 🔄 Real-time Updates: WebSocket-based live data synchronization
• 🧠 Intelligent Caching: Multi-strategy caching (LRU, LFU, FIFO) with background refresh
• 📴 Offline Support: Complete offline functionality with automatic sync
• 🔒 Enhanced Security: Token refresh, biometric auth, security monitoring
• ⚡ GraphQL Support: Full GraphQL client with subscriptions
• 🎯 Optimistic Updates: Immediate UI updates with automatic rollback
• 🔍 Global Search: Search across multiple collections simultaneously
• 💾 Transactions: Multi-operation atomic transactions
• 📊 Aggregations: Advanced data analysis and grouping
• 🔔 Event Streams: Real-time notifications for all major events

Getting Started #

Add LDK to your pubspec.yaml:

dependencies:
  strapi_ldk: ^2.0.3

Quick Start #

🎯 Phase 1 (Basic) - Stable API #

import 'package:strapi_ldk/strapi_ldk.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  
  await LDK.initialize(
    baseUrl: 'https://your-strapi-app.com',
    enableLogging: true,
  );
  
  runApp(MyApp());
}

🚀 Phase 2 (Advanced) - New Features #

import 'package:strapi_ldk/strapi_ldk.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  
  await LDK.initialize(
    baseUrl: 'https://your-strapi-app.com',
    enableLogging: true,
    enableGraphQL: true,           // 🔄 Real-time subscriptions
    enableRealtime: true,          // ⚡ Live updates
    enableIntelligentCache: true,  // 🧠 Smart caching
    enableOfflineStorage: true,    // 📴 Offline support
    enableEnhancedAuth: true,      // 🔒 Advanced security
  );
  
  runApp(MyApp());
}

2. Authentication #

// Sign up a new user
try {
  final user = await LDK.authService.signUp(
    email: 'user@example.com',
    password: 'securePassword123',
    username: 'johndoe',
  );
  print('User created: ${user.email}');
} catch (e) {
  print('Sign up failed: $e');
}

// Sign in existing user
try {
  final user = await LDK.authService.signIn(
    email: 'user@example.com',
    password: 'securePassword123',
  );
  print('Signed in: ${user.email}');
} catch (e) {
  print('Sign in failed: $e');
}

// Listen to auth state changes
LDK.authService.authStateStream.listen((isAuthenticated) {
  if (isAuthenticated) {
    print('User is signed in');
  } else {
    print('User is signed out');
  }
});

// Sign out
await LDK.authService.signOut();

3. CRUD Operations #

// Get a collection reference
final posts = LDK.collection('posts');

// Create a new post
final newPost = await posts.create({
  'title': 'My First Post',
  'content': 'This is the content of my first post.',
  'status': 'published',
});

// Get all posts
final allPosts = await posts.get();
print('Found ${allPosts.data.length} posts');

// Get a specific post by ID
final post = await posts.getById(1);
print('Post title: ${post['title']}');

// Update a post
final updatedPost = await posts.update(1, {
  'title': 'Updated Post Title',
});

// Delete a post
await posts.delete(1);

4. Advanced Querying #

final posts = LDK.collection('posts');

// Complex query with filters, sorting, and pagination
final response = await posts
    .where('status', equals: 'published')
    .where('title', contains: 'Flutter')
    .where('createdAt', greaterThan: '2023-01-01')
    .sort('createdAt', descending: true)
    .populate('author')
    .populate('category')
    .paginate(page: 1, pageSize: 10)
    .get();

// Using query builder directly
final query = LDKQueryBuilder()
    .where('category', equals: 'technology')
    .or([
      LDKQueryBuilder().where('featured', equals: true),
      LDKQueryBuilder().where('views', greaterThan: 1000),
    ])
    .sort('publishedAt', descending: true)
    .limit(5);

final featuredPosts = await posts.get(query: query);

5. File Upload #

import 'dart:io';

// Upload a single file
final file = File('path/to/image.jpg');
try {
  final uploadedFile = await LDK.storageService.upload(
    file,
    alternativeText: 'Profile picture',
    caption: 'User profile image',
  );
  print('File uploaded: ${uploadedFile.url}');
} catch (e) {
  print('Upload failed: $e');
}

// Upload multiple files with progress tracking
final files = [File('image1.jpg'), File('image2.jpg')];
try {
  final uploadedFiles = await LDK.storageService.uploadMultiple(
    files,
    onProgress: (sent, total) {
      print('Progress: ${(sent / total * 100).toStringAsFixed(1)}%');
    },
  );
  print('Uploaded ${uploadedFiles.length} files');
} catch (e) {
  print('Upload failed: $e');
}

// Validate file before upload
final isValid = LDK.storageService.validateFile(
  file,
  maxSizeBytes: 5 * 1024 * 1024, // 5MB
  allowedMimeTypes: ['image/jpeg', 'image/png'],
  allowedExtensions: ['jpg', 'jpeg', 'png'],
);

if (isValid) {
  // Proceed with upload
}

🚀 Phase 2 Advanced Usage #

Real-time Updates #

// Subscribe to collection changes
final posts = LDK.enhancedCollection('posts');
posts.subscribeToUpdates().listen((event) {
  switch (event.mutation) {
    case MutationType.create:
      print('New post created: ${event.data}');
      break;
    case MutationType.update:
      print('Post updated: ${event.data}');
      break;
    case MutationType.delete:
      print('Post deleted');
      break;
  }
});

// Watch a query for live updates
posts.watchQuery(
  query: posts.where('status', equals: 'published').limit(10)
).listen((result) {
  updateUI(result.data);
});

Intelligent Caching #

// Automatic caching with smart strategies
final posts = LDK.enhancedCollection('posts');

// First call hits the network, subsequent calls use cache
final data1 = await posts.get(); // Network call
final data2 = await posts.get(); // Cache hit

// Force refresh from network
final freshData = await posts.get(forceRefresh: true);

// Cache statistics
LDK.cache.cacheStatsStream.listen((stats) {
  print('Cache hit ratio: ${(stats.hitRatio * 100).toStringAsFixed(1)}%');
});

Offline Support #

// Monitor online/offline status
LDK.subscribeToOfflineStatus().listen((isOnline) {
  if (isOnline) {
    showSuccessMessage('Back online! Syncing data...');
  } else {
    showWarningMessage('Offline mode - changes will sync later');
  }
});

// Operations work seamlessly offline
final post = await posts.create({
  'title': 'Offline Post',
  'content': 'This works offline too!',
}); // Queued for sync when online

// Monitor pending operations
LDK.offlineStorage.pendingOperationsStream.listen((operations) {
  print('${operations.length} operations pending sync');
});

Optimistic Updates #

// UI updates immediately, rolls back on error
try {
  final updatedPost = await posts.update(postId, {
    'title': 'New Title',
  }, optimistic: true);
  
  // UI already shows the new title
  showSuccess('Post updated!');
} catch (e) {
  // UI automatically reverted to original title
  showError('Update failed: $e');
}

Enhanced Security #

// Automatic token refresh
LDK.enhancedAuth.tokenRefreshStream.listen((isRefreshing) {
  if (isRefreshing) {
    showSpinner('Refreshing authentication...');
  }
});

// Enable biometric authentication
await LDK.enhancedAuth.enableBiometric(
  password: 'current_password',
);

// Sign in with biometrics
final user = await LDK.enhancedAuth.signInWithBiometric(
  email: 'user@example.com',
);

// Monitor security events
LDK.subscribeToSecurityEvents().listen((event) {
  if (event.type == SecurityEventType.suspiciousActivity) {
    showSecurityAlert('Suspicious activity detected!');
  }
});

Global Search #

// Search across multiple collections
final results = await LDK.globalSearch(
  'flutter tutorial',
  collections: ['posts', 'tutorials', 'documentation'],
  limit: 10,
);

// results = {
//   'posts': [...],
//   'tutorials': [...],
//   'documentation': [...]
// }

for (final entry in results.entries) {
  print('Found ${entry.value.length} results in ${entry.key}');
}

Transactions #

// Execute multiple operations atomically
final results = await LDK.executeTransaction([
  TransactionOperation(
    type: TransactionType.create,
    collection: 'posts',
    data: {'title': 'New Post', 'status': 'draft'},
  ),
  TransactionOperation(
    type: TransactionType.update,
    collection: 'users',
    entityId: userId,
    data: {'postCount': userPostCount + 1},
  ),
]);

print('Transaction completed: ${results.length} operations');

Aggregations #

// Advanced data analysis
final stats = await posts.aggregate(
  groupBy: ['category', 'status'],
  aggregates: {
    'views': AggregateFunction.sum,
    'id': AggregateFunction.count,
    'createdAt': AggregateFunction.min,
  },
  filters: posts.where('createdAt', greaterThan: '2023-01-01'),
);

print('Total views: ${stats['views']}');
print('Total posts: ${stats['count']}');

Custom Cache Strategies #

await LDK.initialize(
  baseUrl: 'https://your-strapi-app.com',
  cacheConfig: {
    'strategies': {
      'user': {
        'ttl': Duration(hours: 2).inMilliseconds,
        'maxSize': 50,
        'evictionPolicy': 'lru',
        'backgroundRefresh': true,
      },
      'posts': {
        'ttl': Duration(minutes: 15).inMilliseconds,
        'maxSize': 200,
        'evictionPolicy': 'lfu',
        'refreshOnAccess': true,
      },
    },
  },
);

Phase 1 Advanced Usage #

Custom Query Conditions #

final products = LDK.collection('products');

// Multiple filter conditions
final expensiveProducts = await products
    .where('price', greaterThanOrEqual: 100)
    .where('price', lessThan: 1000)
    .where('category', isIn: ['electronics', 'gadgets'])
    .where('inStock', equals: true)
    .get();

// Text search
final searchResults = await products
    .where('name', containsi: 'iphone') // Case-insensitive
    .where('description', contains: 'smartphone')
    .get();

// Null checks
final productsWithoutImages = await products
    .where('image', isNull: true)
    .get();

Error Handling #

try {
  final posts = await LDK.collection('posts').get();
} on LDKAuthException catch (e) {
  print('Authentication error: ${e.message}');
  // Redirect to login
} on LDKNetworkException catch (e) {
  print('Network error: ${e.message}');
  // Show retry option
} on LDKValidationException catch (e) {
  print('Validation error: ${e.message}');
  print('Field errors: ${e.errors}');
  // Show field-specific errors
} on LDKServerException catch (e) {
  print('Server error: ${e.message}');
  // Show generic error message
} catch (e) {
  print('Unexpected error: $e');
}

Working with Relations #

// Populate related data
final postsWithAuthors = await LDK.collection('posts')
    .populate('author')
    .populate('category')
    .populate('tags')
    .get();

// Deep population
final postsWithAuthorProfile = await LDK.collection('posts')
    .populate('author.profile')
    .get();

Configuration Options #

await LDK.initialize(
  baseUrl: 'https://your-strapi-app.com',
  authToken: 'optional-existing-jwt-token',
  enableLogging: true,
  connectTimeout: Duration(seconds: 30),
  receiveTimeout: Duration(seconds: 30),
);

Models #

LDK provides built-in models for common Strapi entities:

// User model
final user = LDKUser(
  id: 1,
  email: 'user@example.com',
  username: 'johndoe',
  confirmed: true,
  blocked: false,
);

// File model
final file = StrapiFile(
  id: 1,
  name: 'image.jpg',
  url: 'https://example.com/uploads/image.jpg',
  mime: 'image/jpeg',
  size: 1024.0,
  // ... other properties
);

Testing #

LDK is thoroughly tested. To run tests:

flutter test

Contributing #

Contributions are welcome! Please read our contributing guide for details on our code of conduct and the process for submitting pull requests.

License #

This project is licensed under the MIT License - see the LICENSE file for details.

Support #

• 📖 Official Documentation
• 🐛 Issue Tracker
• 💬 Discussions

Roadmap #

• ❌ GraphQL support
• ❌ Real-time subscriptions
• ❌ Offline caching
• ❌ CLI for code generation
• ❌ Advanced caching strategies

Made with ❤️ for the Flutter and Strapi communities.