🎯 Major API Refactor #

Unified API with Clean Namespace

• NEW: All Guardo methods now organized under context.guardo.xxx for better readability and organization
• NEW: Introduced GuardoContextWrapper class to house all Guardo-related methods
• IMPROVED: Clean separation of concerns with dedicated wrapper class

Unified Action Method

• NEW: Single action<T>() method handles both synchronous and asynchronous operations using FutureOr<T>
• BREAKING: Merged secureAction, actionWithResult, asyncAction, and asyncActionWithResult into one unified method
• IMPROVED: Automatic detection and handling of sync/async operations - no separate methods needed
• IMPROVED: Single method handles operations with or without return values using generic type parameter

Backward Compatibility

• DEPRECATED: Old API methods (secureAction, asyncAction, etc.) are now deprecated but still functional
• MAINTAINED: All existing code continues to work with deprecation warnings
• MIGRATION PATH: Clear upgrade path documented with examples

🌍 Multi-Language Support #

Built-in Localization System

• NEW: Comprehensive localization support with GuardoLocalizations
• NEW: Built-in translations for English, Spanish, and Arabic
• NEW: RTL (Right-to-Left) language support for Arabic
• NEW: 50+ localized strings covering all UI elements
• NEW: Automatic localization based on device language settings

Extensible Localization

• NEW: Easy-to-extend system for adding new languages
• NEW: Custom delegate creation guide for additional languages
• NEW: Fallback system: Device locale → English → localizedReason → hardcoded
• NEW: Testing instructions for different locales

Localized Components

• UPDATED: Default lock screen now uses localized strings
• UPDATED: All error messages and UI text support localization
• UPDATED: Accessibility labels are localized for screen readers

🔧 Technical Improvements #

Enhanced Extension API

• RENAMED: isGuardoEnabled() → context.guardo.isEnabled()
• RENAMED: guardoState → context.guardo.state
• IMPROVED: All authentication methods moved to GuardoContextWrapper
• IMPROVED: Consistent API naming and organization

Code Organization

• NEW: Added dart:async import for FutureOr<T> support
• IMPROVED: Better separation of concerns in extension methods
• IMPROVED: Cleaner code structure with wrapper pattern

Dependencies

• ADDED: flutter_localizations support
• INTEGRATED: Localization delegates in configuration examples

📚 Documentation Overhaul #

Comprehensive README Update

• UPDATED: "What's New" section highlighting v1.0.0 features
• NEW: Detailed migration guide from old API to new API
• NEW: Complete localization documentation integrated into README
• NEW: Custom localization delegate creation guide
• UPDATED: All examples updated to use new context.guardo.xxx API
• IMPROVED: Enhanced error handling examples

API Documentation

• UPDATED: All method signatures reflect new unified API
• NEW: Deprecation notices with clear replacement instructions
• IMPROVED: Better code examples throughout documentation
• NEW: Localization strings reference table

Examples and Use Cases

• UPDATED: All code examples use new unified API
• NEW: Localization setup examples
• NEW: Custom delegate implementation examples
• IMPROVED: More comprehensive real-world use cases

⚠️ Breaking Changes #

While most changes maintain backward compatibility, there are some architectural changes:

API Changes (Backward Compatible)

• Old methods are deprecated but still functional
• New context.guardo.xxx namespace is the recommended approach
• Migration is optional but recommended for future compatibility

Method Consolidation

• Four separate action methods consolidated into one action<T>() method
• Old methods forward calls to new unified method
• No immediate breaking changes - deprecation warnings guide migration

🔄 Migration Guide #

Recommended API Migration

// Old API (still works, but deprecated)
await context.lockApp();                    // → await context.guardo.lockApp()
await context.secureAction(...);            // → await context.guardo.action(...)
await context.guardoAsyncAction(...);       // → await context.guardo.action(...) 
final result = await context.guardoActionWithResult<T>(...); // → await context.guardo.action<T>(...)

// Property access
context.isAuthenticated                     // → context.guardo.isAuthenticated
context.isGuardoEnabled()                   // → context.guardo.isEnabled()
context.guardoState                         // → context.guardo.state

Localization Setup

// Add to MaterialApp
MaterialApp(
  localizationsDelegates: const [
    GuardoLocalizations.delegate,  // NEW: Add this
    GlobalMaterialLocalizations.delegate,
    GlobalWidgetsLocalizations.delegate,
    GlobalCupertinoLocalizations.delegate,
  ],
  supportedLocales: const [
    Locale('en'), Locale('es'), Locale('ar'), // NEW: Add supported locales
  ],
)

Unified Action Method Usage

