💥 Breaking Changes #

• API Alignment: Refactored core data models (ShortLinkEntity, CreateShortLinkRequest) to align with the backend API specification. This is a major breaking change affecting how short links are created and parsed.
• Simplified Fields: Removed customAlias, expiresAt, and metadata from CreateShortLinkRequest to match the new API DTO.
• Entity Structure: ShortLinkEntity now includes pageType, pageId, and deepLinkPath directly, and no longer contains a nested ShortLinkStats object in its constructor for API responses.

🔧 Fixed #

• Compilation Errors: Fixed all compilation errors across the facade, factory, and repository layers caused by the data model refactoring.
• In-Memory Repository: Updated MemoryShortLinkRepository to correctly handle the new entity structure and request objects.

✨ Improved #

• API-First Design: The data models are now a direct reflection of the backend API, ensuring more reliable network communication.
• Code Consistency: Ensured that all layers of the application now use the same, consistent data structures for creating and handling short links.

---

🚀 Major Improvements #

• HTTP Repository: Enabled HTTP repository by default (useHttpRepository: true)
• Real HTTP Client: Replaced mock HTTP client with actual Dio implementation
• Network Logging: Added comprehensive request/response logging for debugging
• Error Handling: Enhanced DioException handling with detailed error messages

🔧 Fixed #

• NoSuchMethodError: Fixed createShortLink() method not existing (use createLink() instead)
• Mock HTTP Client: Replaced with real Dio-based HTTP client for actual network requests
• Network Requests: HTTP requests now actually reach the configured API server
• Debug Logging: Added detailed logging to track network requests and responses

📚 API Clarification #

• Correct Method: Use createLink(GenericLinkRequest) instead of non-existent createShortLink()
• Share Methods: share() and shareLink() return void (not null) - this is expected behavior
• GenericLinkRequest.curation(): Confirmed working correctly with curationType and id parameters

⚡ Performance #

• Real Network Requests: HTTP calls now use Dio client with proper timeout and error handling
• Request Interceptors: Added logging interceptors for debugging network issues
• Connection Management: Proper connection pooling and timeout configuration

🔧 Fixed #

• Repository Selection: Fixed HTTP repository not being used when useHttpRepository: true
• System Initializer: Added conditional repository initialization based on configuration
• Fallback Mechanism: Added graceful fallback to memory repository when HTTP repository fails

✨ Improved #

• Testing Support: Added repositoryType getter for testing repository selection
• Error Handling: Enhanced error handling with fallback strategies

🎉 Initial Release #

✨ Added

• Core Domain Entities

  • DeepLinkEntity - Comprehensive deep link representation
  • ShortLinkEntity - Short URL management with analytics
  • NavigationRouteEntity - Route configuration and metadata
  • Result<T> - Functional error handling pattern

• DeepLink Management System

  • Universal Link Support for both app schemes and web URLs
  • Parametrized link processing with query parameter extraction
  • Fallback strategies for handling unknown or malformed links
  • Route validation to ensure links point to valid destinations
  • Preview mode for debugging and testing deeplinks

• Short URL System

  • HTTP-based short link creation and management
  • Click analytics with geographic, device, and referrer tracking
  • Expiration management with time-based link expiration
  • Custom alias support for branded short links
  • Batch operations for efficient multiple link creation

• Framework-Agnostic DI System

  • Support for GetX, get_it, Provider, and built-in DI
  • Automatic adapter detection and initialization
  • Custom adapter interface for extending to other DI frameworks
  • Comprehensive lifecycle management with disposable pattern

• Configuration Management

  • Environment-based configuration (development, staging, production)
  • Runtime configuration modification without rebuilding
  • Security controls including domain whitelisting and rate limiting
  • Performance tuning with caching and request optimization

• Enterprise Features

  • Comprehensive logging with debug, performance, and error tracking
  • Type safety with full Dart null safety support
  • Testing utilities with built-in mocks and test helpers
  • Performance optimization with caching and request coalescing

🏗️ Architecture Components

• Domain Layer: Pure business logic with entities, repositories, and services
• Application Layer: Use cases, factories, and facades orchestrating domain logic
• Infrastructure Layer: External integrations, HTTP clients, and platform services
• Configuration Layer: Framework-agnostic setup and dependency management

🔧 Integration Points

• GetX Integration: Seamless integration with GetX state management and routing
• get_it Integration: Support for get_it service locator pattern
• Built-in DI: No external dependencies required for basic functionality
• Custom DI: Extensible adapter pattern for any DI framework

📱 Platform Support

• ✅ Android - App Links and Custom Schemes
• ✅ iOS - Universal Links and Custom Schemes
• ✅ Web - URL Routing with History API
• ✅ macOS - Custom URL Schemes
• ✅ Windows - Protocol Registration
• ✅ Linux - Desktop Integration

🧪 Testing Support

• Unit test utilities with mock implementations
• Integration test helpers for end-to-end scenarios
• Test configuration presets for different environments
• Comprehensive example app demonstrating all features

📚 Documentation

• Complete README with quickstart guide
• API documentation with detailed examples
• Architecture overview with diagrams
• Migration guides for existing implementations
• Best practices and common patterns

🛡️ Security Features #

• URL validation with configurable domain whitelisting
• Rate limiting to prevent abuse
• Input sanitization and validation
• Secure error handling without information leakage

⚡ Performance Features #

• Request caching with configurable timeout
• Request coalescing to prevent duplicate operations
• Lazy loading of non-critical components
• Memory-efficient data structures
• Optimized batch operations

🔍 Debugging & Monitoring #

• Detailed logging with configurable levels
• Performance metrics and timing information
• Error tracking with context preservation
• System status reporting and diagnostics
• Preview mode for deeplink testing

[Unreleased] #

🔮 Planned Features #

• Analytics dashboard integration
• A/B testing support for deeplinks
• Advanced caching strategies
• GraphQL integration for short links
• Custom domain support
• QR code generation
• Link expiration notifications
• Webhook integration for link events

---

Migration Guide #

From Custom Implementation #

If you're migrating from a custom deeplink implementation:

1. Install the package:

   dependencies:
     flutter_deeplink_architect: ^1.0.0
   

2. Initialize the system:

   final config = DeepLinkConfig.defaults(
     appScheme: 'your-app-scheme',
     baseUrl: 'https://your-domain.com',
   );
   await DeepLinkArchitect.initialize(config);
   

3. Replace deeplink handling:

   // Old way
   void handleDeepLink(String url) {
     // Custom parsing and routing logic
   }
      
   // New way
   final facade = DIContainer.get<DeepLinkFacade>();
   final success = await facade.handleDeepLink(url);
   

4. Update short link creation:

   // Old way
   final shortUrl = await createShortLink(originalUrl);
      
   // New way
   final shortUrl = await facade.createPageLink(
     pageType: 'product',
     pageId: productId,
     originalUrl: originalUrl,
   );
   

Breaking Changes #

• None (initial release)

Deprecations #

• None (initial release)

---

For more information, visit our GitHub repository.