diff --git a/CHANGELOG.md b/CHANGELOG.md index cfea98a..2375a3c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,14 @@ +## 1.0.0 + +- **BREAKING**: Raised the minimum Dart SDK version to 3.12.0. +- **BREAKING**: Platform implementations must implement the new abstract query methods and accept `packageNamePrefix` in their `listApps` override. +- Added `isAppInstalled`, `isSystemApp`, `isAppEnabled`, and `isAppLaunchable` to query app state without loading full app metadata. +- Added `getAppIcon` to retrieve an app icon separately as PNG bytes. +- Added `getInstallSourceInfo` and the `AppInstallSourceInfo` model with `installingPackageName`, `initiatingPackageName`, `originatingPackageName`, `packageSource`, and `updateOwnerPackageName`. +- Deprecated `getInstallerStore`. Use `getInstallSourceInfo` and its `installingPackageName` field instead. +- Added the optional `packageNamePrefix` filter to `listApps`. Matching is case-sensitive; null or empty disables the filter. +- Updated package topics and directed issue reports to the main `flutter_device_apps` repository. + ## 0.7.0 - Expanded `AppInfo` with additional Android raw metadata fields: `uid`, `apkPath`, `apkSizeBytes`, `dataPath`, and `isOnExternalStorage`. - Updated `AppInfo` unit tests to cover parsing and null-safety behavior for the new fields. diff --git a/analysis_options.yaml b/analysis_options.yaml index e6bfde7..e254b4d 100644 --- a/analysis_options.yaml +++ b/analysis_options.yaml @@ -20,9 +20,7 @@ linter: avoid_init_to_null: true avoid_js_rounded_ints: true avoid_multiple_declarations_per_line: true - avoid_null_checks_in_equality_operators: true avoid_print: true - avoid_private_typedef_functions: true avoid_redundant_argument_values: true avoid_renaming_method_parameters: true avoid_return_types_on_setters: true @@ -84,7 +82,7 @@ linter: no_leading_underscores_for_local_identifiers: true no_literal_bool_comparisons: true no_logic_in_create_state: true - no_runtimeType_toString: true + no_runtimeType_tostring: true no_self_assignments: true no_wildcard_variable_uses: true non_constant_identifier_names: true @@ -148,7 +146,6 @@ linter: type_init_formals: true type_literal_in_constant_pattern: true unawaited_futures: true - unnecessary_await_in_return: true unnecessary_brace_in_string_interps: true unnecessary_breaks: true unnecessary_const: true @@ -178,7 +175,6 @@ linter: use_enums: true use_full_hex_values_for_flutter_colors: true use_function_type_syntax_for_parameters: true - use_if_null_to_convert_nulls_to_bools: true use_is_even_rather_than_modulo: true use_late_for_private_fields_and_variables: true use_named_constants: true @@ -199,15 +195,22 @@ linter: unnecessary_library_name: true use_truncating_division: true strict_top_level_inference: true - unnecessary_async: true + unnecessary_async: false unnecessary_underscores: true unsafe_variance: true + simplify_variable_pattern: true specify_nonobvious_property_types: true switch_on_type: true unnecessary_ignore: true unnecessary_unawaited: true use_null_aware_elements: true - public_member_api_docs: true + simple_directive_paths: true + var_with_no_type_annotation: true + empty_container_bodies: true + initialize_in_field_declaration: true + unnecessary_primary_constructor_body: true + use_declaring_parameters: true + migrate_design_widgets: true ###------------------------------------------------------- omit_local_variable_types: false use_setters_to_change_properties: false @@ -215,7 +218,6 @@ linter: unnecessary_final: false prefer_expression_function_bodies: false prefer_null_aware_method_calls: false - prefer_final_parameters: false prefer_if_elements_to_conditional_expressions: false prefer_double_quotes: false avoid_catches_without_on_clauses: false @@ -232,9 +234,15 @@ linter: flutter_style_todos: false eol_at_end_of_file: false lines_longer_than_80_chars: false - one_member_abstracts: false + public_member_api_docs: false use_build_context_synchronously: false do_not_use_environment: false omit_obvious_local_variable_types: false unintended_html_in_doc_comment: false omit_obvious_property_types: false + unnecessary_type_name_in_constructor: false + async_return_with_no_await: false + no_raw_types: false + unnecessary_const_in_enum_constructor: false + no_dynamic_casts: false + remove_deprecations_in_breaking_versions: false diff --git a/lib/flutter_device_apps_app_change_event.dart b/lib/flutter_device_apps_app_change_event.dart index 5c4f8c0..a924597 100644 --- a/lib/flutter_device_apps_app_change_event.dart +++ b/lib/flutter_device_apps_app_change_event.dart @@ -17,11 +17,7 @@ class AppChangeEvent { /// Creates an [AppChangeEvent] with the specified properties. /// /// All parameters are optional and represent the details of the app change. - const AppChangeEvent({ - this.packageName, - this.type, - this.isReplacing, - }); + const AppChangeEvent({this.packageName, this.type, this.isReplacing}); /// Creates an [AppChangeEvent] from a map of key-value pairs. /// @@ -30,8 +26,9 @@ class AppChangeEvent { factory AppChangeEvent.fromMap(Map m) { final String? pkg = m['packageName']?.toString(); final String? t = m['type']?.toString(); - final bool? replacing = - m['isReplacing'] != null ? bool.tryParse(m['isReplacing']!.toString()) : null; + final bool? replacing = m['isReplacing'] != null + ? bool.tryParse(m['isReplacing']!.toString()) + : null; return AppChangeEvent( packageName: pkg, @@ -53,15 +50,15 @@ class AppChangeEvent { /// /// Useful for serialization to platform channels or other data formats. Map toMap() => { - 'packageName': packageName, - 'type': type?.name, - 'isReplacing': isReplacing, - }; + 'packageName': packageName, + 'type': type?.name, + 'isReplacing': isReplacing, + }; static AppChangeType? _parseType(String raw) => switch (raw) { - 'installed' => AppChangeType.installed, - 'removed' => AppChangeType.removed, - 'updated' => AppChangeType.updated, - _ => null, - }; + 'installed' => AppChangeType.installed, + 'removed' => AppChangeType.removed, + 'updated' => AppChangeType.updated, + _ => null, + }; } diff --git a/lib/flutter_device_apps_platform_interface.dart b/lib/flutter_device_apps_platform_interface.dart index 916a775..f00f208 100644 --- a/lib/flutter_device_apps_platform_interface.dart +++ b/lib/flutter_device_apps_platform_interface.dart @@ -38,24 +38,31 @@ class AppInfo { /// The map typically comes from platform-specific implementations. /// Handles type conversion and null safety for various data types. factory AppInfo.fromMap(Map m) { - final int? firstInstallTime = - m['firstInstallTime'] != null ? int.tryParse(m['firstInstallTime']!.toString()) : null; - final DateTime? firstInstallTimeDate = - firstInstallTime != null ? DateTime.fromMillisecondsSinceEpoch(firstInstallTime) : null; - - final int? lastUpdateTime = - m['lastUpdateTime'] != null ? int.tryParse(m['lastUpdateTime']!.toString()) : null; - final DateTime? lastUpdateTimeDate = - lastUpdateTime != null ? DateTime.fromMillisecondsSinceEpoch(lastUpdateTime) : null; + final int? firstInstallTime = m['firstInstallTime'] != null + ? int.tryParse(m['firstInstallTime']!.toString()) + : null; + final DateTime? firstInstallTimeDate = firstInstallTime != null + ? DateTime.fromMillisecondsSinceEpoch(firstInstallTime) + : null; + + final int? lastUpdateTime = m['lastUpdateTime'] != null + ? int.tryParse(m['lastUpdateTime']!.toString()) + : null; + final DateTime? lastUpdateTimeDate = lastUpdateTime != null + ? DateTime.fromMillisecondsSinceEpoch(lastUpdateTime) + : null; final int? category = m['category'] != null ? int.tryParse(m['category']!.toString()) : null; - final int? targetSdkVersion = - m['targetSdkVersion'] != null ? int.tryParse(m['targetSdkVersion']!.toString()) : null; - final int? minSdkVersion = - m['minSdkVersion'] != null ? int.tryParse(m['minSdkVersion']!.toString()) : null; + final int? targetSdkVersion = m['targetSdkVersion'] != null + ? int.tryParse(m['targetSdkVersion']!.toString()) + : null; + final int? minSdkVersion = m['minSdkVersion'] != null + ? int.tryParse(m['minSdkVersion']!.toString()) + : null; final bool? enabled = m['enabled'] != null ? bool.tryParse(m['enabled']!.toString()) : null; - final int? installLocation = - m['installLocation'] != null ? int.tryParse(m['installLocation']!.toString()) : null; + final int? installLocation = m['installLocation'] != null + ? int.tryParse(m['installLocation']!.toString()) + : null; return AppInfo( packageName: m['packageName']?.toString(), @@ -72,8 +79,9 @@ class AppInfo { firstInstallTime: firstInstallTimeDate, lastUpdateTime: lastUpdateTimeDate, isSystem: m['isSystem'] != null ? bool.tryParse(m['isSystem']!.toString()) : null, - iconBytes: - m['iconBytes'] is List ? Uint8List.fromList(m['iconBytes']! as List) : null, + iconBytes: m['iconBytes'] is List + ? Uint8List.fromList(m['iconBytes']! as List) + : null, category: category, targetSdkVersion: targetSdkVersion, minSdkVersion: minSdkVersion, @@ -145,6 +153,50 @@ class AppInfo { final int? installLocation; } +/// Information about how an app was installed. +class AppInstallSourceInfo { + /// Creates installation source information with optional platform metadata. + const AppInstallSourceInfo({ + this.installingPackageName, + this.initiatingPackageName, + this.originatingPackageName, + this.packageSource, + this.updateOwnerPackageName, + }); + + /// Creates installation source information from a platform map. + factory AppInstallSourceInfo.fromMap(Map m) => AppInstallSourceInfo( + installingPackageName: m['installingPackageName']?.toString(), + initiatingPackageName: m['initiatingPackageName']?.toString(), + originatingPackageName: m['originatingPackageName']?.toString(), + packageSource: m['packageSource'] != null ? int.tryParse(m['packageSource']!.toString()) : null, + updateOwnerPackageName: m['updateOwnerPackageName']?.toString(), + ); + + /// The installer of record, or null when unavailable. + /// + /// This value can be changed after installation. Null does not establish + /// whether an app was sideloaded. + final String? installingPackageName; + + /// The package that requested installation (Android API 30+). + final String? initiatingPackageName; + + /// The package on whose behalf installation was requested (Android API 30+). + /// + /// Supplied by the installer and not verified by Android. Access is restricted + /// by Android permissions, so this value is usually null for ordinary apps. + final String? originatingPackageName; + + /// Raw Android PackageInstaller.PACKAGE_SOURCE_* value (API 33+). + /// + /// Null on older Android versions. Zero means the source is unspecified. + final int? packageSource; + + /// The package owning updates (Android API 34+), or null when unavailable. + final String? updateOwnerPackageName; +} + /// Base class every platform implementation must extend. abstract class FlutterDeviceAppsPlatform extends PlatformInterface { /// Creates a [FlutterDeviceAppsPlatform] with the provided [token]. @@ -168,15 +220,50 @@ abstract class FlutterDeviceAppsPlatform extends PlatformInterface { } /// Lists installed apps. + /// + /// [packageNamePrefix] filters package names with a case-sensitive prefix + /// before loading app metadata and icons. Null or empty disables this filter. Future> listApps({ bool includeSystem = false, bool onlyLaunchable = true, bool includeIcons = false, + String? packageNamePrefix, }); /// Gets details for a single app. Future getApp(String packageName, {bool includeIcon = false}); + /// Gets the app icon as PNG bytes without loading the full app metadata. + /// + /// Returns null when the package is missing, not visible, or its icon resources + /// cannot be loaded. Returns Android's default icon if no icon is defined. + Future getAppIcon(String packageName); + + /// Whether [packageName] is installed and visible to the calling app. + /// + /// Includes disabled apps and apps without a launcher entry. Returns false + /// when the package is missing or hidden by Android package visibility rules. + Future isAppInstalled(String packageName); + + /// Whether [packageName] is a system app, using the same flag as [AppInfo.isSystem]. + /// + /// Returns null when the package is missing or hidden by Android package + /// visibility rules. Includes disabled apps and apps without a launcher entry. + Future isSystemApp(String packageName); + + /// Whether [packageName] is enabled, using the same value as [AppInfo.enabled]. + /// + /// Returns null when the package is missing or hidden by Android package + /// visibility rules. An enabled app may still have no launchable activity. + Future isAppEnabled(String packageName); + + /// Whether Android provides a launch intent for [packageName], as in [openApp]. + /// + /// Does not open the app. Returns false when the package is missing, not + /// visible, or has no suitable entry activity. True does not guarantee that + /// a subsequent launch will succeed. + Future isAppLaunchable(String packageName); + /// Gets the requested permissions for a specific app. /// /// Implementations should return the Android PackageInfo.requestedPermissions @@ -207,10 +294,19 @@ abstract class FlutterDeviceAppsPlatform extends PlatformInterface { /// Returns true if the app was successfully uninstalled, false otherwise. Future uninstallApp(String packageName); + /// Gets installation source information without loading full app metadata. + /// + /// Returns null when the package is missing or not visible. On Android before + /// API 30, only installingPackageName is available. A returned model can have + /// null fields when Android does not provide the corresponding information. + Future getInstallSourceInfo(String packageName); + /// Gets the installer store for the specified package name. /// /// Platform implementations should return the installer store for the given package. /// Returns the installer store name or null if not available. + // Newly deprecated; retain the method for backwards compatibility. + @Deprecated('Use getInstallSourceInfo() and its installingPackageName instead.') Future getInstallerStore(String packageName); } @@ -223,13 +319,33 @@ class _UnimplementedPlatform extends FlutterDeviceAppsPlatform { bool includeSystem = false, bool onlyLaunchable = true, bool includeIcons = false, - }) => - Future.error(UnsupportedError('FlutterDeviceAppsPlatform not implemented')); + String? packageNamePrefix, + }) => Future.error(UnsupportedError('FlutterDeviceAppsPlatform not implemented')); @override Future getApp(String packageName, {bool includeIcon = false}) => Future.error(UnsupportedError('FlutterDeviceAppsPlatform not implemented')); + @override + Future getAppIcon(String packageName) => + Future.error(UnsupportedError('FlutterDeviceAppsPlatform not implemented')); + + @override + Future isAppInstalled(String packageName) => + Future.error(UnsupportedError('FlutterDeviceAppsPlatform not implemented')); + + @override + Future isSystemApp(String packageName) => + Future.error(UnsupportedError('FlutterDeviceAppsPlatform not implemented')); + + @override + Future isAppEnabled(String packageName) => + Future.error(UnsupportedError('FlutterDeviceAppsPlatform not implemented')); + + @override + Future isAppLaunchable(String packageName) => + Future.error(UnsupportedError('FlutterDeviceAppsPlatform not implemented')); + @override Future?> getRequestedPermissions(String packageName) => Future.error(UnsupportedError('FlutterDeviceAppsPlatform not implemented')); @@ -251,6 +367,12 @@ class _UnimplementedPlatform extends FlutterDeviceAppsPlatform { Future.error(UnsupportedError('FlutterDeviceAppsPlatform not implemented')); @override + Future getInstallSourceInfo(String packageName) => + Future.error(UnsupportedError('FlutterDeviceAppsPlatform not implemented')); + + @override + // Newly deprecated; retain the method for backwards compatibility. + @Deprecated('Use getInstallSourceInfo() and its installingPackageName instead.') Future getInstallerStore(String packageName) => Future.error(UnsupportedError('FlutterDeviceAppsPlatform not implemented')); } diff --git a/pubspec.yaml b/pubspec.yaml index d5ded5f..f159559 100644 --- a/pubspec.yaml +++ b/pubspec.yaml @@ -1,21 +1,21 @@ name: flutter_device_apps_platform_interface description: Platform-agnostic API contract for flutter_device_apps (federated). -version: 0.7.0 +version: 1.0.0 repository: https://github.com/okmsbun/flutter_device_apps_platform_interface -issue_tracker: https://github.com/okmsbun/flutter_device_apps_platform_interface/issues +issue_tracker: https://github.com/okmsbun/flutter_device_apps/issues topics: - flutter - - plugin - - platform-interface - - federated-plugin - - app-events + - android + - installed-apps + - app-management + - package-manager environment: - sdk: ">=3.0.0 <4.0.0" + sdk: ">=3.12.0 <4.0.0" dependencies: plugin_platform_interface: ^2.1.8 dev_dependencies: - lints: ^6.1.0 - test: ^1.31.1 + lints: 6.1.0 + test: 1.32.0 diff --git a/test/app_change_event_test.dart b/test/app_change_event_test.dart index b6ce084..45e210c 100644 --- a/test/app_change_event_test.dart +++ b/test/app_change_event_test.dart @@ -40,9 +40,7 @@ void main() { }); test('creates instance with partial values', () { - const event = AppChangeEvent( - packageName: 'com.example.app', - ); + const event = AppChangeEvent(packageName: 'com.example.app'); expect(event.packageName, 'com.example.app'); expect(event.type, isNull); @@ -60,81 +58,59 @@ void main() { }); test('parses packageName correctly', () { - final event = AppChangeEvent.fromMap({ - 'packageName': 'com.test.app', - }); + final event = AppChangeEvent.fromMap({'packageName': 'com.test.app'}); expect(event.packageName, 'com.test.app'); }); test('parses type "installed" correctly', () { - final event = AppChangeEvent.fromMap({ - 'type': 'installed', - }); + final event = AppChangeEvent.fromMap({'type': 'installed'}); expect(event.type, AppChangeType.installed); }); test('parses type "removed" correctly', () { - final event = AppChangeEvent.fromMap({ - 'type': 'removed', - }); + final event = AppChangeEvent.fromMap({'type': 'removed'}); expect(event.type, AppChangeType.removed); }); test('parses type "updated" correctly', () { - final event = AppChangeEvent.fromMap({ - 'type': 'updated', - }); + final event = AppChangeEvent.fromMap({'type': 'updated'}); expect(event.type, AppChangeType.updated); }); test('returns null type for invalid type string', () { - final event = AppChangeEvent.fromMap({ - 'type': 'unknown', - }); + final event = AppChangeEvent.fromMap({'type': 'unknown'}); expect(event.type, isNull); }); test('returns null type for empty type string', () { - final event = AppChangeEvent.fromMap({ - 'type': '', - }); + final event = AppChangeEvent.fromMap({'type': ''}); expect(event.type, isNull); }); test('parses isReplacing from bool value', () { - final eventTrue = AppChangeEvent.fromMap({ - 'isReplacing': true, - }); - final eventFalse = AppChangeEvent.fromMap({ - 'isReplacing': false, - }); + final eventTrue = AppChangeEvent.fromMap({'isReplacing': true}); + final eventFalse = AppChangeEvent.fromMap({'isReplacing': false}); expect(eventTrue.isReplacing, true); expect(eventFalse.isReplacing, false); }); test('parses isReplacing from string value', () { - final eventTrue = AppChangeEvent.fromMap({ - 'isReplacing': 'true', - }); - final eventFalse = AppChangeEvent.fromMap({ - 'isReplacing': 'false', - }); + final eventTrue = AppChangeEvent.fromMap({'isReplacing': 'true'}); + final eventFalse = AppChangeEvent.fromMap({'isReplacing': 'false'}); expect(eventTrue.isReplacing, true); expect(eventFalse.isReplacing, false); }); test('returns null isReplacing for invalid string', () { - final event = AppChangeEvent.fromMap({ - 'isReplacing': 'yes', - }); + final event = AppChangeEvent.fromMap({'isReplacing': 'yes'}); expect(event.isReplacing, isNull); }); @@ -190,10 +166,7 @@ void main() { }); test('converts partial event to map', () { - const event = AppChangeEvent( - packageName: 'com.partial.app', - isReplacing: true, - ); + const event = AppChangeEvent(packageName: 'com.partial.app', isReplacing: true); final Map map = event.toMap(); expect(map['packageName'], 'com.partial.app'); diff --git a/test/app_info_test.dart b/test/app_info_test.dart index 1fd2192..d3ba0f6 100644 --- a/test/app_info_test.dart +++ b/test/app_info_test.dart @@ -259,10 +259,7 @@ void main() { }); test('handles invalid DateTime strings gracefully', () { - final map = { - 'firstInstallTime': 'not_a_timestamp', - 'lastUpdateTime': '', - }; + final map = {'firstInstallTime': 'not_a_timestamp', 'lastUpdateTime': ''}; final appInfo = AppInfo.fromMap(map); @@ -272,9 +269,7 @@ void main() { test('parses iconBytes from List', () { final iconData = [255, 216, 255, 224, 0, 16]; - final map = { - 'iconBytes': iconData, - }; + final map = {'iconBytes': iconData}; final appInfo = AppInfo.fromMap(map); @@ -283,9 +278,7 @@ void main() { }); test('handles non-List iconBytes gracefully', () { - final map = { - 'iconBytes': 'not_a_list', - }; + final map = {'iconBytes': 'not_a_list'}; final appInfo = AppInfo.fromMap(map); @@ -293,9 +286,7 @@ void main() { }); test('handles null iconBytes gracefully', () { - final map = { - 'iconBytes': null, - }; + final map = {'iconBytes': null}; final appInfo = AppInfo.fromMap(map); diff --git a/test/app_install_source_info_test.dart b/test/app_install_source_info_test.dart new file mode 100644 index 0000000..030f88b --- /dev/null +++ b/test/app_install_source_info_test.dart @@ -0,0 +1,42 @@ +import 'package:flutter_device_apps_platform_interface/flutter_device_apps_platform_interface.dart'; +import 'package:test/test.dart'; + +void main() { + test('parses installation source metadata from a platform map', () { + final AppInstallSourceInfo info = AppInstallSourceInfo.fromMap({ + 'installingPackageName': 'com.android.vending', + 'initiatingPackageName': 'com.example.installer', + 'originatingPackageName': 'com.example.browser', + 'packageSource': 2, + 'updateOwnerPackageName': 'com.example.owner', + }); + + expect(info.installingPackageName, 'com.android.vending'); + expect(info.initiatingPackageName, 'com.example.installer'); + expect(info.originatingPackageName, 'com.example.browser'); + expect(info.packageSource, 2); + expect(info.updateOwnerPackageName, 'com.example.owner'); + }); + + test('preserves unavailable fields in legacy and empty responses', () { + final AppInstallSourceInfo legacy = AppInstallSourceInfo.fromMap({ + 'installingPackageName': 'com.android.vending', + }); + final AppInstallSourceInfo unknown = AppInstallSourceInfo.fromMap({}); + + expect(legacy.installingPackageName, 'com.android.vending'); + expect(legacy.initiatingPackageName, isNull); + expect(legacy.originatingPackageName, isNull); + expect(legacy.packageSource, isNull); + expect(legacy.updateOwnerPackageName, isNull); + expect(unknown.installingPackageName, isNull); + expect(unknown.packageSource, isNull); + }); + + test('distinguishes unspecified source from unavailable or invalid source', () { + expect(AppInstallSourceInfo.fromMap({'packageSource': 0}).packageSource, 0); + expect(AppInstallSourceInfo.fromMap({'packageSource': '2'}).packageSource, 2); + expect(AppInstallSourceInfo.fromMap({'packageSource': 'invalid'}).packageSource, isNull); + expect(AppInstallSourceInfo.fromMap({'packageSource': null}).packageSource, isNull); + }); +} diff --git a/test/package_queries_test.dart b/test/package_queries_test.dart new file mode 100644 index 0000000..a41e529 --- /dev/null +++ b/test/package_queries_test.dart @@ -0,0 +1,15 @@ +import 'package:flutter_device_apps_platform_interface/flutter_device_apps_platform_interface.dart'; +import 'package:test/test.dart'; + +void main() { + test('an unregistered platform still reports unsupported operations', () async { + final FlutterDeviceAppsPlatform platform = FlutterDeviceAppsPlatform.instance; + await expectLater(platform.listApps(packageNamePrefix: 'com.example.'), throwsUnsupportedError); + await expectLater(platform.getAppIcon('com.example.user'), throwsUnsupportedError); + await expectLater(platform.isAppInstalled('com.example.user'), throwsUnsupportedError); + await expectLater(platform.isSystemApp('com.example.user'), throwsUnsupportedError); + await expectLater(platform.isAppEnabled('com.example.user'), throwsUnsupportedError); + await expectLater(platform.isAppLaunchable('com.example.user'), throwsUnsupportedError); + await expectLater(platform.getInstallSourceInfo('com.example.user'), throwsUnsupportedError); + }); +}