@_nazmiforreal/flutter-ota 0.1.19 → 0.1.21

package/dart-src/packages/cli-tools/test/pocketbase_schema_test.dart

@@ -29,7 +29,7 @@ class _MockPocketBase {
 
   Future<void> _handle(HttpRequest req) async {
     final path = req.uri.path;
-    if (path == '/api/admins/auth-with-password') {
+    if (path == '/api/collections/_superusers/auth-with-password') {
       authCalled = true;
       final body = jsonDecode(await utf8.decoder.bind(req).join()) as Map;
       lastAuthEmail = body['identity'] as String?;
@@ -63,6 +63,14 @@ class _MockPocketBase {
   }
 }
 
+const _allCollections = [
+  'bundles',
+  'channels',
+  'audit_log',
+  'bundles_patches',
+  'app_meta',
+];
+
 void main() {
   late _MockPocketBase mock;
   setUp(() async {
@@ -73,7 +81,7 @@ void main() {
   });
 
   test(
-    'schema installer creates the three collections on a fresh PB',
+    'schema installer creates all five collections on a fresh PB',
     () async {
       final installer = PocketBaseSchemaInstaller(
         url: mock.baseUrl,
@@ -83,24 +91,21 @@ void main() {
       final result = await installer.install();
       expect(mock.authCalled, isTrue);
       expect(mock.lastAuthEmail, 'admin@x.com');
-      expect(result.created, containsAll(['bundles', 'channels', 'audit_log']));
+      expect(result.created, containsAll(_allCollections));
       expect(result.skipped, isEmpty);
-      expect(
-        mock.createdCollections,
-        containsAll(['bundles', 'channels', 'audit_log']),
-      );
+      expect(mock.createdCollections, containsAll(_allCollections));
     },
   );
 
   test('schema installer skips collections that already exist', () async {
-    mock.existingCollections = ['bundles', 'channels', 'audit_log'];
+    mock.existingCollections = _allCollections;
     final installer = PocketBaseSchemaInstaller(
       url: mock.baseUrl,
       adminEmail: 'admin@x.com',
       adminPassword: 'secret',
     );
     final result = await installer.install();
-    expect(result.skipped, containsAll(['bundles', 'channels', 'audit_log']));
+    expect(result.skipped, containsAll(_allCollections));
     expect(result.created, isEmpty);
     expect(mock.createdCollections, isEmpty);
   });

package/dart-src/packages/core/CHANGELOG.md

@@ -1 +1,6 @@
-## 0.1.4
+## 0.1.6
+
+- Added `gitCommitHash` field to `UpdateInfo` for commit tracking.
+- General maintenance.
+
+## 0.1.5

package/dart-src/packages/core/lib/flutter_ota_kit_core.dart

@@ -21,6 +21,8 @@ export 'src/update_bundle_params.dart';
 // Algorithms.
 export 'src/rollout.dart';
 export 'src/semver.dart';
+export 'src/semver_range.dart' show satisfies;
+export 'src/semver_version.dart' show SemVer;
 export 'src/uuid.dart';
 
 // Bundle artifact helpers.

package/dart-src/packages/core/lib/src/app_update_info.dart

@@ -1,17 +1,36 @@
 import 'changed_asset.dart' show ChangedAsset;
 import 'status.dart';
 
-/// hot-updater `UpdateInfo` — database-layer update decision.
+/// Database-layer update decision — hot-updater `UpdateInfo`.
+///
+/// This is the raw result from the database query before the storage
+/// resolver converts URIs to download URLs. Not directly sent to devices.
 class UpdateInfo {
+  /// Bundle UUID.
   final String id;
+
+  /// Whether the device must install this update before proceeding.
   final bool shouldForceUpdate;
+
+  /// Optional message to display to the user during the update.
   final String? message;
+
+  /// Deployment status (`update` or `rollback`).
   final UpdateStatus status;
+
+  /// Protocol URI for the artifact in storage (e.g. `s3://bucket/key`).
   final String? storageUri;
+
+  /// MD5 hex of the artifact for verification.
   final String? fileHash;
 
+  /// Git commit hash of the build, if available.
+  final String? gitCommitHash;
+
   /// Internal rollout metadata; never serialized to update-check clients.
   final int? rolloutCohortCount;
+
+  /// Cohort identifiers for targeted rollouts; never sent to devices.
   final List<String>? targetCohorts;
 
   const UpdateInfo({
@@ -21,6 +40,7 @@ class UpdateInfo {
     required this.status,
     required this.storageUri,
     required this.fileHash,
+    this.gitCommitHash,
     this.rolloutCohortCount,
     this.targetCohorts,
   });
@@ -28,20 +48,39 @@ class UpdateInfo {
 
 /// Device-facing payload for an available update —
 /// hot-updater `AppUpdateAvailableInfo`.
+///
+/// This is the resolved update info sent to the device SDK after the
+/// storage resolver converts URIs to signed download URLs.
 class AppUpdateAvailableInfo extends AppUpdateInfo {
+  @override
   final String id;
+
+  @override
   final bool shouldForceUpdate;
+
+  @override
   final String? message;
+
+  @override
   final UpdateStatus status;
+
+  /// Signed download URL for the artifact.
   final String? fileUrl;
+
+  /// MD5 hex of the artifact for download verification.
   final String? fileHash;
 
   /// Ed25519 (base64) signature over the artifact MD5 hex string. Consumed by
   /// the device SDK to verify the patch (`PatchInfo.signature`).
   final String? signature;
 
+  /// Signed URL for the asset manifest (if asset-based patch).
   final String? manifestUrl;
+
+  /// MD5 hex of the manifest file for verification.
   final String? manifestFileHash;
+
+  /// Map of asset path to diff descriptor for incremental asset updates.
   final Map<String, ChangedAsset>? changedAssets;
 
   const AppUpdateAvailableInfo({
@@ -92,19 +131,52 @@ class AppUpdateAvailableInfo extends AppUpdateInfo {
 }
 
 /// Device-facing "nothing to do" — hot-updater `AppUpToDateInfo`.
+///
+/// Returned when the device is already on the latest bundle for its
+/// channel/platform. All fields are empty/null defaults.
 class AppUpToDateInfo extends AppUpdateInfo {
   const AppUpToDateInfo();
 
+  @override
+  String get id => '';
+
+  @override
+  bool get shouldForceUpdate => false;
+
+  @override
+  String? get message => null;
+
+  @override
+  UpdateStatus get status => UpdateStatus.update;
+
   @override
   Map<String, dynamic> toJson() => {'status': 'UP_TO_DATE'};
 }
 
 /// Sealed union: hot-updater `AppUpdateInfo`.
+///
+/// Pattern-match on [AppUpdateAvailableInfo] or [AppUpToDateInfo] to
+/// handle the two possible outcomes of an update check.
 sealed class AppUpdateInfo {
   const AppUpdateInfo();
 
+  /// Bundle UUID (empty string for up-to-date).
+  String get id;
+
+  /// Whether the device must install this update.
+  bool get shouldForceUpdate;
+
+  /// Optional message to display during the update.
+  String? get message;
+
+  /// Deployment status.
+  UpdateStatus get status;
+
+  /// Serialize to JSON for device SDK consumption.
   Map<String, dynamic> toJson();
 
+  /// Deserialize from JSON. Returns [AppUpToDateInfo] if status is
+  /// `"UP_TO_DATE"`, otherwise [AppUpdateAvailableInfo].
   factory AppUpdateInfo.fromJson(Map<String, dynamic> j) {
     final raw = j['status'];
     if (raw == 'UP_TO_DATE') return const AppUpToDateInfo();

package/dart-src/packages/core/lib/src/bundle.dart

@@ -172,28 +172,73 @@ class Bundle {
     'enabled': enabled,
     'file_hash': fileHash,
     'storage_uri': storageUri,
-    'git_commit_hash': gitCommitHash,
-    'message': message,
     'channel': channel,
-    'target_app_version': targetAppVersion,
-    'fingerprint_hash': fingerprintHash,
-    'metadata': metadata?.toJson() ?? <String, dynamic>{},
-    'manifest_storage_uri': manifestStorageUri,
-    'manifest_file_hash': manifestFileHash,
-    'asset_base_storage_uri': assetBaseStorageUri,
-    'patches': patches?.map((p) => p.toJson()).toList(),
-    'patch_base_bundle_id': patchBaseBundleId,
-    'patch_base_file_hash': patchBaseFileHash,
-    'patch_file_hash': patchFileHashLegacy,
-    'patch_storage_uri': patchStorageUri,
-    'rollout_cohort_count': rolloutCohortCount,
-    'target_cohorts': targetCohorts,
+    if (gitCommitHash != null) 'git_commit_hash': gitCommitHash,
+    if (message != null) 'message': message,
+    if (targetAppVersion != null) 'target_app_version': targetAppVersion,
+    if (fingerprintHash != null) 'fingerprint_hash': fingerprintHash,
+    if (metadata != null) 'metadata': metadata!.toJson(),
+    if (manifestStorageUri != null)
+      'manifest_storage_uri': manifestStorageUri,
+    if (manifestFileHash != null) 'manifest_file_hash': manifestFileHash,
+    if (assetBaseStorageUri != null)
+      'asset_base_storage_uri': assetBaseStorageUri,
+    if (patches != null) 'patches': patches!.map((p) => p.toJson()).toList(),
+    if (patchBaseBundleId != null) 'patch_base_bundle_id': patchBaseBundleId,
+    if (patchBaseFileHash != null)
+      'patch_base_file_hash': patchBaseFileHash,
+    if (patchFileHashLegacy != null) 'patch_file_hash': patchFileHashLegacy,
+    if (patchStorageUri != null) 'patch_storage_uri': patchStorageUri,
+    if (rolloutCohortCount != null)
+      'rollout_cohort_count': rolloutCohortCount,
+    if (targetCohorts != null) 'target_cohorts': targetCohorts,
   };
 
   @override
   bool operator ==(Object o) =>
-      o is Bundle && o.toJson().toString() == toJson().toString();
+      o is Bundle &&
+      o.id == id &&
+      o.platform == platform &&
+      o.shouldForceUpdate == shouldForceUpdate &&
+      o.enabled == enabled &&
+      o.fileHash == fileHash &&
+      o.storageUri == storageUri &&
+      o.channel == channel &&
+      o.gitCommitHash == gitCommitHash &&
+      o.message == message &&
+      o.targetAppVersion == targetAppVersion &&
+      o.fingerprintHash == fingerprintHash &&
+      o.metadata == metadata &&
+      o.manifestStorageUri == manifestStorageUri &&
+      o.manifestFileHash == manifestFileHash &&
+      o.assetBaseStorageUri == assetBaseStorageUri &&
+      o.patchBaseBundleId == patchBaseBundleId &&
+      o.patchBaseFileHash == patchBaseFileHash &&
+      o.patchFileHashLegacy == patchFileHashLegacy &&
+      o.patchStorageUri == patchStorageUri &&
+      o.rolloutCohortCount == rolloutCohortCount;
 
   @override
-  int get hashCode => toJson().toString().hashCode;
+  int get hashCode => Object.hash(
+    id,
+    platform,
+    shouldForceUpdate,
+    enabled,
+    fileHash,
+    storageUri,
+    channel,
+    gitCommitHash,
+    message,
+    targetAppVersion,
+    fingerprintHash,
+    metadata,
+    manifestStorageUri,
+    manifestFileHash,
+    assetBaseStorageUri,
+    patchBaseBundleId,
+    patchBaseFileHash,
+    patchFileHashLegacy,
+    patchStorageUri,
+    rolloutCohortCount,
+  );
 }

package/dart-src/packages/core/lib/src/bundle_artifacts.dart

@@ -7,9 +7,11 @@ library;
 import 'bundle.dart';
 import 'bundle_patch_artifact.dart';
 
-/// Identity — returns the metadata as-is.
-/// (TS version strips artifact-specific keys; Dart uses strong types so
-/// there is nothing to strip.)
+/// Identity function — returns the metadata as-is.
+///
+/// In the TypeScript version this strips artifact-specific keys from the
+/// metadata map. The Dart version uses strong types so there is nothing
+/// to strip; this function is kept for API compatibility.
 Map<String, Object?>? stripBundleArtifactMetadata(
   Map<String, Object?>? metadata,
 ) => metadata;
@@ -25,6 +27,8 @@ String? getAssetBaseStorageUri(Bundle bundle) => bundle.assetBaseStorageUri;
 
 /// Deduplicate patches by [BundlePatchArtifact.baseBundleId], keeping the
 /// first occurrence (by insertion order).
+///
+/// Returns an empty list if the bundle has no patches.
 List<BundlePatchArtifact> getBundlePatches(Bundle bundle) {
   final patches = bundle.patches;
   if (patches == null || patches.isEmpty) return const [];

package/dart-src/packages/core/lib/src/bundle_patch_artifact.dart

@@ -1,10 +1,26 @@
 /// Binary patch artifact — hot-updater `BundlePatchArtifact`.
+///
+/// Represents a single binary diff between two bundles. The device SDK uses
+/// [patchStorageUri] to download the patch, verifies it against [patchFileHash],
+/// then applies it on top of the base bundle identified by [baseBundleId].
 library;
 
+/// A binary diff artifact that patches an older bundle into a newer one.
+///
+/// Patch artifacts are stored in [Bundle.patches] as an ordered list. The
+/// device SDK tries each patch in order and applies the first one whose base
+/// matches the installed bundle.
 class BundlePatchArtifact {
+  /// UUID of the bundle this patch transforms from.
   final String baseBundleId;
+
+  /// MD5 hex of the base bundle's artifact (for verification).
   final String baseFileHash;
+
+  /// MD5 hex of the patch artifact (for download verification).
   final String patchFileHash;
+
+  /// Protocol URI pointing to the patch artifact in storage.
   final String patchStorageUri;
 
   const BundlePatchArtifact({

package/dart-src/packages/core/lib/src/changed_asset.dart

@@ -1,9 +1,16 @@
 /// Per-asset diff descriptors — hot-updater `ChangedAsset*`.
+///
+/// Used by the CLI's asset diffing pipeline to describe how individual
+/// assets changed between two bundles. The device SDK uses these descriptors
+/// to apply incremental asset updates.
 library;
 
+/// A single asset file that changed between bundles.
 class ChangedAssetFile {
-  /// "br" or null.
+  /// Compression format (e.g. `"br"` for Brotli), or null if uncompressed.
   final String? compression;
+
+  /// Download URL for the full asset file.
   final String url;
 
   const ChangedAssetFile({required this.url, this.compression});
@@ -16,13 +23,27 @@ class ChangedAssetFile {
   Map<String, dynamic> toJson() => {'url': url, 'compression': compression};
 }
 
+/// A binary patch for a changed asset.
+///
+/// When an asset is modified between bundles, a bsdiff patch is generated
+/// to avoid re-downloading the full file. The device SDK downloads [patchUrl],
+/// verifies it against [patchFileHash], then applies the diff on top of
+/// the base asset.
 class ChangedAssetPatch {
+  /// UUID of the bundle containing the original (unpatched) asset.
   final String baseBundleId;
+
+  /// MD5 hex of the original asset file (for verification).
   final String baseFileHash;
+
+  /// MD5 hex of the patch file (for verification).
   final String patchFileHash;
+
+  /// Download URL for the binary patch file.
   final String patchUrl;
 
-  /// Always "bsdiff" in hot-updater; kept for wire compatibility.
+  /// Diff algorithm identifier. Always `"bsdiff"` in hot-updater;
+  /// kept for wire compatibility with future algorithms.
   final String algorithm;
 
   const ChangedAssetPatch({
@@ -51,10 +72,19 @@ class ChangedAssetPatch {
   };
 }
 
+/// Describes a single asset that changed between two bundles.
+///
+/// Exactly one of [file] or [patch] is non-null:
+/// - [file] is set when the asset is new or replaced entirely.
+/// - [patch] is set when the asset was modified and a binary diff is available.
 class ChangedAsset {
-  /// SHA256 hex of the asset file.
+  /// SHA-256 hex of the asset file content.
   final String fileHash;
+
+  /// Full replacement file descriptor. Null if a patch is available instead.
   final ChangedAssetFile? file;
+
+  /// Binary diff patch. Null if the asset is new (use [file] instead).
   final ChangedAssetPatch? patch;
 
   const ChangedAsset({required this.fileHash, this.file, this.patch});

package/dart-src/packages/core/lib/src/get_bundles_args.dart

@@ -6,14 +6,26 @@ import 'uuid.dart' show nilUuid;
 ///
 /// Two variants keyed by [UpdateStrategy]; shared fields defaulted the same
 /// way (minBundleId = NIL_UUID, channel = "production").
+///
+/// Use [AppVersionGetBundlesArgs] for semver-based targeting or
+/// [FingerprintGetBundlesArgs] for device-specific targeting.
 sealed class GetBundlesArgs {
+  /// The update strategy this request uses.
   final UpdateStrategy _updateStrategy;
+
+  /// Target platform (`ios` or `android`).
   final Platform platform;
+
+  /// Currently installed bundle ID.
   final String bundleId;
+
+  /// Minimum bundle ID to consider (for rollback protection).
   final String minBundleId;
+
+  /// Release channel to query (default: `"production"`).
   final String channel;
 
-  /// Cohort identifier for server-side rollout decisions.
+  /// Optional cohort identifier for server-side rollout decisions.
   final String? cohort;
 
   const GetBundlesArgs({
@@ -38,7 +50,13 @@ sealed class GetBundlesArgs {
   };
 }
 
+/// Update-check args using device fingerprint for targeting.
+///
+/// The server matches [fingerprintHash] against bundles that have a
+/// `targetCohorts` list, enabling device-specific rollouts without
+/// exposing device IDs.
 class FingerprintGetBundlesArgs extends GetBundlesArgs {
+  /// SHA-256 hex of the device fingerprint.
   final String fingerprintHash;
 
   const FingerprintGetBundlesArgs({
@@ -57,8 +75,12 @@ class FingerprintGetBundlesArgs extends GetBundlesArgs {
   };
 }
 
+/// Update-check args using semver range for targeting.
+///
+/// The server matches [appVersion] against bundles' `targetAppVersion`
+/// semver ranges to determine eligibility.
 class AppVersionGetBundlesArgs extends GetBundlesArgs {
-  /// Current app version (semver).
+  /// Current app version (semver string, e.g. `"1.2.3"`).
   final String appVersion;
 
   const AppVersionGetBundlesArgs({

package/dart-src/packages/core/lib/src/platform.dart

@@ -2,13 +2,21 @@
 /// first but keep the full union for wire compatibility.
 library;
 
+/// Target platform for bundle deployment and update checks.
 enum Platform {
+  /// Apple iOS platform.
   ios('ios'),
+
+  /// Google Android platform.
   android('android');
 
+  /// String value used in database rows and API payloads.
   final String value;
+
   const Platform(this.value);
 
+  /// Parse a platform string. Throws [ArgumentError] if [v] is not a
+  /// recognized platform value.
   static Platform fromValue(String v) => Platform.values.firstWhere(
     (p) => p.value == v,
     orElse: () => throw ArgumentError('unknown platform: $v'),

package/dart-src/packages/core/lib/src/semver.dart

@@ -1,9 +1,6 @@
 import 'semver_range.dart' show satisfies;
 import 'semver_version.dart';
 
-export 'semver_range.dart' show satisfies;
-export 'semver_version.dart' show SemVer;
-
 /// hot-updater `semverSatisfies(targetAppVersion, currentVersion)`
 /// (plugins/plugin-core/src/semverSatisfies.ts):
 ///

package/dart-src/packages/core/lib/src/status.dart

@@ -1,25 +1,44 @@
 /// Update status enums — hot-updater `UpdateStatus` / `AppUpdateStatus`.
+///
+/// [UpdateStatus] is used in database rows to mark bundles as deployed or
+/// rolled back. [AppUpdateStatus] is derived by the client SDK to indicate
+/// the result of an update check.
 library;
 
+/// Server-side deployment status for a bundle.
 enum UpdateStatus {
+  /// Bundle has been rolled back (no longer served to devices).
   rollback('ROLLBACK'),
+
+  /// Bundle is active and served to eligible devices.
   update('UPDATE');
 
+  /// String value stored in database rows.
   final String value;
+
   const UpdateStatus(this.value);
 
+  /// Parse an update status string. Throws [ArgumentError] if [v] is not
+  /// a recognized status value.
   static UpdateStatus fromValue(String v) => UpdateStatus.values.firstWhere(
     (s) => s.value == v,
     orElse: () => throw ArgumentError('unknown status: $v'),
   );
 }
 
-/// What the client derives: UP_TO_DATE | ROLLBACK | UPDATE.
+/// Client-side update check result.
 enum AppUpdateStatus {
+  /// Device is already on the latest bundle for its channel/platform.
   upToDate('UP_TO_DATE'),
+
+  /// Device should roll back to a previous bundle.
   rollback('ROLLBACK'),
+
+  /// Device should download and install a new bundle.
   update('UPDATE');
 
+  /// String value returned in update-check API responses.
   final String value;
+
   const AppUpdateStatus(this.value);
 }

package/dart-src/packages/core/lib/src/strategy.dart

@@ -1,10 +1,20 @@
 /// Update targeting strategy — hot-updater `UpdateStrategy`.
+///
+/// Determines how the server matches bundles to devices during update checks.
 library;
 
+/// Strategy for targeting bundles to devices.
 enum UpdateStrategy {
+  /// Match by device fingerprint hash. The server compares the hash against
+  /// bundles' `targetCohorts` list.
   fingerprint('fingerprint'),
+
+  /// Match by app version semver range. The server compares the version
+  /// against bundles' `targetAppVersion` range.
   appVersion('appVersion');
 
+  /// String value used in API payloads.
   final String value;
+
   const UpdateStrategy(this.value);
 }

package/dart-src/packages/core/lib/src/update_bundle_params.dart

@@ -2,12 +2,27 @@ import 'platform.dart';
 
 /// hot-updater `UpdateBundleParams` — device-side parameters sent with
 /// update requests.
+///
+/// These parameters are collected by the device SDK and sent to the
+/// backend's update-check endpoint to determine which bundle the
+/// device should install.
 class UpdateBundleParams {
+  /// Target platform (`ios` or `android`).
   final Platform platform;
+
+  /// Currently installed bundle ID.
   final String bundleId;
+
+  /// Minimum bundle ID to consider (for rollback protection).
   final String minBundleId;
+
+  /// Release channel to query.
   final String channel;
+
+  /// Current app version (semver string).
   final String appVersion;
+
+  /// Optional device fingerprint hash for targeted rollouts.
   final String? fingerprintHash;
 
   const UpdateBundleParams({

package/dart-src/packages/core/lib/src/uuid.dart

@@ -6,18 +6,28 @@ library;
 
 import 'dart:math';
 
+/// The zero UUID, used as a sentinel for "no bundle" or "latest".
 const String nilUuid = '00000000-0000-0000-0000-000000000000';
 
+/// Regex pattern for validating UUIDv7 strings.
 final RegExp _uuidV7Pattern = RegExp(
   r'^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$',
 );
 
+/// Secure random number generator for UUIDv7 variant bits.
 final Random _random = Random.secure();
 
+/// Format an integer as a zero-padded hex string.
 String _hex(int value, int width) =>
     value.toRadixString(16).padLeft(width, '0');
 
 /// Generates a lowercase RFC 9562 UUIDv7 string (unix-ms timestamp based).
+///
+/// The UUIDv7 format encodes a 48-bit millisecond timestamp in the first
+/// 48 bits, making strings lexicographically sortable by creation time.
+///
+/// Throws [ArgumentError] if the current timestamp is outside the valid
+/// UUIDv7 range (0 to 2^48 - 1 milliseconds).
 String uuidV7({DateTime? now}) {
   final ts = (now ?? DateTime.now()).millisecondsSinceEpoch;
   if (ts < 0 || ts > 0xFFFFFFFFFFFF) {
@@ -38,6 +48,7 @@ String uuidV7({DateTime? now}) {
       '7$g3-$g4-$g5';
 }
 
+/// Returns true if [value] is a valid UUIDv7 string.
 bool isUuidV7(String value) => _uuidV7Pattern.hasMatch(value);
 
 /// Lexicographic comparison used by hot-updater for bundle ordering.

package/dart-src/plugins/aws/CHANGELOG.md

@@ -1 +1,5 @@
-## 0.1.5
+## 0.1.7
+
+- General maintenance.
+
+## 0.1.6