feat: Enhance configuration documentation and integrate OTP routing in HomeScreen and TransportList (#810)

Author: SamuelRioTz

apps/example/README.md

@@ -86,13 +86,76 @@ flutter run
 
 ## Configuration
 
-The app is configured to use:
-- **OTP Endpoint**: `https://otp-240.trufi-core.trufi.dev`
+All configuration is at the top of [lib/main.dart](lib/main.dart). Modify these values for your deployment:
+
+### Required Parameters
+
+| Parameter | Description |
+|-----------|-------------|
+| `_otpConfiguration` | OTP server endpoint and version for route planning |
+| `_photonUrl` | Geocoding service URL for location search |
+| `_defaultCenter` | Initial map coordinates (latitude, longitude) |
+
+### OTP Version
+
+**IMPORTANT:** The `OtpVersion` must match your OTP server exactly:
+
+| Version | API Type | Notes |
+|---------|----------|-------|
+| `OtpVersion.v1_5` | REST | Legacy servers |
+| `OtpVersion.v2_4` | GraphQL | Most common |
+| `OtpVersion.v2_8` | GraphQL | Latest, with emissions support |
+
+Using the wrong version will cause routing errors.
+
+### App Identity
+
+| Parameter | Description |
+|-----------|-------------|
+| `_appName` | Display name in UI and shared routes |
+| `_deepLinkScheme` | URL scheme for deep links (e.g., `trufiapp://route/...`) |
+| `_cityName` | City name for About screen |
+| `_countryName` | Country name for About screen |
+| `_emailContact` | Support email |
+
+### URLs
+
+| Parameter | Description |
+|-----------|-------------|
+| `_feedbackUrl` | User feedback form URL |
+| `_facebookUrl` | Facebook page URL |
+| `_xTwitterUrl` | X (Twitter) profile URL |
+| `_instagramUrl` | Instagram profile URL |
+
+### Geocoding Services
+
+Two geocoding services are available:
+
+**PhotonSearchService** (default):
+```dart
+PhotonSearchService(
+  baseUrl: 'https://photon.komoot.io',  // Required
+  biasLatitude: -17.39,                  // Optional: prioritize nearby results
+  biasLongitude: -66.16,
+)
+```
+
+**NominatimSearchService** (alternative):
+```dart
+NominatimSearchService(
+  baseUrl: 'https://nominatim.openstreetmap.org',  // Required
+  userAgent: 'MyApp/1.0',                          // Required
+  countryCodes: ['bo'],                            // Optional: filter by country
+)
+```
+
+### Current Values
+
+- **OTP Endpoint**: `https://otp-240.trufi-core.trufi.dev` (v2.4)
 - **Default Location**: Cochabamba, Bolivia (-17.3988354, -66.1626903)
-- **Map Engines**: MapLibre GL and Flutter Map
+- **Map Engines**: MapLibre (Liberty and Dark styles)
 - **Deep Link Scheme**: `trufiapp://`
 - **POI Layers**: Tourism, Food, and Transport categories enabled by default
-- **POI Data**: Sample GeoJSON data for Cochabamba included in `assets/pois/`
 
 ## Dependencies
 

apps/example/lib/main.dart

@@ -9,19 +9,37 @@ import 'package:trufi_core_home_screen/trufi_core_home_screen.dart';
 import 'package:trufi_core_maps/trufi_core_maps.dart';
 import 'package:trufi_core_navigation/trufi_core_navigation.dart';
 import 'package:trufi_core_poi_layers/trufi_core_poi_layers.dart';
+import 'package:trufi_core_routing/trufi_core_routing.dart'
+    show OtpConfiguration, OtpVersion;
 import 'package:trufi_core_saved_places/trufi_core_saved_places.dart';
 import 'package:trufi_core_search_locations/trufi_core_search_locations.dart';
 import 'package:trufi_core_settings/trufi_core_settings.dart';
 import 'package:trufi_core_transport_list/trufi_core_transport_list.dart';
 import 'package:trufi_core_ui/trufi_core_ui.dart';
 
+// ============ CONFIGURATION ============
+const _otpConfiguration = OtpConfiguration(
+  endpoint: 'https://otp-240.trufi-core.trufi.dev',
+  version: OtpVersion.v2_4,
+);
+const _photonUrl = 'https://photon.komoot.io';
 const _defaultCenter = LatLng(-17.3988354, -66.1626903);
+const _appName = 'Trufi App';
+const _deepLinkScheme = 'trufiapp';
+const _cityName = 'Cochabamba';
+const _countryName = 'Bolivia';
+const _emailContact = 'info@trufi-association.org';
+const _feedbackUrl = 'https://www.trufi-association.org/feedback/';
+const _facebookUrl = 'https://facebook.com/trufiapp';
+const _xTwitterUrl = 'https://x.com/trufiapp';
+const _instagramUrl = 'https://instagram.com/trufiapp';
+// ========================================
 
 void main() {
   runTrufiApp(
     AppConfiguration(
-      appName: 'Trufi App',
-      deepLinkScheme: 'trufiapp',
+      appName: _appName,
+      deepLinkScheme: _deepLinkScheme,
       defaultLocale: Locale('es'),
       appOverlayManagers: [
         OnboardingManager(
@@ -35,17 +53,17 @@ void main() {
       ],
       socialMediaLinks: const [
         SocialMediaLink(
-          url: 'https://facebook.com/trufiapp',
+          url: _facebookUrl,
           icon: Icons.facebook,
           label: 'Facebook',
         ),
         SocialMediaLink(
-          url: 'https://x.com/trufiapp',
+          url: _xTwitterUrl,
           icon: Icons.close,
           label: 'X (Twitter)',
         ),
         SocialMediaLink(
-          url: 'https://instagram.com/trufiapp',
+          url: _instagramUrl,
           icon: Icons.camera_alt_outlined,
           label: 'Instagram',
         ),
@@ -60,6 +78,7 @@ void main() {
         BlocProvider(
           create: (_) => SearchLocationsCubit(
             searchLocationService: PhotonSearchService(
+              baseUrl: _photonUrl,
               biasLatitude: _defaultCenter.latitude,
               biasLongitude: _defaultCenter.longitude,
             ),
@@ -69,9 +88,9 @@ void main() {
       screens: [
         HomeScreenTrufiScreen(
           config: HomeScreenConfig(
-            otpEndpoint: 'https://otp-240.trufi-core.trufi.dev',
-            appName: 'Trufi App',
-            deepLinkScheme: 'trufiapp',
+            otpConfiguration: _otpConfiguration,
+            appName: _appName,
+            deepLinkScheme: _deepLinkScheme,
             poiLayersManager: POILayersManager(assetsBasePath: 'assets/pois'),
           ),
           onStartNavigation: (context, itinerary, locationService) {
@@ -85,9 +104,7 @@ void main() {
         ),
         SavedPlacesTrufiScreen(),
         TransportListTrufiScreen(
-          config: TransportListOtpConfig(
-            otpEndpoint: 'https://otp-240.trufi-core.trufi.dev',
-          ),
+          otpConfiguration: _otpConfiguration,
         ),
         FaresTrufiScreen(
           config: FaresConfig(
@@ -119,16 +136,16 @@ void main() {
         ),
         FeedbackTrufiScreen(
           config: FeedbackConfig(
-            feedbackUrl: 'https://www.trufi-association.org/feedback/',
+            feedbackUrl: _feedbackUrl,
           ),
         ),
         SettingsTrufiScreen(),
         AboutTrufiScreen(
           config: AboutScreenConfig(
-            appName: 'Trufi App',
-            cityName: 'Cochabamba',
-            countryName: 'Bolivia',
-            emailContact: 'info@trufi-association.org',
+            appName: _appName,
+            cityName: _cityName,
+            countryName: _countryName,
+            emailContact: _emailContact,
           ),
         ),
       ],

packages/screens/trufi_core_home_screen/example/lib/main.dart

@@ -6,6 +6,8 @@ import 'package:provider/provider.dart';
 import 'package:trufi_core_home_screen/trufi_core_home_screen.dart';
 import 'package:trufi_core_maps/trufi_core_maps.dart';
 import 'package:trufi_core_poi_layers/trufi_core_poi_layers.dart';
+import 'package:trufi_core_routing/trufi_core_routing.dart'
+    show OtpConfiguration, OtpVersion;
 import 'package:trufi_core_search_locations/trufi_core_search_locations.dart';
 
 void main() async {
@@ -17,14 +19,19 @@ void main() async {
 class MyApp extends StatelessWidget {
   static const _defaultCenter = LatLng(-17.3988354, -66.1626903);
   static const _otpEndpoint = 'https://otp-240.trufi-core.trufi.dev';
+  static const _otpVersion = OtpVersion.v2_4;
+  static const _photonUrl = 'https://photon.komoot.io';
 
   const MyApp({super.key});
 
   @override
   Widget build(BuildContext context) {
     final screen = HomeScreenTrufiScreen(
       config: HomeScreenConfig(
-        otpEndpoint: _otpEndpoint,
+        otpConfiguration: OtpConfiguration(
+          endpoint: _otpEndpoint,
+          version: _otpVersion,
+        ),
         poiLayersManager: POILayersManager(
           assetsBasePath: 'assets/pois',
         ),
@@ -42,6 +49,7 @@ class MyApp extends StatelessWidget {
         BlocProvider(
           create: (_) => SearchLocationsCubit(
             searchLocationService: PhotonSearchService(
+              baseUrl: _photonUrl,
               biasLatitude: _defaultCenter.latitude,
               biasLongitude: _defaultCenter.longitude,
             ),

packages/screens/trufi_core_home_screen/example/pubspec.lock

@@ -976,7 +976,7 @@ packages:
     source: path
     version: "1.0.0"
   trufi_core_routing:
-    dependency: "direct overridden"
+    dependency: "direct main"
     description:
       path: "../../../trufi_core_routing"
       relative: true

packages/screens/trufi_core_home_screen/example/pubspec.yaml

@@ -19,6 +19,8 @@ dependencies:
     path: ../../../trufi_core_search_locations
   trufi_core_poi_layers:
     path: ../../../trufi_core_poi_layers
+  trufi_core_routing:
+    path: ../../../trufi_core_routing
   flutter_bloc: ^9.1.1
   latlong2: ^0.9.1
   provider: ^6.0.0

packages/screens/trufi_core_home_screen/lib/src/config/home_screen_config.dart

@@ -1,21 +1,19 @@
 import 'package:trufi_core_maps/trufi_core_maps.dart';
 import 'package:trufi_core_poi_layers/trufi_core_poi_layers.dart';
+import 'package:trufi_core_routing/trufi_core_routing.dart' show OtpConfiguration;
 import 'package:trufi_core_search_locations/trufi_core_search_locations.dart';
 
 /// Configuration for the Home Screen module.
 class HomeScreenConfig {
-  /// OTP server endpoint for route planning
-  final String otpEndpoint;
+  /// OTP configuration for route planning
+  final OtpConfiguration otpConfiguration;
 
   /// Zoom level when choosing a location
   final double chooseLocationZoom;
 
   /// Search service for location search (defaults to Photon)
   final SearchLocationService? searchService;
 
-  /// Photon server URL for search (used if searchService is not provided)
-  final String photonUrl;
-
   /// List of saved places to show in search (Home, Work, etc.)
   /// Only used if SavedPlacesCubit is not available in context.
   final List<SearchLocation> myPlaces;
@@ -59,10 +57,9 @@ class HomeScreenConfig {
   final POILayersManager? poiLayersManager;
 
   const HomeScreenConfig({
-    required this.otpEndpoint,
+    required this.otpConfiguration,
     this.chooseLocationZoom = 16.0,
     this.searchService,
-    this.photonUrl = 'https://photon.komoot.io/api/',
     this.myPlaces = const [],
     this.appName,
     this.deepLinkScheme,

packages/screens/trufi_core_home_screen/lib/src/home_screen_trufi_screen.dart

@@ -52,9 +52,7 @@ class HomeScreenTrufiScreen extends TrufiScreen {
     _repository = repository ?? HomeScreenRepositoryImpl();
     _requestService =
         requestService ??
-        RoutingRequestPlanService(
-          routing.OtpConfiguration(endpoint: config.otpEndpoint),
-        );
+        RoutingRequestPlanService(config.otpConfiguration);
     _routingPreferencesManager = routing.RoutingPreferencesManager();
   }
 

packages/screens/trufi_core_home_screen/test/trufi_core_home_screen_test.dart

@@ -1,5 +1,7 @@
 import 'package:flutter_test/flutter_test.dart';
 import 'package:trufi_core_home_screen/trufi_core_home_screen.dart';
+import 'package:trufi_core_routing/trufi_core_routing.dart'
+    show OtpConfiguration, OtpVersion;
 
 void main() {
   group('RoutePlannerState', () {
@@ -49,21 +51,28 @@ void main() {
 
   group('HomeScreenConfig', () {
     test('has correct defaults', () {
-      const config = HomeScreenConfig(otpEndpoint: 'https://example.com');
+      const config = HomeScreenConfig(
+        otpConfiguration: OtpConfiguration(
+          endpoint: 'https://example.com',
+          version: OtpVersion.v2_4,
+        ),
+      );
 
       expect(config.chooseLocationZoom, equals(16.0));
       expect(config.myPlaces, isEmpty);
     });
 
     test('can set custom values', () {
       const config = HomeScreenConfig(
-        otpEndpoint: 'https://example.com',
+        otpConfiguration: OtpConfiguration(
+          endpoint: 'https://example.com',
+          version: OtpVersion.v2_8,
+        ),
         chooseLocationZoom: 18.0,
-        photonUrl: 'https://custom.photon.url/api/',
       );
 
       expect(config.chooseLocationZoom, equals(18.0));
-      expect(config.photonUrl, equals('https://custom.photon.url/api/'));
+      expect(config.otpConfiguration.version, equals(OtpVersion.v2_8));
     });
   });
 }

packages/screens/trufi_core_transport_list/example/lib/main.dart

@@ -3,6 +3,8 @@ import 'package:flutter_localizations/flutter_localizations.dart';
 import 'package:latlong2/latlong.dart';
 import 'package:provider/provider.dart';
 import 'package:trufi_core_maps/trufi_core_maps.dart';
+import 'package:trufi_core_routing/trufi_core_routing.dart'
+    show OtpConfiguration, OtpVersion;
 import 'package:trufi_core_transport_list/trufi_core_transport_list.dart';
 
 void main() {
@@ -12,13 +14,17 @@ void main() {
 class MyApp extends StatelessWidget {
   static const _defaultCenter = LatLng(-17.3988354, -66.1626903);
   static const _otpEndpoint = 'https://otp-240.trufi-core.trufi.dev';
+  static const _otpVersion = OtpVersion.v2_4;
 
   const MyApp({super.key});
 
   @override
   Widget build(BuildContext context) {
     final screen = TransportListTrufiScreen(
-      config: TransportListOtpConfig(otpEndpoint: _otpEndpoint),
+      otpConfiguration: OtpConfiguration(
+        endpoint: _otpEndpoint,
+        version: _otpVersion,
+      ),
     );
 
     return MultiProvider(

packages/screens/trufi_core_transport_list/example/pubspec.lock

@@ -1007,7 +1007,7 @@ packages:
     source: path
     version: "1.0.0"
   trufi_core_routing:
-    dependency: "direct overridden"
+    dependency: "direct main"
     description:
       path: "../../../trufi_core_routing"
       relative: true