// Synchronous action
await context.guardo.action(
  onSuccess: () => _performSync(),
  reason: 'Please authenticate',
);

// Asynchronous action  
await context.guardo.action(
  onSuccess: () async => await _performAsync(),
  reason: 'Please authenticate',
);

// Action with return value
final result = await context.guardo.action<String>(
  onSuccess: () => _getSecretKey(),
  onFailure: (error) => 'default_key',
  reason: 'Get encryption key',
);

---

🎉 New Features #

Smart Authentication Detection

• Automatic Bypass: Guardo now automatically detects when authentication methods are unavailable and gracefully bypasses authentication
• hasAuthenticationMethods(): New method to check if any authentication methods are available on the device
• BypassedState: New state to handle scenarios where authentication is bypassed due to unavailable methods

Complete Authentication Control

• enabled Property: New enabled property on Guardo widget allows complete enable/disable of authentication
• isGuardoEnabled(): New extension method to check if Guardo is currently enabled/functional
• Perfect for Testing: Easy to disable authentication in debug mode or for testing environments

Enhanced Error Handling

• Async lockApp(): lockApp() method is now async and provides better error handling
• UnsupportedError: Clear error messages when trying to lock on devices without authentication methods
• Smart Error Messages: More descriptive error messages for different scenarios

Developer Experience Improvements

• Better State Management: Improved handling of authentication states across app lifecycle
• Enhanced Logging: More detailed logging for authentication flow debugging
• Comprehensive Documentation: Updated README with new features and examples

🔧 Technical Improvements #

Core Changes

• Added BypassedState to the state management system
• Enhanced GuardoService with hasAuthenticationMethods getter
• Improved initialization flow to check authentication availability first
• Updated lifecycle management to respect enabled/disabled state

API Updates

• lockApp() is now Future<void> lockApp() (breaking change)
• Added Future<bool> hasAuthenticationMethods() extension method
• Added bool isGuardoEnabled() extension method
• Added enabled: bool property to Guardo widget (defaults to true)

📚 Documentation #

• Updated README.md with comprehensive examples of new features
• Added "What's New" section highlighting v0.1.0 features
• Enhanced troubleshooting guide with new scenarios
• Updated API reference with new methods and properties

🐛 Bug Fixes #

• Fixed BuildContext async gap warning in example app
• Improved error handling when authentication methods are unavailable
• Better state management for edge cases

⚠️ Breaking Changes #

• context.lockApp() is now async: await context.lockApp()
• Apps using lockApp() will need to add await and handle potential UnsupportedError

🔄 Migration Guide #

For lockApp() Usage

// Before (v0.0.1)
context.lockApp();

// After (v0.1.0)
try {
  await context.lockApp();
} catch (e) {
  // Handle case where authentication is disabled/unavailable
  print('Cannot lock: $e');
}

Using New Features

// Enable/disable authentication
Guardo(
  enabled: !kDebugMode, // Disable in debug mode
  child: MyApp(),
)

// Check authentication availability
if (await context.hasAuthenticationMethods()) {
  await context.lockApp(); // Safe to lock
}

// Check if Guardo is enabled
if (context.isGuardoEnabled()) {
  // Authentication is active
}

---

🎉 Initial Release #

Core Features

• Biometric Authentication: Support for fingerprint, Face ID, and other biometric methods
• Device Credentials Fallback: Automatic fallback to PIN/Pattern/Password when biometrics are locked out
• Automatic Lockout Handling: Smart handling of temporary and permanent biometric lockouts
• Customizable Lock Screens: Build your own lock screen or use the default
• Auto-lock Timer: Configurable inactivity timeout
• App Lifecycle Management: Proper handling of app resume/pause states

Developer Experience

• Extension Methods: Convenient BuildContext extensions for easy integration
• Comprehensive Error Handling: Typed exceptions with detailed error information
• State Management: Built-in state notifier with reactive updates
• Debug Support: Extensive logging and debugging capabilities

Authentication Actions

• Secure Actions: Execute actions that require authentication
• Async Actions: Handle asynchronous operations with authentication
• Actions with Results: Execute operations that require authentication and return values
• Device Capability Checks: Check device biometric capabilities

Platform Support

• iOS: Face ID, Touch ID support (iOS 9.0+)
• Android: Fingerprint, Face, Iris support (Android API 23+)
• Cross-platform: Consistent API across both platforms

UI Components

• Multiple States: Loading, authenticated, locked, error, and failed states
• Theme Support: Light and dark theme compatibility
• Accessibility: Full screen reader support and WCAG compliance
• Customizable: Extensive customization options for UI components